dsh-plugin-core 0.32.0 → 0.33.0

package/docs/design/structure.md

@@ -1,165 +1,169 @@
 # 结构规范
 
-本文件回答两个问题：
+本文件回答三个问题：
 
-1. **代码怎么分** —— 每个目录放什么、谁依赖谁。
-2. **预览插件（packages/demo）左侧怎么分** —— 组件预览的分区，跟代码结构对齐。
+1. **控件怎么归类** —— 一个新控件该放哪，按固定顺序判定，不用开会。
+2. **代码怎么分** —— 每个目录放什么、谁依赖谁。
+3. **预览插件（packages/demo）左侧怎么分** —— 与代码同构的两级目录。
 
-> 本文是**目标态**（2026-10-19 用户拍板）。哪些已在、哪些暂缓，用状态标注区分；
-> 现状与目标的差异见文末「未落地项」。
 > 运行逻辑（样式注入机制、数据流、触发关系）的真源在 `docs/design/architecture.md`，本文不重复。
+> 2026-11-05 用户拍板：分类改用**业界通名**（对齐 Ant Design / Element Plus / MUI / Mantine / Chakra 的菜单），
+> 并且**结构优先于兼容** —— 消费方该改就改，不为保持旧 import 而选不合理结构。
 
-## 命名约定
+## 一、三级：区 → 类 → 控件
 
-- **`ui`** = 基础能力：纯零件 + 可复用的基础容器（`Modal`、侧边栏/拉栏、选工作区/选文件），不碰业务成品。
-- **`adv.`** = advanced，高级空间：**成品**——拿 `ui` 的基础能力拼出来、与业务对象相关的共享件。
-- 高级空间统一加 `adv.` 前缀：`adv.explorer`、`adv.session`。
-- npm 子路径允许带点，引用写法就是 `dsh-plugin-core/adv.explorer`。
+| 级 | 是什么 | 举例 |
+|---|---|---|
+| **区** | 能力域，导航一级 | 入门 / 设计 / 控件 / 应用模块 / 工具方法 |
+| **类** | 控件按用途归的类，导航二级 + 目录一级 | 动作 / 录入 / 展示 / 反馈 / 布局 / 导航 |
+| **控件** | 一个导出件 = 目录里的一个文件 | `Button.ts` / `Picker.ts` / `Table.ts` |
+
+「区」只存在于**导航与文档**里；代码目录只有类和控件。两棵树不是同一棵树，别互相找。
+
+## 二、控件归类：三步判定
 
-## 状态图例
+拿一个新控件，从上往下走，走到哪停就放哪：
+
+1. **import React 或 DOM 吗？** 不 import → 它不是控件：落 `src/utils/`（纯方法）或 `src/design/`（值 / 注入机制）。
+2. **必须拿到业务对象（工作区 / 会话 / 文件 / 模型）才能工作吗？** → 落 `src/adv/`，不进 `ui`。
+3. **按「用户拿它做什么」选类**：
+
+| 类 | 判据 | 成员（2026-11-05） |
+|---|---|---|
+| **动作** `actions` | 点它触发一次操作，本身不产生值 | Button、IconButton |
+| **录入** `inputs` | 产生或修改一个值 | Input、NumberInput、PrefixedInput、Textarea、Checkbox、Segmented、Picker、DateTimePicker、WorkspacePicker、ModelPicker、InputGroup |
+| **展示** `display` | 只呈现内容，不改变状态 | Card、StripCard、Surface、Chip、Table、CodeViewer、MarqueeText、FlipText、LiveText、SectionHead、FieldHint |
+| **反馈** `feedback` | 表达「正在进行 / 刚完成 / 出错了」 | Modal、SideSheet、AlertModal、ConfirmModal、alertModal、confirmModal、Toast、host-toast、Loader、LoaderBar、Loading |
+| **布局** `layout` | 只决定内部元素怎么摆、怎么拼 | SplitGroup、PanelDock、QuickToolbar、resizer |
+| **导航** `navigation` | 在多个视图 / 页之间移动 | Pagination |
+| **基础设施** `infra` | **不是控件**：宿主桥、注入器、纯逻辑、跨类共用底座 | official、css、controls-css、locale、tooltip、host-data、modal-host、loading-host、toast-host、overlay、panel + 皮肤、thenable、ticker、chevron |
 
