dsh-web-icon-indicator 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0](https://github.com/waknow/dsh-web-icon-indicator/compare/v0.5.2...v0.6.0) (2026-09-24)
+
+### Added
+
+* show the settings form on the plugin's own page ([a85a8b0](https://github.com/waknow/dsh-web-icon-indicator/commit/a85a8b0ce3821743c45bd8cca6ea0d969e8a419f))
+
+## [0.5.2](https://github.com/waknow/dsh-web-icon-indicator/compare/v0.5.1...v0.5.2) (2026-09-24)
+
+### Added
+
+* give the official Plugins page its own artwork ([332896b](https://github.com/waknow/dsh-web-icon-indicator/commit/332896b4b05af94877e63a33ad9c4895b94ad7dd))
+
+### Fixed
+
+* repaint the favicon on DSH 0.1.7's theme-scoped link pair ([a57f78f](https://github.com/waknow/dsh-web-icon-indicator/commit/a57f78ff98acd4d9ae41c03c3b0519113e357bb2))
+
 ## [0.5.1](https://github.com/waknow/dsh-web-icon-indicator/compare/v0.5.0...v0.5.1) (2026-09-22)
 
 ### Fixed

package/README.md

@@ -7,7 +7,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/dsh-web-icon-indicator)](https://www.npmjs.com/package/dsh-web-icon-indicator)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-> **⚠️ DSH version support** — requires **DSH ≥ 0.1.2-rc.1**. One bundle serves both settings generations: **modern** (≥ 0.1.7-alpha.1: exported `Config` schema + `configForms` + `plugins.row.config`) and **legacy** (≤ 0.1.6-alpha.1: `settings.installSection` + `settingsScope` + `settings.plugin.item`). Verified on **DSH 0.1.5-rc.3** and **DSH 0.1.7-alpha.1**; on any older host the favicon still works even if the settings page is not reachable.
+> **⚠️ DSH version support** — requires **DSH ≥ 0.1.2-rc.1**. One bundle serves both settings generations: **modern** (≥ 0.1.7-alpha.1: exported `Config` schema + `configForms` + `plugins.bundle.config`) and **legacy** (≤ 0.1.6-alpha.1: `settings.installSection` + `settingsScope` + `settings.plugin.item`). Verified on **DSH 0.1.5-rc.3** and **DSH 0.1.7-alpha.1**; on any older host the favicon still works even if the settings page is not reachable.
 
 Browser tab favicon reflects the current DSH session state — `idle` / `running` / `asking` / `done` — so you can see at a glance whether a session needs your attention, even when the tab is in the background.
 
@@ -34,6 +34,8 @@ Browser tab favicon reflects the current DSH session state — `idle` / `running
 
 Changes are saved through the settings transport into the profile patch and applied to the running tab within ~1 s — no reload, no restart. See [Configure](#configure) for the full key reference.
 
+> 🐳 **The Plugins page shows this plugin's own artwork** — on DSH ≥ 0.1.7 the **Plugins / 插件** page draws a 48 px icon on every bundle card (a 40 px one on every row) from `package.json` → `icon`. This repo declares `"icon": "icons/plugin.svg"`, so the card shows the whale instead of the generic placeholder. The icon is read by the host (`readPluginMeta` → `iconOf`) and shipped to the browser as a base64 `data:` URL; **a missing or malformed icon never blanks the card — it turns the plugin's `meta.error` on and the card shows a problem tag**, so keep the path relative, inside the package, and ≤ 256 KiB. Adding `icon` needs no settings, no code, and no host restart — only a new install or publish; see [Plugin artwork on the Plugins page](#plugin-artwork-on-the-plugins-page).
+
 ## 🎬 Default configuration, visualized
 
 The four default states, exactly as they appear in the browser tab (the `asking` whale really blinks):
@@ -115,6 +117,11 @@ dsh plugin --profile web add <path-or-tarball>
 
 Or drop the directory into `~/.dsh/profiles/web/node_modules/<name>/` and ship a `cordis.patch.yml` that matches the one shipped here.
 
+> ℹ️ The official **Plugins** page reads the artwork from **`package.json.icon` of the
+> installed package**, so it appears only after an install (or a publish) — a page
+> that was already open keeps its last snapshot until you reload it. See
+> [Plugin artwork on the Plugins page](#plugin-artwork-on-the-plugins-page).
+
 ## Configure
 
 All keys are optional; defaults shown. `statusPath` and `iconPathPrefix` are
@@ -133,6 +140,10 @@ they are intentionally **not** part of the settings page's live form (they are
 | `defaultColor` | *(unset)* | Default icon color (the idle whale's primary) — tell multiple DSH instances apart. Warns when it is too close to another state's color |
 | `states` | see below | Per-state visual config |
 
+> The Plugins-page artwork is **not** a config key — it comes from
+> `package.json.icon` (see [Plugin artwork on the Plugins page](#plugin-artwork-on-the-plugins-page)).
+> `iconsDir` only tells the *favicon* routes where `base.svg` lives.
+
 Each entry in `states` is one object per state: `{ effect, colors[], speed? }`:
 
 ```yaml
@@ -216,9 +227,12 @@ patch declares); **≤ 0.1.6-alpha.1** uses the plugin-chosen
 `web-icon-indicator`, the same string 0.5.x used, so an existing section keeps
 resolving:
 
-- **Web GUI:** open **设置 → 插件**, expand the **dsh-web-icon-indicator**
-  bundle and configure its row. The *Favicon indicator* page edits the same
-  keys: asking/done hold, the **default icon color** (with a
+- **Web GUI:** open **设置 → 插件** and click the **dsh-web-icon-indicator**
+  card — the settings form opens directly on the plugin's page (the same place
+  the official plugins put theirs) — including on **0.1.6-alpha.2**, which still
+  binds through the legacy `settingsScope` but already renders the bundle slot.
+  The
+  *Favicon indicator* page edits the same keys: asking/done hold, the **default icon color** (with a
   live palette preview and the similarity warning), and the per-state effect /
   colors / cycle for `running` / `asking` / `done`. Each of those states is a
   collapsible row whose header shows one **color chip** per state — split in two
@@ -263,14 +277,58 @@ resolving:
   omitted from the resolved form until a user sets it.
 - The browser half is a hand-written `lib/client.js` (ModuleLoader factory
   format — no build step, no runtime deps beyond the shell's `react`). It
-  registers on both page slots (`plugins.row.config` — gated on the served
-  namespace — and the legacy `settings.plugin.item`) and resolves whichever
+  registers on the slot the running host declares — `plugins.bundle.config`
+  on ≥ 0.1.7 (so the Plugins list's card opens straight onto the form), else
+  `plugins.row.config`; both gated on the served namespace — plus the legacy
+  `settings.plugin.item` — and resolves whichever
   settings provider the host exposes (`configForms` or `settingsScope`) at
   render time, so neither is a hard dependency of the module. The DSH client
   scanner picks a new `dsh.client` declaration up on the next profile start.
 - Deployments without a settings service are unaffected: the plugin keeps
   running on the composition entry + schema defaults it was mounted with.
 
+## Plugin artwork on the Plugins page
+
+DSH ≥ 0.1.7 renders a **per-plugin icon on the official Plugins page**: 48 px on
+each bundle card, 40 px on each row (`PackageArtwork` in
+`@deepseek-ai/dsh-client-ui-plugin-manager`, which falls back to a generic
+placeholder when a package declares none). The artwork comes straight from the
+package manifest, so shipping one is pure metadata — **no code, no settings, no
+host restart**:
+
+```jsonc
+// package.json
+{
+  "name": "dsh-web-icon-indicator",
+  "icon": "icons/plugin.svg"   // relative to package.json, and inside the package
+}
+```
+
+The host reads it before evaluating any plugin code
+(`readPluginMeta` → `iconOf` in `@deepseek-ai/dsh-app-boot`):
+
+| Rule | Value |
+| --- | --- |
+| Field | top-level `package.json.icon` (a sibling of `name`/`version` — **not** under `dsh`) |
+| Path form | relative to the manifest's directory; absolute paths, Windows drive letters (`C:\…`) and URLs are rejected |
+| Containment | must stay inside the manifest directory after `realpath` resolution (`..` escapes are rejected) |
+| Formats | `.svg` → `image/svg+xml`, `.png` → `image/png`, `.jpg` / `.jpeg` → `image/jpeg`, `.webp` → `image/webp` |
+| Size | ≤ 256 KiB (checked both on `stat` and on the bytes actually read) |
+| Delivery | read as bytes and shipped to the browser as a base64 `data:` URL on the wire (`PluginLocalizedMeta.icon`) |
+
+> ⚠️ **A bad icon is worse than no icon.** Any violation is a *metadata error*,
+> not a silent fallback: the reader returns `meta.error`, the host surfaces it,
+> and the card shows a **problem tag** for the plugin. Keep the file in the
+> package (`files` ships `icons/`) and make sure it is standalone — a raw
+> `icons/base.svg` would be **invalid**, because its `#p { fill: __COLOR__ }`
+> placeholder is not a colour. This repo therefore ships the pre-filled
+> [`icons/plugin.svg`](./icons/plugin.svg) (`base.svg` with `__COLOR__` →
+> `#1a1a1a`) and asserts the whole contract in `test/verify.js` (F62–F65).
+
+Because the icon is read from the **installed** package, a local edit takes
+effect only after reinstalling the plugin (`dsh plugin --profile web add
+<path>`) or publishing a new version.
+
 ## How it works
 
 - Host plugin with a small browser half: registers routes on the existing `webServer` — the status JSON endpoint, a static `/dsh-web-icon-indicator/base.svg` (the whale template), and one `tapIndex` that injects a small browser script into every served `index.html`. The config surface is the plugin's exported `Config` schema, which the DSH settings service projects into a live page keyed by the `dsh-web-icon-indicator` entry id (see above).
@@ -293,6 +351,7 @@ The favicon is a plain image, so browsers never run the SVG's own CSS/JS animati
 Known limitations (current as of Safari 26.3):
 
 - **Favicons have their own cache.** Chrome keeps a favicon database, Firefox a `favicons.sqlite`, and **Safari a system-level icon cache** — none of which a normal *clear cache* touches, and WebKit even caches the "no icon" case. That is why a changed icon can linger for an existing tab. The plugin already mitigates this: it serves `base.svg` and the status endpoint with `Cache-Control: no-store`, bundles a freshness query (`?t=Date.now()`) on its fetches, and replaces the `<link rel=icon>` node on each state change.
+- **A theme-scoped favicon pair must be collapsed first (DSH ≥ 0.1.7).** The shell's `index.html` ships *two* `rel=icon` links — `favicon-dark.svg` for `prefers-color-scheme: dark` and `favicon.svg` for light — because up to `0.1.6-alpha.2` there was exactly one. A browser resolves the favicon to the **last connected link whose `media` matches**, so repainting only the first one left the tab showing the shell's icon no matter what the session did. The plugin now normalizes the set to a single always-matching link at startup (keeping the variant your scheme selects) before painting. If you are on a version before 0.5.2 and the tab icon simply never changes, this is why.
 - **Safari renders SVG favicons but ignores their internal CSS** — no `@media`, no `prefers-color-scheme`, no CSS animation. So all recoloring must be baked into each frame's markup (which the plugin does) rather than driven by CSS variables.
 - **`data:`-URI SVG favicons are unreliable in Safari** (WebKit bug 236616, still open; reproduced on Safari 17.6). The plugin currently builds each frame as a `data:image/svg+xml` URI, so on Safari the tab icon may not render at all — the biggest known gap.
 - **Dynamic JS updates in Safari are hit-or-miss;** they may require a reload, and Safari "locks onto" the first icon it sees. There is no guaranteed, spec-supported way to swap a favicon live in Safari today.

package/README.zh.md

@@ -7,7 +7,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/dsh-web-icon-indicator)](https://www.npmjs.com/package/dsh-web-icon-indicator)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-> **⚠️ DSH 版本支持** —— 需要 **DSH ≥ 0.1.2-rc.1**。同一份插件同时兼容两代 settings 契约：**新一代**（≥ 0.1.7-alpha.1：导出 `Config` schema + `configForms` + `plugins.row.config`）与**旧一代**（≤ 0.1.6-alpha.1：`settings.installSection` + `settingsScope` + `settings.plugin.item`）。已在 **DSH 0.1.5-rc.3** 与 **DSH 0.1.7-alpha.1** 上验证；更早的宿主上 favicon 仍可用，只是配置页可能不可达。
+> **⚠️ DSH 版本支持** —— 需要 **DSH ≥ 0.1.2-rc.1**。同一份插件同时兼容两代 settings 契约：**新一代**（≥ 0.1.7-alpha.1：导出 `Config` schema + `configForms` + `plugins.bundle.config`）与**旧一代**（≤ 0.1.6-alpha.1：`settings.installSection` + `settingsScope` + `settings.plugin.item`）。已在 **DSH 0.1.5-rc.3** 与 **DSH 0.1.7-alpha.1** 上验证；更早的宿主上 favicon 仍可用，只是配置页可能不可达。
 
 浏览器标签页 favicon 实时反映 DSH 会话状态——`待机` / `运行中` / `提问` / `完成`——让你在标签页置于后台时也能一眼看出是否有会话需要处理。
 
@@ -34,6 +34,8 @@
 
 改动会通过 settings 传输层持久化到 profile patch，约 1 秒内应用到已打开的标签页——无需刷新、无需重启。完整键说明见 [配置](#配置)。
 
+> 🐳 **插件页会显示本插件自己的图标** —— DSH ≥ 0.1.7 的 **设置 → 插件** 页面会为每个 bundle 卡片画一个 48px 图标（每一行 40px），来源是 `package.json` → `icon`。本仓库声明了 `"icon": "icons/plugin.svg"`，所以卡片显示的是鲸鱼而不是通用占位图。图标由宿主读取（`readPluginMeta` → `iconOf`），并以 base64 `data:` URL 传给浏览器；**图标缺失或不合规不会把卡片变空——而是点亮该插件的 `meta.error`，卡片上出现「问题」标签**，所以路径必须相对、必须在包内、且 ≤ 256 KiB。加这个字段不需要任何配置、代码或宿主重启，只需重新安装或发一个新版本；详见[插件页图标](#插件页图标)。
+
 ## 🎬 默认配置，可视化
 
 四个默认状态在浏览器标签页中的实际效果（`asking` 那条鲸鱼真的在闪烁）：
@@ -110,6 +112,10 @@ dsh plugin --profile web add <路径或tarball>
 
 或将目录放进 `~/.dsh/profiles/web/node_modules/<name>/`，并附带与包内一致的 `cordis.patch.yml`。
 
+> ℹ️ 官方**插件页**的图标读取的是**已安装包的 `package.json.icon`**，因此只有在安装
+> （或发布新版本）之后才会出现——已经打开的插件页会一直显示上一次的快照，直到你刷新。
+> 详见[插件页图标](#插件页图标)。
+
 ## 配置
 
 所有键均可选，默认值如下。`statusPath` 与 `iconPathPrefix` 是**注册期**键：
@@ -126,6 +132,10 @@ dsh plugin --profile web add <路径或tarball>
 | `defaultColor` | *（未设置）* | 默认图标颜色（待机鲸鱼的主色）—— 用于区分多个 DSH 实例；与其它状态颜色过于接近时会告警 |
 | `states` | 见下 | 每个状态的视觉配置 |
 
+> 插件页的图标**不是**配置键——它来自 `package.json.icon`
+> （见[插件页图标](#插件页图标)）。`iconsDir` 只告诉 *favicon* 路由去哪里取
+> `base.svg`。
+
 `states` 中每个状态是一个对象：`{ effect, colors[], speed? }`：
 
 ```yaml
@@ -195,8 +205,9 @@ schemastery schema），**并在宿主仍提供旧版服务时**用同一份 sch
 表单，即 `dsh-web-icon-indicator`（bundle patch 声明的行 id）；**≤ 0.1.6-alpha.1**
 使用插件自定的 `web-icon-indicator`，与 0.5.x 保持一致，老用户的 section 继续生效：
 
-- **Web GUI：** 打开 **设置 → 插件**，展开 **dsh-web-icon-indicator** bundle 并
-  配置它的行，即出现 *标签页图标指示器* 页面，可编辑：提问/完成驻留、
+- **Web GUI：** 打开 **设置 → 插件**，点开 **dsh-web-icon-indicator** 卡片，
+  设置表单就直接出现在插件页上（与官方插件的位置一致）；**0.1.6-alpha.2** 虽然还在用
+  旧的 `settingsScope`，但它同样渲染 bundle 插槽，因此表单位置一致。可编辑：提问/完成驻留、
   **默认图标颜色**（带配色一览与相似度告警），以及
   `running` / `asking` / `done` 三个状态各自的特效 / 颜色 / 周期。这三个状态
   各占一行可折叠条目，行首是一个**色块**——多色状态（asking）会左右分格同时显示
@@ -229,13 +240,52 @@ schemastery schema），**并在宿主仍提供旧版服务时**用同一份 sch
 - 因此实时设置面覆盖 `askingHoldMs`、`doneHoldMs`、`iconsDir`、`defaultColor`
   与 `states`。`iconsDir` 没有 schema 默认值，用户未设置时不会出现在解析后的表单中。
 - 浏览器半区是手写的 `lib/client.js`（ModuleLoader factory 格式——无构建步骤、
-  无额外运行期依赖，仅用 shell 自带的 `react`）。它同时往两代页面插槽注册
-  （`plugins.row.config`——按「Host 是否提供该命名空间」门控；以及旧的
+  无额外运行期依赖，仅用 shell 自带的 `react`）。它按宿主实际声明的插槽注册
+  （≥ 0.1.7 用 `plugins.bundle.config`，这样插件列表的卡片点开即见表单；否则退回
+  `plugins.row.config`——两者都按「Host 是否提供该命名空间」门控；另有旧的
   `settings.plugin.item`），并在渲染时按宿主实际提供的服务解析表单
   （`configForms` 或 `settingsScope`），因此两者都不是模块的硬依赖。DSH 客户端
   扫描器会在下次启动 profile 时识别新的 `dsh.client` 声明。
 - 未组合 settings 服务的部署不受影响：插件继续使用挂载时的合成条目 + schema 默认值。
 
+## 插件页图标
+
+DSH ≥ 0.1.7 会在官方**插件页**为每个插件渲染图标：bundle 卡片 48px、每一行
+40px（`@deepseek-ai/dsh-client-ui-plugin-manager` 的 `PackageArtwork`，未声明时
+回退到通用占位图）。图标直接来自包清单，所以给出它纯粹是元数据——**不需要改代码、
+不需要配置、不需要重启宿主**：
+
+```jsonc
+// package.json
+{
+  "name": "dsh-web-icon-indicator",
+  "icon": "icons/plugin.svg"   // 相对 package.json，且必须留在包内
+}
+```
+
+宿主在**不执行任何插件代码**的前提下读取它（`@deepseek-ai/dsh-app-boot` 的
+`readPluginMeta` → `iconOf`）：
+
+| 规则 | 取值 |
+| --- | --- |
+| 字段 | 顶层 `package.json.icon`（与 `name`/`version` 同级，**不是**放在 `dsh` 下） |
+| 路径形式 | 相对清单所在目录；绝对路径、Windows 盘符（`C:\…`）与 URL 都会被拒绝 |
+| 包含关系 | 经 `realpath` 解析后必须仍在清单目录内（`..` 越界会被拒绝） |
+| 格式 | `.svg` → `image/svg+xml`，`.png` → `image/png`，`.jpg` / `.jpeg` → `image/jpeg`，`.webp` → `image/webp` |
+| 大小 | ≤ 256 KiB（`stat` 与实际读到的字节数各校验一次） |
+| 传输 | 读成字节后以 base64 `data:` URL 随元数据下发（`PluginLocalizedMeta.icon`） |
+
+> ⚠️ **坏的图标比没有图标更糟。** 任何不合规都不是静默回退，而是**元数据错误**：
+> 读取器返回 `meta.error`，宿主把它暴露出来，卡片上会给这个插件打上**问题标签**。
+> 所以文件要留在包内（`files` 里已包含 `icons/`），并且必须是独立可用的 SVG——
+> 直接用 `icons/base.svg` 是**无效**的，因为它里面的 `#p { fill: __COLOR__ }`
+> 占位符并不是颜色。本仓库因此提供预填好的
+> [`icons/plugin.svg`](./icons/plugin.svg)（即 `base.svg` 把 `__COLOR__` 换成
+> `#1a1a1a`），并在 `test/verify.js` 里把整套约束都断言下来（F62–F65）。
+
+由于图标是从**已安装**的包读取的，本地改动只有在重新安装插件
+（`dsh plugin --profile web add <path>`）或发布新版本之后才会生效。
+
 ## 实现原理
 
 - Host 插件 + 一个小型浏览器半区：在现有 `webServer` 上注册路由——状态 JSON 端点、静态 `/dsh-web-icon-indicator/base.svg`（鲸鱼模板），以及一个 `tapIndex` 向每个 `index.html` 注入小段浏览器脚本。整套配置就是插件导出的 `Config` schema，DSH settings 服务按 `dsh-web-icon-indicator` entry id 把它投射为实时配置页（见上）。
@@ -258,6 +308,7 @@ favicon 本质是一张图片，浏览器不会在标签页 UI 里运行 SVG 自
 已知限制（截至 Safari 26.3）：
 
 - **favicon 有专属缓存。** Chrome 用 favicon 数据库、Firefox 用 `favicons.sqlite`、**Safari 用系统级图标缓存**——清普通缓存都清不掉，WebKit 甚至会把「无图标」这一状态也缓存起来。这就是改了图标后，已打开的标签页还可能显示旧图标的原因。本插件已通过「给 `base.svg` 与状态端点设置 `Cache-Control: no-store`、请求携带 freshness 参数（`?t=Date.now()`）、每次切换状态时重建 `<link rel=icon>` 节点」来缓解。
+- **必须先折叠「按主题配对」的两个 favicon link（DSH ≥ 0.1.7）。** 宿主的 `index.html` 里有**两个** `rel=icon`——`favicon-dark.svg` 对应 `prefers-color-scheme: dark`、`favicon.svg` 对应浅色（0.1.6-alpha.2 及更早只有一个）。浏览器取的是**最后一个 media 命中的已连接 link**，所以只重绘第一个的话，无论会话状态怎么变，标签页始终显示宿主自己的图标。插件现在会在首次绘制前把这一组规范成**唯一一个不带 media 的 link**（保留你当前配色方案对应的那个）。如果你用的是 0.5.2 之前的版本、且标签页图标完全不变化，原因就在这里。
 - **Safari 渲染 SVG favicon，但忽略其内部 CSS**——不支持 `@media`、`prefers-color-scheme`、CSS 动画。所以所有上色必须烘焙进每一帧的标记（本插件正是这么做的），而不能依赖 CSS 变量。
 - **`data:` URI 的 SVG favicon 在 Safari 不可靠**（WebKit bug 236616，仍未关闭；Safari 17.6 复现）。本插件当前每帧都生成 `data:image/svg+xml` URI，因此在 Safari 上标签页图标可能完全不显示——这是最大的已知缺口。
 - **Safari 的动态 JS 更新为 hit-or-miss**，可能需要刷新一次；Safari 会「锁定」它首次看到的图标。目前没有保证可靠的、符合规范的手段能在 Safari 中实时更换 favicon。

package/icons/plugin.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 50 50" fill="none">
+	<style>
+		#p { fill: #1a1a1a; }
+	</style>
+	<path id="p" fill="#1a1a1a" d="M48.8354 10.0479C48.3232 9.79199 48.1025 10.2798 47.8032 10.5278C47.7007 10.6079 47.6143 10.7119 47.5273 10.8076C46.7793 11.624 45.9048 12.1597 44.7622 12.0957C43.0923 12 41.666 12.5356 40.4058 13.8398C40.1377 12.2319 39.2476 11.272 37.8926 10.6558C37.1836 10.3359 36.4668 10.0156 35.9702 9.31982C35.6235 8.82373 35.5293 8.27197 35.356 7.72754C35.2456 7.3999 35.1353 7.06396 34.7651 7.00781C34.3633 6.94385 34.2056 7.2876 34.0479 7.57568C33.418 8.75195 33.1733 10.0479 33.1973 11.3599C33.2524 14.312 34.4736 16.6641 36.8999 18.3359C37.1758 18.5278 37.2466 18.7197 37.1597 19C36.9946 19.5757 36.7974 20.1357 36.624 20.7119C36.5137 21.0801 36.3486 21.1597 35.9624 21C34.6309 20.4321 33.481 19.5918 32.4644 18.5757C30.7393 16.8721 29.1792 14.9917 27.2334 13.52C26.7764 13.1758 26.3193 12.856 25.8467 12.5518C23.8618 10.584 26.1069 8.96777 26.627 8.77588C27.1704 8.57568 26.8159 7.8877 25.0591 7.896C23.3022 7.90381 21.6953 8.50391 19.647 9.30371C19.3477 9.42383 19.0322 9.51172 18.7095 9.58398C16.8501 9.22363 14.9199 9.14355 12.9033 9.37598C9.10596 9.80762 6.07275 11.6396 3.84326 14.7681C1.16455 18.5278 0.53418 22.7998 1.30664 27.2559C2.11768 31.9521 4.46582 35.8398 8.07373 38.8799C11.8159 42.0322 16.1255 43.5762 21.041 43.2803C24.0269 43.104 27.3516 42.6963 31.1016 39.4561C32.0469 39.936 33.0396 40.1279 34.686 40.272C35.9546 40.3921 37.1758 40.208 38.1211 40.0078C39.6021 39.688 39.4995 38.2881 38.9639 38.0322C34.623 35.9678 35.5762 36.8081 34.71 36.1279C36.9155 33.4639 40.2402 30.6958 41.54 21.728C41.6426 21.0161 41.5557 20.5679 41.54 19.9917C41.5322 19.6396 41.6108 19.5039 42.0049 19.4639C43.0923 19.3359 44.1479 19.0317 45.1167 18.4878C47.9292 16.9199 49.064 14.3438 49.3315 11.2559C49.3711 10.7837 49.3237 10.2959 48.8354 10.0479ZM24.3262 37.8398C20.1196 34.4639 18.0791 33.3521 17.2358 33.3999C16.4482 33.4482 16.5898 34.3682 16.7632 34.9678C16.9443 35.5601 17.1812 35.9683 17.5117 36.4878C17.7402 36.832 17.8979 37.3442 17.2832 37.728C15.9282 38.584 13.5728 37.4399 13.4624 37.3838C10.7207 35.7358 8.42822 33.5601 6.81348 30.584C5.25342 27.7197 4.34766 24.6479 4.19775 21.3677C4.1582 20.5757 4.38672 20.2959 5.15869 20.1519C6.17529 19.96 7.22314 19.9199 8.23926 20.0718C12.5327 20.7119 16.1885 22.6719 19.2529 25.7759C21.002 27.5439 22.3252 29.6558 23.6885 31.7202C25.1377 33.9121 26.6978 36 28.6831 37.7119C29.3843 38.312 29.9434 38.7681 30.479 39.104C28.8643 39.2881 26.1699 39.3281 24.3262 37.8398ZM26.3433 24.6001C26.3433 24.248 26.6191 23.9678 26.9658 23.9678C27.0444 23.9678 27.1152 23.9839 27.1782 24.0078C27.2651 24.04 27.3438 24.0879 27.4067 24.1602C27.5171 24.272 27.5801 24.4321 27.5801 24.6001C27.5801 24.9521 27.3042 25.2319 26.9575 25.2319C26.6108 25.2319 26.3433 24.9521 26.3433 24.6001ZM32.6064 27.8799C32.2046 28.0479 31.8027 28.1919 31.4165 28.208C30.8179 28.2397 30.1641 27.9922 29.8096 27.688C29.2583 27.2158 28.8643 26.9521 28.6987 26.1279C28.6279 25.7759 28.6675 25.2319 28.7305 24.9199C28.8721 24.248 28.7144 23.8159 28.2495 23.4238C27.8716 23.104 27.3911 23.0161 26.8633 23.0161C26.666 23.0161 26.4849 22.9277 26.3511 22.856C26.1304 22.7441 25.9492 22.4639 26.1226 22.1201C26.1777 22.0078 26.4458 21.7358 26.5088 21.688C27.2256 21.272 28.0527 21.4077 28.8169 21.7197C29.5259 22.0161 30.0615 22.5601 30.834 23.3281C31.6216 24.2559 31.7632 24.5117 32.2124 25.208C32.5669 25.752 32.8901 26.312 33.1104 26.9521C33.2446 27.3521 33.0713 27.6802 32.6064 27.8799Z"/>
+</svg>

package/lib/client.js

@@ -5,9 +5,15 @@
  * Registers one configuration page and serves BOTH host generations from one
  * bundle:
  *
- * - DSH ≥ 0.1.7 (modern): page slot `plugins.row.config` keyed
- *   `<package name>#<row id>`, bound to the profile-entry settings namespace
- *   through `configForms` (`ctx.configForms.get(entryId)`).
+ * - DSH ≥ 0.1.7 (modern): the official Plugins page, bound to the
+ *   profile-entry settings namespace through `configForms`
+ *   (`ctx.configForms.get(entryId)`). The form registers into
+ *   `plugins.bundle.config` keyed by the bundle's package name, which the
+ *   bundle's page renders under its description — the page a card in the
+ *   Plugins list opens, so the settings are one click from that list (the
+ *   shape the official plugins use). A host that declares only the row slot —
+ *   no released host does (see AGENTS.md) — gets the row's configure control
+ *   instead; the two are mutually exclusive, never both.
  * - DSH ≤ 0.1.6-alpha.1 (legacy): page slot `settings.plugin.item` keyed by the
  *   legacy `web-icon-indicator` namespace, bound through `settingsScope`.
  *
@@ -57,6 +63,14 @@ window.__ModuleLoader__.load({
      * settings tab dispatches in `settings.plugin.item`.
      */
     var LEGACY_NS = "web-icon-indicator";
+    /**
+     * `plugins.bundle.config` key: the bundle's own package name. The bundle
+     * page renders this entry between its description and its rows, and that
+     * page is exactly what a card in the Plugins list opens — so this is the
+     * slot that keeps the settings one click from the list. Must match the
+     * installed package name in `package.json`.
+     */
+    var BUNDLE_KEY = "dsh-web-icon-indicator";
     /** `plugins.row.config` key: `<bundle package name>#<row id as the patch declares it>`. */
     var ROW_KEY = "dsh-web-icon-indicator#dsh-web-icon-indicator";
     var LOCALE = "dsh-web-icon-indicator";
@@ -1355,26 +1369,67 @@ window.__ModuleLoader__.load({
       // card follows whichever provider is mounted and renders nothing while
       // neither is.
       var pageFace = function () { return { scope: resolveScope(ctx), t: t }; };
-      // Register on BOTH page slots. `ctx.slots.inject(key, …)` is a no-op for a
-      // slot this host never declares, so each line runs exactly the branch it
-      // understands:
-      //   - `plugins.row.config` (≥0.1.6-alpha.2): keyed `<package>#<row id>`,
-      //     the row's configure control comes from this registration;
-      //   - `settings.plugin.item` (≤0.1.6-alpha.1): keyed by the legacy
+      // One settings card, three page slots across the host generations.
+      // `ctx.slots.inject(key, …)` is a no-op for a slot this host never
+      // declares, so `start` runs exactly the branches the running host
+      // understands. A DSH ≥ 0.1.7 host declares BOTH modern slots, so those
+      // two branches are mutually exclusive:
+      //   - `plugins.bundle.config` (≥ 0.1.7): keyed by the bundle's own package
+      //     name. The bundle page renders it under the description, and that
+      //     page is exactly what a card in the Plugins list opens — so the
+      //     settings sit one click from the list. This is the shape the
+      //     official plugins use (the official voice-input bundle registers
+      //     this slot).
+      //   - `plugins.row.config` (≥ 0.1.6-alpha.2): keyed `<package>#<row id>`,
+      //     it only adds the configure control on the bundle page's row, which
+      //     buries the form one level deeper (bundle page -> row -> configure).
+      //     Registered only where the bundle slot is absent — a guard no
+      //     released host reaches, since every host with a Plugins page
+      //     declares the bundle slot too (see AGENTS.md).
+      //   - `settings.plugin.item` (≤ 0.1.6-alpha.1): keyed by the legacy
       //     settings namespace, dispatched by the settings tab per served
       //     namespace.
       var start = function () {
-        var disposeRow = ctx.slots.inject("plugins.row.config", function () {
+        var rowInject = null;
+        var bundleLive = false;
+        var dropRow = function () {
+          var cancelRow = rowInject;
+          rowInject = null;
+          if (cancelRow !== null) cancelRow();
+        };
+        var disposeBundle = ctx.slots.inject("plugins.bundle.config", function () {
+          bundleLive = true;
+          // The bundle slot owns the card wherever it exists: cancel the row
+          // wait, or dispose a row registration the host declared first, so the
+          // same form is never drawn twice on one page.
+          dropRow();
           return ctx.slots.register(
             {
-              name: "plugins.row.config",
-              key: ROW_KEY,
+              name: "plugins.bundle.config",
+              key: BUNDLE_KEY,
               locale: LOCALE,
               inject: pageFace,
             },
             IconConfigCard
           );
         });
+        if (!bundleLive) {
+          rowInject = ctx.slots.inject("plugins.row.config", function () {
+            // The bundle slot may still be declared after this one (both slots
+            // arrive with the Plugins page's own registration): stay out of its
+            // way rather than registering a second copy of the same card.
+            if (bundleLive) return function () {};
+            return ctx.slots.register(
+              {
+                name: "plugins.row.config",
+                key: ROW_KEY,
+                locale: LOCALE,
+                inject: pageFace,
+              },
+              IconConfigCard
+            );
+          });
+        }
         var disposeItem = ctx.slots.inject("settings.plugin.item", function () {
           return ctx.slots.register(
             {
@@ -1386,7 +1441,7 @@ window.__ModuleLoader__.load({
             IconConfigCard
           );
         });
-        return function () { disposeRow(); disposeItem(); };
+        return function () { disposeBundle(); dropRow(); disposeItem(); };
       };
       // On the modern line, gate registration on the served namespace so an
       // uncomposed plugin shows no page; `whileServed` owns the returned

package/lib/index.js

@@ -237,6 +237,36 @@ const INJECTED_SCRIPT = `
       );
     }
 
+    // Every DSH shell up to 0.1.6-alpha.2 carried ONE <link rel=icon>. From
+    // 0.1.7-alpha.1 the shell ships a THEME-SCOPED PAIR instead:
+    //   <link rel=icon href=favicon-dark.svg media="(prefers-color-scheme: dark)">
+    //   <link rel=icon href=favicon.svg      media="(prefers-color-scheme: light)">
+    // Both links carry rel=icon, so querying just the first one and repainting
+    // it was silently useless: the browser resolves the favicon to the LAST
+    // connected link whose media condition matches, i.e. the second one — the
+    // one this script never touched. The tab then kept the shell's icon forever
+    // while the status endpoint changed underneath (the "icon never changes"
+    // bug). Normalize to ONE always-matching link first, then keep painting it.
+    function normalizeIconLinks() {
+      try {
+        var all = document.querySelectorAll("[rel~='icon']");
+        if (!all || !all.length) return;
+        var pick = all[0];
+        for (var i = 1; i < all.length; i++) {
+          // Prefer the variant the current scheme actually selects, so a
+          // dark-mode tab keeps the shell's dark artwork as its resting state.
+          var m = all[i].getAttribute("media");
+          if (m && window.matchMedia && window.matchMedia(m).matches) pick = all[i];
+        }
+        for (var j = 0; j < all.length; j++) {
+          var node = all[j];
+          if (node !== pick && typeof node.remove === "function") { try { node.remove(); } catch (e) {} }
+        }
+        // Drop the media condition: a link that no longer matches the scheme
+        // would be dead weight, and the frame we paint is scheme-agnostic.
+        try { pick.removeAttribute("media"); } catch (e) {}
+      } catch (e) {}
+    }
     // Capture the shell's own favicon ONCE, together with an offline-safe
     // data-URI copy of it. The copy matters: while the DSH host is stopped
     // the original href (a URL served by that same host) is unreachable, so
@@ -552,6 +582,7 @@ const INJECTED_SCRIPT = `
         });
     }
     captureOriginal();
+    normalizeIconLinks();
     TIMER = setInterval(poll, 1000);
     poll();
     // A BACKGROUND tab's timers are throttled (Chrome clamps setInterval to

package/lib/types/client/index.d.ts

@@ -2,10 +2,16 @@
  * Browser half of dsh-web-icon-indicator (dsh.client bundle).
  *
  * Registers one configuration page and serves both host generations from one
- * bundle: `plugins.row.config` (keyed `dsh-web-icon-indicator#dsh-web-icon-indicator`)
- * bound through the modern `configForms` service on DSH ≥ 0.1.7, and
- * `settings.plugin.item` (keyed by the legacy `web-icon-indicator` namespace)
- * bound through the legacy `settingsScope` service on DSH ≤ 0.1.6-alpha.1.
+ * bundle. Modern (DSH ≥ 0.1.7): `plugins.bundle.config` keyed by the bundle
+ * package name `dsh-web-icon-indicator`, so the bundle page a Plugins-list card
+ * opens renders the form directly; a host that declares only
+ * `plugins.row.config` (no released host does) gets that slot instead, keyed
+ * `dsh-web-icon-indicator#dsh-web-icon-indicator` — never both. Either binds
+ * through `configForms` on ≥ 0.1.7 or `settingsScope` on 0.1.6-alpha.2 (which
+ * already renders the bundle slot). Legacy (DSH ≤ 0.1.6-alpha.1):
+ * `settings.plugin.item`, keyed by the legacy `web-icon-indicator` namespace,
+ * bound through `settingsScope`.
+ *
  * Neither settings provider appears in `inject`: both are read weakly at render
  * time, so the fiber activates on either line.
  */

package/lib/types/index.d.ts

@@ -21,7 +21,8 @@
 * The same surface is registered with the DSH settings service under the
 * `web-icon-indicator` namespace (schemastery schema in `lib/index.js`): it is
 * validated, persisted into the profile's `settings.yaml`, and editable from
-* 设置 → 插件 → 插件配置 through the browser half (`./client`). While no
+* the Plugins page (设置 → 插件) through the browser half (`./client`) — the
+* settings form is registered on the plugin's own page. While no
 * settings service is composed, the plugin reads the composition entry only.
 */
 

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "dsh-web-icon-indicator",
   "description": "Browser tab favicon reflects the DSH session state: idle / running / asking / done, recolored and animated from one base SVG in the browser (fully configurable colors + effects). · 浏览器标签页 favicon 实时反映 DSH 会话状态：待机 / 运行中 / 提问 / 完成，由单个 base.svg 在浏览器中动态上色与动画（颜色与特效完全可配置）。",
-  "version": "0.5.1",
+  "icon": "icons/plugin.svg",
+  "version": "0.6.0",
   "type": "module",
   "engines": {
     "dsh": ">=0.1.2-rc.1"

package/test/verify.js

@@ -21,7 +21,7 @@
  */
 import { register } from "node:module";
 import { spawnSync } from "node:child_process";
-import { readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { readFileSync, statSync, writeFileSync, unlinkSync } from "node:fs";
 import vm from "node:vm";
 import os from "node:os";
 import path from "node:path";
@@ -416,6 +416,15 @@ const { default: plugin } = await import(new URL("../lib/index.js", import.meta.
   emit(h.onHandlers, "tools/result", { name: "ask_user_question", agent: { id: "A" } }, {});
   const askTimer = h.timers[h.timers.length - 1];
   ok("H10b ask hold timer scheduled", !!askTimer);
+  // The hold's whole point: a user who answers INSTANTLY must still see the
+  // asking icon. So the timer has to be armed for the resolved askingHoldMs and
+  // the pin has to survive every aggregate read until that timer fires — a live
+  // run cannot prove this (the answer's real latency dwarfs the hold).
+  eq("H10b2 hold waits the resolved askingHoldMs", askTimer.ms, 3500);
+  agg = aggregate();
+  eq("H10b3 still asking while the hold runs, though the answer already returned",
+    { state: agg.state, active: agg.active }, { state: "asking", active: 1 });
+  ok("H10b4 hold still pending (not fired, not disposed)", askTimer.fired === false);
   askTimer.cb(); // hold expired, answer already returned
   agg = aggregate();
   eq("H10c ask hold expired -> live running active 1",
@@ -879,29 +888,70 @@ const { default: plugin } = await import(new URL("../lib/index.js", import.meta.
 // ============================================================================
 // PART 2 — browser injected script (real template, VM + DOM/fetch/rAF stubs)
 // ============================================================================
-function makeFakeLink(initialHref) {
-  const attrs = { rel: "icon", type: "", href: initialHref || "" };
+function makeFakeLink(initialHref, attrs) {
+  const a = { rel: "icon", type: "", href: initialHref || "", ...(attrs || {}) };
   return {
     isConnected: true,
-    __attrs: attrs,
+    __attrs: a,
     setAttribute(k, v) {
-      attrs[k] = String(v);
+      if (v === null || v === undefined) delete a[k];
+      else a[k] = String(v);
     },
     getAttribute(k) {
-      return k in attrs ? attrs[k] : null;
+      return k in a ? a[k] : null;
+    },
+    // The real shell's favicon pair is scoped by a `media` condition, so the
+    // stub records its own media state and `remove()` detaches it — the two
+    // facts the fix's normalization has to act on.
+    hasMediaCondition(media) {
+      return a.media === media;
     },
+    remove() {
+      this.isConnected = false;
+    },
+    // A real replaceChild swaps NODES: the fresh link takes this one's place and
+    // does NOT inherit its attributes. Modelling that faithfully matters — the
+    // script relies on it to shed the shell's stale `media` condition, and the
+    // old "copy the fresh attrs onto the same object" shortcut hid exactly that.
     parentNode: {
+      __current: null,
       replaceChild(fresh) {
-        // adopt the fresh node's attrs into this link
-        for (const k of Object.keys(fresh.__attrs)) attrs[k] = fresh.__attrs[k];
+        fresh.__parent = this;
+        this.__current = fresh;
       },
     },
   };
 }
 
 class BrowserDriver {
-  constructor({ initialHref = "http://orig.example/favicon.ico", states = DEFAULT_STATES, withFileReader = false } = {}) {
-    this.link = makeFakeLink(initialHref);
+  constructor({ initialHref = "http://orig.example/favicon.ico", states = DEFAULT_STATES, withFileReader = false, links, matchMedia } = {}) {
+    this.links = links || [makeFakeLink(initialHref)];
+    this.matchMedia = matchMedia || (() => true); // a plain page: nothing is media-scoped
+    this.removed = []; // nodes detached by the script, in order
+    // Model a node swap faithfully (a real replaceChild does NOT copy the old
+    // node's attributes) and keep `links` in sync with the live DOM. The script
+    // replaces the <link> on every state change to defeat favicon caching, so
+    // this has to be installed on EVERY node — including the ones createElement
+    // makes later — or later swaps would silently leave `links` pointing at a
+    // detached node. (Getting this wrong hid the fix under test: the assertion
+    // kept reading the stale whale link.)
+    const patchSwap = (node) => {
+      node.parentNode.__current = node;
+      node.parentNode.replaceChild = (fresh) => {
+        const p = node.parentNode;
+        fresh.__parent = p;
+        p.__current = fresh;
+        const at = ctrl.links.indexOf(node);
+        if (at === -1) ctrl.links.push(fresh);
+        else ctrl.links[at] = fresh;
+        node.isConnected = false;
+        ctrl.removed.push(node);
+        patchSwap(fresh); // the replacement can be swapped again
+      };
+      return node;
+    };
+    for (const l of this.links) patchSwap(l);
+    const origCreate = (attrs) => patchSwap(makeFakeLink("", attrs));
     this.rafQueue = [];
     this.pollFn = null;
     this.queue = [];
@@ -917,10 +967,17 @@ class BrowserDriver {
       },
       document: {
         visibilityState: "visible",
-        querySelector: (sel) => (sel.includes("icon") ? ctrl.link : null),
-        createElement: () => makeFakeLink(""),
+        querySelector: (sel) => {
+          const all = ctrl.querySelectorAll(sel);
+          return all.length ? all[0] : null;
+        },
+        // [rel~='icon'] matches the real selector; 'icon' as a bare word keeps
+        // the historic `sel.includes("icon")` stub behavior for other callers.
+        querySelectorAll: (sel) => ctrl.querySelectorAll(sel),
+        createElement: () => origCreate(),
         head: { appendChild() {} },
       },
+      matchMedia: (q) => ({ matches: !!ctrl.matchMedia(q), media: q }),
       location: { origin: "http://localhost:3080" },
       setInterval: (fn) => {
         ctrl.pollFn = fn;
@@ -970,10 +1027,32 @@ class BrowserDriver {
     this.context = context;
     vm.runInContext(buildScript(states), context);
   }
+  // The `[rel~='icon']` selector the script uses, resolved against the stub
+  // DOM: detached nodes are gone, so a normalized/removed link stops matching.
+  querySelectorAll(sel) {
+    if (!sel.includes("icon")) return [];
+    return this.links.filter((l) => l.isConnected);
+  }
+  /** The link the browser would actually honour: the LAST connected one
+   * (the last connected is what a browser resolves an unscoped rel=icon to). */
+  get effectiveLink() {
+    const connected = this.links.filter((l) => l.isConnected);
+    // Honour `media` when the stub has one, so "run" and "assert" agree.
+    const live = connected.filter((l) => l.__attrs.media === undefined || this.matchMedia(l.__attrs.media));
+    const pick = live.length ? live : connected;
+    return pick.length ? pick[pick.length - 1] : null;
+  }
+  /** The current favicon node. *Not* a stored property: the script replaces the
+   * node (to defeat favicon caching), which would leave a stored reference
+   * pointing at a detached element. */
+  get link() {
+    return this.effectiveLink;
+  }
   get href() {
     // Favicon frames are encodeURIComponent'd data URIs; decode so assertions
     // can match literal SVG substrings (rx="11", >3<, #E5484D, ...).
-    return decodeURIComponent(this.link.__attrs.href || "");
+    const l = this.effectiveLink || this.link;
+    return decodeURIComponent(l.__attrs.href || "");
   }
   svgRes(text) {
     return { ok: true, status: 200, text: async () => text, json: async () => ({}) };
@@ -1233,6 +1312,60 @@ console.log("\n=== Part 2: browser injected script ===");
   // poll a different state while visible and confirm the listener path stays safe.
   await v.poll({ state: "running", active: 1, states: DEFAULT_STATES });
   ok("B18d subsequent polls unaffected after visible-return poll", v.href.includes("FACC15"));
+
+  // B19 the DSH >= 0.1.7 shell ships a THEME-SCOPED PAIR of favicon links:
+  //   <link rel=icon href=favicon-dark.svg media="(prefers-color-scheme: dark)">
+  //   <link rel=icon href=favicon.svg      media="(prefers-color-scheme: light)">
+  // The browser honours the LAST connected link whose media matches, so
+  // repainting only the first one left the tab on the shell's icon forever
+  // while the status endpoint changed underneath — the "icon never changes"
+  // report. The script must collapse the pair onto one always-matching link.
+  const shellPair = () => [
+    makeFakeLink("http://localhost:3080/favicon-dark.svg", { media: "(prefers-color-scheme: dark)" }),
+    makeFakeLink("http://localhost:3080/favicon.svg", { media: "(prefers-color-scheme: light)" }),
+  ];
+  const light = new BrowserDriver({
+    links: shellPair(),
+    matchMedia: (q) => q === "(prefers-color-scheme: light)",
+  });
+  await light.ready({ state: "running", active: 1, states: DEFAULT_STATES });
+  await light.poll({ state: "running", active: 1, states: DEFAULT_STATES });
+  ok("B19a a media-scoped pair collapses to ONE icon link at startup",
+    light.links.filter((l) => l.isConnected).length === 1,
+    "connected=" + light.links.filter((l) => l.isConnected).length);
+  ok("B19b that link carries no media condition left to mis-match",
+    light.effectiveLink.getAttribute("media") === null,
+    JSON.stringify(light.effectiveLink.getAttribute("media")));
+  ok("B19c the browser-effective href is the painted frame, not the shell icon",
+    light.href.indexOf("data:image/svg+xml") === 0 && light.href.includes("FACC15"),
+    light.href.slice(0, 90));
+  // Dark scheme: the shell's dark variant is the one kept as the resting href.
+  const dark = new BrowserDriver({
+    links: shellPair(),
+    matchMedia: (q) => q === "(prefers-color-scheme: dark)",
+  });
+  await dark.ready({ state: "idle", active: 0, states: DEFAULT_STATES });
+  ok("B19d dark scheme keeps the dark variant (its own scheme wins)",
+    dark.effectiveLink.__attrs.href.indexOf("favicon-dark.svg") !== -1 ||
+    dark.effectiveLink.__attrs.href.indexOf("data:image/svg+xml") === 0,
+    dark.effectiveLink.__attrs.href.slice(0, 90));
+  const beforeRepaint = dark.links.length;
+  await dark.poll({ state: "running", active: 1, states: DEFAULT_STATES });
+  ok("B19e the count-block/whale frame repaints the single kept link",
+    dark.href.includes("FACC15"), dark.href.slice(0, 90));
+  // A same-key re-poll mutates the live link in place and a key change swaps the
+  // node (how the plugin defeats favicon caching). Either way the invariants
+  // are: exactly one link stays connected, its href is a painted data: URI, and
+  // the retired shell link never comes back.
+  await dark.poll({ state: "done", active: 1, states: DEFAULT_STATES });
+  ok("B19f repainting keeps exactly one connected link, still the painted one",
+    dark.links.filter((l) => l.isConnected).length === 1 &&
+    dark.links.length === 2 &&                       // the retired shell link never returns
+    dark.links.filter((l) => !l.isConnected).length === 1 &&
+    dark.href.indexOf("data:image/svg+xml") === 0,
+    "before=" + beforeRepaint + " now=" + dark.links.length + " connected=" +
+    dark.links.map((l) => (l.isConnected ? "+" : "-")).join("") +
+    " href=" + dark.href.slice(0, 60));
 }
 
 // ============================================================================
@@ -1442,6 +1575,7 @@ console.log("\n=== Part 6: browser half (lib/client.js) ===");
   const makeClientCtx = (opts) => {
     const declared = new Set(opts.declared || []);
     const services = opts.services || {};
+    const sink = opts.sink || registered;
     return {
       get(name) { return services[name]; },
       locale: {
@@ -1450,13 +1584,23 @@ console.log("\n=== Part 6: browser half (lib/client.js) ===");
       },
       slots: {
         inject(name, cb) { if (declared.has(name)) cb(); return () => {}; },
-        register(slotSpec, component) { registered.push({ slotSpec, component }); return () => {}; },
+        register(slotSpec, component) {
+          const entry = { slotSpec, component, disposed: false };
+          sink.push(entry);
+          return () => { entry.disposed = true; };
+        },
       },
       effect(fn) { return fn(); },
     };
   };
+  // A DSH >= 0.1.7 host declares BOTH configuration slots when the Plugins
+  // page's own registration commits, and the card must land in exactly one of
+  // them: `plugins.bundle.config` renders on the bundle's page — the page a
+  // Plugins-list card opens, so one click from the list — while
+  // `plugins.row.config` only puts a configure control on that page's row,
+  // one level deeper. Registering into both would draw the same form twice.
   const clientCtx = makeClientCtx({
-    declared: ["plugins.row.config"],
+    declared: ["plugins.bundle.config", "plugins.row.config"],
     services: {
       configForms: {
         get(entryId) { boundEntryId = entryId; return scope; },
@@ -1469,15 +1613,18 @@ console.log("\n=== Part 6: browser half (lib/client.js) ===");
   ok("F6 locale dictionaries registered (en + zh)",
     dictionaries.length === 1 && !!dictionaries[0].dicts.en && !!dictionaries[0].dicts.zh,
     "ns=" + (dictionaries[0] && dictionaries[0].ns));
-  ok("F7 modern line: one card registered into plugins.row.config",
-    registered.length === 1 && registered[0].slotSpec.name === "plugins.row.config",
+  ok("F7 modern line: one card registered into plugins.bundle.config",
+    registered.length === 1 && registered[0].slotSpec.name === "plugins.bundle.config",
     "count=" + registered.length + " " + JSON.stringify(registered.map((r) => r.slotSpec.name)));
   ok("F7b registration is gated on whileServed(entry id)",
     Array.isArray(servedNamespaces) && servedNamespaces.length === 1 &&
     servedNamespaces[0] === "dsh-web-icon-indicator",
     JSON.stringify(servedNamespaces));
   const slotSpec = registered[0] && registered[0].slotSpec;
-  eq("F8 slot key is <package>#<row id>", slotSpec && slotSpec.key, "dsh-web-icon-indicator#dsh-web-icon-indicator");
+  eq("F8 bundle slot key is the bundle package name", slotSpec && slotSpec.key, "dsh-web-icon-indicator");
+  ok("F8b the row slot stays untouched where the bundle slot exists",
+    registered.every((r) => r.slotSpec.name !== "plugins.row.config"),
+    JSON.stringify(registered.map((r) => r.slotSpec.name)));
   eq("F9 slot locale namespace", slotSpec && slotSpec.locale, "dsh-web-icon-indicator");
   // The scope is resolved lazily inside the inject face (the two settings
   // providers are mutually exclusive), so evaluate it before asserting.
@@ -1530,6 +1677,99 @@ console.log("\n=== Part 6: browser half (lib/client.js) ===");
     ok("F61f legacy component renders the card", !!legacyCard && legacyCard.type === "div");
   }
 
+  // ---- the row-only Plugins page (DSH 0.1.6-alpha.2) ------------------------
+  // The bundle slot arrived with the 0.1.7 Plugins page. A host that declares
+  // only `plugins.row.config` keeps that older entry point — the configure
+  // control on the row the bundle declares — and must still get exactly one
+  // card, keyed by the row slot's `<package>#<row id>`.
+  {
+    const rowSink = [];
+    const rowCtx = makeClientCtx({
+      declared: ["plugins.row.config"],
+      sink: rowSink,
+      services: {
+        configForms: {
+          get: () => scope,
+          whileServed: (namespaces, register) => register(new Set(namespaces)),
+        },
+      },
+    });
+    client.apply(rowCtx);
+    eq("F66 row-only page: exactly one registration", rowSink.length, 1);
+    eq("F66b row-only page: registered into plugins.row.config",
+      rowSink[0] && rowSink[0].slotSpec.name, "plugins.row.config");
+    eq("F66c row-only page: key is <package>#<row id>",
+      rowSink[0] && rowSink[0].slotSpec.key, "dsh-web-icon-indicator#dsh-web-icon-indicator");
+  }
+
+  // ---- both modern slots, declared in either order --------------------------
+  // The real 0.1.7 host declares `plugins.bundle.config` and
+  // `plugins.row.config` from the Plugins page's own registration, so both
+  // waits this bundle installs resolve AFTER apply(). Whichever declaration
+  // lands first, exactly one entry must survive — and it must be the bundle
+  // one, or the settings would sit a level deeper than the official plugins'.
+  {
+    const makeLazyCtx = (sink) => {
+      const pending = new Map();
+      const ctx = {
+        get: (name) => (name === "configForms"
+          ? { get: () => scope, whileServed: (_ns, register) => register(new Set()) }
+          : undefined),
+        locale: { register: () => () => {}, bind: () => (k) => k },
+        slots: {
+          inject(name, cb) {
+            const controller = { cb, active: true, disposers: [] };
+            if (!pending.has(name)) pending.set(name, []);
+            pending.get(name).push(controller);
+            return () => {
+              if (!controller.active) return;
+              controller.active = false;
+              for (const dispose of controller.disposers.splice(0)) dispose();
+            };
+          },
+          register(slotSpec, component) {
+            const entry = { slotSpec, component, disposed: false };
+            sink.push(entry);
+            return () => { entry.disposed = true; };
+          },
+        },
+        effect: (fn) => fn(),
+      };
+      return {
+        ctx,
+        declare(name) {
+          for (const controller of pending.get(name) || []) {
+            if (!controller.active) continue;
+            const dispose = controller.cb();
+            if (typeof dispose === "function") controller.disposers.push(dispose);
+          }
+        },
+      };
+    };
+
+    const rowFirstSink = [];
+    const rowFirst = makeLazyCtx(rowFirstSink);
+    client.apply(rowFirst.ctx);
+    rowFirst.declare("plugins.row.config");
+    eq("F67 row declaration first: the row entry is registered", rowFirstSink.length, 1);
+    eq("F67b ... into plugins.row.config", rowFirstSink[0].slotSpec.name, "plugins.row.config");
+    rowFirst.declare("plugins.bundle.config");
+    const survivors = rowFirstSink.filter((entry) => !entry.disposed);
+    eq("F67c the bundle declaration takes the card over — one live entry", survivors.length, 1);
+    eq("F67d ... and it is the bundle entry",
+      survivors[0] && survivors[0].slotSpec.name, "plugins.bundle.config");
+    eq("F67e ... keyed by the bundle package name",
+      survivors[0] && survivors[0].slotSpec.key, "dsh-web-icon-indicator");
+
+    const bundleFirstSink = [];
+    const bundleFirst = makeLazyCtx(bundleFirstSink);
+    client.apply(bundleFirst.ctx);
+    bundleFirst.declare("plugins.bundle.config");
+    bundleFirst.declare("plugins.row.config");
+    eq("F68 bundle declaration first: exactly one entry", bundleFirstSink.length, 1);
+    eq("F68b ... the bundle one", bundleFirstSink[0].slotSpec.name, "plugins.bundle.config");
+  }
+
   // ---- card render ---------------------------------------------------------
   // React is stubbed, so a re-render is driven explicitly: the card's own
   // setState calls `rerender()`, which re-invokes the component with the same
@@ -2258,8 +2498,62 @@ console.log("\n=== Part 6: browser half (lib/client.js) ===");
       CLIENT_SRC.indexOf("settingsScope") !== -1 &&
       CLIENT_SRC.indexOf("settings.plugin.item") !== -1 &&
       CLIENT_SRC.indexOf("configForms") !== -1 &&
+      CLIENT_SRC.indexOf("plugins.bundle.config") !== -1 &&
       CLIENT_SRC.indexOf("plugins.row.config") !== -1 &&
       CLIENT_SRC.indexOf("whileServed") !== -1);
+
+    // ---- official Plugins page icon (host manifest contract) ---------------
+    // The 0.1.7 page reads `package.json.icon` through <pkg>/package.json and
+    // base64s the file (readPluginMeta -> iconOf in @deepseek-ai/dsh-app-boot):
+    // a manifest-relative SVG/PNG/JPEG/WebP at most 256 KiB, contained in the
+    // manifest directory after realpath. Any violation does not blank the card
+    // — it turns the plugin's `meta.error` on and the card shows a problem tag,
+    // so every rule below is load-bearing.
+    const MANIFEST = JSON.parse(readFileSync(new URL("package.json", REPO), "utf8"));
+    const ICON_REL = MANIFEST.icon;
+    const ICON_EXT = typeof ICON_REL === "string" ? ICON_REL.slice(ICON_REL.lastIndexOf(".")).toLowerCase() : "";
+    ok("F62 the manifest declares a relative image icon",
+      typeof ICON_REL === "string" && ICON_REL.trim() !== "" &&
+      !/^[A-Za-z][A-Za-z\d+.-]*:/u.test(ICON_REL) &&           // rejects URLs (and Windows drive letters)
+      !ICON_REL.startsWith("/") && !ICON_REL.startsWith("\\") &&
+      !/^[A-Za-z]:/u.test(ICON_REL) &&                        // rejects C:\... absolute paths
+      !ICON_REL.split(/[\\/]/u).includes("..") &&             // must stay inside the manifest directory
+      [".svg", ".png", ".jpg", ".jpeg", ".webp"].includes(ICON_EXT),
+      JSON.stringify(ICON_REL));
+
+    let ICON_SVG = "";
+    let ICON_BYTES = 0;
+    try {
+      ICON_SVG = readFileSync(new URL(ICON_REL, REPO), "utf8");
+      ICON_BYTES = statSync(new URL(ICON_REL, REPO)).size;
+    } catch {
+      /* the F63 check below reports the missing file */
+    }
+    ok("F63 the declared icon ships and stays under the 256 KiB manifest bound",
+      ICON_BYTES > 0 && ICON_BYTES <= 256 * 1024,
+      ICON_BYTES + " bytes");
+
+    // A leftover __COLOR__ placeholder is not valid SVG: the page would render
+    // an unpainted whale (or nothing) where the artwork goes.
+    ok("F64 the icon is standalone SVG with no placeholder left in it",
+      ICON_SVG !== "" &&
+      ICON_SVG.startsWith("<svg ") && ICON_SVG.trimEnd().endsWith("</svg>") &&
+      !ICON_SVG.includes("__COLOR__"),
+      ICON_SVG.slice(0, 40));
+
+    // icons/plugin.svg and docs/assets/favicon.svg are the same static whale;
+    // keep them byte-identical so regenerating one from icons/base.svg cannot
+    // silently leave the other stale. Repo-only (absent from the npm tarball).
+    let DOCS_FAVICON = null;
+    try {
+      DOCS_FAVICON = readFileSync(new URL("docs/assets/favicon.svg", REPO), "utf8");
+    } catch {
+      /* published tarball: docs/ is repo-only */
+    }
+    if (DOCS_FAVICON !== null) {
+      ok("F65 icons/plugin.svg stays identical to docs/assets/favicon.svg",
+        DOCS_FAVICON === ICON_SVG);
+    }
   }
 }