跨端: 壁纸遮盖色改用页面底色系（mask 两套主题都深，浅色下方向与 WebUI 相反）；模态遮罩保持 mask

pi 提了一个**方向性**疑问，让我先把值读出来再定 —— 读完确认**他是对的**，而且这是"机制上确定不同"。

## 实测（两张 SDK 表交叉验证，不靠记忆）

`ets/build-tools/ets-loader/sysResource.js` 给名字→id，`previewer/.../resources.txt` 给 id→值：

| 令牌 | 浅色主题 | 深色主题 |
|---|---|---|
| `ohos_id_color_mask_regular`（原 `Theme.overlay`） | `#99182431` **深蓝灰** | `#b2000000` 黑 |
| `ohos_id_color_background` | `#ffffffff` **白** | `#ff18181a` 近黑 |

⇒ mask 的 light/regular/thick 是**浓度档**（同一深色的三个 alpha），不是深浅两套值：
它在**两套主题下都是深色**（模态遮罩语义）。而 WebUI 的 `--bg-scrim` 浅色是**白**
（原话「浅色下用白把花哨的图案洗淡」）—— 壁纸遮盖用 mask 就是**反方向**：
浅色主题下把预设压暗，而 WebUI 是把它洗淡。

## 改法

- 新增 `Theme.wallpaperScrim = $r('sys.color.ohos_id_color_background')`（页面底色系：
  浅色白、深色近黑，**自动换向**，与"朝底色淡化"同一意图）；预设档与图片档的遮盖层都用它。
- `Theme.overlay`（mask）**只留给模态弹层**（那里语义确实是压暗背后）。
- 不复用 `pageBg` 的原因写进注释：页面底在背景开启时会被换成**透明**
  （`bgActive ? Color.Transparent : Theme.pageBg`），而遮盖层**永远要一个真实颜色** ——
  两个用途生命周期不同，共用一个名字迟早坏一头（这个仓库撞过四次的模式）。

## 判据（从 SDK 读真值再判，不写死结论）

断言「mask 两套主题都深」「页面底色系浅白深黑」「WebUI 的 `--bg-scrim` 浅色是白」，
再落到代码：两处遮盖层必须用 `wallpaperScrim`、弹层仍用 `overlay`、两个令牌不许混用。
**这样"令牌选错方向"以后不能靠记性避免。**

变异：遮盖退回 mask → 红 1 条；只改一层 → 红 2 条。

## 文档

§7.17b-2 记这次读数（表格 + 两张表怎么读 + 为什么不复用 pageBg + 变异结果）；
§7.12 有意差异表加一行（遮盖色令牌：两个语义两个令牌，"不允许混用"）。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（12 个判据文件全绿 + vitest 258/258；harmony-appearance 23 → 24 条）。

docs/HARMONY-ALIGN-PLAN.md

@@ -517,6 +517,7 @@ deb 也不必从 targets 里摘。已写进 `client/electron/BUILD.md`（含排
 | 遮罩 | 自声明 `--bg-scrim` + `--bg-dim` 两段式 | 系统 `sys.color.ohos_id_color_mask_regular` | 遮罩要随主题换向（浅色洗白/深色压黑），这件事系统已经做了 |
 | **品牌色** | `--c-blue-600: 37 99 235` | `Theme.accent = '#2563EB'` | **不允许差异** —— 两个客户端是同一个产品 |
 | **本地外观缓存的键** | 全局常量 `agentmail.background` | **按账号**：`appearance.<accountId>` | **鸿蒙是对的，不许为"对齐"退回全局键** —— 全局键的后果是切到服务端没有记录的账号时，`saved=false` 分支会把**上一个账号的外观** push 上去（新账号"继承"了外观，而且写进了服务端）。pi 2026-09-14 确认这条记在 WebUI 侧为开项（换键，或至少在把继承来的值当"本地的"推给从未有记录的账号前停一下） |
