dsh-background-by-model 0.4.0 → 0.4.2

package/README.md

@@ -99,15 +99,23 @@ One interface, one config — only the current model differs:
 - **Conversation & Trajectory** — The message list is wrapped in a translucent card automatically, and the trajectory page gets whole-page opacity & blur controls, letting the wallpaper shine through the content.
 - **Right Panel** — The column that slides in from the right when you open a file now has a card of its own: its opacity follows **Main background** until you drag it (then this card owns it), and its blur stacks on top of the main-background blur. While closed it takes no space and costs nothing.
 
+### Host check (Config tab)
+
+- **Every host interface, evaluated against the build you are running** — The plugin re-emits the host's design tokens, hangs backdrop filters on the host's structural elements and reads the host's session/model services; each of those is a contract with a dsh release, and each can be renamed without an error. The check reports, per point, whether it holds, what its loss looks like on screen, the literal it depends on, the host file that should define it and the plugin file that reads it.
+- **Three states, honestly** — *ok* (the host still provides it), *n/a* (it cannot be observed from here right now — the chat view is off screen while the settings dialog is open, the file-preview panel is not in the DOM until a file has been opened) and *broken* (it is gone while the surface that uses it is on screen). Only the third is a failure.
+- **Copy diagnostics** — One click copies both halves (the live probe and the offline scan of the installed files) as markdown, ready to paste into an issue.
+- **Offline equivalent** — `pnpm scan` runs the same contract table against the installed packages with no browser, and exits non-zero when a target is gone. Use it right after upgrading dsh.
+
 ## Settings
 
-Settings → **Theme** now has three tabs:
+Settings → **Theme** now has four tabs:
 
 | Tab | Scope | Contents |
 | --- | --- | --- |
 | **Interface** | Global, shared by every model | Opacity & blur for the main background, left panel, right panel, cards & panels, input & controls, settings panel, conversation text box and trajectory page |
 | **Model Background** | Per rule | The ordered rule list, the live match readout, and each rule's wallpaper, theme color, layout mode, framing, opacity and blur |
 | **Config** | — | Import / export the whole rule set (`dsh-background-by-model-theme.json`) |
+| **Host check** | — | Every host interface this plugin depends on, evaluated against the running dsh: what holds, what broke, and a copyable report |
 
 The old **Color** tab is gone — the theme color is now a property of each rule. The old **Background** tab became **Model Background**.
 
@@ -180,8 +188,21 @@ To mount a working copy into a profile instead, add it to the profile's `package
 
 After changing anything under `src/`, run `pnpm run bundle` again — the mounted profile loads `lib/`, so edits do not take effect until the bundle is rebuilt.
 
+### Checking a new dsh release
+
+The plugin talks to dsh through a small, explicit set of host interfaces (see [`src/host-contracts.ts`](src/host-contracts.ts)). After upgrading dsh, check them before wondering why something looks off:
+
+```sh
+pnpm run bundle
+pnpm run scan    # offline: fails when a contract target vanished from the installed dsh
+pnpm test        # the contract table, the live probe's logic, the UI stylesheet, the version floor
+```
+
+`pnpm scan` accepts `--host <dir>` (the `node_modules` directory holding `@deepseek-ai/dsh-app-boot`) and `--json`. The same check runs inside the app, against the live interface, on Settings → **Host check**.
+
 ## Compatibility
 
