# 变更记录

本文件记录 dsh-ui-font 的版本变化、新功能和问题修复。

格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循语义化版本。

## [0.9.6]

### 修复

- **DSH ≥ 0.1.2-rc.1 升级后全局字号再次不影响对话正文、准星只显示「主界面」**。
  新版主题把正文字号体系整个重构为「内容轴」：
  - 新增原生字号设置（设置 → 通用 → 字号，12–17px），由 ThemePresenter 以
    **body 内联 style** 写入 `--dsh-content-font-size`
  - `--dsw-font-markdown-*` 的值不再是 `14px/22px` 字面量，全部变为
    `var(--dsh-content-font-size,…)` / `calc(21px + var(--dsh-content-font-delta))`
    形式的表达式（h1–h3 与行高经 delta 派生、表格经 secondary 派生，派生变量
    声明在 body 上）
  三处连锁断裂与本版的修复：
  - **库存解析失效**：`stockSizeOf`/stocks/`buildTokenCss` 只认 `^数字px` 字面量，
    var()/calc() 形式全部解析失败 → 令牌库存为空 → body 覆盖不发。新增
    `resolveTokenValue`：按当前原生字号（读 body 内联值，非 computed，避免被
    本插件自己的覆盖污染）代入 content 变量并求值 calc，新旧两种值形态都兼容
    （负 delta 亦正确）
  - **令牌归属失效**：消费规则的字号声明从 `font-size:var(--x)` 长写法改为
    `font:var(--x)` 简写后，Chromium 的 CSSOM 会把 font-size 长项序列化为解析
    后的像素值，var() 被隐藏 → 家族提取失败 → 规则被整体丢弃 → 准星兜底
    「主界面」。家族提取改从规则原文（cssText 永远保留 var() 原文）读取；直接
    消费 `--dsh-content-font-size*` 的规则归入「聊天正文」家族；
    `--dsw-font-family`（纯字体族引用）不再误登记为字号家族
  - **覆盖通道失效**：对 var() 表达式内的字面量做缩放是无效的（var 仍解析到
    内联值）。改为在 body 上以 `!important` 覆盖上游轴
    `--dsh-content-font-size`（important 样式表声明压过非 important 内联样
    式）——delta/secondary/h1–h3/行高整条派生链在 body 上自动跟随，一处覆盖
    全族生效；净调整为零时不发该覆盖，原生字号设置保持可用。h1/h2/h3/表格的
    perToken 独立偏移通过「代入计算后的具体 px 覆盖」实现分歧
  - 新增 body style 属性的 MutationObserver（防抖 200ms）：原生字号/主题变化
    重写内联轴时自动重算叠加——本插件唯一的观察器，依然零轮询
  - 新增 `tools/test-content-axis.cjs`：以安装的主题包与 shell CSS 的**真实**
    令牌值/规则文本做解析与归属回归（含原生 12/17 的负/正 delta 跟踪）

## [0.9.5]

### 修复

- **插件加载失败：`Cannot find package '@deepseek-ai/dsh-settings'`**（0.9.3 引入）。
  settings.yaml 持久化（PR #2）在 host 侧顶层静态 import 了
  `@deepseek-ai/dsh-settings` 与 `@deepseek-ai/schemastery`，并以 peerDependencies
  声明。但 `link:` 方式挂载的插件被 Node 以真实路径解析（E 盘目录链），既走不到
  profile 的 node_modules，E 盘上也没有这两个包——模块链接阶段即失败，插件整体
  无法加载，dsh 升级后首次以新挂载方式启动时暴露
  修复：恢复零运行时依赖——
  - 命名空间改用常量 `"ui-font"`（`settingsNamespace()` 仅是 kebab-case 规范化）
  - `z.object(...)` 换成手写的规范化函数：补默认值、钳制区间、丢弃畸形条目，
    镜像 client.js `validateSettings()` 的规则；挂 `toJSON()` 以满足
    `ctx.settings.describe()` 的序列化契约
  - 顺带消除了原 schema 的启动脆弱性：schemastery 的区间校验对脏数据是抛错
    语义，手动编辑 settings.yaml 写出超范围值（如 `delta: 99`）会让插件在
    register 阶段直接加载失败；新函数永不抛错，脏值读取时静默修正、下次保存
    自愈写回
  - 409 冲突识别从 `instanceof SettingsConflictError` 改为稳定机器码
    `e.code === "SETTINGS_CONFLICT"`（该错误类本就无法从插件目录导入）
  - package.json 移除这两个 peerDependencies

## [0.9.4]

### 修复

