dsh-plugin-core 0.31.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/ui.doc.ts

@@ -825,8 +825,8 @@ const doc: DocTopic = {
           en: 'The callback’s return value decides whether it closes: **only `false`** (returned directly, or resolved to `false`) means it did not succeed — the dialog stays for a retry; `true` / `undefined` / anything else closes as usual; a rejection also keeps it open (the error is logged). The callback owns its failure message, so call sites need no `try/catch`.',
         },
         {
-          zh: '**要「整框谁都别动」就传 `locked`**，别拿按钮 loading 顶替 —— 两者是两件事：loading 只管那一颗按钮转圈，`locked` 管整块面板不可交互（自绘滑块、原生 input、下位选择器一并管住）+ 三条关闭路径失效 + 压灰与禁止手势。声明式传 `locked={saving}` 即可；它是受控项，不传 = 未锁，关掉重开自然复位，也不会改动任何子控件自己的 `disabled`。命令式那两个函数的回调会收到 `ctl`（`{ setLocked(bool) }`），在异步过程中自己开 / 关：`onConfirm: async (ctl) => { ctl.setLocked(true); await save(); ctl.setLocked(false) }`；框关掉之后再调 `setLocked` 是空操作。',
-          en: '**When the whole dialog must be untouchable, pass `locked`** — do not fake it with button loading: loading only spins that one button, while `locked` makes the entire panel non-interactive (custom sliders, native inputs and selects included), disables all three close paths, dims the surface and shows a not-allowed cursor. Declaratively just pass `locked={saving}`; it is controlled and stateless — omitted means unlocked, reopening starts clean, and it never touches a child’s own `disabled`. The two imperative dialogs hand their callbacks a `ctl` (`{ setLocked(bool) }`) so you can flip it mid-flight: `onConfirm: async (ctl) => { ctl.setLocked(true); await save(); ctl.setLocked(false) }`. Calling `setLocked` after the dialog closed is a no-op.',
+          zh: '**要「整框谁都别动」就传 `locked`**，别拿按钮 loading 顶替 —— 两者是两件事：loading 只管那一颗按钮转圈，`locked` 管整块面板。做法是**控件各自按自己的禁用态渲染**（Button / Input / Textarea / Checkbox / Segmented / Picker / 日期选择 / 分页 都会自己变灰并真的禁用，Tab 自然跳过），再盖一层**全透明**点击层兜住自绘元素与鼠标 —— 所以界面不会整体蒙灰（蒙灰会让人以为坏了），只有控件自己变灰 + 禁止手势。它**只做「或」、从不写回**任何 `disabled`：本来禁用的解锁后照样禁用，锁定期间你把某个控件改成能用 / 禁用，解锁后也照你的。声明式传 `locked={saving}` 即可；受控项，不传 = 未锁，关掉重开自然复位。命令式那两个函数的回调会收到 `ctl`（`{ setLocked(bool) }`）：`onConfirm: async (ctl) => { ctl.setLocked(true); await save(); ctl.setLocked(false) }`；框关掉之后再调是空操作。',
+          en: '**When the whole dialog must be untouchable, pass `locked`** — do not fake it with button loading: loading only spins that one button, while `locked` covers the whole panel. It works by letting **each control render its own disabled state** (Button / Input / Textarea / Checkbox / Segmented / Picker / date picker / pagination all dim themselves and are genuinely disabled, so Tab skips them), plus a **fully transparent** click layer that catches self-drawn elements and the pointer — so the surface is never dimmed as a whole (a veil reads as "the app broke"); only the controls dim and the cursor turns not-allowed. It **only ORs and never writes back** any `disabled`: already-disabled controls stay disabled after unlocking, and anything you flip mid-lock stays as you left it. Declaratively pass `locked={saving}`; it is controlled and stateless — omitted means unlocked, reopening starts clean. The imperative dialogs hand their callbacks a `ctl` (`{ setLocked(bool) }`): `onConfirm: async (ctl) => { ctl.setLocked(true); await save(); ctl.setLocked(false) }`. Calling it after the dialog closed is a no-op.',
         },
       ],
       api: [
@@ -861,7 +861,7 @@ const doc: DocTopic = {
             { name: 'closeOnMask', type: 'boolean', def: "'true'", desc: { zh: '点遮罩关闭；误触代价大的场景设 false', en: 'Close on mask click; set false where mis-clicks are costly' } },
             { name: 'escClose', type: 'boolean', def: "'true'", desc: { zh: 'Esc 关闭', en: 'Close on Esc' } },
             { name: 'busy', type: 'boolean', def: 'false', desc: { zh: '有异步在跑（footer 里的 `Button` 正在 loading）：遮罩 / Esc / ✕ 三条关闭路径一起失效，内容照常。否决项，不替代 closeOnMask / escClose', en: 'Async work in flight (a footer `Button` is loading): mask / Esc / ✕ all stop closing while content keeps rendering. A veto, not a replacement for closeOnMask / escClose' } },
-            { name: 'locked', type: 'boolean', def: 'false', desc: { zh: '**锁死全部交互**（与 loading 解耦）：面板整块 `inert` —— 里面任何控件（自绘滑块、原生 input、按钮、下拉）点不到、Tab 也进不去；三条关闭路径同时失效；压一层灰 + 鼠标变禁止手势。受控项、不落内部 state（关掉重开自然回到未锁）；不碰子控件的 `disabled`，原本禁用的解锁后照样禁用', en: '**Locks every interaction** (decoupled from loading): the panel becomes `inert` — no control inside (custom slider, native input, button, select) can be clicked or reached with Tab; all three close paths stop working; a dim layer plus a not-allowed cursor. Controlled and stateless (reopening starts unlocked); it never touches a child’s `disabled`, so already-disabled controls stay disabled after unlocking' } },
+            { name: 'locked', type: 'boolean', def: 'false', desc: { zh: '**锁死全部交互**（与 loading 解耦）：面板里的核心控件各自按**自己的禁用态**渲染（灰掉、点不动、Tab 跳过），再盖一层**全透明**点击层兜住自绘元素与鼠标（禁止手势）—— **不压任何灰色遮罩**；同时 Tab 键整个吃掉、锁定瞬间把面板里的活动焦点 blur 掉（自绘的 input 也打不了字）；三条关闭路径同时失效。自绘的原生表单元素会顺带**近似变灰**（一条特异性为 0 的规则，只写 opacity / cursor，被你自己任何一条规则或 `--dshpc-lock-dim: 1` 覆盖掉）。只做「或」、不写回调用方的 `disabled`：本来禁用的解锁后照样禁用，锁定期间改的也不被覆盖。受控项、不落内部 state（关掉重开自然回到未锁）', en: '**Locks every interaction** (decoupled from loading): core controls inside render in **their own disabled state** (dimmed, unclickable, skipped by Tab), plus a **fully transparent** click layer that catches self-drawn elements and the pointer (not-allowed cursor) — **no dim veil at all**; Tab is swallowed outright and whatever was focused inside is blurred on lock (so a self-drawn input cannot be typed into); all three close paths stop working. Self-drawn native form elements get an **approximate dim** too (one zero-specificity rule writing only opacity / cursor, beaten by any rule of yours or by `--dshpc-lock-dim: 1`). It only ORs and never writes back a caller’s `disabled`: already-disabled controls stay disabled after unlocking, and mid-lock changes are not overwritten. Controlled and stateless (reopening starts unlocked)' } },
             { name: 'maxWidth', type: 'string', def: '按 size', desc: { zh: '任意 CSS 值，覆盖 size 的宽度上限；不要用 vw（遮罩已按右侧分栏让位）', en: 'Any CSS value, overriding the size’s max width; avoid vw (the mask already yielded to the right column)' } },
             { name: 'hideHeader', type: 'boolean', def: "'false'", desc: { zh: '不渲染头部（沉浸式）', en: 'Skip header (immersive)' } },
             { name: 'footer', type: 'ReactNode', def: '—', desc: { zh: '底栏（按钮区；上下内距相等、内容垂直居中）', en: 'Footer (button area; symmetric padding, vertically centred)' } },
@@ -945,7 +945,7 @@ const doc: DocTopic = {
             { name: 'open', type: 'boolean', def: 'true', desc: { zh: '受控开关：传 false 时先播收起动画再卸载（想有收起效果就常驻渲染它、只切这个布尔）', en: 'Controlled flag: false plays the collapse animation before unmounting (keep it mounted and toggle this to get the exit motion)' } },
             { name: 'closeOnMask / escClose', type: 'boolean', def: "'true' / 'true'", desc: { zh: '点遮罩关闭 / Esc 关闭', en: 'Close on mask click / on Esc' } },
             { name: 'busy', type: 'boolean', def: 'false', desc: { zh: '有异步在跑（footer 里的 `Button` 正在 loading）：遮罩 / Esc / ✕ 三条关闭路径一起失效，内容照常。否决项，不替代 closeOnMask / escClose', en: 'Async work in flight (a footer `Button` is loading): mask / Esc / ✕ all stop closing while content keeps rendering. A veto, not a replacement for closeOnMask / escClose' } },
-            { name: 'locked', type: 'boolean', def: 'false', desc: { zh: '锁死全部交互（含义同 `Modal.locked`）：抽屉整块 `inert`、点不到也 Tab 不进去，三条关闭路径同时失效，压一层灰 + 禁止手势', en: 'Lock every interaction (same as `Modal.locked`): the drawer goes `inert` — no clicks, no Tab — all three close paths stop working, plus a dim layer and a not-allowed cursor' } },
+            { name: 'locked', type: 'boolean', def: 'false', desc: { zh: '锁死全部交互（含义同 `Modal.locked`）：核心控件各自按自己的禁用态渲染 + 全透明点击层 + 三条关闭路径失效；不压灰色遮罩、不写回任何 `disabled`', en: 'Lock every interaction (same as `Modal.locked`): core controls render in their own disabled state, a fully transparent click layer catches the rest, all three close paths stop working; no dim veil and no writing back to any `disabled`' } },
             { name: 'width / minWidth / maxWidth', type: 'number / number / number', def: '460 / 320 / —', desc: { zh: '初始宽度 / 拖拽下限 / 拖拽上限（px；上限缺省 = 遮罩盒宽）', en: 'Initial width / resize floor / resize ceiling (px; ceiling defaults to the mask box)' } },
             { name: 'resizable', type: 'boolean', def: 'true', desc: { zh: '能否拖宽（关掉就没有拖拽条）', en: 'Whether it resizes by dragging (off = no handle)' } },
             { name: 'footer / children', type: 'ReactNode / ReactNode', def: '— / —', desc: { zh: '底栏 / 主体（主体是唯一滚动容器）', en: 'Footer / body (the body is the only scroll container)' } },

package/docs/help/ui.md

@@ -696,9 +696,9 @@ Modal 是自绘 overlay，不走 react-dom portal。
 
 > EN: The callback’s return value decides whether it closes: **only `false`** (returned directly, or resolved to `false`) means it did not succeed — the dialog stays for a retry; `true` / `undefined` / anything else closes as usual; a rejection also keeps it open (the error is logged). The callback owns its failure message, so call sites need no `try/catch`.
 
-**要「整框谁都别动」就传 `locked`**，别拿按钮 loading 顶替 —— 两者是两件事：loading 只管那一颗按钮转圈，`locked` 管整块面板不可交互（自绘滑块、原生 input、下位选择器一并管住）+ 三条关闭路径失效 + 压灰与禁止手势。声明式传 `locked={saving}` 即可；它是受控项，不传 = 未锁，关掉重开自然复位，也不会改动任何子控件自己的 `disabled`。命令式那两个函数的回调会收到 `ctl`（`{ setLocked(bool) }`），在异步过程中自己开 / 关：`onConfirm: async (ctl) => { ctl.setLocked(true); await save(); ctl.setLocked(false) }`；框关掉之后再调 `setLocked` 是空操作。
+**要「整框谁都别动」就传 `locked`**，别拿按钮 loading 顶替 —— 两者是两件事：loading 只管那一颗按钮转圈，`locked` 管整块面板。做法是**控件各自按自己的禁用态渲染**（Button / Input / Textarea / Checkbox / Segmented / Picker / 日期选择 / 分页 都会自己变灰并真的禁用，Tab 自然跳过），再盖一层**全透明**点击层兜住自绘元素与鼠标 —— 所以界面不会整体蒙灰（蒙灰会让人以为坏了），只有控件自己变灰 + 禁止手势。它**只做「或」、从不写回**任何 `disabled`：本来禁用的解锁后照样禁用，锁定期间你把某个控件改成能用 / 禁用，解锁后也照你的。声明式传 `locked={saving}` 即可；受控项，不传 = 未锁，关掉重开自然复位。命令式那两个函数的回调会收到 `ctl`（`{ setLocked(bool) }`）：`onConfirm: async (ctl) => { ctl.setLocked(true); await save(); ctl.setLocked(false) }`；框关掉之后再调是空操作。
 
-> EN: **When the whole dialog must be untouchable, pass `locked`** — do not fake it with button loading: loading only spins that one button, while `locked` makes the entire panel non-interactive (custom sliders, native inputs and selects included), disables all three close paths, dims the surface and shows a not-allowed cursor. Declaratively just pass `locked={saving}`; it is controlled and stateless — omitted means unlocked, reopening starts clean, and it never touches a child’s own `disabled`. The two imperative dialogs hand their callbacks a `ctl` (`{ setLocked(bool) }`) so you can flip it mid-flight: `onConfirm: async (ctl) => { ctl.setLocked(true); await save(); ctl.setLocked(false) }`. Calling `setLocked` after the dialog closed is a no-op.
+> EN: **When the whole dialog must be untouchable, pass `locked`** — do not fake it with button loading: loading only spins that one button, while `locked` covers the whole panel. It works by letting **each control render its own disabled state** (Button / Input / Textarea / Checkbox / Segmented / Picker / date picker / pagination all dim themselves and are genuinely disabled, so Tab skips them), plus a **fully transparent** click layer that catches self-drawn elements and the pointer — so the surface is never dimmed as a whole (a veil reads as "the app broke"); only the controls dim and the cursor turns not-allowed. It **only ORs and never writes back** any `disabled`: already-disabled controls stay disabled after unlocking, and anything you flip mid-lock stays as you left it. Declaratively pass `locked={saving}`; it is controlled and stateless — omitted means unlocked, reopening starts clean. The imperative dialogs hand their callbacks a `ctl` (`{ setLocked(bool) }`): `onConfirm: async (ctl) => { ctl.setLocked(true); await save(); ctl.setLocked(false) }`. Calling it after the dialog closed is a no-op.
 
 | 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
 |---|---|---|---|---|
@@ -728,7 +728,7 @@ Modal 是自绘 overlay，不走 react-dom portal。
 | `closeOnMask` | `boolean` | 'true' | 点遮罩关闭；误触代价大的场景设 false | Close on mask click; set false where mis-clicks are costly |
 | `escClose` | `boolean` | 'true' | Esc 关闭 | Close on Esc |
 | `busy` | `boolean` | false | 有异步在跑（footer 里的 `Button` 正在 loading）：遮罩 / Esc / ✕ 三条关闭路径一起失效，内容照常。否决项，不替代 closeOnMask / escClose | Async work in flight (a footer `Button` is loading): mask / Esc / ✕ all stop closing while content keeps rendering. A veto, not a replacement for closeOnMask / escClose |
-| `locked` | `boolean` | false | **锁死全部交互**（与 loading 解耦）：面板整块 `inert` —— 里面任何控件（自绘滑块、原生 input、按钮、下拉）点不到、Tab 也进不去；三条关闭路径同时失效；压一层灰 + 鼠标变禁止手势。受控项、不落内部 state（关掉重开自然回到未锁）；不碰子控件的 `disabled`，原本禁用的解锁后照样禁用 | **Locks every interaction** (decoupled from loading): the panel becomes `inert` — no control inside (custom slider, native input, button, select) can be clicked or reached with Tab; all three close paths stop working; a dim layer plus a not-allowed cursor. Controlled and stateless (reopening starts unlocked); it never touches a child’s `disabled`, so already-disabled controls stay disabled after unlocking |
+| `locked` | `boolean` | false | **锁死全部交互**（与 loading 解耦）：面板里的核心控件各自按**自己的禁用态**渲染（灰掉、点不动、Tab 跳过），再盖一层**全透明**点击层兜住自绘元素与鼠标（禁止手势）—— **不压任何灰色遮罩**；同时 Tab 键整个吃掉、锁定瞬间把面板里的活动焦点 blur 掉（自绘的 input 也打不了字）；三条关闭路径同时失效。自绘的原生表单元素会顺带**近似变灰**（一条特异性为 0 的规则，只写 opacity / cursor，被你自己任何一条规则或 `--dshpc-lock-dim: 1` 覆盖掉）。只做「或」、不写回调用方的 `disabled`：本来禁用的解锁后照样禁用，锁定期间改的也不被覆盖。受控项、不落内部 state（关掉重开自然回到未锁） | **Locks every interaction** (decoupled from loading): core controls inside render in **their own disabled state** (dimmed, unclickable, skipped by Tab), plus a **fully transparent** click layer that catches self-drawn elements and the pointer (not-allowed cursor) — **no dim veil at all**; Tab is swallowed outright and whatever was focused inside is blurred on lock (so a self-drawn input cannot be typed into); all three close paths stop working. Self-drawn native form elements get an **approximate dim** too (one zero-specificity rule writing only opacity / cursor, beaten by any rule of yours or by `--dshpc-lock-dim: 1`). It only ORs and never writes back a caller’s `disabled`: already-disabled controls stay disabled after unlocking, and mid-lock changes are not overwritten. Controlled and stateless (reopening starts unlocked) |
 | `maxWidth` | `string` | 按 size | 任意 CSS 值，覆盖 size 的宽度上限；不要用 vw（遮罩已按右侧分栏让位） | Any CSS value, overriding the size’s max width; avoid vw (the mask already yielded to the right column) |
 | `hideHeader` | `boolean` | 'false' | 不渲染头部（沉浸式） | Skip header (immersive) |
 | `footer` | `ReactNode` | — | 底栏（按钮区；上下内距相等、内容垂直居中） | Footer (button area; symmetric padding, vertically centred) |
@@ -800,7 +800,7 @@ Modal 是自绘 overlay，不走 react-dom portal。
 | `open` | `boolean` | true | 受控开关：传 false 时先播收起动画再卸载（想有收起效果就常驻渲染它、只切这个布尔） | Controlled flag: false plays the collapse animation before unmounting (keep it mounted and toggle this to get the exit motion) |
 | `closeOnMask / escClose` | `boolean` | 'true' / 'true' | 点遮罩关闭 / Esc 关闭 | Close on mask click / on Esc |
 | `busy` | `boolean` | false | 有异步在跑（footer 里的 `Button` 正在 loading）：遮罩 / Esc / ✕ 三条关闭路径一起失效，内容照常。否决项，不替代 closeOnMask / escClose | Async work in flight (a footer `Button` is loading): mask / Esc / ✕ all stop closing while content keeps rendering. A veto, not a replacement for closeOnMask / escClose |
-| `locked` | `boolean` | false | 锁死全部交互（含义同 `Modal.locked`）：抽屉整块 `inert`、点不到也 Tab 不进去，三条关闭路径同时失效，压一层灰 + 禁止手势 | Lock every interaction (same as `Modal.locked`): the drawer goes `inert` — no clicks, no Tab — all three close paths stop working, plus a dim layer and a not-allowed cursor |
+| `locked` | `boolean` | false | 锁死全部交互（含义同 `Modal.locked`）：核心控件各自按自己的禁用态渲染 + 全透明点击层 + 三条关闭路径失效；不压灰色遮罩、不写回任何 `disabled` | Lock every interaction (same as `Modal.locked`): core controls render in their own disabled state, a fully transparent click layer catches the rest, all three close paths stop working; no dim veil and no writing back to any `disabled` |
 | `width / minWidth / maxWidth` | `number / number / number` | 460 / 320 / — | 初始宽度 / 拖拽下限 / 拖拽上限（px；上限缺省 = 遮罩盒宽） | Initial width / resize floor / resize ceiling (px; ceiling defaults to the mask box) |
 | `resizable` | `boolean` | true | 能否拖宽（关掉就没有拖拽条） | Whether it resizes by dragging (off = no handle) |
 | `footer / children` | `ReactNode / ReactNode` | — / — | 底栏 / 主体（主体是唯一滚动容器） | Footer / body (the body is the only scroll container) |

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 |