dsh-web-icon-indicator 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

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.
 
@@ -227,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
@@ -274,8 +277,10 @@ 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.

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 会话状态——`待机` / `运行中` / `提问` / `完成`——让你在标签页置于后台时也能一眼看出是否有会话需要处理。
 
@@ -205,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）会左右分格同时显示
@@ -239,8 +240,9 @@ 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` 声明。

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/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

@@ -2,7 +2,7 @@
   "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 在浏览器中动态上色与动画（颜色与特效完全可配置）。",
   "icon": "icons/plugin.svg",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "type": "module",
   "engines": {
     "dsh": ">=0.1.2-rc.1"

package/test/verify.js

@@ -1575,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: {
@@ -1583,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; },
@@ -1602,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.
@@ -1663,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
@@ -2391,6 +2498,7 @@ 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);