- **字号快捷键的三个疑难症状：「按了没反应要按两次」「按缩小反而变大」「偶尔正常」**。
  根因是持久化层的 HTTP 竞态，三路叠加：
  - 每次按键在 `bumpDelta` 里同步步进缓存后发 POST（连接 A），紧接着
    `reapply()`→`loadSettings()` 发 GET（连接 B）。两个 fetch 并行，GET 常抢在
    POST 落地前返回旧值，`loadSettings` 无条件 `localCache = 旧值` 把刚步进的
    值覆盖回去 → 该次按键视觉上失效（"按两次才生效"）
  - 页面刚加载时缓存是 DEFAULTS（delta=3）种子，首次 GET 未返回前按键会以 3
    为基准步进：持久值 8 的用户按一下缩小直接落到 2（一次跳 6 格）；持久值低
    于 3 的用户按缩小反而落在 2 → 字变大（"按 Ctrl+- 会增加"）
  - 快速连按 +/− 混合时，乱序到达宿主的 POST 让最终值偏离预期，下一次 GET
    把偏离值载回渲染 → 方向翻转
  修复：所有宿主往返（GET 与 POST）排进单一 promise 队列，本页内绝不交错；
  引入写纪元（writeEpoch），加载期间发生过本地写则以本地为准、不用过期响应
  覆盖缓存；`reapply` 改为渲染同步缓存不再 fetch；`bumpDelta` 的读-改-写整体
  入队（必然运行在初始加载之后，种子竞态消除）；设置页 `update` 的合并基准从
  React 旧状态改为同步缓存（打开面板期间的旧状态覆盖问题一并消除）
- **keyCode 187/189 旧路径匹配自 0.9.2 起是死代码**：守卫
  `e.code === "" → return false` 恰好拦掉了唯一需要走 keyCode 的场景（无
  code 的按键事件永远到不了 keyCode 比较）。改为「有真实 code 且未匹配即不
  匹配；无 code 才落 keyCode」
- **小键盘 +/- 不触发快捷键**：`Ctrl+NumpadAdd`/`Ctrl+NumpadSubtract` 现在
  等同 `Ctrl+=`/`Ctrl+-`（仅当存储组合期望 = / - 时）
- **缩放接管兜底**：任一字号快捷键设置后，未被匹配的 Ctrl+ +/- 变体（小键
  盘、多按 Shift、无 code 事件）一律 `preventDefault`，不再漏给浏览器原生页
  面缩放——原生缩放一旦漏进来，页面视觉字号与本插件 delta 脱钩，表现为
  "按了没反应/方向不对"
- **跨标签页漂移**：无轮询是设计使然，但后台标签的缓存会永久过期，回到该
  标签后第一次按键会把 delta 跳回旧值。新增 visibilitychange/focus 时的防抖
  重同步（走队列与写纪元，不会覆盖更新的本地写）
- 移除 `onHotkey` 在 document 上的重复注册（window 捕获已覆盖；匹配时
  `stopImmediatePropagation` 本就阻止了 document 侧重复触发，重复挂载只在未
  匹配按键上白跑一次）
- 新增 `tools/test-persistence-race.cjs`：以模拟宿主时序复现上述全部症状并
  回归新旧逻辑（旧逻辑四场景全败、新逻辑全过）

## [0.9.3]

### 修复

- **DSH ≥ 0.1.1 升级后 AI 回复不再随全局偏移放大**：新版把 `--dsw-font-*` 令牌的
  定义从外壳 `<link href="/assets/*.css">` 样式表挪进了 `dsh-client-ui-theme`
  运行时注入的 `<style data-plugin>`（design-platform.css，声明在 `:root`），
  link 表里只剩 `var()` 消费者。引擎的两处令牌采集（`findShellTokenDecls` 与
  `scan()` 预扫描）都只读 link 表，采集结果为空 → body 上的令牌覆盖一条不发 →
  正文 / 标题 / 行内代码 / 代码块全部保持原尺寸（准星的「文字类型」判定与全局
  滑杆看着正常，唯独不生效）。现改为从**所有可读样式表**（link + 注入 style，
  跳过本插件自己的覆盖表防叠加缩放）合并令牌定义，新旧两种分布都兼容
- **字体族选择可能被 theme 重挂反杀**：`--dsw-font-family` / `--ds-font-family-code`
  的覆盖从 `:root` 挪到 `body` 上——ui-theme 的样式表挂在插件 fiber 上，重激活时
  会先移除再重挂，`:root` 同优先级谁后谁赢，重挂后排到本插件之后会丢掉所选字体
  族；body 层的自定义属性按继承稳定压过任何 `:root` 声明且与标签顺序无关。换肤
  插件在 body 层重声明仍然后赢，「以皮肤为准」的既有约定不变

