@done-coding/admin-core 0.12.1 → 0.12.2-alpha.0

package/types/bridge/layout.d.ts

@@ -0,0 +1,25 @@
+import { Ref, DeepReadonly } from 'vue';
+import { StorageLike } from './index';
+export declare const DEFAULT_LAYOUT_STORAGE_KEY = "dc-core-layout";
+export interface LayoutCollapsePersistShape {
+    sidebarCollapsed: boolean;
+    asideCollapsed: boolean;
+}
+export interface BridgeLayoutInit {
+    storage: StorageLike;
+    storageKey?: string;
+    defaultSidebarCollapsed?: boolean;
+    defaultAsideCollapsed?: boolean;
+}
+export interface CoreLayoutModule {
+    readonly sidebarCollapsed: DeepReadonly<Ref<boolean>>;
+    readonly asideCollapsed: DeepReadonly<Ref<boolean>>;
+    setSidebarCollapse: (collapsed: boolean) => void;
+    toggleSidebar: () => void;
+    setAsideCollapse: (collapsed: boolean) => void;
+    toggleAside: () => void;
+}
+export interface BridgeLayoutHook {
+    layout: CoreLayoutModule;
+}
+export declare function createBridgeLayoutHook(init: BridgeLayoutInit): BridgeLayoutHook;

package/types/bridge/plugin.d.ts

@@ -1,39 +1,21 @@
-import { AdminBridge } from './index';
+import { CoreBridge } 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 的便捷引用 */
+export type CoreBridgePluginBridgeSlice<UserInfo = unknown, LoginParams = unknown> = Omit<CoreBridge<UserInfo, LoginParams>, "init" | "register" | "getToken" | "goToLogin" | "refreshToken" | "refreshAuth" | "loginApi" | "logoutApi" | "getUserInfoApi" | "refreshTokenApi" | "use" | "install">;
+export interface CoreBridgePluginContext<UserInfo = unknown, LoginParams = unknown> {
+    bridge: CoreBridgePluginBridgeSlice<UserInfo, LoginParams>;
     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> {
-    /** 插件名；存在时用于跨对象实例的幂等安装 */
+export type CoreBridgePluginInstall<UserInfo = unknown, LoginParams = unknown, Options = unknown> = (ctx: CoreBridgePluginContext<UserInfo, LoginParams>, options?: Options) => void;
+export interface CoreBridgePlugin<UserInfo = unknown, LoginParams = unknown, Options = unknown> {
     name?: string;
-    /** 插件安装函数 */
-    install: AdminBridgePluginInstall<UserInfo, LoginParams, Options>;
+    install: CoreBridgePluginInstall<UserInfo, LoginParams, Options>;
 }
-/** admin bridge 支持函数插件与对象插件两种形态。 */
-export type AdminBridgePluginLike<UserInfo = unknown, LoginParams = unknown, Options = unknown> = AdminBridgePlugin<UserInfo, LoginParams, Options> | AdminBridgePluginInstall<UserInfo, LoginParams, Options>;
-/** 创建单个 bridge 实例专属的插件安装宿主。 */
+export type CoreBridgePluginLike<UserInfo = unknown, LoginParams = unknown, Options = unknown> = CoreBridgePlugin<UserInfo, LoginParams, Options> | CoreBridgePluginInstall<UserInfo, LoginParams, Options>;
 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>;
+        bridge: CoreBridge<UserInfo, LoginParams>;
+        update: CoreBridgePluginContext<UserInfo, LoginParams>["update"];
+        plugin: CoreBridgePluginLike<UserInfo, LoginParams, Options>;
         options?: Options;
-    }) => AdminBridge<UserInfo, LoginParams>;
+    }) => CoreBridge<UserInfo, LoginParams>;
 };

package/types/bridge/route.d.ts

@@ -1,36 +1,17 @@
 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,23 +1,9 @@
 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,10 +1 @@
