dsh-theme-palette 1.3.1 → 1.3.3

package/CHANGELOG.md

@@ -0,0 +1,334 @@
+# 更新记录
+
+本文件记录 **dsh-theme-palette** 每个版本改了什么；README 只讲当前版本的设计与用法。
+
+## 版本一览
+
+### 1.3.3
+- 文档拆分：README 只留用法与当前设计（759 → 210 行），版本记录移到 `CHANGELOG.md`，逐组件设计说明移到 `docs/DESIGN.md`
+- 修正 README 里过期的「当前版本 0.8.2」
+
+### 1.3.2
+- README 安装说明改为 npm / Release tarball / 源码三条路径，去掉本机绝对路径
+- 新增 `tools/release.mjs`：一键发版（检查 → 发布 → 等 registry → 校验 latest → 可选打 tag）
+
+### 1.3.1
+- 自愈：override 层被宿主丢掉时（插件 fiber 重载等）自动重放，设置页显示恢复次数
+- 触发点：visibilitychange / focus / pageshow / theme/change / 4s 定时；健康时零写入
+
+### 1.3.0
+- 设置页重排：2×2 缩略图卡片（随明暗切换）+ 段落式设置行 + 分段控件 + 版本徽标
+- 样式从内联改为独立注入的 `settings.css`（支持 hover / 窄屏 / `body[data-ds-dark-theme]`）
+- 新增 `tools/preview-settings.mjs` + `tools/shoot-html.mjs`：不打开 App 也能截设置页
+
+### 1.2.0
+- 代码块底色独立成 `--dsh-code-fill`：与画布 ΔE 5.5（浅）/ 11.0（深），原来浅色下同色
+- 行内代码用更浅的 `--dsh-code-inline`；两者都不需要 `!important`
+
+### 1.1.0
+- Markdown 标题 / 加粗用「正文色 + 强调色相」染色（标题 12.3、加粗 14.4，均远高于 AA）
+- 「更多选项」加一档 Markdown 强调开关；黑白配色不染
+
+### 1.0.0
+- `fromOklch` 加色域钳位（二分收色度），修「通道顶满 255 → 色相被压歪」
+- 浅色侧重标定：近白端 −0.044、`lightC` 上调、暖砂/苔绿色相收敛，套间最弱一对 ΔE 2.15 → 3.07
+- 黑白配色接入引擎：三级 4.67、链接 4.63、主按钮 4.54（原 3.42 / 3.91 / 4.34）
+- 主按钮 `button-primary-fill` 从宿主红色改为强调色（并压到按钮文字 ≥4.5）
+- 设置页改为「配色 / 强度 / 面板表面 / 更多选项」，运行时 token 自检
+
+### 0.18.0
+- 主人气泡 `--dsw-specific-bubble` 改由「强调色 11%（深 13%）混画布」派生：暖砂 `#ffede0` → `#f2e5d1`，不再发粉
+- 气泡与画布 ΔE 4.2–7.9、气泡内文字对比 9.99–13.53
+
+### 0.17.0
+- 文字着色第二版标定：跟随 3.0/+0.055（ΔE 2.77 → 5.5）、浓一些 4.6/+0.085（ΔE 8.5）
+- 会话条目标题与正文共用 token，一并变深变暖
+
+### 0.16.0
+- 注释文字跟随文字着色：`mid` 角色乘 `1+(textScale-1)×2.0`，`midC` 0.006 → 0.010（注释 ΔE 1.76 / 3.61）
+- 深色注释 `label-caption` 改用色阶 500：对比 3.0 → 6.0–6.3
+
+### 0.15.0
+- 修：深色模式下选中卡片是白底白字（内联色混错了浅色画布）→ 改由 `--dsh-card-picked` 按模式给值
+- 设置页细项收进「更多选项」，默认折叠，只留配色卡片
+
+### 0.14.0
+- 新增 `darkHue`：暖砂深色层色相 88° → 60°（黄 → 橙棕），修掉暗部「发绿 / 橄榄」
+- 深端 neutral（深色滚动条）跟同一夜色相；浅色侧与另两套未变
+
+### 0.13.0
+- 深色侧栏改用独立 `darkLift`（0.048 / 0 / −0.042）：与画布 ΔE 从 1.9–2.3 提到 4.03–5.05
+- 侧栏内正文对比 12.48–16.40（仍 AAA）
+
+### 0.12.0
+- 文字着色重新标定：加 `textLift`（正文抬 0.030 / 0.065），三档 ΔE 从 0.35–1.66 提到 2.77–6.79
+- 左栏会话条目与正文共用 `label-*`，一并生效
+- MIN_MAIN 15.5 → 12（给带色正文留空间，仍 ≥ 1.7 倍 AAA）
+
+### 0.11.0
+- 开关 / 复选框 / 单选 / 插件页主按钮改跟强调色（覆盖 `--dsw-alias-brand-primary`，13 处引用一个支点）
+- 设置页现为六行：配色 · 文字着色 · 左侧栏 · 右侧栏 · 滚动条 · 开关勾选
+
+### 0.10.0
+- 滚动条三档着色（中性 / 跟随 / 强调），只抬色度不改明度；黑白配色下该行说明会自述无效
+- 设置页现为五行：配色 · 文字着色 · 左侧栏 · 右侧栏 · 滚动条
+
+### 0.9.0
+- 右侧栏可单独上色（默认与左栏同色）；注入一条命中 `data-rightbar-col` 的 CSS，颜色走 `--dsh-rightbar-fill`
+- 全屏右栏退回画布色
+
+### 0.8.2 （强调色改为设计稿标准值）
+- 强调色新增 `accentL`：色阶中段 `500` 的明度定死成设计值，不再乘 `accentScale`
+  —— 乘性缩放会把选中态软底 `deepseek-50/100/200` 一起压暗 13%
+- 暖砂 `#a9683e`（h 68→52.4，C 0.105→0.101）、靛蓝 `#3f66a3`（C 0.135→0.107，L 0.589→0.511）、
+  苔绿 `#4f7a42`（h 165→139），三档 8-bit 精确复现
+- 链接与基准色**解耦**：`--dsw-alias-link` 从基准色派生（浅 `#915227 / #3c629f / #436d36`，
+  深 `#c8a28b / #95acd0 / #9cb695`）—— 基准色当正文只有 3.40–4.41，过不了 AA
+- `tuneRamps` 不再改写 `deepseek-500`（品牌面保持标准值），只兜深色链接 `400`
+- `palette-dev.mjs`：链接列改读 `--dsw-alias-link`；每套新增「品牌基准色 / 链接」一行
+
+### 0.8.1 （深色专项审计后）
+- `ROLE` 深色权重拉平（`800/850` 0.6/0.75 → 1.0，`875` 0.85 → 0.95）—— 卡片/模块不再比画布灰 30–45%，三套在深色层上的区分度从 ΔE 1.02 回到 2.05
+- `darkC` 按色相归一化：暖砂 0.016→0.014、靛蓝 0.017→0.028、苔绿不动；三套占可用色域 30/19/24%（原 35/11/24%，暖砂发脏、靛蓝发灰）
+- `darkLift` 三套错开 0.026 / 0.032 / 0.042（原统一 0.034）—— 暖砂↔苔绿 850 层 ΔE 1.15 → 2.05
+- `paperC` 下调 0.014 / 0.009 / 0.0125 —— 靛蓝不再撞 8-bit 天花板（原「浓一些」请求 0.033 实得 0.0241）
+- 深色交互 alpha 0.08/0.14/0.24 → 0.05/0.09/0.14 —— 深色悬停强度从浅色的 1.8–2.1 倍回到 1.2–1.3 倍
+- 侧栏深色放开下沉阻尼 —— 深色导轨边界 ΔE 0.49 → 1.86–2.10，与浅色同档对齐
+- 苔绿强调 `155°→165°` —— 与底色（h≈152）从 2° 拉开到 13°，链接不再只靠明度识别
+- 深色对比度：正文 14.40–14.98、三级 4.79 起、链接 4.65 起（0 处低于下限）
+
+### 0.8.0 （- 新增「文字着色」三档（中性 / 跟随 / 浓一些），默认「跟随」；只放大文字色度，不影响对比度）
+- 配色重建缓存按（配色, 文字档）分键；设置页新增第三行控件
+
+### 0.7.0 （UI 设计审计后全面修订）
+- 求解靶点从画布改为真实承载面（`60` / `800` / `150`），上限 0.09 → 0.13 —— 修掉 12 处真实的 AA 违规
+- `accentScale` 三套全部 1.0 —— 强调色浅端恢复四档层次
+- 阈值 15.5 / 6.2 / 4.62；三级与次级重新拉开明度
+- 近白端压缩改等量下移 —— 画布↔卡层 ΔL 从 0.0147 回到 0.026
+- 深色：`darkC` 下调、`darkLift` 上调 —— 底色不再读成深咖，卡片不再脱色
+- 暖砂强调 `55°→68°`（离橙棕脏区）、苔绿 `146°→155°`（绿字可读性）、靛蓝 `276°→262°`（回到品牌蓝）
+- 暖砂/苔绿拉开色相与色度 —— 唯一低于 JND 的一对从 ΔE 1.30 提到 2.15
+- 侧栏步进 0.012 → 0.024/0.030，默认档改「更深」，并给「更浅」加穿层护栏
+- `palette-dev.mjs` 改为加载生产引擎
+
+## 版本详解
+
+### 为什么配色会自己跳回默认（v1.3.1）
+
+现象：设了暖砂，用了一阵（跑模型操作、切窗口、长时间放着），**突然变成黑白**，但设置页里
+「暖砂」还是选中的。原因在宿主的 override 生命周期：
+
+```js
+// ThemeRuntime（宿主）
+overrideTokens(source, tokens) {
+  const layer = { seq: this.overrideSeq++, tokens: validateOverrides(source, tokens) }
+  this.overrides.set(source, layer)
+  this.publish()
+  return () => { if (this.overrides.get(source) !== layer) return; this.overrides.delete(source); this.publish() }
+}
+```
+
+而插件侧拿到的是被 runner 包装过的版本 —— **每一层的 disposer 都被挂在调用方的 fiber 上**：
+
+```js
+const dispose = Reflect.apply(method, target, [id, tokens])
+ctx.effect(() => dispose, 'cordis-client-runner: dynamic theme override layer')
+```
+
+也就是说：**这一层的生命周期 = 插件 fiber 的生命周期**。插件被卸载/重载、或 fiber 的
+effect 被清理时，层就没了；`composeActive` 在 `overrides.size === 0` 时直接返回内置主题，
+于是页面**静默**变回默认色 —— localStorage 里的选择还在，设置页自然还显示暖砂。
+
+会触发 fiber 重载的典型情况：动态插件被宿主重载（改过插件文件/profile、宿主自我更新）、
+渲染进程恢复、以及某些"模型操作"引起的插件重载。
+
+**v1.3.1 的处理**：加了一个自愈环。窗口重新可见 / 获焦 / `pageshow` / `theme/change` /
+每 4 秒，回读 `body` 上的 5 个关键 token；不在了就把最后一层重放：
+
+```
+[dsh-theme-palette] 配色层不见了（visibility），已重放第 1 次
+```
+
+设置页顶部会显示"配色层被宿主丢过一次，已自动恢复 N 次"；健康时不产生任何写入。
+
+**另一种可能**（值得先分辨）：如果是 **localStorage 被清**（换 profile、清缓存），设置页会回到
+「黑白」选中态 —— 那种情况自愈救不回来，因为连"你想用哪套"都丢了。判据就是**设置页里选中的
+是不是你原来那套**。
+
+### 设置页重排（v1.3.0）
+
+原来的设置页是六行"工程参数"堆在一起、每行都是同一种小药丸。v1.3.0 重做成四段：
+
+```
+主题色                                            v1.3.0
+配色与明暗模式独立；切换后立即生效并保存在 localStorage。
+┌────────────┬────────────┐
+│ 缩略图      │ 缩略图   ✓  │   2×2 卡片：每张是「侧栏 + 画布 + 两行文字 + 强调色」的微缩图
+│ 黑白 无色调 │ 暖砂 米白+棕 │
+└────────────┴────────────┘
+强度      正文与强调的着色程度        [静][标准][浓]
+左侧栏底色 相对会话区的层次           [更浅][同色][更深]
+右侧栏底色 面板底色                   [同左栏][跟随画布]
+▸ 更多选项
+```
+
+四个变化：
+
+1. **卡片有缩略图**，而且**跟随明暗模式**（深色下缩略图自动用深色画布/侧栏/强调色 —— 靠
+   `body[data-ds-dark-theme]` 切换两组 CSS 变量，不是靠 JS 猜模式）；
+2. **段落式行**：左边标题 + 副标题，右边分段控件，中间一条 0.5px 分隔线；
+3. **分段控件**（segmented）替代散落的药丸，选中项是"抬起"的白色/深色片；
+4. 标题右侧有版本徽标；样式表是**独立注入的一条 CSS**（`data-plugin-css=.../settings.css`），
+   不再全是内联样式 —— 于是能写 `:hover`、媒体查询（窄屏单列）和 `body[data-ds-dark-theme]` 作用域。
+
+### 怎么"看见"它
+
+设置页在 App 里，外部浏览器进不去；但组件树可以脱离 React 渲染成静态 HTML：
+
+```bash
+node tools/preview-settings.mjs     # → tools/preview-light.html / preview-dark.html
+node tools/shoot-html.mjs --file preview-light.html --out tools/out/settings
+node tools/shoot-html.mjs --file preview-dark.html  --out tools/out/settings
+```
+
+`preview-settings.mjs` 用生产引擎算 token、用插件真正注入的 `SETTINGS_CSS`，
+再用一个 20 行的树→HTML 渲染器把组件铺开 —— 所以截图就是"设置页长什么样"，
+不是另画一版。
+
+### 代码块底色（v1.2.0）
+
+宿主的代码块底色是 `--dsw-alias-bg-layer-1`，而**浅色模式下 layer-1 就是画布色（都指色阶 00）** ——
+所以代码框和正文底是同一块，只剩一条发丝线。v1.2.0 给它一档独立的"内嵌面板"色：
+
+| token | 暖砂 | 与画布 ΔE | 代码文字对比 |
+|---|---|---|---|
+| `--dsh-code-fill`（围栏代码块） | `#eadcc7` / `#3e342d` | **5.52 / 11.05** | 5.75 / 8.04 |
+| `--dsh-code-inline`（行内 `code`） | 更浅一档（色阶 50 打底） | ~5.9 | — |
+
+规则同样注入到 `<head>`：
+
+```css
+[class*="_markdown_"] .md-code-block{background:var(--dsh-code-fill,inherit)}
+[class*="_markdown_"] :not(pre) > code{background:var(--dsh-code-inline,inherit)}
+```
+
+`.md-code-block` 是宿主自己的类（不是 CSS Modules 哈希），特异性 0,2,0 高于宿主的 `.block`（0,1,0），
+**不需要 `!important`**。`:not(pre) > code` 把围栏块里的 `code` 排除掉，只染行内代码。
+
+### Markdown 标题与加粗（v1.1.0）
+
+宿主的 Markdown 里，标题和正文**同色**（都继承 `label-primary`），只靠字号/字重区分。
+v1.1.0 起把「标题」和「加粗」各染一档配色：
+
+| token | 暖砂 | 对比度（画布 / 卡层） |
+|---|---|---|
+| `--dsh-md-heading` | `#42250b`（浅）/ `#fed9bd`（深） | 12.3 / 11.3 |
+| `--dsh-md-strong` | `#2f1b08` / `#ffe2cc` | 14.4 |
+
+**加粗只加色度、不动明度** —— 一开始用"混到强调色"，结果加粗比正文更亮（浅色下反而更弱）；
+改成只叠加色相后，加粗与正文同深、只是"更有色"。标题则再往中间推一点明度
+（浅色提亮 0.065 / 深色压暗 0.030），配合更大的字号拉开层级。
+
+规则注入到 `<head>`，用 CSS Modules 的局部名做钩子（`[class*="_markdown_"]`，比整串哈希耐版本）：
+
+```css
+[class*="_markdown_"] :where(h1,h2,h3,h4,h5,h6){color:var(--dsh-md-heading,inherit)}
+[class*="_markdown_"] strong{color:var(--dsh-md-strong,inherit)}
+```
+
+「更多选项 → Markdown 强调 > 同正文」可以关掉（token 置 `inherit`，回到宿主原样）。
+黑白配色不染（它没有色相可跟）。
+
+### 主人气泡（v0.18.0）
+
+用户消息的底色是 `--dsw-specific-bubble`，宿主指向 `deepseek-50` —— 也就是「品牌色的极浅底」。
+我的强调色色度比宿主的品牌蓝高得多，浅端直接算出 **`#ffede0`（R 顶满 255）**，在暖砂下看着发粉发红。
+
+v0.18.0 改成「强调色按比例混进画布」，气泡是**有色味的浅底**而不是一块彩色：
+
+| | 气泡 | 与画布 ΔE | 文字对比 |
+|---|---|---|---|
+| 暖砂 | `#f2e5d1`（浅）/ `#362c24`（深） | 4.2 / 7.9 | 13.53 / 11.89 |
+| 靛蓝 | `#dce5f5` / `#272f40` | 4.9 / 7.8 | 13.29 / 11.62 |
+| 苔绿 | `#dde9dd` / `#2b342b` | 4.6 / 7.5 | 13.39 / 11.37 |
+
+混合比例：浅色 11%、深色 13%（`mix(强调色, 画布)`）。ΔE 4–8 足以让气泡读成一块面，
+又不会盖过正文。
+
+### 文字着色第二版标定（v0.17.0）
+
+v0.12 把三档从“不可见”提到“可感知”，但**默认档 ΔE 只有 2.77** —— 在 14px 的会话标题上仍然读作黑字。
+v0.17.0 再标定一次，让默认档真正看得出配色：
+
+| 档位 | scale / lift | 暖砂标题 | ΔE | 正文对比 |
+|---|---|---|---|---|
+| 中性 | 1 / 0 | `#12110f` | 0 | 17.2 |
+| **跟随（默认）** | 3.0 / +0.055 | **`#201d17`** | **5.5** | 15.3 |
+| 浓一些 | 4.6 / +0.085 | `#28241a` | 8.5 | 14.1 |
+
+靛蓝跟随是 `#1b1d23`（ΔE 5.4）、苔绿 `#191f1b`（ΔE 5.6）。
+深色正文同步加深：暖砂 `#f3efe5` → `#f9efd6` → `#feeeca`（ΔE 2.1 / 3.6）。
+
+会话条目标题与正文共用 `label-primary`，所以左栏列表跟着一起变 —— 侧栏内对比 14.41（跟随）/ 13.27（浓一些），
+仍远高于 AAA 的 7。**如果想要纯黑**，切「中性」即可。
+
+### 注释 / 说明文字（v0.16.0）
+
+DSH 里“注释类”文字走的是 `--dsw-alias-label-caption`：宿主浅色指色阶 **400**、深色指 **600**。
+它落在 `mid` 角色上，原来只给 0.006 的色度 —— 等于灰字。v0.16.0 两件事：
+
+**① 跟着「文字着色」走（部分强度）**。`mid` 角色（注释 400/600、三级、`label-dimmed` 200）
+乘 `1 + (textScale-1) × 2.0`，并且 `midC` 从 0.006 提到 0.010：
+
+| 档位 | 暖砂注释 | ΔE | 靛蓝 / 苔绿注释 |
+|---|---|---|---|
+| 中性 | `#b3b1ad` | 0 | `#afb1b6` / `#aeb3af` |
+| 跟随 | `#b8b1a1` | 1.76 | `#abb2c1` / `#a7b6aa` |
+| 浓一些 | `#bdb194` | 3.61 | `#a5b2cd` / `#9ebaa5` |
+
+注释刻意比正文弱一档（正文 跟随 ≈2.8、浓一些 ≈6.4），否则整页都会“彩色化”。
+
+**② 修掉深色注释的对比度**。宿主深色注释用 600，而这个步为了「浅色三级文字达标」被求解压暗过，
+在深底上只剩 **3.0:1**。深色这一侧改用 500 → **6.0–6.3:1**；浅色保持宿主原值
+（宿主自己的浅色注释就是 1.95，那是它的低对比设计，要提亮我可以换 500）。
+
+### 设置页的两条约定（v0.15.0）
+
+**① 选中卡片用 token，不用内联色。** 之前选中项的淡底是「强调色 8% 混**浅色**画布」写成内联样式的，
+深色模式下就变成一张近白卡片，而卡片文字是 `label-primary`（深色下近白）—— 白底白字。
+现在由 token 层给 `--dsh-card-picked` 一对值：
+
+| | 选中底色 | 卡片文字对比 |
+|---|---|---|
+| 暖砂 浅 / 深 | `#f3e6d3` / `#3b3028` | 14.55 / 11.17 |
+| 靛蓝 浅 / 深 | `#dde7f6` / `#2a3345` | 14.25 / 11.00 |
+| 苔绿 浅 / 深 | `#deebdf` / `#2f392f` | 14.42 / 10.55 |
+
+**② 细项默认折叠。** 配色卡片下面是「▸ 更多选项」；文字着色 / 左侧栏 / 右侧栏 / 滚动条 /
+开关勾选这五行只在展开后出现。所有档位都保留，默认值就是我推荐的那套，不展开也能正常用。
+
+### 1.0.0：按设计审计重做的四件事
+
+**① 色域安全钳位。** `fromOklch` 现在先判断是否超出 sRGB（线性通道必须落在 [0,1]），
+超了就二分收色度，而不是把通道硬钳到 0/255。此前「暖砂气泡算出 `#ffede0`、R 恒为 255」
+就是这个缺口的症状 —— 颜色会被压成另一个色相。
+
+> 顺带更正审计里的一个数字：我第一次测「占色域 %」只判断了负通道（漏了超 1 的情况），
+> 所以报成 3–12%。真实值是 暖砂 62% / 靛蓝 **99%** / 苔绿 26% —— 靛蓝不是"没上色"，
+> 而是**顶到高明度的蓝色上限还超了一点**（14.8‰ 请求 vs 14.1‰ 上限）。
+
+**② 浅色侧重标定。** 近白端整段下移 0.044（画布 0.968 → 0.955），高明度处色域上限因此抬高
+（蓝色在 L 0.97 只有 14‰、L 0.95 有 24‰）；`lightC` 上调到 0.030 / 0.020 / 0.016；
+暖砂浅底色相 88→84、强调 52→60（收敛到 ±20° 内）；苔绿 152→162 与暖砂拉开。
+
+套间区分度（浅画布 ΔE）：暖砂↔苔绿 **2.15 → 3.07**、暖砂↔靛蓝 3.84 → 5.04、靛蓝↔苔绿 2.28 → 2.85。
+
+**③ 黑白配色也过引擎。** 它色度全 0（保持宿主原貌），但走 `tuneRamps` 求解：
+三级文字 3.42 → **4.67**、链接 3.91 → **4.63**（都到 AA 了），主按钮顺带压暗到 4.54。
+
+**④ 信息架构从 6 行参数改成 3 段。**
+配色卡片 → **强度**（静 / 标准 / 浓）→ **面板表面**（侧栏三档 + 右栏两档）→ **▸ 更多选项**（滚动条、控件）。
+「文字着色」改名为「强度」并升为主控件；旧的「跟随 / 浓一些」是相对量，现在是一档风格。
+
+**⑤ 运行时自检。** 应用后回读 `body` 上的 5 个关键 token，写不进去就在设置页显示
+「⚠ 部分 token 未生效」并在控制台告警 —— 宿主改 token 名时不再静默失效。