dsh-web-icon-indicator 0.5.0 → 0.5.1

package/lib/index.js

@@ -40,17 +40,17 @@
  * Configuration object (all optional):
  *   iconsDir       Absolute directory holding base.svg. Default `<package>/icons/`.
  *   statusPath     JSON status endpoint path. Default `/dsh-web-icon-status.json`.
- *                  Registration-time: composition entry only (never settings.yaml).
+ *                  Registration-time (non-volatile): composition entry only.
  *   iconPathPrefix URL prefix for static icon files. Default `/dsh-web-icon-indicator`.
- *                  Registration-time: composition entry only (never settings.yaml).
+ *                  Registration-time (non-volatile): composition entry only.
  *   askingHoldMs   Minimum visibility for the asking state (ms). Default 3500.
  *   doneHoldMs     How long the done state stays before falling back to idle.
  *                  Default 5000.
  *   defaultColor   Default icon color — the idle whale's primary color, as
  *                  `#rgb` / `#rrggbb`. Absent = the idle state's own colors[0]
  *                  (today's behavior). Give each DSH instance (its own profile /
- *                  settings.yaml) a different value to tell their browser tabs
- *                  apart. A value perceptually too close to another state's
+ *                  user settings layer) a different value to tell their browser
+ *                  tabs apart. A value perceptually too close to another state's
  *                  color raises a WARNING — surfaced in the settings card, in
  *                  the host log, and as `warnings` on the status endpoint — but
  *                  is still honored.
@@ -67,12 +67,23 @@
  *                  - speed: optional per-state cycle in ms (blink toggle interval too).
  *                    Default 1200.
  *
- * The whole config surface is also registered with the DSH settings service
- * (namespace `web-icon-indicator`): validated against a schemastery schema,
- * persisted to the profile's `settings.yaml`, and editable from
- * 设置 → 插件 → 插件配置 in the Web GUI (see the `dsh.client` browser half).
- * While the profile composes no settings service, the plugin keeps working
- * exactly as before, reading the composition entry directly.
+ * The whole config surface is the plugin's Cordis `Config` schema (exported as
+ * both `Config` and `CONFIG_SCHEMA`), and the same schema is registered with
+ * the LEGACY settings service when the running host still exposes
+ * `installSection` — one bundle serves every published host generation:
+ *
+ *   - DSH ≥ 0.1.7: the settings service projects the schema's `.volatile()`
+ *     fields into a live form, persisted into the profile patch
+ *     (`~/.dsh/profiles/<profile>/cordis.patch.yml`); a write mutates the
+ *     running plugin's config references in place and emits
+ *     `loader/volatile-update` instead of restarting it.
+ *   - DSH ≤ 0.1.6-alpha.1: the plugin registers the namespace itself under
+ *     `web-icon-indicator` and the service drives it through
+ *     `setSource`/`onChange`, persisted into `~/.dsh/settings.yaml`.
+ *
+ * `statusPath` / `iconPathPrefix` stay non-volatile in both. When the profile
+ * composes no settings service at all, the plugin keeps working on the
+ * composition entry + defaults it was mounted with.
  *
  * @module dsh-web-icon-indicator
  */