+| **遮盖色的令牌** | `--bg-scrim`（浅色白 / 深色黑，"朝底色淡化"） | `Theme.wallpaperScrim` = `sys.color.ohos_id_color_background`（同向）；`Theme.overlay` = mask **只用于模态弹层** | **不允许混用** —— mask 两套主题下都是深色（浅色 `#99182431`），拿它当壁纸遮盖会在浅色主题下压暗（与 WebUI 反向）。两个语义两个令牌，理由与实测值见 §7.17b-2 |
 | **遮罩浓度的默认值** | 两套：store 的 `dim=24/blur=8` 与 `lib/appearance.ts` 的 `clamp(...,12,4)` | 12 / 4（只有一套） | 服务端**缺字段**时真正落地的是 `clamp` 的默认值，所以按 12/4 对齐；WebUI 那两套值迟早要统一（pi 记在他那边） |
 
 **关于 `overlayColor` / `overlayAlpha` 消失**（pi 要求把删除理由记在这里，否则下一个人会当成漏改补回来）：
@@ -826,6 +827,40 @@ SDK 锚点（免得后人凭记忆写）：回调接口是 `@ohos.app.ability.En
 踩过两个编译错：`Configuration.colorMode` 是**枚举 | undefined**，字段写成 `number` 直接报错；
 `ApplicationContext.on('environment')` 返回的是 **number 型 callbackId**（不是 void）。
 
+### 7.17b-2 遮盖色的**方向**：模态遮罩 ≠ 壁纸遮盖（pi 的方向性疑问，按实测改）
+
+pi 的疑问：「系统那三个 `mask_*` —— light/regular/thick 是**浓度档**（同一个色的三个 alpha），
+不是深浅两套值；用途是**模态遮罩**（弹层背后压暗），所以两套主题下通常都是深色。
+如果壁纸遮盖用 mask 色，**浅色主题下会把预设压暗，而 WebUI 是把预设洗淡**：方向相反。」
+
+他让我先把值读出来再定。读数方式（两张 SDK 表交叉验证，不靠记忆）：
+`ets/build-tools/ets-loader/sysResource.js` 给**名字→id**，
+`previewer/common/resources/entry/resources.txt` 给 **id→值**：
+
+| 令牌 | 浅色主题 | 深色主题 |
+|---|---|---|
+| `ohos_id_color_mask_regular`（= 原 `Theme.overlay`） | `#99182431` **深蓝灰** | `#b2000000` 黑 |
+| `ohos_id_color_mask_thick` / `_light` | `#cc182431` / `#66182431` 深 | 同为深 |
+| `ohos_id_color_background` | `#ffffffff` **白** | `#ff18181a` 近黑 |
+
+⇒ **pi 是对的，而且这是"机制上确定不同"**：mask 在两套主题下都是深色（它是模态遮罩），
+而 WebUI 的 `--bg-scrim` 浅色是**白**（把花哨的图案洗淡）、深色才是黑。
+壁纸遮盖用 mask = 浅色下把预设压暗，方向与 WebUI 相反。
+
+**改法**：新增 `Theme.wallpaperScrim = $r('sys.color.ohos_id_color_background')`
+（页面底色系：浅色白、深色近黑，自动换向，与"朝底色淡化"同一意图），
+壁纸两档的遮盖层都改用它；`Theme.overlay`（mask）**只留给模态弹层**（那里的语义确实是压暗背后）。
+
+**为什么不再复用 `pageBg`**（值一样是 `ohos_id_color_background`）：页面底在背景开启时会被换成
+语义上的**透明**（`bgActive ? Color.Transparent : Theme.pageBg`），而遮盖层**永远要一个真实颜色**。
+两个用途生命周期不同，共用一个名字迟早坏一头 —— 就是这个仓库撞过四次的模式
+（`text-white` vs `bg-white`、`--c-*` vs `--s-*`、掩码 vs 遮罩）。
+
+**判据**：从 SDK 两张表读出真值，断言「mask 两套主题都深」「页面底色系浅白深黑」
+「WebUI 的 `--bg-scrim` 浅色是白」，再落到代码（两处遮盖层都必须用 `wallpaperScrim`、
+弹层仍用 `overlay`）。变异：遮盖退回 mask → 红 1 条；只改一层 → 红 2 条。
+**这样"令牌选错方向"以后不能再靠记性避免。**
+
 ### 7.17c 手写色清册升级成**跨文件按类扫**（pi 建议）
 
 原来的 A2 只保护 `Theme.ets`；而 `Wallpaper.ts` 也有手写色（14 个预设色）。