-| 标记 | 含义 |
-|---|---|
-| ✅ | 代码已在（质量待逐个重审） |
-| 🟡 | 缺口 / 待迁：需要补或需要挪位置的 |
-| ⚪ | 暂缓：先标着，不做 |
+三条边界裁决（按顺序用）：
 
----
+1. **同时持有「值」和「操作」** → 归布局（它其实是两个控件焊在一起），或者直接拆成两个。
+2. **内部元素位置由它决定** → 布局；**只加一层外观、位置全由调用方给** → 展示（Card / Surface 属展现外壳）。
+3. **跨类说不清** → 按**多数派**：查 AntD / Element / MUI / Mantine / Chakra 的菜单，装得多的那类胜出，并在本文登记结果。
 
-## 一、代码分层
+**新增第 8 个类要用户拍板**，agent 一律不自建 —— 这是防「又冒出一个新空间」的闸门。
+拿不准时归现有 6 类，宁可挤一点也不另开。
+
+## 三、代码分层
 
 ```
-dsh-plugin-core/
-│
-├── design/              ① 设计层 —— 只放「值」和「注入机制」，零 React
-│   ├── tokens              ✅ 颜色 / 字号 / 间距 / 圆角 / 层级（别名官方 --dsw-alias-*）
-│   └── style-kit           ✅ 运行时注入 <style>，createStyleKit({ id })
+src/
+├── design/                 ① 设计层 —— 只放「值」和「注入机制」，零 React
+│   ├── tokens                 颜色 / 字号 / 间距 / 圆角 / 层级（别名官方 --dsw-alias-*）
+│   └── style-kit              运行时注入 <style>，createStyleKit({ id })
 │
-├── ui/                  ② 基础控件 —— 纯零件 + 可复用基础能力（依赖 design）
-│   ├── official.ts         ✅ 全仓唯一 import 官方 primitives 的入口（L1）
-│   ├── 表单                ✅ Input / NumberInput / PrefixedInput / Textarea /
-│   │                          Checkbox / Segmented / Picker（下拉选择）/
-│   │                          DateTimePicker（日期时间：单值 / 时间段 × 精度到秒）
-│   ├── 动作                ✅ Button / IconButton
-│   ├── 反馈                ✅ Modal / Toast / Loader 家族（2026-10-30）：
-│   │   │                      Loader（ring / blocks × 五档尺寸）、LoaderBar（胶囊不定进度）；
-│   │   │                      两者都只画图形，无背景无定位，背景与位置归调用方
-│   │   └── Loading         ✅ 旧复合浮层（贴右下角的 pill + 两种加载卡），保留、已标 deprecated
-│   ├── 展示                ✅ Card / StripCard / Chip / MarqueeText /
-│   │                          SectionHead / FieldHint / LiveText /
-│   │                          Table（第一档 Plain：外框 + 灰底表头 + 按列分隔线；
-│   │                            表级 density / striped / borders，列级 divider / padding / headerTone，
-│   │                            单元格可跨列跨行；TableGrid / TableZebra 预留同族独立组件）
-│   ├── 选择                ✅ WorkspacePicker（选工作区，自取宿主快照）
-│   │                          通用 Picker 是纯零件；领域选择器经 connectHost 自取数（2026-10-20）
-│   ├── 组合                ✅ SplitGroup（两格焊成一体：只画外框 / 分隔 / 聚焦圈，不持状态）
-│   │                          InputGroup（输入框 + 按钮组焊成一体：可选前置标题 / 撤销 / 自定义高度）
-│   └── 布局                ✅ PanelDock / createPanelDock（可停靠分栏：多面板 + 拖拽拉栏）
-│                              组名 = 窗口一对一、同名覆盖、默认上限 3 超限拒绝；
-│                              不做 tab 切换 / 自动淘汰 / 浮动层（用户 2026-10-20 定案）
-│                           ✅ QuickToolbar（右侧浮动快捷工具栏：内置回顶部 + 自定义按钮；
-│                              纵向恒贴屏幕底边，横向默认贴屏幕右缘或指定控件右缘外侧）
+├── ui/                     ② 控件（依赖 design）
+│   ├── index.ts               对外唯一入口（导出面扁平，不按类开子路径）
+│   ├── official.ts            L1 官方 adapter —— 全仓唯一 import 官方 primitives 的地方
+│   ├── actions/               Button · IconButton（+ button.css / generated）
+│   ├── inputs/                Field（Input/NumberInput/PrefixedInput）· Textarea · Checkbox
+│   │                          Segmented · Picker（+ picker-logic / picker-icons）
+│   │                          DateTimePicker（+ datetime-logic）· InputGroup
+│   │                          WorkspacePicker · ModelPicker
+│   ├── display/               Card · StripCard · Surface · Chip · Table（+ table-logic / table-shared）
+│   │                          CodeViewer（+ code-viewer-lang / -theme）· MarqueeText · FlipText
+│   │                          LiveText · SectionHead · FieldHint
+│   ├── feedback/              Modal · SideSheet · AlertModal · ConfirmModal（+ modal-host）
+│   │                          Toast（+ toast-host）· host-toast · Loader · LoaderBar · Loading
+│   ├── layout/                SplitGroup · PanelDock（+ panel-dock-logic）· QuickToolbar
+│   │                          （+ quick-toolbar-logic）· resizer
+│   ├── navigation/            Pagination（+ pagination-logic）
+│   └── infra/                 css · controls-css · locale · tooltip · host-data
+│                              overlay / panel（跨类共用浮层底座 + 皮肤）· thenable · ticker · chevron
 │
-├── utils/               ③ 纯方法 —— 零 React / 零 DOM（谁都能用，它不依赖谁）
-│   ├── date                ✅ 日期 / 相对时间 / 时间区间
-│   ├── i18n                ✅ 内置中英字典
-│   ├── string              ⚪ 暂缓
-│   ├── number              ⚪ 暂缓（注：formatBytes 已被 adv.session 附件卡使用，只「不对外承诺」，不删）
-│   ├── http                ⚪ 暂缓
-│   └── path                ✅ 纯路径方法（无 UI）：joinPath / parentOf / crumbsOf / extOf / mimeOf
-│                              （已从 explorer/types.ts 迁入，2026-10-20）
+├── utils/                  ③ 纯方法 —— 零 React / 零 DOM（谁都能用，它不依赖谁）
+│   ├── date                   日期 / 相对时间 / 时间区间
+│   ├── i18n                   内置中英字典
+│   ├── path                   joinPath / parentOf / crumbsOf / extOf / mimeOf
+│   └── number / string / http 暂缓（不对外承诺，但代码在）
 │
-├── adv.explorer/        ④ 高级空间①：文件浏览（依赖 ui + utils）
-│   ├── FileBrowser        ✅ 面板本体：面包屑（▾ 选层）+ 内联展开树 + 预览（+ picker 形态）
-│   ├── open               ✅ 两命令式能力：openFilePreview（侧边栏预览）/ pickWorkspaceFile（锚定弹窗选文件）
-│   ├── types              ✅ 纯逻辑层（零 React / 零官方件）：预览分发 / 错误码 / 根反推 / 过滤
-│   └── preview            ✅ 预览体家族：md / 代码 / HTML / PDF / Office / 图片
+├── adv/                    ④ 应用模块 —— ui + utils 拼出来的成品
+│   ├── explorer/              文件浏览：FileBrowser · openFilePreview · pickWorkspaceFile · 预览体家族
+│   └── session/               会话记录：SessionPreview
 │
-└── adv.session/         ⑤ 高级空间②：会话记录（依赖 ui + utils）
-    └── SessionPreview      ✅ 成品：ui.Modal 承载会话消息（modal / sidebar / page）
+└── host/                      宿主接口类型（无运行时）
 ```
 