@@ -104,21 +115,54 @@ const EFFECT_NAMES = ["static", "blink", "breath", "rainbow", "heartbeat", "boun
 const STATE_NAMES = ["idle", "running", "asking", "done"];
 
 /**
- * Settings namespace under which this plugin's config is registered (the
- * `web-icon-indicator:` section of the profile's settings.yaml, surfaced in
- * 设置 → 插件 → 插件配置). Lowercase kebab, per the settings domain's rule.
+ * Settings namespace of this plugin on the MODERN host line (DSH ≥ 0.1.7):
+ * the settings namespace IS the profile entry id (`schema(entry)` reads
+ * `entry.fiber.runtime.Config` and `describe()` keys every form by
+ * `entry.options.id`), and this plugin's bundle patch declares exactly one row:
+ * `dsh-web-icon-indicator`. The browser half reads the same namespace through
+ * `ctx.configForms.get(...)`, so the two halves must keep this literal in sync
+ * (it is also the row id in `cordis.patch.yml`).
+ */
+const SETTINGS_NAMESPACE = "dsh-web-icon-indicator";
+
+/**
+ * Settings namespace on the LEGACY host line (DSH ≤ 0.1.6-alpha.1), where the
+ * consumer-owned namespace is an arbitrary string it passes to
+ * `settings.installSection` and the settings document section is named after
+ * it. Kept at the historical value so an existing 0.5.x user's
+ * `web-icon-indicator:` section keeps working after this upgrade; the browser
+ * half binds its legacy scope to the same string.
+ */
+const LEGACY_SETTINGS_NAMESPACE = "web-icon-indicator";
+
+/**
+ * Mark one field as LIVE when the resolved schemastery supports it.
  *
- * Since DSH 0.1.2 the namespace is a plain string literal (the type-level
- * `SettingsNamespace` brand exists only at compile time; the runtime value is
- * the same string), so no helper import is needed here.
+ * `.volatile()` exists since schemastery 3.18.3 and is what makes the modern
+ * settings service render a field at all (`volatileForm()` keeps volatile
+ * fields only) and what makes a settings write mutate the running plugin's
+ * references + emit `loader/volatile-update` instead of restarting it. On the
+ * legacy host line the installed schemastery (3.18.2) has no `.volatile()`,
+ * and the legacy settings service owns the whole live-form lifecycle through
+ * `installSection`/`setSource`/`onChange`, so the same schema object works
+ * unwrapped there.
  */
-const SETTINGS_NAMESPACE = "web-icon-indicator";
+const LIVE = (schema) => (typeof schema.volatile === "function" ? schema.volatile() : schema);
 
 /**
- * Schemastery schema mirroring `DEFAULTS`. Registered with the settings
- * service so the config is validated, persisted, and editable from the Web
- * settings page; resolution order is schema defaults → composition `base`
- * → user layer (`~/.dsh/settings.yaml`).
+ * Schemastery schema mirroring `DEFAULTS`. Exported as the plugin's `Config`,
+ * which is what the Cordis loader validates the composition row against and
+ * what the modern host settings service projects into its live form
+ * (`volatileForm` keeps only `.volatile()` fields, so the settings page can
+ * never advertise a key it cannot honor).
+ *
+ * `.volatile()` marks a field as LIVE: the loader commits a settings write
+ * into the running fiber's references and emits `loader/volatile-update`
+ * instead of restarting the plugin (see `apply`). Ordinary (non-volatile)
+ * fields — `statusPath` / `iconPathPrefix` — are baked into the route table
+ * and the injected script at registration time, so a document change to them
+ * could never take effect; keeping them non-volatile removes them from the
+ * live form while still validating the composition entry.
  */
 const STATE_CONFIG_SCHEMA = z.object({
   effect: z.union(EFFECT_NAMES).default("static"),
@@ -129,24 +173,24 @@ const STATE_CONFIG_SCHEMA = z.object({
 });
 
 const CONFIG_SCHEMA = z.object({
-  askingHoldMs: z.number().min(0).default(DEFAULTS.askingHoldMs),
-  doneHoldMs: z.number().min(0).default(DEFAULTS.doneHoldMs),
+  askingHoldMs: LIVE(z.number().min(0).default(DEFAULTS.askingHoldMs)),
+  doneHoldMs: LIVE(z.number().min(0).default(DEFAULTS.doneHoldMs)),
   // Default icon color (`#rgb` / `#rrggbb`). Deliberately WITHOUT a schema
   // default: an absent value keeps the idle state's own colors[0], exactly as
   // before this key existed. `resolveConfig` folds a valid value into
   // `states.idle.colors[0]` and drops an invalid one with a warning.
-  defaultColor: z.string(),
-  // `statusPath` / `iconPathPrefix` are deliberately NOT part of this schema.
-  // They are baked at registration time (the route table and the injected
-  // script's URLs are built in apply()), so a settings-document change to them
-  // could never take effect: the browser would poll the new path while the
-  // server still served the old one — a dead favicon. Keeping them out of the
-  // schema means the settings surface cannot advertise a key it cannot honor;
-  // they stay composition-entry only (see the README config table).
-  iconsDir: z.string(),
+  defaultColor: LIVE(z.string()),
+  iconsDir: LIVE(z.string()),
   // dict (not a four-key object): the user layer may override only some
-  // states; the plugin merges the resolved value over DEFAULTS anyway.
-  states: z.dict(STATE_CONFIG_SCHEMA).default(DEFAULTS.states),
+  // states; the plugin merges the resolved value over DEFAULTS anyway. The
+  // whole dict is one volatile field, so the custom card can stage and write
+  // it atomically through `scope.mutate([{ op: 'set', path: ['states'], … }])`.
+  states: LIVE(z.dict(STATE_CONFIG_SCHEMA).default(DEFAULTS.states)),
+  // Registration-time keys: route table + injected script URLs are built in
+  // apply(), so they are composition-entry only (non-volatile ⇒ absent from
+  // the live settings form). See the README config table.
+  statusPath: z.string().default(DEFAULTS.statusPath),
+  iconPathPrefix: z.string().default(DEFAULTS.iconPathPrefix),
 });
 
 /** Browser script injected into every served index.html response. */
@@ -695,34 +739,49 @@ function colorWarnings(states) {
 }
 
 /**
- * Cordis plugin entry. Returns the standard `{ apply, inject, config }`
- * shape so the host composition can mount it once at startup.
+ * Cordis plugin entry. Returns the standard `{ apply, inject, Config }`
+ * shape so the host composition can mount it once at startup. `Config` (the
+ * schemastery schema) is what the loader validates the row against and what
+ * the host settings service projects into its live form — a plugin without it
+ * has no server-declared configuration surface at all. One bundle serves both
+ * host lines: the legacy `settings.installSection` path is feature-detected at
+ * runtime (see `apply`).
  */
 export default {
   name: "dsh-web-icon-indicator",
   inject: ["webServer", "timer", "agents", "fs"],
-  config: {
-    askingHoldMs: DEFAULTS.askingHoldMs,
-    doneHoldMs: DEFAULTS.doneHoldMs,
-    statusPath: DEFAULTS.statusPath,
-    iconPathPrefix: DEFAULTS.iconPathPrefix,
-    iconsDir: undefined,
-    defaultColor: undefined,
-    states: DEFAULTS.states,
-  },
-  /** Settings namespace + validation schema (exported for reuse/tooling). */
+  Config: CONFIG_SCHEMA,
+  /** Settings namespace (the profile entry id on ≥0.1.7) + schema, for tooling. */
   SETTINGS_NAMESPACE,
+  /** Settings namespace used on the legacy (≤0.1.6-alpha.1) settings service. */
+  LEGACY_SETTINGS_NAMESPACE,
   CONFIG_SCHEMA,
   apply(ctx, config) {
-    // Cordis passes the resolved composition config as the second argument
-    // (`apply(ctx, config)`). `config` is the row's own `config` from the
-    // profile composition (merged over the schema only when a `Config` schema
-    // is declared); this plugin merges its `DEFAULTS` itself via `resolveConfig`,
-    // so an absent row config simply yields the defaults. Fall back to the old
-    // `ctx.get("config")` read for compatibility (it is undefined on the host
-    // but kept for the zero-dep test harness and older hosts).
-    const entry = config ?? ctx.get("config") ?? {};
-    let source = () => entry;
+    // Cordis passes the schema-resolved config as the second argument
+    // (`apply(ctx, config)`). Every `.volatile()` field arrives as a live
+    // reference (`config.states.get()`), and the loader mutates those
+    // references in place when a settings write lands — that is what
+    // `loader/volatile-update` below reacts to. Unwrap the references once per
+    // read so the rest of this file keeps working on plain values. The
+    // `ctx.get("config")` fallback keeps the zero-dependency test harness (and
+    // any host that hands the row config through the service container) working.
+    const readRef = (value) =>
+      value !== null && typeof value === "object" && typeof value.get === "function" ? value.get() : value;
+    const readConfig = (raw) => {
+      const out = {};
+      for (const [key, value] of Object.entries(raw || {})) {
+        const plain = readRef(value);
+        if (plain !== undefined) out[key] = plain;
+      }
+      return out;
+    };
+    // Legacy host line (DSH ≤ 0.1.6-alpha.1): `settings.installSection` owns the
+    // namespace lifecycle and hands this plugin a live source through
+    // `setSource`. Until it does, the composition config passed to `apply` (or
+    // the zero-dep test harness's `ctx.get("config")`) is the source.
+    let legacySource = null;
+    const source = () =>
+      readConfig(legacySource ? legacySource() : config ?? ctx.get("config") ?? {});
     // Merge each configured state over its default: { effect, colors, speed }.
     // Idempotent on schema-resolved values, so it doubles as the fallback
     // normalization when the profile composes no settings service.
@@ -806,54 +865,72 @@ export default {
         }
       } catch (e) {}
     };
-    let cfg = resolveConfig(entry);
+    let cfg = resolveConfig(source());
     logWarnings(cfg.warnings);
     // The injected script bakes config at injection time; rebuild it whenever
-    // the settings section changes so the NEXT page load picks the new values
-    // up (reload the tab — same contract as before this registration).
+    // the live config changes so the NEXT page load picks the new values up
+    // (reload the tab — the running tab is already carried by the status poll's
+    // `states` echo).
     const buildScript = (c) => INJECTED_SCRIPT
       .replace("__STATUS_PATH__", c.statusPath)
       .replace("__BASE_PATH__", c.iconPathPrefix + "/base.svg")
       .replace("__CFG__", JSON.stringify({ states: c.states }));
     let script = buildScript(cfg);
     let iconsDir = resolveIconsDir(cfg.iconsDir);
-    // Register the settings namespace with the host `settings` service. Since
-    // DSH 0.1.2 the standalone `installSettingsSection` export is gone — the
-    // host exposes a `settings` service whose `installSection(owner, ns,
-    // schema, entry, hooks)` carries the same attach/detach lifecycle (base
-    // layer + `setSource` sink + `onChange` notification). The host's own
-    // plugins all use `ctx.inject(["settings"], …)` so the section attaches as
-    // soon as the provider is available — a plain `ctx.get("settings")` can run
-    // before the provider is ready and silently skip the registration. When no
-    // settings provider is composed the callback never fires and the plugin
-    // keeps working on its composition entry + DEFAULTS only.
-    ctx.inject(["settings"], (settingsCtx) => {
-      settingsCtx.settings.installSection(ctx, SETTINGS_NAMESPACE, CONFIG_SCHEMA, entry, {
-        setSource: (next) => { source = next; },
-        onChange: () => {
-          // Settings service mounted, or the section changed: re-resolve, then
-          // mutate cfg in place so the state-machine closures (asking/done hold)
-          // and the injected script see the new values immediately.
-          // `statusPath` / `iconPathPrefix` are NOT taken from the settings
-          // source: they are baked into the route table and the injected script
-          // at registration time, so honoring a settings edit here would break
-          // the live poll (see CONFIG_SCHEMA).
-          const next = resolveConfig(source());
-          cfg.askingHoldMs = next.askingHoldMs;
-          cfg.doneHoldMs = next.doneHoldMs;
-          if (next.iconsDir !== undefined) cfg.iconsDir = next.iconsDir;
-          cfg.states = next.states;
-          // `defaultColor` / `warnings` ride along with `states`: the color is
-          // already folded into `states.idle.colors[0]`, so the browser needs no
-          // new key — they are kept for observability (status echo + log).
-          cfg.defaultColor = next.defaultColor;
-          cfg.warnings = next.warnings;
-          iconsDir = resolveIconsDir(cfg.iconsDir);
-          script = buildScript(cfg);
-          logWarnings(cfg.warnings);
-        },
+    // Live settings, modern line (DSH ≥ 0.1.7). The host owns the whole
+    // configuration lifecycle: the loader validates the composition row against
+    // `Config`, the `settings` service (`SettingsForms`) derives the live form
+    // from the schema's `.volatile()` fields and writes them into the profile
+    // patch, and a volatile-only write is committed into the running fiber's
+    // references with a `loader/volatile-update` event instead of a restart.
+    // This listener rebuilds the cached `cfg` and the injected script from the
+    // same references; the legacy line below drives it through `onChange`
+    // instead. `statusPath` / `iconPathPrefix` are NOT volatile: they are baked
+    // into the route table and the injected script at registration time, so a
+    // document change to them re-applies the whole plugin instead (they stay
+    // outside the live form — see CONFIG_SCHEMA).
+    const refreshFromConfig = () => {
+      const next = resolveConfig(source());
+      cfg.askingHoldMs = next.askingHoldMs;
+      cfg.doneHoldMs = next.doneHoldMs;
+      if (next.iconsDir !== undefined) cfg.iconsDir = next.iconsDir;
+      cfg.states = next.states;
+      // `defaultColor` / `warnings` ride along with `states`: the color is
+      // already folded into `states.idle.colors[0]`, so the browser needs no
+      // new key — they are kept for observability (status echo + log).
+      cfg.defaultColor = next.defaultColor;
+      cfg.warnings = next.warnings;
+      iconsDir = resolveIconsDir(cfg.iconsDir);
+      script = buildScript(cfg);
+      logWarnings(cfg.warnings);
+    };
+    // A plain `ctx.on` listener is enough: the loader emits this event on the
+    // owning fiber's context only, so a volatile write to another plugin's
+    // config never reaches here. Guard for the zero-dep test harness, whose
+    // fake ctx carries no event bus.
+    if (typeof ctx.on === "function") ctx.on("loader/volatile-update", refreshFromConfig);
+    // Legacy host line (DSH ≤ 0.1.6-alpha.1): the `settings` service exposes
+    // `installSection`, and the plugin must register its namespace itself —
+    // that service method was removed in 0.1.7, where the exported `Config`
+    // schema plus `loader/volatile-update` carry the same lifecycle. Feature-
+    // detect instead of switching on a version: whichever service the running
+    // host provides decides the path, so one bundle serves both lines.
+    // The base layer is a RESOLVED PLAIN COPY (`resolveConfig(source())`), not
+    // the raw `apply` config: the legacy loader deep-freezes the config it
+    // resolved against the exported `Config` schema, and the legacy settings
+    // service resolves the schema over the base IN PLACE (its `mergeLayers`
+    // returns the base unchanged when no user section exists) — handing it a
+    // frozen object throws "Cannot assign to read only property".
+    if (typeof ctx.inject === "function") {
+      ctx.inject(["settings"], (settingsCtx) => {
+        const settings = settingsCtx.settings;
+        if (!settings || typeof settings.installSection !== "function") return;
+        settings.installSection(ctx, LEGACY_SETTINGS_NAMESPACE, CONFIG_SCHEMA, resolveConfig(source()), {
+          setSource: (next) => { legacySource = next; },
+          onChange: refreshFromConfig,
+        });
       });
-    });
+    }
     const webServer = ctx.webServer;
     const agents = ctx.agents;
     const fs = ctx.fs;

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

@@ -1,14 +1,20 @@
 /**
  * Browser half of dsh-web-icon-indicator (dsh.client bundle).
  *
- * Registers one card into the shared plugin-configuration surface
- * (`settings.plugin.item` slot, keyed by the `web-icon-indicator` settings
- * namespace). The card is inert unless the host serves the namespace, which
- * the dispatching tab (`dsh-client-ui-settings-plugins`) checks for us.
+ * 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.
+ * Neither settings provider appears in `inject`: both are read weakly at render
+ * time, so the fiber activates on either line.
  */
 
-/** Cordis services this browser plugin injects. */
-export declare const inject: readonly ["slots", "settingsScope", "locale"];
+/**
+ * Cordis services this browser plugin injects. Only the two services every
+ * host generation provides; the settings providers are optional weak reads.
+ */
+export declare const inject: readonly ["slots", "locale"];
 
-/** Mount the settings card for the `web-icon-indicator` namespace. */
+/** Mount the settings page on whichever host generation is running. */
 export declare function apply(ctx: unknown): void;

package/lib/types/index.d.ts

@@ -163,17 +163,26 @@ export interface DshWebIconColorWarning {
 }
 
 /**
- * Cordis plugin entry: `{ name, inject, config, apply, SETTINGS_NAMESPACE,
- * CONFIG_SCHEMA }`. Mount once per profile through the bundle patch
- * (`cordis.patch.yml`), never as a session-scoped agent preset.
+ * Cordis plugin entry: `{ name, inject, Config, apply, SETTINGS_NAMESPACE,
+ * LEGACY_SETTINGS_NAMESPACE, CONFIG_SCHEMA }`. Mount once per profile through
+ * the bundle patch (`cordis.patch.yml`), never as a session-scoped agent
+ * preset.
+ *
+ * `Config` is the schemastery schema the loader validates the profile row
+ * against and the host settings service projects into its live form
+ * (`.volatile()` fields only); this entry has no `config` object. The same
+ * bundle serves the legacy host line through a feature-detected
+ * `settings.installSection` registration.
  */
 declare const plugin: {
   name: "dsh-web-icon-indicator";
   inject: readonly ["webServer", "timer", "agents", "fs"];
-  config: DshWebIconIndicatorConfig;
+  Config: unknown;
   apply(ctx: unknown, config?: unknown): void;
-  /** Settings namespace carrying the config (`web-icon-indicator`). */
+  /** Settings namespace on DSH ≥ 0.1.7 (= the profile entry id). */
   SETTINGS_NAMESPACE: string;
+  /** Settings namespace on the legacy settings service (DSH ≤ 0.1.6-alpha.1). */
+  LEGACY_SETTINGS_NAMESPACE: string;
   /** Schemastery schema validating the config surface. */
   CONFIG_SCHEMA: unknown;
 };

package/package.json

@@ -1,7 +1,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 在浏览器中动态上色与动画（颜色与特效完全可配置）。",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "engines": {
     "dsh": ">=0.1.2-rc.1"
@@ -27,7 +27,8 @@
         "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-renderer",
         "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-client-ui-settings-plugins"
+        "@deepseek-ai/dsh-client-ui-settings-plugins",
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
       ]
     }
   },