@done-coding/admin-core 0.17.1-alpha.0 → 0.18.1-alpha.0

package/types/bridge/layout.d.ts

@@ -1,25 +1,65 @@
 import { Ref, DeepReadonly } from 'vue';
 import { StorageLike } from './index';
+/**
+ * bridge 布局折叠 hook（按耦合度从 index.ts 拆出，规则 12）。
+ *
+ * 折叠态真相源在 bridge——对称主题架构反转（store 退役本地 ref、仅转发）：
+ * sidebar / aside 的折叠开关态由本 hook 持有，对外 `bridge.layout.{setSidebarCollapse,
+ * toggleSidebar,setAsideCollapse,toggleAside}` 切换 + `sidebarCollapsed / asideCollapsed`
+ * 响应式只读真相源。appStore 转发（`changeSidebarCollapseStatus` → `setSidebarCollapse`、
+ * `sidebarIsCollapse` → 读 `sidebarCollapsed`），AppSidebar / AppAside 经 store 转发驱动。
+ *
+ * 真相落 bridge 的收益：① 折叠态可持久化（复用注入 storage，同 theme 持久化范式）；
+ * ② 可被 agent / 主题经 bridge 公开面驱动（aside = AI 副驾，副驾自行收起 / 展开）。
+ * 每次 `createCoreBridge` 各自闭包内构造（零模块级单例，守实例隔离，规则 8）。
+ */
+/** core 折叠态持久化的命名空间 key（命名空间前缀已由 storage 加）；缺省值。 */
 export declare const DEFAULT_LAYOUT_STORAGE_KEY = "dc-core-layout";
+/** 折叠态持久化载荷。 */
 export interface LayoutCollapsePersistShape {
+    /** sidebar 是否折叠 */
     sidebarCollapsed: boolean;
+    /** aside 是否折叠 */
     asideCollapsed: boolean;
 }
+/** bridge 布局折叠 hook 工厂入参。 */
 export interface BridgeLayoutInit {
+    /** 注入的命名空间 storage（折叠态持久化读写） */
     storage: StorageLike;
+    /** 持久化 key，缺省 {@link DEFAULT_LAYOUT_STORAGE_KEY} */
     storageKey?: string;
+    /** sidebar 折叠初值（业务侧无缓存默认）；缺省 false */
     defaultSidebarCollapsed?: boolean;
+    /** aside 折叠初值（业务侧无缓存默认）；缺省 false */
     defaultAsideCollapsed?: boolean;
 }
+/**
+ * 布局折叠模块（bridge 公开面 `bridge.layout`）。
+ *
+ * 状态（响应式只读真相源）+ 切换方法聚于一个内聚命名空间——agent / 主题 / store
+ * 经此读 / 驱折叠（aside = AI 副驾自收起）。[MUST NOT] 解构/快照折叠态（⚠️ 切换后定格）。
+ */
 export interface CoreLayoutModule {
+    /** sidebar 是否折叠（响应式只读真相源） */
     readonly sidebarCollapsed: DeepReadonly<Ref<boolean>>;
+    /** aside 是否折叠（响应式只读真相源） */
     readonly asideCollapsed: DeepReadonly<Ref<boolean>>;
+    /** 设 sidebar 折叠态（持久化随写） */
     setSidebarCollapse: (collapsed: boolean) => void;
+    /** 反转 sidebar 折叠态 */
     toggleSidebar: () => void;
+    /** 设 aside 折叠态（持久化随写） */
     setAsideCollapse: (collapsed: boolean) => void;
+    /** 反转 aside 折叠态 */
     toggleAside: () => void;
 }
+/** bridge 布局折叠 hook 工厂返回（聚合到 `bridge.layout`）。 */
 export interface BridgeLayoutHook {
     layout: CoreLayoutModule;
 }
+/**
+ * bridge 布局折叠 hook 工厂。
+ *
+ * init：读持久化恢复 sidebar / aside 折叠态（无持久化值 → 回落初值）。
+ */
 export declare function createBridgeLayoutHook(init: BridgeLayoutInit): BridgeLayoutHook;

package/types/bridge/plugin.d.ts

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

package/types/bridge/route.d.ts

@@ -1,17 +1,36 @@
 import { RouteRecordRaw } from 'vue-router';
 import { RouteMetaResolveRaw } from '../types';
+/** 路由元信息默认配置（工厂参数最小 shape） */
 export interface RouteMetaDefaultConfig {
+    /** 各路由[未配置情况下]默认是否展示在菜单 */
     menuShow: boolean;
+    /** 各路由[未配置情况下]默认是否需要登录 */
     needLogin: boolean;
 }