-### 组合关系（成品 = 基础能力 + 定制）
-
-| 成品 | 用到的 `ui` 基础能力 | 定制了什么 |
-|---|---|---|
-| `adv.session` · `SessionPreview` | `Modal` | 把会话消息放进弹窗 |
-| `adv.explorer` · `FileBrowser` | `Button`（面包屑 ghost / 行尾 outline）/ `IconButton` / `Segmented` / `MarqueeText` / `PanelDock`（浏览态外壳与拖宽）+ 官方件（`FileTypeIcon` / `MarkdownText` / `CodeBlock`，经 `ui/official`） | 面包屑 + 内联展开树 + 预览体家族 + 两命令式能力 |
-
-`adv.*` 只做「拼装 + 业务定制」，不重新实现按钮 / 下拉 / 弹窗 / 侧栏。
+**一个控件的四份东西放同一个目录**：`X.ts` + `X-logic.ts`（若有）+ `X.css`（真源）+ `X-css.generated.ts`（生成物）。
+CSS 真源位置改动要同步 `scripts/gen-css.mjs` 的 `MAP`（显式清单，刻意保留摩擦）。
 
-### 依赖方向（单向，不许反向）
+## 四、依赖方向（单向，不许反向）
 
 ```
-design ──▶ ui ──▶ adv.explorer / adv.session
+design ──▶ ui ──▶ adv/explorer · adv/session
 utils（谁都不依赖，谁都可以用）
 ```
 