## [0.9.2]

### 新增

- **全局字号快捷键**：新增长大 / 缩小两个快捷键槽位，按一下全局偏移 ±1px，即时
  生效并同步回设置页。默认留空，各提供 `Ctrl =` / `Ctrl -` 一键预填（会接管浏
  览器同键位的页面缩放——本插件的字号偏移正是浏览器缩放的精细替代）；同样支
  持自由录制，与 UI 捕捉键共用同一套录制交互
- 快捷键引擎支持符号键：补全 `=`、`-`、`[`、`;`、方向键等 14 个键的 code ↔ 短名
  映射（此前只认字母/数字，`Ctrl+=` 无法匹配）

### 修复

- **预填/设置点击后不落盘**：`update()` 的 React 更新器在个别时序下静默丢弃写
  入（控制台验证 `hotkeyUp` 为 undefined 而引擎链路正常）。改为同步直写
  localStorage 优先，setState 作为后续——即使 React 更新器未执行设置也已生效
- **浏览器抢走 Ctrl+=/-**：监听从 document 挪到 **window 捕获阶段**（页面可见
  按键的最早时机）并加 `stopImmediatePropagation`；补 `keyCode 187/189` 旧路
  径匹配（部分键盘布局下 `e.code` 为空）；忽略输入法组合态按键（`isComposing`）
  防误触。控制台实测：存储有值时按键字号即时 ±1 且浏览器不再缩放

### 已知边界

- 焦点位于 iframe 内（如文件预览面板展开时）按键事件不经过主页面，快捷键失
  效——先点一下主界面再按即可

## [0.9.1]

### 新增

- **准星选取改为"声明点"架构**（本轮核心重做）：点击时从元素向上找最近的字号声明
  点，按声明方式自动选择调法——
  - 声明用设计令牌（`var(--dsw-font-*)`）→ 调该令牌的独立偏移（新设置维度
    perToken），**同类文字全局统一变**（聊天正文、标题、行内代码、代码块、各
    类界面文字等 21 个家族，配中文人话名）
  - 声明是写死像素 → 精确到**那一条 CSS 规则**（新设置维度 perRule），只动点中
    的组件。底部 LLM 用量条与用户气泡同属会话插件，现在可各自独立调整
  - 兜不到 → 全局偏移
- 令牌别名追源：代码块字号经 `--dsl-code-block-content-font` 间接引用
  `--dsw-font-markdown-code-block`，登记时自动解析到真实家族

### 修复

- **令牌通道在真实浏览器中完全失效的根因**：Chromium 的 CSSOM
  `style.item()` 枚举**不包含自定义属性**，导致令牌提取永远为空、body 覆盖静
  默不生成——表现为"字体换了但大小不变"（助手正文、轨迹视图等令牌驱动的文
  字全部不缩放，只有硬编码像素的区域能调）。改用 cssText 解析提取
- **刷新页面后覆盖丢失**：插件代码可能在 dist 样式表解析完成前运行首次扫描，
  提取到 0 个令牌。新增就绪等待循环（100ms 重试直至成功，上限约 6 秒）；重启
  后正常而刷新后失效的现象由此解释
- `reapply()` 加异常护栏，单次失败不再中断补扫链；新增
  `window.__dshUiFontDebug` 运行时自检（令牌数、覆盖是否生成、错误信息）
- var 简写误登记：Chromium 对 `font:var(--dsw-font-X)` 的 getPropertyValue 可
  能返回解析后的具体像素值，导致令牌规则被当成插件像素规则（用量条归错桶的
  原因之一）。以规则原文 cssText 中的 var() 为准强制按令牌登记
- 归属判定经历三轮演进（类名索引 → 选择器遍历 → 计算值指纹 → 声明点），最终
  以"规则原文写的变量名"为唯一判据，前几轮的误判（轨迹视图全报外壳、处处双
  归属等）均由声明点架构解决

### 变更

- 令牌驱动的规则不再进入插件像素桶（调插件偏移不再影响令牌文字，各通道互不
  干扰）
- 准星点击 px 组件的目标粒度从"插件"细化为"插件 + 单条规则"；设置页列表仍为
  插件粒度

## [0.9.0] - 未发布

### 新增

- **设置页全面重做**：卡片式布局、配色跟随界面明暗主题（浅色/深色模式自动适配）、统
  一的按钮和间距风格
