dsh-background-by-model 0.4.1 → 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,6 +188,18 @@ 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.
@@ -205,6 +225,13 @@ 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.

package/README.zh.md

@@ -99,15 +99,23 @@
 - **对话与轨迹页** — 消息列表自动包裹为半透明卡片，轨迹页可整页调节透明度与模糊，让壁纸从内容后方透出来。
 - **右侧栏** — 点开文件后从右侧滑出的那一栏有了自己的卡片：透明度默认跟随「主背景」（拖动后本卡片接管），模糊则在主背景模糊之上再叠加；关闭时不占位置、无副作用。
 
+### 宿主自检（「宿主自检」页）
+
+- **逐条检查插件依赖的宿主接口** — 本插件会重新发出宿主的设计令牌、把毛玻璃挂在宿主的界面元素上、并读取宿主的会话与模型服务；这些每一条都是与某个 dsh 版本之间的约定，而任何一条被改名都不会报错。自检会逐条给出：是否仍然成立、失效时界面上会是什么样子、依赖的那个字面量、本应由哪个宿主文件定义、以及本插件哪个文件在读取它。
+- **三种状态，如实报告** — *正常*（宿主仍然提供）、*未观察*（当前无法从界面上看到：设置弹窗打开时对话页不在屏幕上，没开过文件时右侧栏也不在 DOM 里）、*失效*（界面在屏幕上，但接口已经没了）。只有第三种算故障。
+- **复制诊断报告** — 一键把两侧结果（实时探测 + 对安装目录的离线扫描）合并成一份 markdown，直接贴进 issue 即可。
+- **离线等价物** — `pnpm scan` 用同一张约定表检查已安装的包，不需要浏览器；一旦某个目标消失就以非零码退出。升级 dsh 后先跑它。
+
 ## 设置界面
 
-设置的 **「主题」** 分类下现在有三个选项卡：
+设置的 **「主题」** 分类下现在有四个选项卡：
 
 | 选项卡 | 作用范围 | 内容 |
 | --- | --- | --- |
 | **界面** | 全局，所有模型共用 | 主背景、左侧栏、右侧栏、卡片面板、输入框与控件、设置面板、对话文本框、轨迹页的透明度与模糊度 |
 | **模型背景** | 每条规则 | 有序规则列表、顶部实时状态，以及每条规则的壁纸、主题色、布局模式、取景、透明度与模糊度 |
 | **配置** | — | 导入 / 导出整套规则（`dsh-background-by-model-theme.json`） |
+| **宿主自检** | — | 逐条检查本插件依赖的宿主接口在当前 dsh 上是否仍然成立，并给出可复制的诊断报告 |
 
 原先的 **「色彩」** 选项卡已删除——主题色改为每条规则自己的属性；原 **「背景」** 选项卡已改造成 **「模型背景」**。
 
@@ -180,6 +188,18 @@ 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，因此更旧的宿主会直接按名字报出「不兼容」，而不是静默运行。
@@ -205,6 +225,13 @@ 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]` 时生效，折叠态绝不走滤镜。