-- `utils` 不得 import `ui` / `design` / React / DOM / 宿主 API —— 将来要能整体剥出去复用。
+- `utils` 不得 import `ui` / `design` / React / DOM / 宿主 API。
 - `design` 不得依赖 `ui`（否则「只想要 token 的插件」被迫拖进 React）。
-- `ui` 不得依赖 `adv.*`（反向依赖成环）。
-- `adv.*` 只从 `ui` / `utils` 的公开导出消费，不直接 import 官方平台模块（要包先过 `ui/official.ts`）。
+- `ui` 不得依赖 `adv/*`（反向成环）。
+- `adv/*` 只从 `ui` / `utils` 的公开导出消费，不直接 import 官方平台模块（要包先过 `ui/official.ts`）。
 
-### 立包判据
+## 五、立包判据
 
-**有实质内容、会持续长大的功能模块才独立成子包；只是一个控件就进 `ui`。**
+**有实质内容、会持续长大的功能模块才独立成区；只是一个控件就进 `ui`。**
 统一到「控件」粒度，不提整个页面。
 
----
+## 六、对外入口
 
-## 二、demo 展示分区（左侧导航）
+| 子路径 | 用途 | 为什么单独开 |
+|---|---|---|
+| `dsh-plugin-core/ui` | 全部控件（唯一主入口，扁平导出） | 单入口是业界共识（AntD / MUI 同）；按类开 7 条子路径只增加记忆成本 |
+| `dsh-plugin-core/ui/official` | L1 官方 adapter | `adv/*` 要直接取官方件，属结构性第二入口 |
+| `dsh-plugin-core/ui/code-viewer` | CodeViewer | 直接引 `@uiw/react-codemirror`，重依赖必须可选 |
+| `dsh-plugin-core/ui/host-toast` | 宿主原生 Toast | 入口静态 import 官方件会让 Node 单测崩（旧坑） |
+| `dsh-plugin-core/adv/explorer` | 文件浏览 | 应用模块独立子路径 |
+| `dsh-plugin-core/adv/session` | 会话预览 | 同上 |
+
+**不再新增子路径**：想加，先问「是重依赖，还是只是分类？」—— 分类归目录，不归导出口。
+
+## 七、demo 展示分区（两级，17 页）
+
+侧栏与右侧共用 `packages/demo/src/sections/index.tsx` 的 `ALL_SECTIONS`（单一事实源）。
 
 ```
-组件预览
-│
-├─ ① 设计
-│     色板 / 字号 / 间距 / 圆角 / 阴影 / 明暗
-│     （只摆值，不点交互）
-│
-├─ ② 基础控件
-│   ├─ 表单    Input / NumberInput / PrefixedInput / Textarea / Checkbox / Segmented / Picker / DateTimePicker
-│   ├─ 动作    Button / IconButton
-│   ├─ 反馈    Modal / Toast
-│   ├─ 展示    Card / StripCard / Chip / Table / MarqueeText / SectionHead / FieldHint / LiveText
-│   ├─ 组合    SplitGroup（展示在选择器页）/ InputGroup（展示在表单页）
-│   └─ 布局    PanelDock / 拉栏 / QuickToolbar
-│
-├─ ③ 高级空间
-│   ├─ 文件浏览   FileBrowser + openFilePreview / pickWorkspaceFile（点文件夹、点文件看预览）
-│   └─ 会话预览   SessionPreview（弹窗里放会话记录）
-│
-└─ ④ 工具方法
-      日期格式化 / 相对时间（拿真实值演示，不是控件）
+① 入门        start     帮助索引 / 快速开始 / 参考
+② 设计        design    设计基础（token · 明暗）
+③ 控件        components
+   ├─ 动作    actions       Button · IconButton
+   ├─ 录入    inputs        Input · NumberInput · PrefixedInput · Textarea · Checkbox
+   │                        Segmented · Picker · DateTimePicker · WorkspacePicker
+   │                        ModelPicker · InputGroup
+   ├─ 展示    display       Card · StripCard · Surface · Chip · Table · CodeViewer
+   │                        MarqueeText · FlipText · LiveText · SectionHead · FieldHint
+   ├─ 反馈    feedback      Modal · SideSheet · AlertModal · ConfirmModal
+   │                        Toast · Loader · LoaderBar · Loading
+   ├─ 布局    layout        SplitGroup · PanelDock · QuickToolbar
+   └─ 导航    navigation    Pagination
+④ 应用模块    blocks      文件浏览 / 会话预览
+⑤ 工具方法    utils       日期时间 / 文本 / 数字 / HTTP / 多语言
 ```
 
