dsh-background-by-model 0.4.1 → 0.4.3

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,19 @@ No. Both were removed in 0.3.0; each rule uses a static image.
 
 ## Recent Optimizations
 
+### v0.4.3
+
+- **The Host check tab stops crying wolf** — Its first real run on a healthy 0.1.7 install reported **9 failures out of 28 contracts** (7 tokens "no longer declared", 2 attributes gone). Every one was the *probe reading the wrong place*, not the host: the tokens are published as `body{--dsw-…}` while the probe asked `getComputedStyle(document.documentElement)`, and `data-plugin` — which the host's own CSS modules set on every `<style>` they inject — was being used to mean "this plugin's sheet", so the check skipped the entire host theme and then called the tokens renamed. Both are fixed, and both now have tests that fail if they come back: the token root is a named part of `ProbeEnv`, and reading the plugin's own sheets goes through a marker the plugin writes itself (`data-dab-side`), via `getAttribute` rather than `dataset` — `dataset` only exposes the camel-cased key, so a probe indexing it by the dashed name works in a fixture and silently returns nothing in a browser.
+- **`rule` checks now say which side they are about** — A token contract asserts two different things: that the host still *declares* the name, and that it *resolves to a value*. The first can only be answered from the host's rules, the second only from the live cascade, and the one entry whose other half is this plugin's own stylesheet (`.dab-card`) is now marked `side: 'own'` explicitly instead of being indistinguishable from a host rule. Every re-emitted token carries both checks, so a rename is reported as a renamed token rather than as an empty value.
+- **A readable-but-empty host stylesheet is a failure, not a blind spot** — The old code only asked whether *some* sheet was readable, so a host sheet that was readable yet mentioned nothing made every token check pass. Readability is now tracked per side.
+
+### 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,19 @@ pnpm run typecheck
 
 ## 近期优化
 
+### v0.4.3
+
+- **「宿主自检」不再虚报故障** — 它第一次在健康的 0.1.7 上实跑，28 条约定报了 **9 条失效**（7 个令牌「不再声明」、2 个属性「消失」）。**全部是探测读错了地方，宿主一条都没坏**：设计令牌发布在 `body{--dsw-…}` 上，探测却去问 `getComputedStyle(document.documentElement)`；而 `data-plugin` —— 宿主自己的 CSS 模块在**每一个** `<style>` 上都写它 —— 被我当成了「这是插件自己的样式表」，于是检查跳过了整个宿主主题，再把令牌报成改名。两处都已修正，并且各配了会让它复发的测试：令牌读取的宿主元素成了 `ProbeEnv` 的显式成员；识别自己的样式表改用一个只由本插件写入的标记（`data-dab-side`），且用 `getAttribute` 而不是 `dataset` —— `dataset` 只暴露驼峰键，按带连字符的名字去索引它，在夹具里能通过、在浏览器里静默返回空。
+- **`rule` 检查现在会说明自己查的是哪一侧** — 一条令牌约定其实断言了两件不同的事：宿主是否仍**声明**这个名字，以及它是否仍**解析出值**。前者只能从宿主的规则回答，后者只能从实时级联回答；而唯一一条「另一半是本插件自己样式表」的（`.dab-card`）现在显式标为 `side: 'own'`，不再和宿主规则混为一谈。所有被重新发出的令牌都同时带上这两项检查，于是「改名」会被报成改名，而不是「值为空」。
+- **可读但没提到目标的宿主样式表算失效，不算盲区** — 旧逻辑只问「有没有任意一张表可读」，于是一张能读、却什么也没提到的宿主表会让所有令牌检查都通过。现在可读性按侧分别跟踪。
+
+### 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]` 时生效，折叠态绝不走滤镜。