+/**
+ * 创建路由元信息解析 raw 树生成器
+ * ---
+ * 工厂模式：app 层传入 metaDefault 配置（含 menuShow / needLogin 默认值）
+ *
+ * @example
+ *   const generateRouteMetaRawTree = createGenerateRouteMetaRawTree(APP_ROUTER_META_DEFAULT_CONFIG);
+ *   const tree = generateRouteMetaRawTree(routes, { ... });
+ */
 export declare const createGenerateRouteMetaRawTree: (metaDefault: RouteMetaDefaultConfig) => <T extends {
     children: T[];
 } = RouteMetaResolveRaw>(routesList: RouteRecordRaw[], { parentPath, parentPathList, routeLevel, sortFn, mapFn, filterFn, }?: Partial<Pick<RouteMetaResolveRaw, "parentPath" | "parentPathList" | "routeLevel"> & {
+    /** 排序函数 */
     sortFn?: (a: T, b: T) => number;
+    /** 映射函数 */
     mapFn: (route: Omit<RouteMetaResolveRaw, "children"> & {
         children: T[];
     }) => T;
+    /** 过滤函数 */
     filterFn: (raw: Omit<RouteMetaResolveRaw, "children"> & {
         children: T[];
-    }, haveChildren: boolean, haveChildrenRaw: boolean) => boolean;
+    }, 
+    /** 是否有符合过滤条件的子路由 */
+    haveChildren: boolean, 
+    /** [原始配置]是否有子路由 */
+    haveChildrenRaw: boolean) => boolean;
 }>) => T[];

package/types/bridge/state.d.ts

@@ -1,9 +1,23 @@
 export interface UseStateOptions {
+    /** 是否调试  */
     debug: boolean;
+    /** 模块命名空间 */
     moduleKey: string;
+    /** 缓存 */
     cache?: boolean;
+    /** 缓存实现 */
     storage?: Storage;
 }