-### 现有分区 → 新分组映射（全部是重排，不用新写内容）
-
-| 现有 `demo/sections/` | 归到 |
-|---|---|
-| `design.tsx` | ① 设计 |
-| `buttons.tsx` | ② 基础控件 · 动作 |
-| `pickers.tsx` | ② 基础控件 · 表单 |
-| `display.tsx` | ② 基础控件 · 展示 |
-| `feedback.tsx` / `controls.tsx` | ② 基础控件 · 反馈 |
-| `toolbar.tsx` | ② 基础控件 · 布局（QuickToolbar） |
-| `explorer.tsx` | ③ 高级空间 · 文件浏览 |
-| `session.tsx` | ③ 高级空间 · 会话预览 |
-| `utils.tsx` | ④ 工具方法 |
-
----
-
-## 三、未落地项（等调整）
-
-- **目录改名**：`src/explorer` → `src/adv.explorer`、`src/session` → `src/adv.session`；同步改
-  `package.json` 的 `exports`、各 `index.ts`、`packages/demo` 的 import、`docs/design/architecture.md` 的树。
-  代码现在仍是旧名。
-- ~~**收窄导出**：`adv.explorer` 只暴露 `ExplorerPanel`~~ → 已定（2026-10-20）：暴露 `FileBrowser` 面板 +
-  `openFilePreview` / `pickWorkspaceFile` 两命令式能力 + 纯逻辑层；`WorkspacePicker` 留在 `ui`。
-- ~~**路径方法归基础**~~ → **已落地**（2026-10-20）：`joinPath` / `parentOf` / `crumbsOf` / `extOf` / `mimeOf`
-  在 `utils/path`；`previewInfoOf` 等业务判断留 `explorer/types.ts`（纯逻辑层，node 单测直接引）。
-- ~~**补基础组件**：`ui` 需补 `SidebarLayout` / `SplitPane`~~ → **已落地为 `PanelDock`**（2026-10-20），
-  `resizer` 保留为它的底层函数。
-- **暂缓项**：`utils/string`、`utils/number`、`utils/http`、`ui/feedback/Loading` —— 只标注，未删代码。
+合并后的页按旧页面的顺序串联，控件之间的分节就是各 `Example` 块自己的标题（不再额外加一层小标题）。
+
+## 八、对应表：导航 ↔ 代码 ↔ 文档
+
+| 导航项 | 代码 | 文档 |
+|---|---|---|
+| ① 入门 | （无，讲述型） | `docs/help/index.md` + `integration.md` |
+| ② 设计 | `src/design/` | `docs/help/design.md` |
+| ③ 控件 · 动作 | `src/ui/actions/` | `docs/help/ui.md` |
+| ③ 控件 · 录入 | `src/ui/inputs/` | 同上 |
+| ③ 控件 · 展示 | `src/ui/display/` | 同上 |
+| ③ 控件 · 反馈 | `src/ui/feedback/` | 同上 |
+| ③ 控件 · 布局 | `src/ui/layout/` | 同上 |
+| ③ 控件 · 导航 | `src/ui/navigation/` | 同上 |
+| （无导航项） | `src/ui/infra/` | 只在「入门 · 接入」讲一句 |
+| ④ 应用模块 | `src/adv/explorer/`、`src/adv/session/` | `docs/help/explorer.md`、`session.md` |
+| ⑤ 工具方法 | `src/utils/` | `docs/help/methods.md` |
+
+## 九、未落地项
+
+- ~~**分类表 + 自检**~~ → **已落地**（2026-11-05）：`test/ui-taxonomy.test.mjs` 盯三件事 —— `src/ui` 根只许 `index.ts` / `official.ts`、类目录只有登记过的 7 个、`*.css` 与 `*-css.generated.ts` 必须同目录成对。
+- **暂缓项**：`utils/string`、`utils/number`、`utils/http`、`ui/feedback/Loading`（只标注，未删代码）。
 - **库里没有的**：
   - Switch 开关 —— 官方 primitives 有，归「包官方」批次；
