# 更新日志

> 本仓库的发布谱系分两段，**拉代码前请先对齐 tag**：
>
> - **alpha.2 谱系**（当前）：`package.json` 0.4.0 起；tag 带 `-alpha2` 后缀，如 `v0.5.2-alpha2`。
> - **rc.8 谱系**（历史）：`package.json` 0.3.0 及更早；`git tag -l` 里**不带后缀**的 `v0.4.0`–`v0.7.0` 也**全部**指向这一段的提交。
>
> 两段谱系版本号不连续、互相独立，同名版本号（如都有 0.4.0 / 0.5.x）**不是同一棵树**。

---

## alpha.2 谱系

### 0.5.4

**WE 壁纸接入更丝滑**（挂载 / 切换 / 关闭不再是一刀切）

- **挂载淡入**：图层以 `opacity 0 → 1`（480ms ease-out）淡入，`will-change: opacity` 走合成层。
  视频类等 `readyState >= 2`（真的有帧）再揭示，避免在空盒子上爬升；iframe 类立即揭示
  ——等它的文档会把页面干暗着晾住（scrim 从创建就在爬升），而那 480ms 本身已经盖住首帧。
- **切换 crossfade**：旧图层淡出（380ms ease-in）与**新图层淡入同时进行**，不是先删后插。
  实测同屏两图层共存 29 帧，两条过渡都走完（`elapsedTime` 0.38s / 0.48s）。
- **关闭淡出 + 延迟拆除**：图层与 scrim 一起淡出，而 **WE 模式本身（`body[data-we-wallpaper]`、
  scrim、女仆主题挂起）延后到淡出结束才卸下**。这一点是必须的：WE 模式一撤，恢复出来的
  不透明页面背景会画在正在淡出的图层**上面/下面同时铺满**，整段淡出就白做了。
  实测淡出的 68 帧采样里 `data-we-wallpaper` 68 帧仍在。
- 尊重 `prefers-reduced-motion`：该偏好下过渡时长归零，但延迟拆除的定时逻辑照旧（不靠过渡事件驱动）。
- 标签页隐藏时暂停壁纸视频（`visibilitychange`），回到前台且用户仍开着播放时恢复；
  暂停帧留在屏幕上，因此切回来不会闪。

**修复**

- `syncLayers()` 的 scrim 分支用了**创建之前**查到的 `scrim` 变量：首次挂载时该变量仍是 `null`
  （新 scrim 只是被 append 进了 DOM，没有回填变量），`scrim.classList` 抛 `TypeError`，
  把同一次同步里**后面的** `body[data-we-wallpaper]` 设置与女仆主题挂起全部跳过
  —— 表现是"壁纸挂上了，但 WE 模式没生效"（页面没透明、玻璃 token 与浅色文字 ramp 都没上）。
  该缺陷由本次改动引入，并在隔离实例探针里当场抓到（`pageerror` + `active=false`）。

**验证**（隔离实例：独立 `DSH_HOME` + 备用端口 + 系统 Chrome，用户正在跑的实例完全没碰）

- 走真实 UI 路径：设置 → 外观 → 壁纸引擎 → 弹窗选瓦片 →（换一张）→ 关弹窗 → 点主题磁贴关闭。
- 33/33 断言通过，含三个独立观测窗口：挂载淡入 / 切换 crossfade / 关闭淡出。
- 时长用 `TransitionEvent.elapsedTime` 判定（浏览器给出的过渡真实时长），**不用采样序列推算**：
  同源 iframe 加载重型 web 壁纸会占满同一渲染进程的主线程，`requestAnimationFrame` 被饿死
  （实测挂载窗口里 341ms 只有 1 帧），据采样算出的"爬升 137ms"是纯 artifact。

### 0.5.3

**代码精简**
- 删除三处已证实无引用的死代码：
  - 旧版 `WallpaperPicker` 组件 + 整段 `.we-picker*` 样式模板（`src/client/wallpaper-layer.ts`，−298 行）；
  - 未使用的 `.modalPreview` 类（`src/client/DreamSkinSettings.module.css`）；
  - 整份未被任何模块 import 的 `src/client/liquid-glass/liquid-glass.module.css`（127 KB）。
- 实际在用的壁纸选择器是 `DreamSkinSettings.tsx` 的 `WallpaperEngineBlock`（样式走 CSS module），与被删组件无关。
  已在**隔离实例**（独立 `DSH_HOME`、备用端口）实机验证：设置弹窗打开、外观区渲染、壁纸引擎块可点开弹窗，全程无页面报错。
- 产物 `lib/client.js` 重建后同步缩至 4.66 MB。

**仓库瘦身**
- 不再跟踪 `lib` 的构建噪声（`lib/client.js.map`、`lib/types/**/*.js`、`*.js.map`、`*.d.ts.map`，共 127 个文件 / 9.6 MiB）。
  真正发布的是 `package.json#files` 声明的那几个：`lib/index.js`、`lib/invariant.js`、`lib/client.js`、`lib/types/**/*.d.ts`。