-/**
- * 创建带命名空间的 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,10 +1,3 @@
 import { BridgeThemeHook, BridgeThemeInit } from './types';
-/**
- * bridge 主题 hook 工厂。
- *
- * 每次 `createAdminBridge` 调用各自闭包内构造一份（零模块级单例，守实例隔离）。
- * init：自动 `add('default', initConfig)`；读持久化恢复 `themeMode` 即时生效、
- * `themeStyle` 走「desiredStyle 命中再 apply」时序（插件后注册风格亦能恢复）。
- */
 export declare function createBridgeThemeHook(init: BridgeThemeInit): BridgeThemeHook;
-export type { AdminThemePresetLayout, AdminConfigDescription, AdminThemeLifecycleContext, AdminThemeLifecycleHooks, AdminThemeEntry, AdminThemeMode, AdminThemeModule, AdminThemeDensity, AdminThemeMotion, ElSize, AdminThemeComponentDefaults, BridgeThemeLayoutState, BridgeThemeHook, BridgeThemeLayoutBaseline, BridgeThemeInit, } from './types';
+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,23 +1,11 @@
 import { StorageLike } from '../index';
-import { AdminThemeMode } from './types';
-/**
- * bridge 主题模块**持久化**子模块（升级目录拆出）。
- *
- * 负责 localStorage 形态的读取 / 兼容迁移：v2 存 `{themeStyle,themeMode}`，读时兼容
- * 旧 v1 `themeIsDark` 布尔。写入（`persist()`）在工厂内闭包，复用本文件的 shape 类型。
- */
-/** core 主题持久化的命名空间 key（命名空间前缀已由 storage 加）；缺省值。 */
-export declare const DEFAULT_STORAGE_KEY = "admin-core-theme";
-/** 持久化载荷（v2：明暗存 mode 三态，取代旧 themeIsDark 布尔）。 */
+import { CoreThemeMode } from './types';
+export declare const DEFAULT_STORAGE_KEY = "dc-core-theme";
 export interface ThemePersistShape {
-    /** 当前风格名 */
     themeStyle: string;
-    /** 明暗模式三态（亮/暗/跟随系统） */
-    themeMode: AdminThemeMode;
+    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,14 +1,2 @@
-/**
- * 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,336 +1,98 @@
 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 AdminThemePresetLayout {
-    /** header 配置 partial（如 `{height}`），叠加到基线 `APP_LAYOUT_HEADER_CONFIG` */
+export interface CoreThemePresetLayout {
     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 AdminConfigDescription {
-    /** 正向：什么应用 / 场景宜选（如「沉浸式工作台、需上下文面板的应用」）。 */
+export interface CoreConfigDescription {
     suitable?: string;
-    /** 反向：什么场景不宜选（agent 排除用，如「表单密集型后台、窄屏移动端」）。 */
     unsuitable?: string;
 }
-/**
- * 主题生命周期钩子上下文（core 注入，仅一个纯值 `id`）。
- *
- * 只携带 `id`（本钩子针对哪套主题）——供「被多个 preset 复用的同一钩子函数」区分自己
- * 正服务于哪套主题（如打 `<style data-admin-theme="<id>">` 标签）。
- *
- * [MUST NOT] 挂 `document` / DOM 引用（钩子要操作 DOM 直接用全局 `document`，代传 element
- * 易致内存泄漏）。**亦不传 `isDark`**：主题的 `<style>` [SHOULD] 一次注入含 `:root{}`(亮)
- * + `:root.dark{}`(暗) 双态、明暗由 `<html>.dark` 类名切换自适配（同 core `useAdminThemeApply`
- * 范式）——无需按明暗"细化按需加载"，`setMode` 也因此不触发钩子（传 isDark 反诱导单态注入 →
- * 切明暗即坏，与"setMode 不触发"自相矛盾）。
- */
-export interface AdminThemeLifecycleContext {
-    /** 本钩子针对的主题 id（风格 name）。 */
+export interface CoreThemeLifecycleContext {
     id: string;
 }
-/**
- * 主题生命周期钩子（挂 {@link AdminThemeEntry}；plugin `AdminThemePreset` 超集透传）。
- *
- * core 在 `setStyle` 切换时 **try-catch** 调用，让每套主题自管 DOM 副作用——典型：
- * 激活时往 `document.head` 注入本主题专属 `<style data-admin-theme="<id>">`、切走前移除，
- * 既支持复杂样式（@keyframes / 伪元素 / media）又守资产隔离（只当前主题 style 在 head）。
- *
- * 触发规则：仅 `setStyle`（风格切换）触发，`setMode`（明暗切换）**不触发**——主题注入的
- * style [SHOULD] 含 `:root.dark` 双态由 `.dark` 自适配。钩子抛错仅 warn 吞掉，[MUST NOT]
- * 阻断切换、[MUST NOT] 殃及他主题（守资产隔离）。
- */
-export interface AdminThemeLifecycleHooks {
-    /**
-     * 主题**激活后**调用（config / layout 已应用、`themeStyle` 已置新值）。
-     * 典型：往全局 `document.head` 注入本主题专属 `<style data-admin-theme="<id>">`。
-     */
-    onActivate?: (ctx: AdminThemeLifecycleContext) => void;
-    /**
-     * 主题**切走前**调用（即将切到别的风格 / 移除当前主题时回退 default 之前）。
-     * 典型：移除 onActivate 注入的 `<style data-admin-theme="<id>">`，归还干净 head。
-     *
-     * 钩子 [SHOULD] **幂等**：移除前先检测目标 `<style>` 是否仍在（`querySelector` 命中再
-     * removeChild），多次 / 重复清理才稳。core 侧已只在「切走 / 移除**当前**主题」时触发一次
-     * （非当前主题移除不重复触发），但作者自身幂等是更稳的兜底。
-     */
-    onDeactivate?: (ctx: AdminThemeLifecycleContext) => void;
+export interface CoreThemeLifecycleHooks {
+    onActivate?: (ctx: CoreThemeLifecycleContext) => void;
+    onDeactivate?: (ctx: CoreThemeLifecycleContext) => void;
 }
-/**
- * 主题注册项（`bridge.theme.add` 第 2 参）——core 侧主题「preset」结构。
- *
- * core 不依赖 plugin，故自定义此最小注册形；plugin-theme 的 `AdminThemePreset`
- * （含 id/label/description/config）是其结构超集，可整坨直接透传：
- * `bridge.theme.add(preset.id, preset)`（多出的 id 作 excess 字段被忽略，label/description 纳入）。
- *
- * 继承 {@link AdminThemeLifecycleHooks}：可选 `onActivate` / `onDeactivate` 生命周期钩子。
- */
-export interface AdminThemeEntry extends AdminThemeLifecycleHooks {
-    /**
-     * 风格色值（light/dark 两套 `AppThemeColor`）。
-     *
-     * 内部做浅快照（`{light:{...},dark:{...}}`）——与调用方对象解耦，且与 bridge
-     * 响应式 APP_THEME_CONFIG 的 proxy target 解耦（避免切走后反写注册值）。
-     */
+export interface CoreThemeEntry extends CoreThemeLifecycleHooks {
     config: AppThemeConfig;
-    /** 展示名（供 `AppTheme.vue` 下拉显示，如中文「柔光悬浮」）；缺省回退注册 name 自身。 */
     label?: string;
-    /**
-     * 描述（自然语言，供人 / web agent 理解选型）：分「适合 / 不适合」两面。
-     *
-     * 定位：高配置化体系 ≈ 运行期 schema（类 zod），`description` 是 agent「选型 + 排除」
-     * 的语义入口；结构化 traits（`layout.extractLevel1ToHeader` 等）机器可读、本字段补散文语义。
-     * 缺省 undefined。见 {@link AdminConfigDescription}。
-     */
-    description?: AdminConfigDescription;
-    /**
-     * 布局维度（焊缝契约 ④）；缺省 → 切到该 preset 仅复位布局基线（不套框、内置 shell、经典分流）。
-     * 见 {@link AdminThemePresetLayout}。
-     */
-    layout?: AdminThemePresetLayout;
-    /**
-     * 密度档（节奏维度）；缺省 → 切到该 preset 复位为 `'cozy'`。
-     * 见 {@link AdminThemeDensity}。setStyle 时复位 + 应用（同 layout「基线复位 + 叠加」语义）。
-     */
-    density?: AdminThemeDensity;
-    /**
-     * 动效档（节奏维度）；缺省 → 切到该 preset 复位为 `'standard'`。
-     * 见 {@link AdminThemeMotion}。
-     */
-    motion?: AdminThemeMotion;
-    /**
-     * 逐族 EP size 覆盖（**期二消费**，本期仅冻结数据形为焊缝）；缺省不覆盖、走 density 档默认。
-     * 仅声明式 size/border/stripe，[MUST NOT] 收行为（design §9 表现 vs 行为边界）。
-     * 见 {@link AdminThemeComponentDefaults}。
-     */
-    componentDefaults?: AdminThemeComponentDefaults;
+    description?: CoreConfigDescription;
+    layout?: CoreThemePresetLayout;
+    density?: CoreThemeDensity;
+    motion?: CoreThemeMotion;
+    componentDefaults?: CoreThemeComponentDefaults;
 }
-/**
- * element-plus 组件尺寸档（透传给一等公民 size prop）。
- */
 export type ElSize = "large" | "default" | "small";
-/**
- * 密度档（persona 节奏维度）：紧凑 / 适中 / 舒展。
- * 整体平移全局留白 + 控件高 + 字号（取值见 design §2.1）。明暗无关。
- */
-export type AdminThemeDensity = "compact" | "cozy" | "comfortable";
-/**
- * 动效档（persona 节奏维度）：急促 / 标准 / 舒缓。
- * 整体换挡全局过渡时长 + 缓动（取值见 design §2.2）。reduced-motion 无条件压过。
- */
-export type AdminThemeMotion = "snappy" | "standard" | "calm";
-/**
- * 逐族 EP size 覆盖（componentDefaults，**期二真例外补丁**；本期仅冻结类型为焊缝）。
- *
- * 仅声明式 size 枚举 + table 的 border/stripe，[MUST NOT] 收任何行为 / handler /
- * validator / 数据流（design §9 表现 vs 行为边界判据：persona 永不拥有行为）。
- */
-export interface AdminThemeComponentDefaults {
-    /** 表格族默认（size / 是否边框 / 是否斑马纹） */
+export type CoreThemeDensity = "compact" | "cozy" | "comfortable";
+export type CoreThemeMotion = "snappy" | "standard" | "calm";
+export interface CoreThemeComponentDefaults {
     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 AdminThemeMode = "light" | "dark" | "system";
-/** 主题模块对外能力。 */
-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'`）。 */
+export type CoreThemeMode = "light" | "dark" | "system";
+export interface CoreThemeModule {
+    add: (name: string, preset: CoreThemeEntry) => void;
     remove: (name: string) => void;
-    /** 切换风格（未注册回退 `'default'`）：同步 APP_THEME_CONFIG ＋ 持久化。 */
     setStyle: (name: string) => void;
-    /**
-     * 切换明暗模式三态（亮/暗/跟随系统）＋ 持久化。`system` 态下 `themeIsDark` 跟随系统偏好。
-     */
-    setMode: (mode: AdminThemeMode) => void;
-    /**
-     * 切换暗色（向后兼容二态 API）：`true`→`setMode('dark')`、`false`→`setMode('light')`。
-     * 新代码 [SHOULD] 用 {@link AdminThemeModule.setMode}（支持 `system` 第三态）。
-     */
+    setMode: (mode: CoreThemeMode) => void;
     setDark: (isDark: boolean) => void;
-    /**
-     * 直接设密度档（独立于风格切换；供 UI 偏好 / demo 切换器）。
-     * 注：`setStyle` 会按目标 preset 的 density 复位，故风格切换后手设的密度会被覆盖（同 layout 语义）。
-     */
-    setDensity: (density: AdminThemeDensity) => void;
-    /** 直接设动效档（独立于风格切换；语义同 {@link setDensity}）。 */
-    setMotion: (motion: AdminThemeMotion) => void;
-    /** 响应式风格名列表（只读，供 `AppTheme.vue` 下拉；`length>1` 才显示选择）。 */
+    setDensity: (density: CoreThemeDensity) => void;
+    setMotion: (motion: CoreThemeMotion) => void;
     list: DeepReadonly<Ref<string[]>>;
-    /** 取风格展示名（`add` 注册的 label；缺省回退 name 自身）。 */
     labelOf: (name: string) => string;
-    /** 取风格描述（`add` 注册的 description，含 suitable/unsuitable 两面；未设回退 undefined）。 */
-    descriptionOf: (name: string) => AdminConfigDescription | 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: AdminThemeModule;
-    /** 当前风格名（响应式只读；切换真相源，appStore / AppTheme.vue 读此） */
+    theme: CoreThemeModule;
     themeStyle: DeepReadonly<Ref<string>>;
-    /**
-     * 明暗模式三态真相源（响应式只读；亮/暗/跟随系统）。`themeIsDark` 由本 mode + 系统偏好派生。
-     */
-    themeMode: DeepReadonly<Ref<AdminThemeMode>>;
-    /** 是否暗色（响应式只读 **派生**；= mode==='system'?系统偏暗:mode==='dark'。挂值 composable toggle .dark 读此） */
+    themeMode: DeepReadonly<Ref<CoreThemeMode>>;
     themeIsDark: DeepReadonly<Ref<boolean>>;
-    /**
-     * 当前 preset 的 layout 运行时维度（响应式只读；AppLayout 直读 shell + 分流意图）。
-     * 尺寸 / 套框纯数据维度经 setStyle 灌 bridge config，不在此重复。
-     */
     themeLayout: DeepReadonly<Ref<BridgeThemeLayoutState>>;
-    /**
-     * 当前密度档（响应式只读真相源）；`useAdminThemeApply` watch 此重写节奏 `<style>`。
-     * setStyle 按 preset.density 复位（缺省 `'cozy'`），或 `setDensity` 直接改。
-     */
-    themeDensity: DeepReadonly<Ref<AdminThemeDensity>>;
-    /** 当前动效档（响应式只读真相源）；语义同 {@link themeDensity}（缺省 `'standard'`）。 */
-    themeMotion: DeepReadonly<Ref<AdminThemeMotion>>;
+    themeDensity: DeepReadonly<Ref<CoreThemeDensity>>;
+    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 加前缀）；缺省 `"admin-core-theme"` */
     storageKey?: string;
-    /**
-     * 明暗模式默认值（**仅无缓存时生效**）；缺省 `"light"`。
-     *
-     * 读持久化命中 `themeMode` → 缓存优先覆盖本值（缓存语义不变）；无缓存才回落到此。
-     * 业务侧经 `createAdminBridge({ defaultThemeMode })` 注入，如设 `"dark"` =
-     * 「首次进入（无缓存）默认暗色」、`"system"` =「默认跟随系统」。
-     */
-    defaultMode?: AdminThemeMode;
+    defaultMode?: CoreThemeMode;
 }

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

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

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

@@ -0,0 +1,11 @@
+type __VLS_Props = {
+    side: "sidebar" | "aside";
+    collapse: boolean;
+    show: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    toggle: () => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onToggle?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

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

@@ -1,11 +1,8 @@
 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,22 +1,10 @@
 import { AppShellContentAnchor, AppLayoutAppStoreSlice, AppLayoutUserStoreSlice, AppLayoutBridgeSlice } from './types';
 import { WatermarkProps } from 'element-plus';
 type __VLS_Props = {
-    /**
-     * admin bridge 实例（#7.6 期新增必填）。
-     * AppLayout 经 `props.adminBridge` 注入后 provide 给子 layout 组件
-     * （AppBody / AppSidebar 自取 12 readonly 配置 + getRoutes / generateRouteMetaRawTree）。
-     * 业务侧 App.vue 模板：`<AppLayout :admin-bridge="appAdminBridge" ...>`。
-     */
     adminBridge: 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,8 +1,6 @@
 type __VLS_Props = {
-    /** 充满视口 */
     fullViewport?: boolean;
     fullMode?: "min-height" | "height";
-    /** 下个viewport高度 */
     nextViewportMaxHeight?: string;
     background?: string;
 };