-  - Select 下拉 —— 用 `Picker` 代替（`SelectField` 曾因依赖官方 Menu 被删，属待反转的旧决策）。
+  - Select 下拉 —— 用 `Picker` 代替（`SelectField` 曾因依赖官方 Menu 被删，属已反转的旧决策）。

package/docs/design/style.md

@@ -122,13 +122,13 @@ its own assertion.
 
 > EN: There is only one arrow: `Chevron`
 
-`ui` 层零官方依赖，箭头一律走 `src/ui/chevron.ts` 的自绘 chevron（`h(Chevron, { dir, size })`，
+`ui` 层零官方依赖，箭头一律走 `src/ui/infra/chevron.ts` 的自绘 chevron（`h(Chevron, { dir, size })`，
 四向共用一条路径，靠旋转实现）。**不许再写 `'▾'` / `'↑'` 这类字形**——各系统字体下粗细、角度、
 基线都不一样，同一套界面里会冒出第二种箭头（2026-10-26：卡片折叠箭头就是这么来的）。
 有自检盯着：`test/quality.test.mjs`。
 
 EN: The `ui` layer has no official dependency, so every arrow comes from the self-drawn chevron in
-`src/ui/chevron.ts`. Never write a glyph arrow again; a test enforces it.
+`src/ui/infra/chevron.ts`. Never write a glyph arrow again; a test enforces it.
 
 ## 拼成一体：外壳持框，内件交边
 
@@ -140,7 +140,7 @@ EN: The `ui` layer has no official dependency, so every arrow comes from the sel
 自己画 `:focus-visible` 圈——否则格子里会冒出半圈描边。
 
 `SplitGroup` 用后代选择器直接压内件（`.dshpc-split .dshpc-picker__trigger` / `.dshpc-split .dshpc-seg`），