**文档**
- README 精简为「安装 / 功能 / 截图 / 引用 / 开发」五段，把逐条根因与实测记录集中到本 CHANGELOG。
- 修正 README 一处事实错误：音效包是 **2 个**（小黄鸭 / fx1），不是 4 个（源码 `soundOpt('duck'|'fx1')`）。

### 0.5.2
- 修复：插件自有 `Modal`（portal 到 `body`）不再被为主题宿主弹窗写的 5 条泛化 `[role='dialog'][aria-modal='true']` 规则误套。
  实测插件弹窗子树 **56 个元素** computed 被改（边框换成暖金、作者写死的两条阴影被替换成主题阴影、瓦片底色换奶油、遮罩从中性黑变海军蓝）。
  插件 `Modal` 根节点加稳定标记 `data-dshw-surface`，宿主规则改用 `:not(标记, 标记 *)` 精确排除。
- 修复：`package.json` 去掉 UTF-8 BOM（严格 `JSON.parse` 会抛 `Unexpected token`）。
- 修复：设置面板里 Codex 标签重复词。

### 0.5.1
- 修复：主题触发器框艺不再外泄到设置面板的两行（壁纸主题 / 壁纸引擎）。
  此前整行被 `border-image` 的 `fill` 画成藏蓝描金、字体被换成衬线、行高抬到 50px、行自身 hover 底被压掉。
- 修复：插件里一条未作用域的 `:focus-visible` 会变成全应用规则，把宿主原生控件的焦点环也一并换掉（实测 32 个键盘可达元素里 28 个被换）；现已收进插件自有控件。
- 视觉：分组计数胶囊改用可辨悬停底色（原先与卡面同色被画平，读起来就是裸文字）；壁纸瓦片圆角与主题瓦片统一 10px。
- 修复：3 处拼错的样式变量（`--dsw-alias-brand` 并不存在，浏览器静默回退成离线色值）→ 改用真实的 `brand-primary`。
- 修复：鼠标光标开关关闭后再打开，皮肤一定可见（自动恢复 `default` 态）。

### 0.5.0
- 修复：深海女仆工坊深色档改用**夜底色** scrim（此前沿用纸白）。
  否则夜版底图被洗成灰蓝中调，浅墨元信息（回合尾用时 / 时间戳 / 上下文占用百分比）会掉到约 **1.4:1**。
- 深色档元信息墨色按夜海军蓝底重校（`label-tertiary` `#96a6c9` → `#9dabce`，最窄列实测 4.41 → 4.61+）。

### 0.4.0
- **迁移到 DSH alpha.2 客户端契约**：
  - store：`@deepseek-ai/dsh-client-runtime` → `@deepseek-ai/dsh-client-store`
  - `ClientContext`：`dsh-client-runtime/client` → `@deepseek-ai/cordis`
  - renderer 类型合并：来自 ui-slots → `@deepseek-ai/dsh-client-ui-renderer/client`
- 清单声明 `engines.dsh: ">=0.1.6-alpha.2"` 与 `dsh.manifestVersion: 1`。
- ⚠️ alpha.2 与 rc.8 的客户端插件契约不同，**同一份构建无法同时兼容**。

---

## rc.8 谱系（历史）

> 以下版本属于 alpha.2 迁移**之前**的历史（`v0.1.0`–`v0.7.0`），仅供考古，与当前代码不连续。

- **0.7.0** — 34 套主题（30 套社区 + maid-whale 皮肤）、主题网格可折叠、最小 scrim 可读性下限。
- **0.6.x** — 0.6.0 皮肤改「直接写 body token」应用（maid-whale 路线），不再经 theme-service `register`/`setTheme`；0.6.1 移除诊断日志；0.6.2 重写 README。
- **0.5.x** — 0.5.0 外观页新增壁纸引擎块（选择器 + 4 个效果滑块）；0.5.1 断掉 `applyScrim` 重入循环（`overrideTokens` → `theme/change`）；0.5.2 同步注册预设，修复重启后主题恢复失败。
- **0.4.0** — 外观持久化改走 localStorage（刷新安全）。
- **0.3.x** — 0.3.0 主题改本地-only（6 套）、更名「外观」、网格布局 + 调色板图标 + 明/暗/跟随系统；0.3.1 引入 ui 组件库（Button/Slider）+ scrim 强度滑块；0.3.2 自定义主题（壁纸 URL + 主色/背景/文字选择器）。
- **0.2.0** — 主题选择持久化 + 悬停壁纸预览 + 更轻的 scrim。
- **0.1.x** — 0.1.0 初版（33 套 Dream Skin 主题，20 套带壁纸）；0.1.1 壁纸改从 GitHub raw URL 加载 + 焦点定位（去掉 base64 内嵌）。