@lynn123411/dsh-maple-theme 0.1.0 → 0.3.0

package/DETAILS.md

@@ -11,7 +11,7 @@ dsh plugin --profile web add @lynn123411/dsh-maple-theme
 这条命令把包名写进 profile 的 `dependencies` 与 `dsh.profile.bundles`，包内 `cordis.patch.yml` 随之插入一条 root loader entry。这一条行同时承载两个半边：
 
 - **宿主半边**（`lib/index.js`）：只声明 `Config` 的形状，并登记 `settings.configure({ auto: false })`——本插件的配置界面在「插件」页上，不让内核按 schema 再生成一份同字段的设置页。
-- **浏览器半边**（`lib/client.js`）：把两套色板交给宿主的主题通道、注入四张样式表（tokens / markdown / shell / card）、把配置投影到 `<html>` 上、在「插件」页上挂配置卡片。
+- **浏览器半边**（`lib/client.js`）：把两套色板交给宿主的主题通道、注入五张样式表（tokens / markdown / shell / fonts / card）、把配置投影到 `<html>` 上、在「插件」页上挂配置卡片。
 
 声明的服务：宿主半边只要 `settings`；浏览器半边要 `configForms`（读本插件那一行的配置）、`slots` 与 `locale`（画卡片）、`theme`（交两套色板）。`package.json` 的 `dsh.client.inject` 另列了它依赖的插件契约包，两层都要声明，漏一层整条 loader entry 会静默变成 failed。
 
@@ -42,6 +42,42 @@ disposer 由 `ctx.effect` 持有，插件卸载时整层覆盖一起撤掉。
 （`字号 × 配置的行高倍数`），不写死像素——宿主把行高写成「24px + 字号增量」，
 换成乘法之后两个轴同时生效，用户调大字号时行高跟着长。
 
+## 配置页的十项
+
+十项分六组：
+
+| 组 | 项 |
+| --- | --- |
+| 配色 | 预设、浅色色相、深色色相 |
+| 打字体验 | 行高、段落间距 |
+| 标题 | 标题颜色、等级标记 |
+| 代码 | Maple 语法配色 |
+| 字体 | Maple 字体 |
+| 周边 | 侧栏、标签条与输入卡 |
+
+配色组第一行是预设：六个色相组合（Maple 暖白、薰衣草、薄荷、森林、玫瑰、钢青），
+一次把浅色与深色切过去。两个色相是成套的，只改一个会得到「暖白配冷灰」这种半套配色，
+所以切换预设走一次 `form.mutate`，不是两次分开的字段写。
+
+预设下面是两个色相滑块，轨道铺一条色相环，拖到哪就是哪个色，旁边配数字框做精确输入。
+滑块在拖动中就提交（试色要看得见效果），数字框在失焦或回车时才提交
+（避免输入 `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 的哈希串，换一次构建就变。可用的稳定锚点只有两样：
@@ -117,21 +153,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-client.mjs` | 按 Web shell 的方式装载 `lib/client.js`：色板交给主题通道且每条令牌都成对、四张样式表都带 `data-plugin` 归属键、投影真的写到 `<html>`、配置变化后属性跟着换、卡片注册进 `plugins.bundle.config` 且 key 是包名、词典中英键集一致、卸载后属性与变量都撤干净；另带一条反例断言证明「读未声明服务会抛」的守卫还在响 |
+| `scripts/smoke-host.mjs` | 真 cordis `Context`：`Config` 九个字段的默认值、越界值被 schema 拒绝、每个字段都是 `volatile`、`apply` 按 `{ auto: false }` 登记、包内 `cordis.patch.yml` 只有一条装配行且 id 与包名各自对上 |
+| `scripts/test-projection.mjs` | 脏输入收拢（越界、字符串、`null`、缺字段）、投影只写六个属性与四个变量、关掉的开关写成「删属性」、写到真 DOM 再撤掉不留痕迹、重复投影幂等 |
+| `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-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,24 +1,25 @@
 # @lynn123411/dsh-maple-theme
 
-把 Obsidian 的 Maple 主题搬进 DSH：暖白 / 冷灰两套配色，加上对话正文的排版、代码块、以及侧栏与标签条的观感。
+把 Obsidian 的 Maple 主题搬进 DSH：暖白 / 冷灰两套配色、内嵌字体、对话正文的排版、代码块，以及侧栏与标签条的观感。
 
 ## 功能
 
 - **两套配色**：浅色取 Maple 的暖白（基础色相 35°）、深色取冷灰（207°）。整套界面跟着换——背景、文字、边框、气泡、侧栏、代码块、滚动条都在内。
-- **配置页上的八个旋钮**：浅色色相、深色色相、正文行高、段落间距、标题配色方式、等级标记、代码配色、外壳装饰。改一下立刻生效，不用刷新。
-- **对话正文排版**：标题按 Maple 的比例放大加重，六级标题可以是六种颜色；引用变成浅底加左侧色条；表格的表头填色、四角圆角；列表标记按层级换形状；分隔线是两端淡出的渐变。
+- **配置页上的十项**：配色预设、浅色与深色色相（各带色相环滑块）、正文行高、段落间距、标题配色方式、等级标记、代码配色、字体、外壳装饰。改一下立刻生效，不用刷新。
+- **对话正文排版**：标题按 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)。