- **快捷键改为键帽样式展示**（如 `Ctrl` `Alt` `F` 三个键帽），录制中高亮提示
- **微调列表改为步进器控件**（−/+ 按钮），每行显示"合计"胶囊 = 全局偏移 + 个体偏移
  的最终生效值，叠加语义一目了然；✕ 一键清除个体偏移
- 微调列表的描述行同时显示插件描述或字号规则数

### 变更

- **明确偏移语义为叠加制**：每个区域的实际缩放 = 全局偏移 + 该区域个体偏移。引擎本
  来就是这么算的，这次把界面呈现改成显式表达（全局 +6、代码 -6 → 代码区标准大小，
  其余全部 +6）

## [0.8.3]

### 修复

- 准星选取时部分区域（如右侧文件预览面板）点击后误判为"主界面（全局）"：归属索引
  只在进入选取时构建一次，而样式注入晚的插件不在索引里。改为悬停时发现未知类名即
  增量补扫新样式表；祖先链查找从 3 层放宽到 10 层，适应嵌套深的面板

## [0.8.2]

### 修复

- **严重**：准星点击后弹出的悬浮条完全不可用——−/+ 按钮点不动、「完成」无效、页面
  其他元素也点不了，只能刷新页面脱身。原因是点击拦截器在捕获阶段吞掉了包括悬浮条
  在内的所有点击。现在悬浮条内部点击正常放行，点击悬浮条以外任意位置则干净退出

### 变更

- 快捷键从写死的 Ctrl+Shift+F 改为用户自定义，默认**不设置**（避免与各处搜索快捷键
  冲突）；设置页新增录制模式，按下组合键即存；未设置时红色提示

## [0.8.1]

### 新增

- 全局快捷键召唤准星选取（当时为固定 Ctrl+Shift+F，后于 0.8.2 改为可配置）。解决设
  置面板是模态框、挡住待选取界面的问题——关掉设置后随时召唤
- 选取器改为完全自包含的 DOM 实现：悬浮控制条不再依赖设置页的 React 树，关闭设置
  面板后照常使用，调整结果通过事件同步回设置页

## [0.8.0]

### 新增

- **🎯 准星选取（Spy++ 式）**：设置页「选取区域」按钮进入，鼠标变准星，悬停高亮 +
  归属提示（插件名 · 当前字号），点击后就地 −/+ 调整该区域字号，即时生效。ESC / 右
  键取消。基于运行时构建的"类名 → 插件"归属索引

## [0.7.1]

### 修复

- 令牌缩放完全失效的根因修复：官方字号令牌（`--dsw-font-*`）声明在 `body` 选择器而
  非 `:root`，引擎此前只读 `:root` 导致只拿到字体族、拿不到任何字号——表现为"字体
  换了但大小不变"。改为收集样式表中所有声明字体令牌的规则（不限选择器），输出
  body 级覆盖

## [0.7.0]

### 新增

- 全局字号偏移上限从 +8 提高到 +20
- 启动后 1s/3s/8s 三次有界补扫，覆盖惰性注入样式的插件（此前只在启动瞬间扫一次，
  晚注入的插件不生效）。依然没有轮询，收敛后引擎完全静止

## [0.6.0]

### 变更

- 字体下拉列表改为枚举系统真实安装的字体（宿主半边直接解析字体文件的 sfnt name
  表，纯文件读取、跨平台、无子进程），替换此前写死的四个选项。未安装的当前值标记
  "（未安装）"；旧设置键自动迁移到新格式

## [0.5.0]

### 新增

- 微调列表每个插件显示**描述**：宿主半边提供 `POST /api/dsh-ui-font/descriptions`，
  从各 profile 的 node_modules 读取插件 `package.json` 的 description（缺失时回退
  README 首个标题）。修复了 createRequire 在 junction 安装下解析不到兄弟包的问题
  （改为扫描所有 profile 的 node_modules）

### 变更

- 去掉 MutationObserver 后台监视，改为纯手动：启动扫一次 + 打开设置页/点「刷新」才
  重扫。原则：不做用户没要求的后台工作

## [0.4.0]

（此版本号在开发过程中跳过用于内部整理，实际改动并入 0.5.0）

## [1.0.0 计划前的 0.1–0.3 系列]

- 0.1：静态 CSS 覆盖方案（构建产物扫描 + 生成覆盖规则，后退役）
- 0.2：重写为运行时引擎——遍历 `document.styleSheets` 按 `data-plugin` 归属分组，
  运行时发现所有界面插件的字号规则；新增设置页（settings.section 注册）；修复
  `exports.inject` 必须是依赖声明数组而非函数的激活问题（此前设置页静默不出现）
- 0.3：设置页布局与存储优化；`shell`（外壳样式表）作为自有扫描分类命名