@robot-admin/layout 2.3.2 → 3.1.0

package/CHANGELOG.md

@@ -0,0 +1,153 @@
+# Changelog
+
+## 3.1.0
+
+### Minor Changes
+
+- Add `createLayoutContext()` and `provideLayout()` to derive the complete reactive layout contract from a settings Store, menus, dark state, brand data, and an optional icon component.
+- Keep the advanced `LayoutContext` API intact while formally deprecating the legacy `C_*Layout` aliases for removal in 4.0.
+- Add browser interaction coverage for SettingsDrawer providers, atomic imports, reset rollback, host-owned cache clearing, and global visual-effect cleanup.
+- Correct integration prerequisites, host-owned setting semantics, migration guidance, architecture diagrams, and stale version references without changing existing layout visuals or interactions.
+
+## 3.0.0
+
+### Major Changes
+
+- Release the 3.0 architecture upgrade while preserving the existing Naive UI layouts, interactions, slots, and visual styling.
+
+  - Add a UI-independent `@robot-admin/layout/core` entrypoint for validated settings and shared contracts.
+  - Make layout/store injection and collapsed state work reliably with custom stores and multi-instance hosts.
+  - Replace destructive built-in storage clearing with explicit host actions and add stable SettingsDrawer extension slots.
+  - Validate complete imported configuration files before applying state and restore host-owned global classes on teardown.
+  - Respect the transition enable switch, harden route caching and responsive measurement, and improve built-in menu keyboard semantics.
+  - Verify all six layout modes in SSR and validate both ESM and CommonJS package entrypoints before publishing.
+
+## 2.3.2
+
+### Patch Changes
+
+- Validate imported settings at runtime, support short hex colors safely, and preserve invalid color input instead of silently turning it black.
+- Use route-segment-aware menu matching so `/users` no longer activates `/users-admin`.
+- Disable cache debug logging and global window helpers by default; add configurable Settings Store ids.
+- Standardize the automatic theme value on `system` and roll back settings if asynchronous theme synchronization fails.
+- Improve menu/drawer keyboard navigation, focus restoration and ARIA state; guard browser and Canvas APIs for SSR or unsupported environments.
+- Synchronize the exported version constant with package version 2.3.2 and add regression tests for the critical settings and routing contracts.
+
+## 2.2.0
+
+### 🐛 Bug 修复
+
+- **ReverseHorizontalMixLayout 右侧菜单错位**: 修复右侧菜单显示在底部而非右侧的问题（`.main-area` 添加 `flex-direction: row`）
+- **MixLayout 二级菜单消失**: 修复鼠标离开后二级菜单内容消失的问题（新增 `displayMenuItem` 作为 `hoveredMenuItem` 的 fallback）
+- **MixTopLayout 全局 CSS 泄漏**: 修复 `.main-area`、`.content-layout` 等选择器污染其他布局的问题（嵌套到 `.mix-top-layout-container` 内）
+
+### ✨ 功能优化
+
+- **ResponsiveMenu 字符宽度估算**: 区分 CJK 字符（15px）和 ASCII 字符（8px），顶部菜单文字完整显示不截断
+- **ReverseHorizontalMixLayout 折叠动画**: 用 width 过渡替代 Transition，避免黑色闪烁，动画更流畅（0.35s cubic-bezier）
+- **MixLayout 交互模式**: 从悬停触发改为纯点击模式，点击同一菜单切换展开/折叠，点击不同菜单切换内容不关闭
+
+### 🎨 视觉设计
+
+- **ReverseHorizontalMixLayout 玻璃质感**: 参考搜索组件样式，应用 indigo 渐变玻璃设计（`linear-gradient` + `backdrop-filter` + 顶部高光线）
+- **pure CSS 图标**: 替换所有 UnoCSS 图标（`i-ri:*`）为纯 CSS 实现（dots-icon、grid-icon、hamburger-icon、collapse-arrow），减少外部依赖
+
+### 📦 依赖
+
+- 移除对 UnoCSS 图标的依赖，提升包的独立性
+
+---
+
+## 2.1.0
+
+### Minor Changes
+
+- 重构目录结构 + 代码优化
+
+  - **目录重构**: 6 种布局骨架迁入 `components/layouts/` 子目录，层次更清晰
+  - **文件分离**: 每个布局的样式从 `<style>` 标签提取到独立的 `index.scss` 文件
+  - **注释统一**: 所有组件注释标准化为 `@robot-admin/layout - ComponentName` 格式
+  - **文档优化**: 重写 README，精简核心内容、添加目录树、API 参考更清晰
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.2] - 2026-02-11
+
+### 🗑️ Removed
+
+- **Dead files**: Removed unused `tsup.config.ts` (actual build uses Vite)
+- **Empty directories**: Removed `composables/`, `core/`, `layouts/` (8 empty directories total)
+- **Unused dependencies**: Removed `vue-router` from peerDependencies and devDependencies (never used in source code)
+
+### 🔧 Fixed
+
+- **package.json**:
+  - Refined `sideEffects` to `["*.css", "*.scss"]` for better tree-shaking
+  - Removed blocking patterns `"*.vue"` and `"src/index.ts"`
+- **Source code**:
+
+  - `constants/index.ts`: Removed commented-out code, fixed version from `"1.0.0"` to `"2.0.2"`
+  - `types/index.ts`: Removed unimplemented `storageKey` option from `SettingsStoreOptions`
+  - `stores/settings.ts`:
+    - Exported `adjustColor` utility function (was private)
+    - Removed redundant `|| false` in collapsed state initialization
+  - `data.ts`:
+    - Fixed `COLOR_SWATCHES` duplication (now imports from constants)
+    - Renamed `LAYOUT_MODES` to `LAYOUT_MODE_OPTIONS` to avoid naming conflict
+
+- **SettingsDrawer component**:
+
+  - Removed unimplemented `storageKey` prop
+  - Fixed hardcoded timezone `"XIAn"` → `Intl.DateTimeFormat().resolvedOptions().timeZone`
+  - Fixed `handleResetLayout` missing `fixedHeader` and `tagsViewStyle` resets
+  - Fixed `handleImportConfig` to use `$patch` instead of `Object.assign` for proper reactivity
+
+- **Styles (`settings.scss`)**:
+
+  - Replaced hardcoded `#409EFF` with `var(--primary-color, #409eff)` for theme color support
+  - Replaced hardcoded `rgba(32, 128, 240)` shadows with CSS variable fallbacks
+
+- **Build config**:
+  - Removed unused `globals` from `vite.config.ts` (no UMD output)
+
+### 📖 Documentation
+
+- **README.md**: Fixed multiple inconsistencies with actual code:
+  - `themeMode` default: `'system'` → `'light'`
+  - `transitionType` default: `'fade'` → `'slide'`
+  - `tagsViewHeight` default: `40` → `44`
+  - `showFooter` default: `false` → `true`
+  - Removed non-existent store properties: `enableWatermark`, `watermarkText`, `enableGrayMode`, `enableColorWeakMode`
+  - Removed non-existent methods: `exportSettings()`, `importSettings()`
+  - Removed unimplemented feature: "持久化存储"
+  - Removed all `storageKey` parameter references
+  - Added `adjustColor` utility function documentation
+  - Fixed `ThemeMode` type: `'system'` → `'auto'`
+
+### ✨ Enhanced
+
+- Exported `adjustColor` utility function for external use
+- Improved CSS variable support for theme customization
+
+---
+
+## [2.0.1] - 2026-02-09
+
+### ✨ Added
+
+- Initial v2.0 release with decoupled architecture
+- Complete settings management system
+- SettingsDrawer UI component
+- 6 layout mode presets
+- Theme customization with CSS variables
+- Full TypeScript support
+
+---
+
+## [2.0.0] - 2026-02-09
+
+### 🎉 Initial Release
+
+- Layout and settings management system
+- Integration with @robot-admin/theme
+- Naive UI components support

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CHENY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@robot-admin/layout.svg)](https://www.npmjs.com/package/@robot-admin/layout)
 [![license](https://img.shields.io/npm/l/@robot-admin/layout.svg)](https://github.com/ChenyCHENYU/robot-admin-packages/blob/main/LICENSE)
 
-当前版本：`2.3.2`。
+当前版本：`3.1.0`。
 
 ---
 
@@ -17,6 +17,7 @@
 - 🧩 **开箱即用** - 提供 SettingsDrawer 设置抽屉，覆盖外观 / 布局 / 功能配置
 - 🧭 **菜单展开方式** - 内置传统展开 / 右侧面板两种菜单展开模式配置
 - 🔌 **插槽系统** - 灵活的 slot 机制，主项目仅关注业务组件
+- 🪄 **精简适配** - `provideLayout()` 从最小宿主输入自动创建完整响应式上下文
 - 🎨 **CSS 变量同步** - 配置变更自动同步到 CSS 变量，样式实时响应
 - ♿ **键盘与焦点可访问性** - 抽屉/菜单支持 Escape、方向键、焦点恢复与语义属性
 - 🛡️ **安全设置导入** - 对枚举、布尔值、数值范围与主题色进行运行时校验
@@ -35,7 +36,7 @@
                │ LayoutContext (provide/inject)
                ▼
 ┌──────────────────────────────────────┐
-│  @robot-admin/layout                  │
+│  @robot-admin/layout（Vue + Naive UI）│
 │  ├─ C_LayoutContainer (智能容器)      │
 │  │   └─ 根据 layoutMode 自动调度      │
 │  ├─ layouts/ (6 种布局骨架)           │
@@ -47,6 +48,12 @@
 │  │   └─ CardLayout                    │
 │  └─ SettingsDrawer (设置 UI)          │
 └──────────────────────────────────────┘
+
+┌──────────────────────────────────────┐
+│  @robot-admin/layout/core             │
+│  设置协议、运行时校验、常量和纯函数    │
+│  不依赖 Vue / Pinia / UI 框架          │
+└──────────────────────────────────────┘
 ```
 
 ---
@@ -57,6 +64,10 @@
 src/
 ├── index.ts                           # 主入口（统一导出）
 ├── setup.ts                           # 一键初始化 setupLayout()
+├── core/                              # 无框架设置协议、校验与纯函数
+│   ├── index.ts
+│   ├── settings.ts
+│   └── types.ts
 ├── components/
 │   ├── C_LayoutContainer/             # 智能布局容器（主入口组件）
 │   │   └── index.vue
@@ -91,6 +102,7 @@ src/
 │   └── MenuTrigger/                   # 菜单触发区域
 ├── composables/
 │   ├── useLayoutContext.ts            # LayoutContext provide/inject
+│   ├── createLayoutContext.ts         # 最小宿主输入适配助手
 │   ├── useLayoutCache.ts              # 页面缓存管理
 │   └── useMenuSplit.ts                # 菜单拆分（一级/二级分离）
 ├── stores/
@@ -110,10 +122,13 @@ src/
 ## 📦 安装
 
 ```bash
-bun add @robot-admin/layout @robot-admin/theme naive-ui
+bun add @robot-admin/layout naive-ui
 ```
 
-**Peer Dependencies**: `vue ^3.4` · `vue-router ^4.0` · `pinia ^2.0 || ^3.0` · `naive-ui ^2.38` · `@robot-admin/theme ^0.3 || ^0.4`
+**Peer Dependencies**: `vue ^3.4` · `vue-router ^4.0` · `pinia ^2.0 || ^3.0` · `naive-ui ^2.38`
+
+> 3.0 仍完整保留现有 Naive UI 组件、交互和样式。状态校验等无 UI 能力可从
+> `@robot-admin/layout/core` 独立导入，为后续适配其他 UI 框架预留稳定边界；当前版本不包含 Element Plus 视图适配器。
 
 ---
 
@@ -126,18 +141,15 @@ bun add @robot-admin/layout @robot-admin/theme naive-ui
 import { createApp } from "vue";
 import { createPinia } from "pinia";
 import { setupLayout } from "@robot-admin/layout";
-import { useThemeStore } from "@robot-admin/theme";
-import "@robot-admin/layout/style";  // 导入样式
+import "@robot-admin/layout/style"; // 导入样式
 import App from "./App.vue";
 
 const app = createApp(App);
 app.use(createPinia());
 
-const themeStore = useThemeStore();
-themeStore.init();
-
 setupLayout(app, {
-  onThemeModeChange: (mode) => themeStore.setMode(mode),
+  // 可选：同步到宿主自己的主题系统
+  onThemeModeChange: (mode) => syncAppTheme(mode),
   defaults: {
     layoutMode: "side",
     primaryColor: "#409eff",
@@ -147,14 +159,15 @@ setupLayout(app, {
 app.mount("#app");
 ```
 
-### 2. 使用布局容器
+### 2. 提供宿主数据并使用布局容器
 
 ```vue
-<!-- src/components/C_Layout/index.vue -->
 <template>
   <C_LayoutContainer>
     <template #logo><AppLogo /></template>
-    <template #menu="{ collapsed }"><AppMenu :collapsed="collapsed" /></template>
+    <template #menu="{ collapsed }"
+      ><AppMenu :collapsed="collapsed"
+    /></template>
     <template #header><AppHeader /></template>
     <template #tags-view><AppTags /></template>
     <template #footer><AppFooter /></template>
@@ -162,51 +175,91 @@ app.mount("#app");
 </template>
 
 <script setup lang="ts">
-import { C_LayoutContainer } from "@robot-admin/layout";
+import {
+  C_LayoutContainer,
+  provideLayout,
+  useSettingsStore,
+  type MenuOptions,
+} from "@robot-admin/layout";
+
+const props = defineProps<{
+  menus: MenuOptions[];
+  isDark: boolean;
+}>();
+
+provideLayout({
+  settings: useSettingsStore(),
+  menus: () => props.menus,
+  isDark: () => props.isDark,
+  brand: { name: "My Admin", homePath: "/home" },
+});
 </script>
 ```
 
+`provideLayout()` 会自动桥接布局模式、折叠状态、尺寸、动画和显示开关。只有需要完全
+自定义响应式来源时，才直接构造 `LayoutContext` 并调用 `provideLayoutContext()`。
+
 ### 3. 添加设置抽屉
 
 ```vue
 <script setup lang="ts">
 import { ref } from "vue";
+import { NDialogProvider, NMessageProvider } from "naive-ui";
 import { SettingsDrawer } from "@robot-admin/layout";
 
 const visible = ref(false);
+const settingsActions = {
+  clearCache: () => localStorage.removeItem("my-app-disposable-cache"),
+};
 </script>
 
 <template>
   <button @click="visible = true">⚙️ 设置</button>
-  <SettingsDrawer v-model:show="visible" />
+  <NDialogProvider>
+    <NMessageProvider>
+      <SettingsDrawer v-model:show="visible" :actions="settingsActions">
+        <template #appearance-prepend>
+          <AppThemeExtension />
+        </template>
+      </SettingsDrawer>
+    </NMessageProvider>
+  </NDialogProvider>
 </template>
 ```
 
+`SettingsDrawer` 使用 Naive UI 的 Message/Dialog API，因此必须位于
+`NMessageProvider` 和 `NDialogProvider` 下；应用根部已有 Provider 时无需重复包裹。
+
+`SettingsDrawer` 不再自行清空 `localStorage` / `sessionStorage`。缓存清理由宿主通过
+`actions.clearCache` 明确实现，避免误删登录态、语言和业务数据。可用扩展插槽：
+`appearance-prepend/append`、`layout-prepend/after-mode/append`、
+`features-prepend/append`；插槽均暴露当前 `settings`。
+
 ---
 
 ## 📐 布局模式
 
-| 模式 | 常量值 | 一级菜单 | 二级菜单 | 适用场景 |
-|------|--------|----------|----------|----------|
-| **左侧菜单** | `side` | 左侧栏 | 左侧栏（折叠） | 经典后台管理（ERP、CRM） |
-| **顶部菜单** | `top` | 顶部横向 | 顶部下拉 | 菜单少，需更宽内容区 |
-| **混合布局** | `mix` | 左侧图标栏 | 悬浮弹出 | 一级菜单少，二级多 |
-| **顶部混合** | `mix-top` | 左侧图标栏 | 顶部横向 | 全局导航 + 侧边详情 |
-| **反转混合** | `reverse-horizontal-mix` | 顶部横向 | 右侧栏 | 特殊需求，右手操作 |
-| **卡片布局** | `card-layout` | hover 抽屉 | 网格铺开 | 应用首页 / 工作台 |
+| 模式         | 常量值                   | 一级菜单   | 二级菜单       | 适用场景                 |
+| ------------ | ------------------------ | ---------- | -------------- | ------------------------ |
+| **左侧菜单** | `side`                   | 左侧栏     | 左侧栏（折叠） | 经典后台管理（ERP、CRM） |
+| **顶部菜单** | `top`                    | 顶部横向   | 顶部下拉       | 菜单少，需更宽内容区     |
+| **混合布局** | `mix`                    | 左侧图标栏 | 悬浮弹出       | 一级菜单少，二级多       |
+| **顶部混合** | `mix-top`                | 左侧图标栏 | 顶部横向       | 全局导航 + 侧边详情      |
+| **反转混合** | `reverse-horizontal-mix` | 顶部横向   | 右侧栏         | 特殊需求，右手操作       |
+| **卡片布局** | `card-layout`            | hover 抽屉 | 网格铺开       | 应用首页 / 工作台        |
 
 ---
 
 ## 🎨 主题预设
 
-| 预设 | 主题色 | 图标 |
-|------|--------|------|
-| 科技蓝 | `#409eff` | 💙 |
-| 清新绿 | `#52c41a` | 💚 |
-| 商务灰 | `#595959` | 🖤 |
-| 活力橙 | `#fa8c16` | 🧡 |
-| 优雅紫 | `#722ed1` | 💜 |
-| 经典红 | `#f5222d` | ❤️ |
+| 预设   | 主题色    | 图标 |
+| ------ | --------- | ---- |
+| 科技蓝 | `#409eff` | 💙   |
+| 清新绿 | `#52c41a` | 💚   |
+| 商务灰 | `#595959` | 🖤   |
+| 活力橙 | `#fa8c16` | 🧡   |
+| 优雅紫 | `#722ed1` | 💜   |
+| 经典红 | `#f5222d` | ❤️   |
 
 ---
 
@@ -220,10 +273,10 @@ import { useSettingsStore } from "@robot-admin/layout";
 const settings = useSettingsStore();
 
 // 读取
-settings.layoutMode;       // 'side' | 'top' | 'mix' | ...
-settings.menuExpandMode;   // 'inline' | 'panel'
-settings.primaryColor;     // '#409eff'
-settings.themeMode;        // 'light' | 'dark' | 'system'
+settings.layoutMode; // 'side' | 'top' | 'mix' | ...
+settings.menuExpandMode; // 'inline' | 'panel'
+settings.primaryColor; // '#409eff'
+settings.themeMode; // 'light' | 'dark' | 'system'
 
 // 修改
 settings.layoutMode = "mix";
@@ -235,21 +288,31 @@ settings.resetSettings();
 
 ### 设置属性一览
 
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `themeMode` | `ThemeMode` | `'light'` | 主题模式 |
-| `primaryColor` | `string` | `'#409eff'` | 主题色 |
-| `layoutMode` | `LayoutMode` | `'side'` | 布局模式 |
-| `menuExpandMode` | `MenuExpandMode` | `'inline'` | 菜单展开方式 |
-| `borderRadius` | `BorderRadiusSize` | `'medium'` | 圆角大小 |
-| `transitionType` | `TransitionType` | `'slide'` | 页面动画 |
-| `fixedHeader` | `boolean` | `true` | 固定头部 |
-| `showBreadcrumb` | `boolean` | `true` | 显示面包屑 |
-| `showTagsView` | `boolean` | `true` | 显示标签页 |
-| `showFooter` | `boolean` | `true` | 显示页脚 |
-| `sidebarWidth` | `number` | `220` | 侧边栏宽度 (px) |
-| `sidebarCollapsedWidth` | `number` | `64` | 折叠宽度 (px) |
-| `headerHeight` | `number` | `56` | 头部高度 (px) |
+| 属性                    | 默认值      | 作用方      | 说明                         |
+| ----------------------- | ----------- | ----------- | ---------------------------- |
+| `themeMode`             | `'light'`   | 宿主回调    | 标准主题模式                 |
+| `primaryColor`          | `'#409eff'` | 包内        | 主题色与派生 CSS 变量        |
+| `borderRadius`          | `'medium'`  | 包内        | 圆角 CSS 变量                |
+| `transitionType`        | `'slide'`   | 包内        | 页面动画类型                 |
+| `enableTransition`      | `true`      | 包内        | 是否启用页面动画             |
+| `layoutMode`            | `'side'`    | 包内        | 当前布局模式                 |
+| `menuExpandMode`        | `'inline'`  | 宿主菜单    | 菜单展开方式                 |
+| `collapsed`             | `false`     | 包内/宿主   | 共享侧栏折叠状态             |
+| `fixedHeader`           | `true`      | 宿主头部    | 固定头部策略                 |
+| `showBreadcrumb`        | `true`      | 宿主头部    | 显示面包屑                   |
+| `showBreadcrumbIcon`    | `true`      | 宿主头部    | 显示面包屑图标               |
+| `showTagsView`          | `true`      | 包内        | 显示标签页                   |
+| `tagsViewHeight`        | `44`        | 包内        | 标签页高度 (px)              |
+| `tagsViewStyle`         | `'default'` | 宿主标签页  | 标签页风格                   |
+| `showFooter`            | `true`      | 包内        | 显示页脚                     |
+| `sidebarWidth`          | `220`       | 包内        | 侧边栏宽度 (px)              |
+| `sidebarCollapsedWidth` | `64`        | 包内        | 折叠宽度 (px)                |
+| `headerHeight`          | `56`        | 包内/宿主   | 头部高度 (px)                |
+| `enableHotkeys`         | `true`      | 宿主扩展    | 是否启用宿主快捷键           |
+| `version`               | `'3.1.0'`   | 配置元数据  | 当前默认配置来源版本         |
+
+“宿主”字段由 Store 和导入导出协议统一维护，但布局包不会越权修改宿主业务组件；这种边界
+避免重复实现面包屑、快捷键和标签页等业务能力。
 
 ### CSS 变量
 
@@ -270,32 +333,37 @@ settings.resetSettings();
 
 ## 🧩 C_LayoutContainer Slots
 
-| Slot 名称 | 说明 | 适用布局 |
-|-----------|------|----------|
-| `#logo` | 品牌 Logo | 全部 |
-| `#menu` | 垂直菜单 | Side |
-| `#header` | 完整头部 | Side / Mix |
+| Slot 名称       | 说明           | 适用布局                      |
+| --------------- | -------------- | ----------------------------- |
+| `#logo`         | 品牌 Logo      | 全部                          |
+| `#menu`         | 垂直菜单       | Side                          |
+| `#header`       | 完整头部       | Side / Mix                    |
 | `#header-extra` | 头部右侧操作区 | Top / MixTop / Reverse / Card |
-| `#top-menu` | 水平菜单 | Top / MixTop / Reverse |
-| `#tags-view` | 标签页 | 全部 |
-| `#footer` | 页脚 | 全部 |
-| `#brand` | 顶部品牌区 | MixTop |
-| `#menu-trigger` | 菜单触发区 | Card |
-| `#drawer-menu` | 抽屉菜单 | Card |
+| `#top-menu`     | 水平菜单       | Top / MixTop / Reverse        |
+| `#tags-view`    | 标签页         | 全部                          |
+| `#footer`       | 页脚           | 全部                          |
+| `#brand`        | 顶部品牌区     | MixTop                        |
+| `#menu-trigger` | 菜单触发区     | Card                          |
+| `#drawer-menu`  | 抽屉菜单       | Card                          |
 
 ---
 
 ## 📖 类型定义
 
 ```typescript
-type LayoutMode = "side" | "top" | "mix" | "mix-top" | "reverse-horizontal-mix" | "card-layout";
+type LayoutMode =
+  "side" | "top" | "mix" | "mix-top" | "reverse-horizontal-mix" | "card-layout";
 type MenuExpandMode = "inline" | "panel";
 type TransitionType = "fade" | "slide" | "zoom" | "none";
 type BorderRadiusSize = "small" | "medium" | "large";
 type TagsViewStyle = "default" | "card" | "smart";
 type ThemeMode = "light" | "dark" | "system";
 
-interface ThemePreset { name: string; icon: string; primaryColor: string; }
+interface ThemePreset {
+  name: string;
+  icon: string;
+  primaryColor: string;
+}
 interface SettingsStoreOptions {
   id?: string;
   defaults?: Partial<SettingsState>;
@@ -328,10 +396,13 @@ export const useSettingsStore = createSettingsStore({
 从文件、URL 或远端接口加载的设置属于不可信输入，写入 Store 前应先校验：
 
 ```typescript
-import { sanitizeSettingsPatch, useSettingsStore } from "@robot-admin/layout";
+import { sanitizeLayoutSettingsConfig } from "@robot-admin/layout/core";
+import { useSettingsStore } from "@robot-admin/layout";
 
 const imported = JSON.parse(await file.text());
-const safePatch = sanitizeSettingsPatch(imported.settings);
+// 一次校验完整文件，失败时不会产生部分状态写入。
+const config = sanitizeLayoutSettingsConfig(imported);
+const safePatch = config.settings ?? {};
 const settings = useSettingsStore();
 
 if (safePatch.themeMode !== undefined) {
@@ -347,6 +418,26 @@ settings.$patch(safePatch);
 `useLayoutCache()` 默认不会输出开发日志，也不会向 `window` 暴露调试函数；仅在
 受控的本地开发场景显式设置 `enableDevLog` / `exposeToWindow`。
 
+### 3.1 升级说明
+
+- 新增 `createLayoutContext()` 与 `provideLayout()`，用于精简普通项目的上下文桥接代码。
+- 原有 `LayoutContext`、`provideLayoutContext()` 和所有组件/插槽继续兼容。
+- `C_SideLayout` 等旧别名已正式标记为废弃，3.x 仍保留，计划在 4.0 移除；请改用
+  `SideLayout`、`TopLayout`、`MixLayout`、`MixTopLayout`、
+  `ReverseHorizontalMixLayout`、`CardLayout`。
+
+### 3.0 升级说明
+
+- 现有根入口、6 种布局、组件名、slot 名和 CSS 入口保持兼容。
+- `LayoutContext.collapsed` 为可选的双向状态；提供后，侧栏与宿主头部共享同一折叠状态。
+- 自定义 Store 可通过 `setupLayout()` 注入，也可用 `SettingsDrawer :store="store"` 显式传入。
+- `enableTransition: false` 现在会真正关闭路由过渡，但保留已选择的动画类型。
+- 缓存清理改为宿主白名单动作；从 2.x 升级时请传入 `actions.clearCache`。
+- `@robot-admin/theme` 不再是 peer dependency；需要主题联动时使用 `onThemeModeChange`。
+
+多 Store 实例可以拥有独立状态，但默认 CSS 变量和设置抽屉的灰度、色弱、水印属于页面级
+视觉效果；同一页面应由一个布局宿主统一管理，避免多个应用同时争用 `document` 根节点。
+
 ### 单独使用布局骨架
 
 ```typescript