+/**
+ * 创建 useState 工厂
+ * ---
+ * 工厂模式：app 层传入命名空间，core 不感知具体值
+ *
+ * @example
+ *   const useState = createUseState("myapp");
+ *   const moduleState = useState({ count: 0 }, { debug: true, moduleKey: "counter" });
+ *   // cacheKey 形如 "myapp/useState/counter"
+ */
 export declare const createUseState: (factoryNamespace: string) => <S extends Record<string, any> = Record<string, any>>(initState: S | (() => S), { debug, moduleKey, cache, storage }?: UseStateOptions) => {
     state: any;
     getStateInit: () => S;

package/types/bridge/storage.d.ts

@@ -1 +1,10 @@
+/**
+ * 创建带命名空间的 localStorage 实例
+ * ---
+ * 工厂模式：app 层传入命名空间，core 不感知具体值
+ *
+ * @example
+ *   const myStorage = createStorageWithNamespace("myapp");
+ *   myStorage.setItem("token", "xxx"); // 实际写入 localStorage 的 key 为 "myapp/token"
+ */
 export declare const createStorageWithNamespace: (namespace: string) => Storage;

package/types/bridge/theme/index.d.ts

@@ -1,3 +1,10 @@
 import { BridgeThemeHook, BridgeThemeInit } from './types';
+/**
+ * bridge 主题 hook 工厂。
+ *
+ * 每次 `createCoreBridge` 调用各自闭包内构造一份（零模块级单例，守实例隔离）。
+ * init：自动 `add('default', initConfig)`；读持久化恢复 `themeMode` 即时生效、
+ * `themeStyle` 走「desiredStyle 命中再 apply」时序（插件后注册风格亦能恢复）。
+ */
 export declare function createBridgeThemeHook(init: BridgeThemeInit): BridgeThemeHook;
 export type { CoreThemePresetLayout, CoreConfigDescription, CoreThemeLifecycleContext, CoreThemeLifecycleHooks, CoreThemeEntry, CoreThemeMode, CoreThemeModule, CoreThemeDensity, CoreThemeMotion, ElSize, CoreThemeComponentDefaults, BridgeThemeLayoutState, BridgeThemeHook, BridgeThemeLayoutBaseline, BridgeThemeInit, } from './types';

package/types/bridge/theme/persist.d.ts

@@ -1,11 +1,23 @@
 import { StorageLike } from '../index';
 import { CoreThemeMode } from './types';
+/**
+ * bridge 主题模块**持久化**子模块（升级目录拆出）。
+ *
+ * 负责 localStorage 形态的读取 / 兼容迁移：v2 存 `{themeStyle,themeMode}`，读时兼容
+ * 旧 v1 `themeIsDark` 布尔。写入（`persist()`）在工厂内闭包，复用本文件的 shape 类型。
+ */
+/** core 主题持久化的命名空间 key（命名空间前缀已由 storage 加）；缺省值。 */
 export declare const DEFAULT_STORAGE_KEY = "dc-core-theme";
+/** 持久化载荷（v2：明暗存 mode 三态，取代旧 themeIsDark 布尔）。 */
 export interface ThemePersistShape {
+    /** 当前风格名 */
     themeStyle: string;
+    /** 明暗模式三态（亮/暗/跟随系统） */
     themeMode: CoreThemeMode;
 }
+/** 读持久化的兼容形态：除 v2 字段外，兼容旧 v1 `themeIsDark` 布尔（迁移用）。 */
 export type ThemePersistRead = Partial<ThemePersistShape & {
     themeIsDark: boolean;
 }>;
+/** 读持久化（JSON.parse 容错；非法/缺失返 null）。返回兼容形态（含旧 themeIsDark）。 */
 export declare const readPersist: (storage: StorageLike, key: string) => ThemePersistRead | null;

package/types/bridge/theme/system-dark.d.ts

@@ -1,2 +1,14 @@
+/**
+ * bridge 主题模块**系统明暗探测**子模块（升级目录拆出）。
+ *
+ * `prefers-color-scheme: dark` 的一次性读取 + 变更监听；无 matchMedia（SSR / 老环境）
+ * 安全降级。`system` 明暗态下 `themeIsDark` 经此派生。
+ */
+/** 读系统是否偏暗（`prefers-color-scheme: dark`）；无 matchMedia（SSR / 老环境）→ false。 */
 export declare const readSystemPrefersDark: () => boolean;
+/**
+ * 监听系统明暗变化，变更时回调最新值；返回清理函数。
+ * bridge 为 app 单例无 teardown，当前不主动清理（listener 随 app 常驻，可接受）；
+ * 返回清理函数留作未来 dispose / 测试用。无 matchMedia → noop。
+ */
 export declare const watchSystemPrefersDark: (cb: (isDark: boolean) => void) => (() => void);

package/types/bridge/theme/types.d.ts

@@ -1,98 +1,336 @@
 import { Component, DeepReadonly, Ref } from 'vue';
 import { AppThemeConfig, AppLayoutHeaderConfig, AppLayoutFooterConfig, AppLayoutSidebarConfig, AppLayoutAsideConfig, AppLayoutBreadcrumbConfig, AppLayoutBodyConfig, AppLayoutViewportConfig, AppLayoutGapConfig, StorageLike } from '../index';
 import { UpdatableConfigKey, UpdatableConfigMap } from '../config-hook';
+/**
+ * bridge 主题模块**类型面**（从 `bridge/theme.ts` 升级目录拆出，CLAUDE.md 规则 12）。
+ *
+ * 纯类型 / 接口定义，无运行时逻辑——工厂在 `./index.ts`、持久化在 `./persist.ts`、
+ * 系统明暗探测在 `./system-dark.ts`。本文件显式 `import type { Component, DeepReadonly,
+ * Ref } from "vue"`（规则 9.0：lib build 下 vite-plugin-dts 不靠 auto-import）。
+ */
+/**
+ * 主题 preset 的 layout 维度（焊缝契约 ④，P1 冻结，跨域共享）。
+ *
+ * layout 归属为 theme preset 的一个维度（一个 preset = 一个人格 = 色 + 局一体），
+ * 单入口 `setStyle` 切换。本结构纯数据可 JSON（除 `shell` 为运行时组件引用）。
+ *
+ * **灌值语义 = 基线复位 + 叠加**：bridge init 时快照六组布局 config 为基线；每次
+ * `setStyle` 先把六组 config 复位到基线、再叠加当前 preset 的 layout partial
+ * （`bridge.update` 单字段一级浅合并）。无跨 preset 残留、幂等。不带 layout 的老
+ * preset → 仅复位到 init 基线，零改动可用。
+ */
 export interface CoreThemePresetLayout {
+    /** header 配置 partial（如 `{height}`），叠加到基线 `APP_LAYOUT_HEADER_CONFIG` */
     header?: Partial<AppLayoutHeaderConfig>;
+    /** footer 配置 partial（如 `{height}`） */
     footer?: Partial<AppLayoutFooterConfig>;
+    /** sidebar 配置 partial（如 `{width, collapseWidth}`） */
     sidebar?: Partial<AppLayoutSidebarConfig>;
+    /** aside 右侧补充区配置 partial（如 `{width}`；P1' additive，带布局变更 preset 可配） */
     aside?: Partial<AppLayoutAsideConfig>;
+    /** breadcrumb 配置 partial（如 `{height}`） */
     breadcrumb?: Partial<AppLayoutBreadcrumbConfig>;
+    /** body 配置 partial（如 `{shimPadding}`） */
     body?: Partial<AppLayoutBodyConfig>;
+    /** viewport 边框配置 partial（四边 padding；套框 / 拆框） */
     viewport?: Partial<AppLayoutViewportConfig>;
+    /** 模块间距配置 partial（内缝 gap；分离式人格设 `{ size }` 让模块间露底色条带） */
     gap?: Partial<AppLayoutGapConfig>;
+    /**
+     * 编排组件（布局形态）。缺省 → AppLayout 回退内置默认 AppShell（经典布局）。
+     * 运行时引用（不持久化）；setStyle 切走 / 老 preset 无 shell → 回退内置。
+     * [MUST] markRaw（theme hook add 时自动 markRaw 兜底，防 reactive proxy 化）。
+     */
     shell?: Component;
+    /**
+     * 数据分流意图（AppLayout 读取执行）：提取 1 级路由模块到 header。
+     * 缺省 / undefined → 复位到 init 默认（false）。
+     */
     extractLevel1ToHeader?: boolean;
 }
+/**
+ * 配置化通用描述（**跨配置块对齐标准**：theme preset / form / table / panel 等配置项复用）。
+ *
+ * 一个描述对象，含正反两面——供人 + web agent 选型：
+ * - `suitable`（正向）：什么场景**宜选**。
+ * - `unsuitable`（反向）：什么场景**不宜选**——对 agent，知道何时不该选与该选同等重要。
+ *
+ * 定位：高配置化体系 ≈ 运行期 schema（类 zod），本描述是 agent 选型 + 排除入口；结构化
+ * traits（如 `layout.extractLevel1ToHeader`）机器可读、本符补散文语义。两面均可选。
+ * 注：展示名 `label` 是 entry 各自的独立字段，不并入本描述对象。
+ */
 export interface CoreConfigDescription {
+    /** 正向：什么应用 / 场景宜选（如「沉浸式工作台、需上下文面板的应用」）。 */
     suitable?: string;
+    /** 反向：什么场景不宜选（agent 排除用，如「表单密集型后台、窄屏移动端」）。 */
     unsuitable?: string;
 }
+/**
+ * 主题生命周期钩子上下文（core 注入，仅一个纯值 `id`）。
+ *
+ * 只携带 `id`（本钩子针对哪套主题）——供「被多个 preset 复用的同一钩子函数」区分自己
+ * 正服务于哪套主题（如打 `<style data-dc-theme="<id>">` 标签）。
+ *
+ * [MUST NOT] 挂 `document` / DOM 引用（钩子要操作 DOM 直接用全局 `document`，代传 element
+ * 易致内存泄漏）。**亦不传 `isDark`**：主题的 `<style>` [SHOULD] 一次注入含 `:root{}`(亮)
+ * + `:root.dark{}`(暗) 双态、明暗由 `<html>.dark` 类名切换自适配（同 core `useCoreThemeApply`
+ * 范式）——无需按明暗"细化按需加载"，`setMode` 也因此不触发钩子（传 isDark 反诱导单态注入 →
+ * 切明暗即坏，与"setMode 不触发"自相矛盾）。
+ */
 export interface CoreThemeLifecycleContext {
+    /** 本钩子针对的主题 id（风格 name）。 */
     id: string;
 }
+/**
+ * 主题生命周期钩子（挂 {@link CoreThemeEntry}；plugin `CoreThemePreset` 超集透传）。
+ *
+ * core 在 `setStyle` 切换时 **try-catch** 调用，让每套主题自管 DOM 副作用——典型：
+ * 激活时往 `document.head` 注入本主题专属 `<style data-dc-theme="<id>">`、切走前移除，
+ * 既支持复杂样式（@keyframes / 伪元素 / media）又守资产隔离（只当前主题 style 在 head）。
+ *
+ * 触发规则：仅 `setStyle`（风格切换）触发，`setMode`（明暗切换）**不触发**——主题注入的
+ * style [SHOULD] 含 `:root.dark` 双态由 `.dark` 自适配。钩子抛错仅 warn 吞掉，[MUST NOT]
+ * 阻断切换、[MUST NOT] 殃及他主题（守资产隔离）。
+ */
 export interface CoreThemeLifecycleHooks {
+    /**
+     * 主题**激活后**调用（config / layout 已应用、`themeStyle` 已置新值）。
+     * 典型：往全局 `document.head` 注入本主题专属 `<style data-dc-theme="<id>">`。
+     */
     onActivate?: (ctx: CoreThemeLifecycleContext) => void;
+    /**
+     * 主题**切走前**调用（即将切到别的风格 / 移除当前主题时回退 default 之前）。
+     * 典型：移除 onActivate 注入的 `<style data-dc-theme="<id>">`，归还干净 head。
+     *
+     * 钩子 [SHOULD] **幂等**：移除前先检测目标 `<style>` 是否仍在（`querySelector` 命中再
+     * removeChild），多次 / 重复清理才稳。core 侧已只在「切走 / 移除**当前**主题」时触发一次
+     * （非当前主题移除不重复触发），但作者自身幂等是更稳的兜底。
+     */
     onDeactivate?: (ctx: CoreThemeLifecycleContext) => void;
 }
+/**
+ * 主题注册项（`bridge.theme.add` 第 2 参）——core 侧主题「preset」结构。
+ *
+ * core 不依赖 plugin，故自定义此最小注册形；plugin-theme 的 `CoreThemePreset`
+ * （含 id/label/description/config）是其结构超集，可整坨直接透传：
+ * `bridge.theme.add(preset.id, preset)`（多出的 id 作 excess 字段被忽略，label/description 纳入）。
+ *
+ * 继承 {@link CoreThemeLifecycleHooks}：可选 `onActivate` / `onDeactivate` 生命周期钩子。
+ */
 export interface CoreThemeEntry extends CoreThemeLifecycleHooks {
+    /**
+     * 风格色值（light/dark 两套 `AppThemeColor`）。
+     *
+     * 内部做浅快照（`{light:{...},dark:{...}}`）——与调用方对象解耦，且与 bridge
+     * 响应式 APP_THEME_CONFIG 的 proxy target 解耦（避免切走后反写注册值）。
+     */
     config: AppThemeConfig;
+    /** 展示名（供 `AppTheme.vue` 下拉显示，如中文「柔光悬浮」）；缺省回退注册 name 自身。 */
     label?: string;
+    /**
+     * 描述（自然语言，供人 / web agent 理解选型）：分「适合 / 不适合」两面。
+     *
+     * 定位：高配置化体系 ≈ 运行期 schema（类 zod），`description` 是 agent「选型 + 排除」
+     * 的语义入口；结构化 traits（`layout.extractLevel1ToHeader` 等）机器可读、本字段补散文语义。
+     * 缺省 undefined。见 {@link CoreConfigDescription}。
+     */
     description?: CoreConfigDescription;
+    /**
+     * 布局维度（焊缝契约 ④）；缺省 → 切到该 preset 仅复位布局基线（不套框、内置 shell、经典分流）。
+     * 见 {@link CoreThemePresetLayout}。
+     */
     layout?: CoreThemePresetLayout;
+    /**
+     * 密度档（节奏维度）；缺省 → 切到该 preset 复位为 `'cozy'`。
+     * 见 {@link CoreThemeDensity}。setStyle 时复位 + 应用（同 layout「基线复位 + 叠加」语义）。
+     */
     density?: CoreThemeDensity;
+    /**
+     * 动效档（节奏维度）；缺省 → 切到该 preset 复位为 `'standard'`。
+     * 见 {@link CoreThemeMotion}。
+     */
     motion?: CoreThemeMotion;
+    /**
+     * 逐族 EP size 覆盖（**期二消费**，本期仅冻结数据形为焊缝）；缺省不覆盖、走 density 档默认。
+     * 仅声明式 size/border/stripe，[MUST NOT] 收行为（design §9 表现 vs 行为边界）。
+     * 见 {@link CoreThemeComponentDefaults}。
+     */
     componentDefaults?: CoreThemeComponentDefaults;
 }
+/**
+ * element-plus 组件尺寸档（透传给一等公民 size prop）。
+ */
 export type ElSize = "large" | "default" | "small";
+/**
+ * 密度档（persona 节奏维度）：紧凑 / 适中 / 舒展。
+ * 整体平移全局留白 + 控件高 + 字号（取值见 design §2.1）。明暗无关。
+ */
 export type CoreThemeDensity = "compact" | "cozy" | "comfortable";
+/**
+ * 动效档（persona 节奏维度）：急促 / 标准 / 舒缓。
+ * 整体换挡全局过渡时长 + 缓动（取值见 design §2.2）。reduced-motion 无条件压过。
+ */
 export type CoreThemeMotion = "snappy" | "standard" | "calm";
+/**
+ * 逐族 EP size 覆盖（componentDefaults，**期二真例外补丁**；本期仅冻结类型为焊缝）。
+ *
+ * 仅声明式 size 枚举 + table 的 border/stripe，[MUST NOT] 收任何行为 / handler /
+ * validator / 数据流（design §9 表现 vs 行为边界判据：persona 永不拥有行为）。
+ */
 export interface CoreThemeComponentDefaults {
+    /** 表格族默认（size / 是否边框 / 是否斑马纹） */
     table?: {
         size?: ElSize;
         border?: boolean;
         stripe?: boolean;
     };
+    /** 表单族默认（size；labelPosition 任务驱动、[MUST NOT] 入此） */
     form?: {
         size?: ElSize;
     };
+    /** 弹窗族默认（size 档→ width 由组件内映射） */
     modal?: {
         size?: ElSize;
     };
+    /** 操作按钮族默认（size） */
     actionBtn?: {
         size?: ElSize;
     };
 }
+/**
+ * 主题明暗模式三态：亮 / 暗 / 跟随系统。
+ * - `light` / `dark`：固定明暗。
+ * - `system`：跟随 `prefers-color-scheme`（系统切换实时响应）。
+ * 派生 `themeIsDark` = `mode==='system' ? 系统偏暗 : mode==='dark'`。
+ */
 export type CoreThemeMode = "light" | "dark" | "system";
+/** 主题模块对外能力。 */
 export interface CoreThemeModule {
+    /**
+     * 注册/覆盖一个风格（插件 install 经 `bridge.theme.add` 调；同名覆盖）。
+     *
+     * 第 2 参收 {@link CoreThemeEntry}（`{config,label?}`）；config 内部浅快照解耦。
+     * 若新注册 name 命中持久化恢复的目标风格（init 时尚未注册），自动 `setStyle(name)`。
+     */
     add: (name: string, preset: CoreThemeEntry) => void;
+    /** 注销一个风格（`'default'` 不可注销；注销当前风格则回退 `'default'`）。 */
     remove: (name: string) => void;
+    /** 切换风格（未注册回退 `'default'`）：同步 APP_THEME_CONFIG ＋ 持久化。 */
     setStyle: (name: string) => void;
+    /**
+     * 切换明暗模式三态（亮/暗/跟随系统）＋ 持久化。`system` 态下 `themeIsDark` 跟随系统偏好。
+     */
     setMode: (mode: CoreThemeMode) => void;
+    /**
+     * 切换暗色（向后兼容二态 API）：`true`→`setMode('dark')`、`false`→`setMode('light')`。
+     * 新代码 [SHOULD] 用 {@link CoreThemeModule.setMode}（支持 `system` 第三态）。
+     */
     setDark: (isDark: boolean) => void;
+    /**
+     * 直接设密度档（独立于风格切换；供 UI 偏好 / demo 切换器）。
+     * 注：`setStyle` 会按目标 preset 的 density 复位，故风格切换后手设的密度会被覆盖（同 layout 语义）。
+     */
     setDensity: (density: CoreThemeDensity) => void;
+    /** 直接设动效档（独立于风格切换；语义同 {@link setDensity}）。 */
     setMotion: (motion: CoreThemeMotion) => void;
+    /** 响应式风格名列表（只读，供 `AppTheme.vue` 下拉；`length>1` 才显示选择）。 */
     list: DeepReadonly<Ref<string[]>>;
+    /** 取风格展示名（`add` 注册的 label；缺省回退 name 自身）。 */
     labelOf: (name: string) => string;
+    /** 取风格描述（`add` 注册的 description，含 suitable/unsuitable 两面；未设回退 undefined）。 */
     descriptionOf: (name: string) => CoreConfigDescription | undefined;
 }
+/**
+ * 当前生效 preset 的 layout 运行时维度（AppLayout 直读，响应式）。
+ *
+ * 尺寸 / 套框等纯数据维度经 setStyle 灌进 bridge 响应式 config（基线复位 + 叠加），
+ * 故不在本结构重复——本结构仅暴露**非 config 的运行时维度**：编排组件 + 分流意图。
+ */
 export interface BridgeThemeLayoutState {
+    /**
+     * 当前 preset 的编排组件（缺省 undefined → AppLayout 回退内置默认 AppShell）。
+     * markRaw 后存储（防 proxy 化）。
+     */
     shell?: Component;
+    /** 当前 preset 的分流意图（提取 1 级路由到 header）；缺省复位 false。 */
     extractLevel1ToHeader: boolean;
 }
+/** 主题 hook 对外契约：模块 ＋ 顶层响应式只读真相源。 */
 export interface BridgeThemeHook {
+    /** 主题模块（add/remove/setStyle/setDark/list） */
     theme: CoreThemeModule;
+    /** 当前风格名（响应式只读；切换真相源，appStore / AppTheme.vue 读此） */
     themeStyle: DeepReadonly<Ref<string>>;
+    /**
+     * 明暗模式三态真相源（响应式只读；亮/暗/跟随系统）。`themeIsDark` 由本 mode + 系统偏好派生。
+     */
     themeMode: DeepReadonly<Ref<CoreThemeMode>>;
+    /** 是否暗色（响应式只读 **派生**；= mode==='system'?系统偏暗:mode==='dark'。挂值 composable toggle .dark 读此） */
     themeIsDark: DeepReadonly<Ref<boolean>>;
+    /**
+     * 当前 preset 的 layout 运行时维度（响应式只读；AppLayout 直读 shell + 分流意图）。
+     * 尺寸 / 套框纯数据维度经 setStyle 灌 bridge config，不在此重复。
+     */
     themeLayout: DeepReadonly<Ref<BridgeThemeLayoutState>>;
+    /**
+     * 当前密度档（响应式只读真相源）；`useCoreThemeApply` watch 此重写节奏 `<style>`。
+     * setStyle 按 preset.density 复位（缺省 `'cozy'`），或 `setDensity` 直接改。
+     */
     themeDensity: DeepReadonly<Ref<CoreThemeDensity>>;
+    /** 当前动效档（响应式只读真相源）；语义同 {@link themeDensity}（缺省 `'standard'`）。 */
     themeMotion: DeepReadonly<Ref<CoreThemeMotion>>;
 }
+/**
+ * 六组布局 config 的 init 基线快照（`setStyle` 复位 + 叠加用）。
+ *
+ * = bridge init 传入的六组布局 config 浅快照（不含 theme）。setStyle 切到任一 preset
+ * 前先把六组 config 复位到本基线、再叠加 preset.layout partial（幂等、无残留）。
+ */
 export interface BridgeThemeLayoutBaseline {
+    /** header 配置基线 */
     header: AppLayoutHeaderConfig;
+    /** footer 配置基线 */
     footer: AppLayoutFooterConfig;
+    /** sidebar 配置基线 */
     sidebar: AppLayoutSidebarConfig;
+    /** aside 右侧补充区配置基线（P1' additive） */
     aside: AppLayoutAsideConfig;
+    /** breadcrumb 配置基线 */
     breadcrumb: AppLayoutBreadcrumbConfig;
+    /** body 配置基线 */
     body: AppLayoutBodyConfig;
+    /** viewport 边框配置基线（已合并核内默认四边 0） */
     viewport: AppLayoutViewportConfig;
+    /** 模块间距配置基线（内缝 gap；已合并核内默认 size 0） */
     gap: AppLayoutGapConfig;
 }
+/** `createBridgeThemeHook` 入参。 */
 export interface BridgeThemeInit {
+    /** init 默认风格 config（= bridge init 传入的 APP_THEME_CONFIG）；core 自动 add 为 `'default'` */
     initConfig: AppThemeConfig;
+    /**
+     * 注入的 config 更新器（= configHook.update 全量 key）。
+     *
+     * setStyle 经此把当前风格 config 灌进 APP_THEME_CONFIG（整体替换 light/dark），
+     * 并把六组布局 config 基线复位 + 叠加 preset.layout partial。复用既有 update
+     * 通道，[MUST NOT] 另持一份主题 / 布局响应式。
+     */
     update: <K extends UpdatableConfigKey>(key: K, partial: Partial<UpdatableConfigMap[K]>) => void;
+    /**
+     * 六组布局 config init 基线（setStyle 复位 + 叠加用）。
+     * 缺省（向后兼容 / 测试）→ 不做布局复位，setStyle 仅切色 + 应用 preset.layout partial。
+     */
     layoutBaseline?: BridgeThemeLayoutBaseline;
+    /** 注入的命名空间 storage（= bridge.getStorage()）；持久化 `{themeStyle,themeIsDark}` */
     storage: StorageLike;
+    /** 持久化 key（命名空间已由 storage 加前缀）；缺省 `"dc-core-theme"` */
     storageKey?: string;
+    /**
+     * 明暗模式默认值（**仅无缓存时生效**）；缺省 `"light"`。
+     *
+     * 读持久化命中 `themeMode` → 缓存优先覆盖本值（缓存语义不变）；无缓存才回落到此。
+     * 业务侧经 `createCoreBridge({ defaultThemeMode })` 注入，如设 `"dark"` =
+     * 「首次进入（无缓存）默认暗色」、`"system"` =「默认跟随系统」。
+     */
     defaultMode?: CoreThemeMode;
 }

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

@@ -1,4 +1,5 @@
 type __VLS_Props = {
+    /** 显隐（= showAside，路由 meta.layout.aside 基线）；false 不渲染 */
     show: boolean;
 };
 declare function __VLS_template(): {

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

@@ -1,6 +1,9 @@
 type __VLS_Props = {
+    /** 悬挂哪侧：sidebar=悬父右外缘、aside=悬父左外缘 */
     side: "sidebar" | "aside";
+    /** 当前是否折叠（驱动箭头朝向 + tooltip 文案） */
     collapse: boolean;
+    /** 显隐（父传，= showSidebar / showAside）；false 不渲染 */
     show: boolean;
 };
 declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {

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

@@ -1,8 +1,11 @@
 import { RouteMetaResolveRaw } from '../../types';
 type __VLS_Props = {
+    /** 整体不用管 AppLayout控制 用在定位出去的子元素的显隐 */
     show: boolean;
     menus: RouteMetaResolveRaw[];
+    /** 聚焦的路由菜单 */
     activeMenu?: RouteMetaResolveRaw;
+    /** 聚焦的模块菜单 */
     activeModuleMenu?: RouteMetaResolveRaw;
     menuFlatList: RouteMetaResolveRaw[];
 };

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

@@ -1,10 +1,22 @@
 import { AppShellContentAnchor, AppLayoutAppStoreSlice, AppLayoutUserStoreSlice, AppLayoutBridgeSlice } from './types';
 import { WatermarkProps } from 'element-plus';
 type __VLS_Props = {
+    /**
+     * bridge 实例（#7.6 期新增必填）。
+     * AppLayout 经 `props.bridge` 注入后 provide 给子 layout 组件
+     * （AppBody / AppSidebar 自取 12 readonly 配置 + getRoutes / generateRouteMetaRawTree）。
+     * 业务侧 App.vue 模板：`<AppLayout :bridge="appBridge" ...>`。
+     */
     bridge: AppLayoutBridgeSlice;
     appStore: AppLayoutAppStoreSlice;
     userStore: AppLayoutUserStoreSlice;
+    /** 水印内容（空数组/空串/undefined 不展示 = 关闭水印）；layout 不耦合 UserInfo shape，由业务侧派生 */
     watermarkContent?: WatermarkProps["content"];
+    /**
+     * sidebar 层级是否高于 header（#7.5 期新增，默认 false）。
+     * true 时 AppSidebar z-index 调高于 AppHeader——适合 sidebar 顶部悬挂内容
+     * 需要覆盖 header 区域的场景（如悬浮 logo/搜索框）。
+     */
     sidebarAboveHeader?: boolean;
 };
 declare function __VLS_template(): {

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

@@ -1,16 +1,33 @@
 type __VLS_Props = {
+    /** 充满视口 */
     fullViewport?: boolean;
     fullMode?: "min-height" | "height";
+    /** 下个viewport高度 */
     nextViewportMaxHeight?: string;
     background?: string;
+    /** 四向悬浮插槽与内容主体 / 插槽间的间隔（px），默认 8 */
     gap?: number;
+    /** top 插槽 shim 容器背景 */
     topBg?: string;
+    /** bottom 插槽 shim 容器背景 */
     bottomBg?: string;
+    /** left 插槽 shim 容器背景 */
     leftBg?: string;
+    /** right 插槽 shim 容器背景 */
     rightBg?: string;
+    /**
+     * 各向插槽尺寸量测是否启用 ResizeObserver（逐槽透传对应 WatchSize 的
+     * observeResize，均默认 false）。默认时机（激活首测 + window resize + onUpdated）
+     * 已覆盖重渲染驱动的槽尺寸变化；某槽内容有 **CSS 过渡折叠 / 异步撑开 / 后代自更新**
+     * 等不触发重渲染的尺寸变化（如右槽宽度过渡动画收起，inset 需实时回流）时按槽显式开启。
+     */
+    /** top 插槽 RO 观测开关 */
     topObserveResize?: boolean;
+    /** bottom 插槽 RO 观测开关 */
     bottomObserveResize?: boolean;
+    /** left 插槽 RO 观测开关 */
     leftObserveResize?: boolean;
+    /** right 插槽 RO 观测开关 */
     rightObserveResize?: boolean;
 };
 declare function __VLS_template(): {