@lynn123411/dsh-maple-theme 0.2.0 → 0.3.1

package/DETAILS.md

@@ -35,6 +35,14 @@ ctx.theme.overrideTokens('@lynn123411/dsh-maple-theme', {
 行内样式沿继承链解析得到，所以整套色板仍然由一个数字转动——配置页拨一下色相，令牌不用重新登记。
 disposer 由 `ctx.effect` 持有，插件卸载时整层覆盖一起撤掉。
 
+取色取的是 Maple 在 Obsidian 里**画出来**的结果，不是它写下的变量原值。两者在一处差得很明显：
+侧栏。Maple 的 `--background-secondary` 写的是 `hsl(h-18 8% 93%)`，但那层颜色是垫在
+卡片布局的渐变背景图上、按 `--bg-opacity` 半透明铺开的，眼睛收到的是它与渐变混合之后的颜色——
+实测 `rgb(232, 228, 236)`，也就是 `hsl(270 17% 91%)` 一带：比原值深两档、饱和度翻倍。
+照抄原值会得到一块发白的灰，和正文纸面分不开，看上去像没画上。所以侧栏取实测值
+（浅色 `hsl(h-10 17% 91%)`、深色 `hsl(h+2 12% 16%)`），与纸面差 6 / 5 个百分点；
+`scripts/test-tokens.mjs` 钉住这个差距与饱和度，退回去就红。
+
 标尺层之外还有三样东西留在样式表里（[src/client/styles/tokens.css](./src/client/styles/tokens.css)）：
 按开关切换的标题配色、shiki 语法色、以及正文排版的复合令牌。它们不是全局主题，是带开关的装饰。
 
@@ -42,6 +50,50 @@ disposer 由 `ctx.effect` 持有，插件卸载时整层覆盖一起撤掉。
 （`字号 × 配置的行高倍数`），不写死像素——宿主把行高写成「24px + 字号增量」，
 换成乘法之后两个轴同时生效，用户调大字号时行高跟着长。
 
+## 配置页的十项
+
+十项分六组：
+
+| 组 | 项 |
+| --- | --- |
+| 配色 | 预设、浅色色相、深色色相 |
+| 打字体验 | 行高、段落间距 |
+| 标题 | 标题颜色、等级标记 |
+| 代码 | Maple 语法配色 |
+| 字体 | Maple 字体 |
+| 周边 | 侧栏、标签条与输入卡 |
+
+配色组第一行是预设：一个下拉按钮，六个色相组合（Maple 暖白、薰衣草、薄荷、森林、玫瑰、钢青），
+一次把浅色与深色切过去。两个色相是成套的，只改一个会得到「暖白配冷灰」这种半套配色，
+所以切换预设走一次 `form.mutate`，不是两次分开的字段写。
+
+按钮上的字本身就是状态：一对色相与某个预设对得上就显示它的名字，对不上显示「自定义」。
+判据是 `presets.ts` 的 `matchPreset`，只认完全相等（色相环上绕圈的写法如 395° 等于 35°），
+不挑「最接近的那个」——手调过的色相不对应任何预设，说它对应某一个是谎话。
+
+这里用下拉而不用分段控件，是因为分段控件没有「一个都没选中」这种状态：传进去的值不在
+选项里时，宿主把它算成下标 −1，那枚白底指示块会被平移到轨道外面、压在同一行的说明文字上，
+七个 tab 也全部失去键盘焦点。要显示「自定义」就必须有一个能落在选项外面的显示位置。
+
+预设下面是两个色相滑块，轨道铺一条色相环，拖到哪就是哪个色，旁边配数字框做精确输入。
+滑块在拖动中就提交（试色要看得见效果），数字框在失焦或回车时才提交
+（避免输入 `1.75` 的中途把页面刷成中间态）。
+
+预设只换色相、不动明度，所以六个预设的正文对比度都在 12:1 以上，与出厂值持平。
+
+## 内嵌字体
+
+Maple 把整个界面的字族都换成内嵌的 Maple Mono，观感的一大半来自这里。两个字体面
+（正常 71KB、斜体 80KB）放在 `src/client/styles/fonts/`，构建时按 data URI 内联进
+客户端 bundle（`build.mjs` 的 `?datauri` 处理器）：插件在 registry 上的实际路径是装的时候
+才知道的，另发字体文件就得拼一个自己不可能知道的 URL。
+
+因此 `files` 不含 `src`：字体只在 `lib/client.js` 里那份内联产物中，源码目录不必随包发布。
+
+字族声明排在宿主之后、并靠一个属性提一级优先级。用户的字体偏好
+（`--dsh-font-family-text` / `-code`）仍然排在最前——用户显式选过的字族不该被主题盖掉，
+主题只提供默认值。
+
 ## 正文装饰的锚点
 
 宿主的正文由 `MarkdownText` 渲染，根节点的类名是 CSS Modules 的哈希串，换一次构建就变。可用的稳定锚点只有两样：
@@ -89,6 +141,7 @@ disposer 由 `ctx.effect` 持有，插件卸载时整层覆盖一起撤掉。
 配色按 Maple 的公式推导，但有几处刻意偏离，都是为了让对话流读得清：
 
 - **链接与强调色压深**。Maple 的浅色强调色 `hsl(35 22% 56%)` 在 `#F8F8F6` 上只有 2.79:1，外链黄更低（2.98:1）。这里把链接换成青绿 `hsl(162 76% 29%)`（4.50:1），强调色换成 `hsl(35 26% 38%)`（5.22:1）。
+- **发送键跟着配色走**。它读的是 `--dsw-alias-button-info-fill`（宿主 InputBar 给那枚圆钮上色就是这个令牌，箭头另由宿主写死 `#fff`），不是 `button-primary-fill`。两档方向相反：浅色深底浅字（36%）、深色亮底浅字（42%）——宿主自己的深色档就指到 deepseek-400 的亮蓝。这一枚只有箭头没有文字，按图形控件的 3:1 守，色环最紧的一档在 60°（黄）；同时与输入卡底色至少差 2.5:1，否则按钮会陷进去。
 - **深色正文不叠透明度**。Maple 用 `--color-opacity: 0.85` 给所有颜色打折，长文会整体发灰。这里保留它的色相与明度关系，正文按原色输出。
 - **正文行距与段距换一档**。Maple 出厂值是行高 1.8、段距 8px；对话正文的行宽比笔记窄，按笔记的行距排会显得稀，所以取行高 1.75、段距 10px。两个值都在配置页上可调，出厂值就是这一组。
 - **h3 与 h4 收小半档**。Maple 六级标题的倍率是 1.6 / 1.5 / 1.4 / 1.3 / 1.2 / 1.1，宿主的分级令牌只到 h4，且 h4 之后没有独立令牌。这里取 1.6 / 1.5 / 1.35 / 1.15，h5 / h6 用自己的元素选择器补 1.05 / 1.0，让相邻两级在对话这种窄栏里分得开又不至于跳太多。
@@ -117,21 +170,22 @@ cd plugins/dsh-maple-theme && pnpm check
 | 步骤 | 断言什么 |
 | --- | --- |
 | `tsc -p tsconfig.json --noEmit` | 类型闸门，覆盖两半边连同配置投影模块 |
-| `scripts/smoke-host.mjs` | 真 cordis `Context`：`Config` 八个字段的默认值、越界值被 schema 拒绝、每个字段都是 `volatile`、`apply` 按 `{ auto: false }` 登记、包内 `cordis.patch.yml` 只有一条装配行且 id 与包名各自对上 |
-| `scripts/test-projection.mjs` | 脏输入收拢（越界、字符串、`null`、缺字段）、投影只写五个属性与四个变量、关掉的开关写成「删属性」、写到真 DOM 再撤掉不留痕迹、重复投影幂等 |
+| `scripts/smoke-host.mjs` | 真 cordis `Context`：`Config` 九个字段的默认值、越界值被 schema 拒绝、每个字段都是 `volatile`、`apply` 按 `{ auto: false }` 登记、包内 `cordis.patch.yml` 只有一条装配行且 id 与包名各自对上 |
+| `scripts/test-projection.mjs` | 脏输入收拢（越界、字符串、`null`、缺字段）、投影只写六个属性与四个变量、关掉的开关写成「删属性」、写到真 DOM 再撤掉不留痕迹、重复投影幂等；六个预设各自匹配回自己、手调过的色相不匹配任何预设、色相环上 360° 绕一圈仍匹配 |
 | `scripts/smoke-client.mjs` | 按 Web shell 的方式装载 `lib/client.js`：色板交给主题通道且每条令牌都成对、五张样式表都带 `data-plugin` 归属键、投影真的写到 `<html>`、配置变化后属性跟着换、卡片注册进 `plugins.bundle.config` 且 key 是包名、词典中英键集一致、卸载后属性与变量都撤干净；另带一条反例断言证明「读未声明服务会抛」的守卫还在响 |
-| `scripts/test-tokens.mjs` | 读 `src/client/tokens.ts` 算 WCAG 对比度：两套模式的正文、次要、三级文字、链接、主按钮、代码块、侧栏、提示框、气泡都过阈值；标题六色两套都过 4.5:1；两套令牌集一一对应 |
+| `scripts/test-tokens.mjs` | 读 `src/client/tokens.ts` 算 WCAG 对比度：两套模式的正文、次要、三级文字、链接、主按钮、代码块、侧栏、提示框、气泡都过阈值；标题六色两套都过 4.5:1；两套令牌集一一对应；侧栏与纸面分成两档且带得住色相；发送键跟随色相、按色环全周扫箭头对比，并与输入卡底色分得开 |
 | `scripts/test-anchors.mjs` | 宿主锚点契约：属性名与座位名仍在宿主源码里、样式表不含哈希类名、圆角无字面值、药丸圆角配了 `corner-shape: round` |
 
 `node scripts/assert-lib-untracked.mjs` 最后确认 `lib/` 没被 git 跟踪。
 
-界面验证走仓库的截图工具，浅色与深色各拍一张：
+界面验证走仓库的截图工具：
 
 ```sh
 node tools/gui-shot.mjs --session <会话 id> --shot tmp/maple-light.png
-node tools/gui-shot.mjs --session <会话 id> --eval 'document.body.setAttribute("data-ds-dark-theme","")' --shot tmp/maple-dark.png
 ```
 
-拍完把深色那句去掉，或在同一条命令里改回浅色，别把会话留在深色上。
+深色要走出宿主自己的外观开关（账号菜单 → 设置 → 通用设置 → 深色），不能用脚本改
+`data-ds-dark-theme`：令牌的值是 `ctx.theme.overrideTokens` 在调用那一刻按当时的模式定下来的，
+手动改属性绕过了宿主的重新组合，读到的仍是浅色那一套。验完记得切回浅色。
 
 改动配色或断言之后做一次变异测试（`docs/rules/plugins.md`「证明断言有牙齿」）：把 `--dsw-alias-label-primary` 改成浅色，`test-tokens.mjs` 会当场报 1.23:1；把投影里关闭开关的分支改成恒 `'on'`，`smoke-client.mjs` 会报「关掉的开关把属性删掉了」。

package/README.md

@@ -1,25 +1,25 @@
 # @lynn123411/dsh-maple-theme
 
-把 Obsidian 的 Maple 主题搬进 DSH：暖白 / 冷灰两套配色，加上对话正文的排版、代码块、以及侧栏与标签条的观感。
+把 Obsidian 的 Maple 主题搬进 DSH：暖白 / 冷灰两套配色、内嵌字体、对话正文的排版、代码块，以及侧栏与标签条的观感。
 
 ## 功能
 
 - **两套配色**：浅色取 Maple 的暖白（基础色相 35°）、深色取冷灰（207°）。整套界面跟着换——背景、文字、边框、气泡、侧栏、代码块、滚动条都在内。
-- **配置页上的八个旋钮**：浅色色相、深色色相、正文行高、段落间距、标题配色方式、等级标记、代码配色、外壳装饰。改一下立刻生效，不用刷新。
+- **配置页上的十项**：配色预设、浅色与深色色相（各带色相环滑块）、正文行高、段落间距、标题配色方式、等级标记、代码配色、字体、外壳装饰。改一下立刻生效，不用刷新。
 - **对话正文排版**：标题按 Maple 的比例放大加重，六级标题可以是六种颜色；引用变成浅底加左侧色条；表格的表头填色、四角圆角；列表标记换成等宽字体；分隔线是两端淡出的渐变。
 - **代码块**：Maple 的边界与标题条——比正文深一档的标题底、一道发丝分隔、圆角收小一档，语言标签用暖色等宽字；行号更淡一档，让代码本身突出。
 - **内嵌 Maple 字体**：把 Maple Mono 打进插件，正文与界面都用它，字形与 Obsidian 一致；配置页上可以关掉回到宿主字体。
 - **标题等级标记**：指针停在标题上时，左侧淡入 `H1`…`H6`。
-- **侧栏与标签条**：侧栏换成 Maple 的暖灰、去掉与中央区之间的那条冷灰分隔线；活动标签从底部短线换成一枚圆角药丸；列表行带圆角；输入卡换成 Maple 的纸色。
+- **侧栏、标签条与输入卡**：侧栏换成 Maple 的暖灰、去掉与中央区之间的那条冷灰分隔线；活动标签从底部短线换成一枚圆角块；列表行带圆角；输入卡换成 Maple 的纸色。
 
 ## 特性
 
-- **配色全局、装饰分层**：令牌是全局的，改了整界面跟着换；正文装饰只落在助手回答里（工具行与推理行不受影响），外壳装饰受「侧栏与标签条」开关控制，关掉就回到宿主原样。
+- **配色全局、装饰分层**：令牌是全局的，改了整界面跟着换；正文装饰只落在助手回答里（工具行与推理行不受影响），外壳装饰受「侧栏、标签条与输入卡」开关控制，关掉就回到宿主原样。
 - **不依赖宿主内部类名**：锚点只有宿主的 `data-slot` 座位名、`data-chat-flow-kind`、`data-row-key`、`data-composer-card` 这类语义属性，CSS Modules 的哈希类名一个都没用。
 - **锚点有契约自检**：`scripts/test-anchors.mjs` 会去宿主源码里逐个确认用到的属性名与座位名仍在，并禁止样式表出现哈希类名——宿主改名时这一条会红，而不是让样式静默失效。
 - **字号行高走宿主的令牌**：通过覆盖 `--dsw-font-markdown-*` 改排版，宿主调字号时跟着一起走。
 - **配色走宿主的主题通道**：两套色板交给 `ctx.theme.overrideTokens`，由宿主按当前模式挑值写到页面上；不另立一份全局主题，卸载时整层撤掉。
-- **配色有对比度闸门**：正文、次要文字、三级文字、链接、主按钮、代码块、侧栏、提示框这几组「文字 / 底色」都由自检按 WCAG AA 算一遍；标注级文字（时间戳一类）只做装饰，不进闸门。浅色链接与三级文字按达标明度取值，不是照抄 Maple 的原始数值。
+- **配色有对比度闸门**：正文、次要文字、三级文字、链接、主按钮、代码块、侧栏、提示框、气泡、轻提示、文档预览、警告标签、九个语法色、六个预设，每一对「文字 / 底色」都由自检按 WCAG AA 算一遍；标注级文字（时间戳一类）只做装饰，不进闸门。浅色链接与三级文字按达标明度取值，不是照抄 Maple 的原始数值。
 - **卸载即还原**：样式表按 `data-plugin` 归属键清理，`<html>` 上写的属性与变量一并撤掉。
 - **装配、锚点与验证**：见 [DETAILS.md](./DETAILS.md)。