-所以**内件类名就是耦合点**：改这些类名或结构必须同步改 `src/ui/controls/split-group.css`，否则拼接
+所以**内件类名就是耦合点**：改这些类名或结构必须同步改 `src/ui/layout/split-group.css`，否则拼接
 静默失效（双边框、底色错位），没有自检能替你发现。高度不写死——内件按自己的 `size`（sm 24 /
 md 28 / lg 32）撑开，外壳跟着长；两格传同一个 `size` 才逐像素等高。**外壳绝不能用 `height:100%`
 拉满内件**：它和 `.dshpc-picker__trigger--lg` / `--sm` 同特异性（两个类）且 `split-group.css`
@@ -154,7 +154,7 @@ md 28 / lg 32）撑开，外壳跟着长；两格传同一个 `size` 才逐像
 EN: Welding controls into one visual unit has exactly one recipe: the shell owns border, radius,
 `overflow:hidden` and the shared `:focus-within` ring; the cells hand over border, background and radius.
 `SplitGroup` overrides inner classes with descendant selectors, so those class names are the coupling point —
-rename them and you must update `src/ui/controls/split-group.css`, or the weld fails silently.
+rename them and you must update `src/ui/layout/split-group.css`, or the weld fails silently.
 
 ## 滚动条让位：一律离边缘 1px
 
@@ -190,7 +190,7 @@ one-liner; `--dshpc-dock-gap` was removed on 2026-11-02. A test enforces the bor
 
 > EN: Three tiers for floating surfaces — modal / popover / menu
 
-所有「浮起来的框」的**表面**（底色 · 描边宽 · 圆角 · 阴影）只在 `src/ui/panel.css` 定义，档位只有三个
+所有「浮起来的框」的**表面**（底色 · 描边宽 · 圆角 · 阴影）只在 `src/ui/infra/panel.css` 定义，档位只有三个
 （2026-11-03 用户定：样式统一，交互各家自己管）：
 
 | 档位 | 用在 | 底色 | 描边 | 圆角 | 阴影 |

package/docs/help/utils.doc.ts

