dsh-web-icon-indicator 0.5.0 → 0.5.2

package/lib/client.js

@@ -2,15 +2,26 @@
  * Browser half of dsh-web-icon-indicator (dsh.client bundle, ModuleLoader
  * factory format — hand-written, no build step).
  *
- * Registers one card into the shared "plugin configuration" surface
- * (`settings.plugin.item`, keyed by the `web-icon-indicator` settings
- * namespace). The card binds the namespace's settings scope, stages edits
- * locally, and writes them through `scope.set` / `scope.unset` (validated and
- * persisted host-side into the profile's settings.yaml).
+ * Registers one configuration page and serves BOTH host generations from one
+ * bundle:
  *
- * The tab that dispatches this slot (`dsh-client-ui-settings-plugins`) only
- * renders the card while the host serves the namespace, so this bundle is
- * inert on deployments that do not compose the host plugin.
+ * - 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.6-alpha.1 (legacy): page slot `settings.plugin.item` keyed by the
+ *   legacy `web-icon-indicator` namespace, bound through `settingsScope`.
+ *
+ * Neither settings provider is declared in `inject` — both are read weakly at
+ * render time (`resolveScope`) and the slot registration is attempted for both
+ * names (`slots.inject` is a no-op for a slot the host never declares). The
+ * card body is generation-agnostic: the modern controller and the legacy scope
+ * expose the same snapshot + `mutate` / `unset` face. The card stages edits
+ * locally and writes them through that scope (validated, revision-fenced, and
+ * persisted host-side).
+ *
+ * The page is inert on deployments that do not compose the host plugin: on the
+ * modern line registration is gated on `configForms.whileServed`, and the
+ * legacy tab only dispatches namespaces the host actually serves.
  */
 window.__ModuleLoader__.load({
   id: "dsh-web-icon-indicator",
@@ -26,9 +37,28 @@ window.__ModuleLoader__.load({
     // Official UI primitives (same source the shell's own plugin cards use,
     // e.g. dsh-client-ui-settings-plugins): the standard collapse chevron.
     var primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+    // The primitives icon set moved from size-suffixed names (`…Outline14`) to
+    // stroke-weight names (`…OutlineRegular` / `…OutlineMedium`); fall back so
+    // one bundle keeps working on both host lines.
+    var ChevronDownIcon = primitives.IconChevronDownOutlineRegular || primitives.IconChevronDownOutline14;
 
-    /** Settings namespace owned by the host plugin (must match lib/index.js). */
-    var NS = "web-icon-indicator";
+    /**
+     * Settings namespace owned by the host plugin on the MODERN host line
+     * (DSH ≥ 0.1.7): the settings service keys every form by the profile entry
+     * id, and the bundle patch in `cordis.patch.yml` inserts exactly one row
+     * with this id. Keep it in sync with `SETTINGS_NAMESPACE` in lib/index.js
+     * and the row id in the patch.
+     */
+    var NS = "dsh-web-icon-indicator";
+    /**
+     * Settings namespace the LEGACY host line (DSH ≤ 0.1.6-alpha.1) serves: the
+     * plugin registers it through `settings.installSection`, and this half binds
+     * the legacy `settingsScope` to the same string. Also the key the legacy
+     * settings tab dispatches in `settings.plugin.item`.
+     */
+    var LEGACY_NS = "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";
     var STATE_NAMES = ["idle", "running", "asking", "done"];
     var EFFECT_NAMES = ["static", "blink", "breath", "rainbow", "heartbeat", "bounce"];
@@ -82,8 +112,17 @@ window.__ModuleLoader__.load({
       bounce: "effectBounce",
     };
 
-    /** Cordis fiber services this browser plugin injects. */
-    var inject = ["slots", "settingsScope", "locale"];
+    /**
+     * Cordis fiber services this browser plugin injects.
+     *
+     * Deliberately only the two services every host line provides: the settings
+     * provider itself is read weakly at render time (`resolveScope`), so one
+     * bundle serves both the modern `configForms` line (DSH ≥ 0.1.7) and the
+     * legacy `settingsScope` line (≤ 0.1.6-alpha.1). A hard `inject` on either
+     * name would leave the fiber un-activated on the other line, which is what
+     * broke the 0.5.x bundle on 0.1.7.
+     */
+    var inject = ["slots", "locale"];
 
     // ---------------------------------------------------------------------------
     // Locale copy
@@ -642,12 +681,17 @@ window.__ModuleLoader__.load({
       return { kind: "set", value: parsed };
     }
 
-    /** Subscribe a React component to the scope's snapshot store. */
+    /**
+     * Subscribe a React component to the scope's snapshot store. `scope` may be
+     * null while the host serves no settings provider for our namespace (or
+     * before one appears); the hook count stays identical either way, and a
+     * null scope yields a null snapshot that renders nothing.
+     */
     function useScopeSnapshot(scope) {
       return useSyncExternalStore(
-        function (listener) { return scope.subscribe(listener); },
-        function () { return scope.getSnapshot(); },
-        function () { return scope.getSnapshot(); }
+        function (listener) { return scope ? scope.subscribe(listener) : function () {}; },
+        function () { return scope ? scope.getSnapshot() : null; },
+        function () { return scope ? scope.getSnapshot() : null; }
       );
     }
 
@@ -1050,11 +1094,18 @@ window.__ModuleLoader__.load({
       };
 
       var disabled = !writable || saving;
+      // The Plugins page asks a configuration entry twice: `view: 'summary'`
+      // for the row's one-liner and `view: 'page'` for the body of its own
+      // page (the page already heads it with the plugin's title and
+      // description). A host that renders this card standalone passes no
+      // `view` and keeps the collapsible header.
+      if (props.view === "summary") return t("description");
+      var pageView = props.view === "page";
 
       return createElement(
         "div",
         { style: styles.card },
-        createElement(
+        pageView ? null : createElement(
           "button",
           {
             type: "button",
@@ -1073,10 +1124,10 @@ window.__ModuleLoader__.load({
           createElement(
             "span",
             { style: Object.assign({}, styles.chevron, open ? styles.chevronOpen : {}) },
-            createElement(primitives.IconChevronDownOutline14, {})
+            createElement(ChevronDownIcon, {})
           )
         ),
-        open ? createElement(
+        (open || pageView) ? createElement(
           "div",
           { style: styles.body },
           !writable ? createElement("p", { style: styles.hint }, t("readOnly")) : null,
@@ -1274,23 +1325,81 @@ window.__ModuleLoader__.load({
     // ---------------------------------------------------------------------------
     // Plugin entry
     // ---------------------------------------------------------------------------
+
+    /**
+     * The settings form this card binds, on whichever host line is running.
+     *
+     * - DSH ≥ 0.1.7 exposes `configForms`, one controller per profile entry id
+     *   (snapshot + revision-fenced `mutate` / `unset`); the provider owns the
+     *   remote write, so this plugin never declares `remote` itself.
+     * - DSH ≤ 0.1.6-alpha.1 exposes `settingsScope`; binding it to the legacy
+     *   namespace yields the same snapshot/write face the card already uses.
+     *
+     * Read weakly on purpose: the two services are mutually exclusive, and the
+     * caller's `inject` list must stay valid on both lines.
+     */
+    function resolveScope(ctx) {
+      var forms = ctx.get("configForms");
+      if (forms && typeof forms.get === "function") return forms.get(NS);
+      var legacy = ctx.get("settingsScope");
+      if (legacy && typeof legacy.bind === "function") return legacy.bind({ namespace: LEGACY_NS });
+      return null;
+    }
+
     function apply(ctx) {
       var t = ctx.locale.bind(LOCALE);
       ctx.effect(function () {
         return ctx.locale.register(LOCALE, { zh: zh, en: en });
-      }, "dsh-web-icon-indicator: settings card dictionaries");
-      var scope = ctx.settingsScope.bind({ namespace: NS });
-      ctx.slots.inject("settings.plugin.item", function () {
-        return ctx.slots.register(
-          {
-            name: "settings.plugin.item",
-            key: NS,
-            locale: LOCALE,
-            inject: function () { return { scope: scope, t: t }; },
-          },
-          IconConfigCard
-        );
-      });
+      }, "dsh-web-icon-indicator: settings page dictionaries");
+      // The scope is resolved per render (see the inject face below), so the
+      // 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
+      //     settings namespace, dispatched by the settings tab per served
+      //     namespace.
+      var start = function () {
+        var disposeRow = ctx.slots.inject("plugins.row.config", 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(
+            {
+              name: "settings.plugin.item",
+              key: LEGACY_NS,
+              locale: LOCALE,
+              inject: pageFace,
+            },
+            IconConfigCard
+          );
+        });
+        return function () { disposeRow(); disposeItem(); };
+      };
+      // On the modern line, gate registration on the served namespace so an
+      // uncomposed plugin shows no page; `whileServed` owns the returned
+      // disposer, so `start` must hand one back. The legacy line needs no gate:
+      // its tab only dispatches namespaces the host serves.
+      var forms = ctx.get("configForms");
+      if (forms && typeof forms.whileServed === "function") {
+        ctx.effect(function () {
+          return forms.whileServed([NS], start);
+        }, "dsh-web-icon-indicator: settings page");
+      } else {
+        ctx.effect(start, "dsh-web-icon-indicator: settings page");
+      }
     }
 
     exports.apply = apply;

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. */
@@ -193,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
@@ -508,6 +582,7 @@ const INJECTED_SCRIPT = `
         });
     }
     captureOriginal();
+    normalizeIconLinks();
     TIMER = setInterval(poll, 1000);
     poll();
     // A BACKGROUND tab's timers are throttled (Chrome clamps setInterval to
@@ -695,34 +770,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 +896,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;