+- **dsh `>=0.1.7-rc.2`** — Declared in `peerDependencies` (every `@deepseek-ai/dsh-*` entry) and mirrored in `engines.dsh`. The host evaluates those peers against its own runtime version, so an older host reports the plugin as incompatible instead of running it silently.
 - **[`dsh web`](https://github.com/deepseek-ai/deepseek-harness)** — Full support on both the npm release and the new source build. The plugin auto-detects which client-module table the host ships (the new `@deepseek-ai/dsh-client-store` or the legacy `@deepseek-ai/dsh-client-runtime`) and resolves `defineStore` accordingly at runtime.
 - **[deepseek-harness-desktop](https://github.com/anywhere-labs/deepseek-harness-desktop)** — Supported
 
@@ -204,6 +225,21 @@ No. Both were removed in 0.3.0; each rule uses a static image.
 
 ## Recent Optimizations
 
+### v0.4.2
+
+- **New "Host check" tab — the plugin now reports what broke, instead of just breaking** — A plugin that styles someone else's interface depends on values it does not own: the host's session and model services, the elements it hangs backdrop filters on, and the design tokens it re-emits. Every one of those can be renamed between dsh releases, and all three 0.1.7 breakages were *silent* — nothing threw, the interface simply stopped following the settings. Settings → **Host check** now evaluates each of those touch points against the running build — the live DOM, the host's own stylesheets and the Cordis services — and shows, per point, whether it holds, what its loss looks like on screen, the literal it depends on, the host file that should define it and the plugin file that reads it. **Copy diagnostics** turns both halves into one markdown block for an issue. A surface that is merely off screen (the conversation view while the settings dialog is open, the file-preview panel before a file has been opened) is reported as *n/a*, never as a failure.
+- **The same table is checked offline, with no browser** — `pnpm scan` (`scripts/host-contract-scan.mjs`) walks the installed dsh packages and fails non-zero the moment a contract target is gone, so a host rename turns into a red build right after `npm i -g @deepseek-ai/dsh@latest`, before anyone looks at the interface. It also prints the host version it found and whether it satisfies this plugin's floor.
+- **One contract table, three consumers** — `src/host-contracts.ts` declares every touch point exactly once; the browser probe, the node scan and the tests all read it, so a newly added selector cannot be forgotten by the check that is supposed to notice it changing. `pnpm test` covers the table, the probe (against a fixture written in the shape of a host DOM), the UI stylesheet and the version floor.
+- **A broken contract is no longer invisible in a log** — Two and a half seconds after boot, if any contract fails, the browser console gets one line per failure naming the literal, the plugin file that reads it and the host file expected to define it.
+
+### v0.4.1
+
+- **The right panel stops painting a permanent frosted plate** — dsh 0.1.7 no longer paints the file-preview panel itself: the container became the slide / fullscreen viewport, stays mounted at its full width for the whole session, and collapsing it only slides the dock out (`transform` + `visibility`, never `display`). A background plus a backdrop-filter on that container therefore covered the empty right half of the frame whenever the panel was closed — the frosted plate 0.1.7 showed. The card now paints the elements the host actually paints (the dock's tab hosts: `[data-dockkit-content]`, `[data-dockkit-empty]`) and rides the host's own open/close and slide transitions; the old panel selector survives behind a `:has()` guard for older hosts, and the backdrop-filter is gated on `[data-sidebar-right-open]` so a collapsed panel is never filtered.
+- **Switching models switches the background again** — 0.1.7's `sessions.list` snapshot no longer publishes `current`, so the plugin could not tell which session was on screen: no session id, no `modelSelection` projection, empty model text, and every model fell through to rule 1. The session id now comes from the host's own `uiSession.current.key` binding, with the legacy `list.current` and a `retainedBy.mainView` row as fallbacks — all optional, so the lookup also works while `uiSession` mounts late. Model switches remain instant, because they ride the per-session `modelSelection` projection subscription rather than a poll.
+- **Menu group headings stop reading as white bands** — 0.1.7 split the menu surface in two: the shared `MenuSurface` material paints the new `--dsw-menu-surface-fill`, and every other overlay paints `--dsw-specific-menu`, which the host aliases to it. The plugin re-emitted only the latter, so a model-selector panel kept the host glass while its sticky provider headings took the plugin's near-opaque palette colour. Both tokens are now generated from one expression and read one plugin-owned variable, so the card slider fades them together and the alias can no longer break.
+- **The card slider's label says what it owns** — It covers menus as well as cards, so the Chinese label changed from 「对话框中选项面板」 to 「卡片与菜单面板」 and the English one from `Cards & panels` to `Cards & menus`.
+- **Declared host raised to `0.1.7-rc.2`** — Every `@deepseek-ai/dsh-*` peer and `engines.dsh` now require 0.1.7-rc.2 or later. The host's compatibility check matches those peers against its own runtime version (`includePrerelease`), so an older host reports the plugin as incompatible by name instead of running it silently. The code's own version fallbacks are unchanged.
+
 ### v0.4.0
 
 - **Color extraction now measures brightness the way a display does** — The auto light/dark band was decided from the average HSV *value* (the max channel), which reads every saturated pixel as bright: pure blue is `v = 1.0` while its Rec.709 luma is `0.072`. A dark, saturated wallpaper was therefore pushed into the light band and got a light palette built on top of a dark picture. The extractor now averages Rec.709 luma — the same measure the wallpaper verdict always used.

package/README.zh.md

@@ -99,15 +99,23 @@
 - **对话与轨迹页** — 消息列表自动包裹为半透明卡片，轨迹页可整页调节透明度与模糊，让壁纸从内容后方透出来。
 - **右侧栏** — 点开文件后从右侧滑出的那一栏有了自己的卡片：透明度默认跟随「主背景」（拖动后本卡片接管），模糊则在主背景模糊之上再叠加；关闭时不占位置、无副作用。
 
+### 宿主自检（「宿主自检」页）
+
+- **逐条检查插件依赖的宿主接口** — 本插件会重新发出宿主的设计令牌、把毛玻璃挂在宿主的界面元素上、并读取宿主的会话与模型服务；这些每一条都是与某个 dsh 版本之间的约定，而任何一条被改名都不会报错。自检会逐条给出：是否仍然成立、失效时界面上会是什么样子、依赖的那个字面量、本应由哪个宿主文件定义、以及本插件哪个文件在读取它。
+- **三种状态，如实报告** — *正常*（宿主仍然提供）、*未观察*（当前无法从界面上看到：设置弹窗打开时对话页不在屏幕上，没开过文件时右侧栏也不在 DOM 里）、*失效*（界面在屏幕上，但接口已经没了）。只有第三种算故障。
+- **复制诊断报告** — 一键把两侧结果（实时探测 + 对安装目录的离线扫描）合并成一份 markdown，直接贴进 issue 即可。
+- **离线等价物** — `pnpm scan` 用同一张约定表检查已安装的包，不需要浏览器；一旦某个目标消失就以非零码退出。升级 dsh 后先跑它。
+
 ## 设置界面
 
-设置的 **「主题」** 分类下现在有三个选项卡：
+设置的 **「主题」** 分类下现在有四个选项卡：
 
 | 选项卡 | 作用范围 | 内容 |
 | --- | --- | --- |
 | **界面** | 全局，所有模型共用 | 主背景、左侧栏、右侧栏、卡片面板、输入框与控件、设置面板、对话文本框、轨迹页的透明度与模糊度 |
 | **模型背景** | 每条规则 | 有序规则列表、顶部实时状态，以及每条规则的壁纸、主题色、布局模式、取景、透明度与模糊度 |
 | **配置** | — | 导入 / 导出整套规则（`dsh-background-by-model-theme.json`） |
+| **宿主自检** | — | 逐条检查本插件依赖的宿主接口在当前 dsh 上是否仍然成立，并给出可复制的诊断报告 |
 
 原先的 **「色彩」** 选项卡已删除——主题色改为每条规则自己的属性；原 **「背景」** 选项卡已改造成 **「模型背景」**。
 
@@ -180,8 +188,21 @@ pnpm run typecheck
 
 改完 `src/` 必须重新执行 `pnpm run bundle` 才会生效——挂载的 profile 加载的是 `lib/`。
 
+### 升级 dsh 后怎么查
+
+插件与 dsh 之间只通过一张明确列出的接口清单通信（见 [`src/host-contracts.ts`](src/host-contracts.ts)）。升级 dsh 之后，先查它，再怀疑别的地方：
+
+```sh
+pnpm run bundle
+pnpm run scan    # 离线：某个约定目标从已安装的 dsh 里消失就以非零码退出
+pnpm test        # 约定表、实时探测逻辑、界面样式表、版本下限
+```
+
+`pnpm scan` 支持 `--host <dir>`（含 `@deepseek-ai/dsh-app-boot` 的 `node_modules` 目录）与 `--json`。同一套检查也在应用内运行：设置 → **宿主自检**，对着真实界面跑。
+
 ## 兼容性
 
+- **dsh `>=0.1.7-rc.2`** — 在 `peerDependencies`（所有 `@deepseek-ai/dsh-*` 条目）中声明，并在 `engines.dsh` 中同步。宿主会用自身运行时版本校验这些 peer，因此更旧的宿主会直接按名字报出「不兼容」，而不是静默运行。
 - **[`dsh web`](https://github.com/deepseek-ai/deepseek-harness)** — 同时兼容 npm 发布版与新版源码构建。插件会自动检测宿主携带的客户端模块表（新版 `@deepseek-ai/dsh-client-store` 或旧版 `@deepseek-ai/dsh-client-runtime`），并在运行时据此解析 `defineStore`。
 - **[deepseek-harness-desktop](https://github.com/anywhere-labs/deepseek-harness-desktop)** — 支持
 
@@ -204,6 +225,21 @@ pnpm run typecheck
 
 ## 近期优化
 
+### v0.4.2
+
+- **新增「宿主自检」页 —— 插件现在能说清哪里坏了，而不只是坏掉** — 一个给别人界面做样式的插件，依赖的全是自己不拥有的东西：宿主的会话与模型服务、挂毛玻璃的那些元素、以及被重新发出的设计令牌。这些在 dsh 版本之间随时可能改名，而 0.1.7 那三次故障**全都是静默的** —— 什么都没抛错，界面只是不再跟随设置。现在 设置 → **宿主自检** 会逐条对当前构建做检查（实时 DOM、宿主自己的样式表、Cordis 服务），并给出：是否成立、失效时界面上是什么样子、依赖的字面量、本该由哪个宿主文件定义、以及本插件哪个文件在读取它。**复制诊断报告** 会把两侧结果合并成一份 markdown，直接贴进 issue。仅仅是「当前不在屏幕上」的情况（设置弹窗打开时的对话页、还没开过文件时的右侧栏）会报成 *未观察*，绝不算故障。
+- **同一张表还能离线查，不需要浏览器** — `pnpm scan`（`scripts/host-contract-scan.mjs`）直接扫已安装的 dsh 包，某个约定目标一消失就以非零码退出；所以 `npm i -g @deepseek-ai/dsh@latest` 之后、还没打开界面之前，就能先红一次。它同时打印找到的宿主版本以及是否满足本插件的下限。
+- **一张约定表，三处消费** — `src/host-contracts.ts` 把每个接触点只声明一次，浏览器探测、离线扫描与测试都读它，所以新加的选择器不可能被「本该发现它变化」的检查漏掉。`pnpm test` 覆盖这张表、探测逻辑（对着一个按宿主 DOM 形状写的夹具）、界面样式表与版本下限。
+- **约定断裂不再只留在日志里没人看** — 启动 2.5 秒后，只要有约定失效，浏览器控制台会逐条打印：字面量、本插件读取它的文件、本应由哪个宿主文件定义。
+
+### v0.4.1
+
+- **右侧面板不再糊出一块常驻磨砂板** — dsh 0.1.7 不再自己绘制文件预览面板：容器变成了滑动/全屏视口，整场会话都以全宽挂载，折叠只是把 dock 用 `transform` + `visibility` 滑出去（从不 `display:none`）。于是这个容器上的背景加 backdrop-filter 在面板折叠时照样盖住右半屏——就是那块磨砂板。现在卡片只画宿主真正在画的元素（dock 的 tab host：`[data-dockkit-content]`、`[data-dockkit-empty]`），跟着宿主自己的开合与滑动过渡走；旧的容器选择器留在 `:has()` 守卫后面以兼容老宿主，backdrop-filter 只在 `[data-sidebar-right-open]` 时生效，折叠态绝不走滤镜。
+- **切换模型重新能切背景** — 0.1.7 的 `sessions.list` 快照不再发布 `current`，插件无法得知当前在屏的是哪个会话：拿不到会话 id → 没有 `modelSelection` 投影 → 模型文本为空 → 所有模型都退到规则 1。现在会话 id 先取宿主自己的 `uiSession.current.key`，老字段 `list.current` 与带 `retainedBy.mainView` 的行作为兜底，三跳都是可选的（`uiSession` 挂载晚也能解析）。换模型仍是即时的：它走的是该会话 `modelSelection` 投影的订阅，而不是轮询。
+- **菜单分组标题不再是白道** — 0.1.7 把菜单面拆成了两个 token：共享的 `MenuSurface` 材质画新的 `--dsw-menu-surface-fill`，其他浮层画 `--dsw-specific-menu`，而宿主把后者别名到前者。插件只重新发射了后者，于是模型选择菜单的面板还是宿主玻璃，吸顶的分组标题却变成了插件近乎不透明的调色板色。现在两个 token 由同一个表达式生成、读同一个插件变量，卡片滑块让它们一起变化，别名也不会再被打断。
+- **卡片滑块的标签改名** — 它同时管菜单与卡片，中文标签从「对话框中选项面板」改为「卡片与菜单面板」，英文从 `Cards & panels` 改为 `Cards & menus`。
+- **声明宿主抬到 `0.1.7-rc.2`** — 所有 `@deepseek-ai/dsh-*` peer 与 `engines.dsh` 现在都要求 0.1.7-rc.2 及以后。宿主的兼容性校验会用自身运行时版本比对（带 `includePrerelease`），因此更旧的宿主会按名字报出插件不兼容，而不是静默运行。代码里的版本兜底逻辑未改动。
+
 ### v0.4.0
 
 - **取色改用「显示器看到的亮度」** — 亮暗带此前按 HSV 明度（max 通道）取平均，它把每个饱和像素都算成亮：纯蓝 `v = 1.0`，而 Rec.709 luma 只有 `0.072`。于是深色但饱和的壁纸被判进亮色带，在暗画面上配出一套浅色界面。现在改为平均 Rec.709 luma——与壁纸判定的同一套度量。