@@ -111,8 +111,8 @@ const doc: DocTopic = {
           en: 'Boundary: a plugin’s own UI copy is the plugin’s responsibility; this package offers no plugin-level i18n framework. To override a string: pass a `translate` prop, or use `t` with your own dictionary.',
         },
         {
-          zh: '语言默认跟随宿主：官方 locale 插件把生效语言写进 `<html lang>`（zh → `zh-CN`），本包直接读它 ⇒ 插件不必再接 locale 服务、也不必自己同步。`setLocale` 只是手动覆盖（测试 / 非宿主环境用），调过就不再跟随宿主。',
-          en: 'The language follows the host by default: the official locale plugin writes the active language into `<html lang>` (zh → `zh-CN`) and this package reads it directly, so a plugin needs neither the locale service nor its own sync. `setLocale` is only a manual override (tests / non-host environments); once called it stops following the host.',
+          zh: '语言默认跟随宿主：官方 locale 插件把生效语言写进 `<html lang>`（zh → `zh-CN`），本包直接读它 ⇒ 插件不必再接 locale 服务、也不必自己同步。`setLocale` 只是手动覆盖（测试 / 非宿主环境用），调过就不再跟随宿主，传 `null` 恢复跟随。',
+          en: 'The language follows the host by default: the official locale plugin writes the active language into `<html lang>` (zh → `zh-CN`) and this package reads it directly, so a plugin needs neither the locale service nor its own sync. `setLocale` is only a manual override (tests / non-host environments); once called it stops following the host, and passing `null` resumes it.',
         },
         {
           zh: '可用 key 全集见 src/utils/i18n.ts 的 UtilMessageKey；要在宿主切语言时重渲组件，顶层调一次 `useLocale()`（ui 导出）。',
@@ -123,7 +123,7 @@ const doc: DocTopic = {
         {
           id: 'utils-i18n',
           rows: [
-            { name: 'setLocale(locale)', type: "('zh' | 'en') => void", def: '不调则跟随宿主', desc: { zh: '手动覆盖语言（测试 / 非宿主）；不调就跟随宿主 `<html lang>`', en: 'Manual override (tests / non-host); otherwise follows the host `<html lang>`' } },
+            { name: 'setLocale(locale)', type: "('zh' | 'en' | null) => void", def: '不调则跟随宿主', desc: { zh: '手动覆盖语言（测试 / 非宿主）；传 `null` 恢复跟随宿主 `<html lang>`', en: 'Manual override (tests / non-host); pass `null` to follow the host `<html lang>` again' } },
             { name: 'getLocale()', type: '() => string', def: '—', desc: { zh: '当前语言（默认跟随宿主）', en: 'Current locale (follows the host by default)' } },
             { name: 't(key, vars?)', type: '(key, vars?) => string', def: '—', desc: { zh: '取文案；{n} 占位由 vars 填', en: 'Get copy; {n} placeholders filled by vars' } },
             { name: 'type Translate', type: '(key, vars?) => string', def: '—', desc: { zh: '组件都收这个参数供覆盖', en: 'Components accept this to override copy' } },

package/docs/help/utils.md

@@ -84,9 +84,9 @@ RequestOptions：{ timeoutMs?, signal?, method?, body?, headers? }。
 
 > EN: Boundary: a plugin’s own UI copy is the plugin’s responsibility; this package offers no plugin-level i18n framework. To override a string: pass a `translate` prop, or use `t` with your own dictionary.
 
-语言默认跟随宿主：官方 locale 插件把生效语言写进 `<html lang>`（zh → `zh-CN`），本包直接读它 ⇒ 插件不必再接 locale 服务、也不必自己同步。`setLocale` 只是手动覆盖（测试 / 非宿主环境用），调过就不再跟随宿主。
+语言默认跟随宿主：官方 locale 插件把生效语言写进 `<html lang>`（zh → `zh-CN`），本包直接读它 ⇒ 插件不必再接 locale 服务、也不必自己同步。`setLocale` 只是手动覆盖（测试 / 非宿主环境用），调过就不再跟随宿主，传 `null` 恢复跟随。
 
-> EN: The language follows the host by default: the official locale plugin writes the active language into `<html lang>` (zh → `zh-CN`) and this package reads it directly, so a plugin needs neither the locale service nor its own sync. `setLocale` is only a manual override (tests / non-host environments); once called it stops following the host.
+> EN: The language follows the host by default: the official locale plugin writes the active language into `<html lang>` (zh → `zh-CN`) and this package reads it directly, so a plugin needs neither the locale service nor its own sync. `setLocale` is only a manual override (tests / non-host environments); once called it stops following the host, and passing `null` resumes it.
 
 可用 key 全集见 src/utils/i18n.ts 的 UtilMessageKey；要在宿主切语言时重渲组件，顶层调一次 `useLocale()`（ui 导出）。
 
@@ -94,7 +94,7 @@ RequestOptions：{ timeoutMs?, signal?, method?, body?, headers? }。
 
 | 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
 |---|---|---|---|---|
-| `setLocale(locale)` | `('zh' \| 'en') => void` | 不调则跟随宿主 | 手动覆盖语言（测试 / 非宿主）；不调就跟随宿主 `<html lang>` | Manual override (tests / non-host); otherwise follows the host `<html lang>` |
+| `setLocale(locale)` | `('zh' \| 'en' \| null) => void` | 不调则跟随宿主 | 手动覆盖语言（测试 / 非宿主）；传 `null` 恢复跟随宿主 `<html lang>` | Manual override (tests / non-host); pass `null` to follow the host `<html lang>` again |
 | `getLocale()` | `() => string` | — | 当前语言（默认跟随宿主） | Current locale (follows the host by default) |
 | `t(key, vars?)` | `(key, vars?) => string` | — | 取文案；{n} 占位由 vars 填 | Get copy; {n} placeholders filled by vars |
 | `type Translate` | `(key, vars?) => string` | — | 组件都收这个参数供覆盖 | Components accept this to override copy |