dsh-web-icon-indicator 0.4.2 → 0.5.0

package/lib/types/index.d.ts

@@ -10,6 +10,7 @@
 *   config:
 *     askingHoldMs: 3500
 *     doneHoldMs: 5000
+*     defaultColor: '#5B8DEF'   # per-instance default icon color
 *     states:
 *       idle:    { effect: static, colors: ['#1a1a1a'] }
 *       running: { effect: static, colors: ['#FACC15'] }
@@ -60,15 +61,50 @@ export interface DshWebIconIndicatorConfig {
    * Defaults to `<package>/icons/`.
    */
   iconsDir?: string;
-  /** Status JSON endpoint the browser polls. Default `/dsh-web-icon-status.json`. */
+  /**
+   * Status JSON endpoint the browser polls. Default `/dsh-web-icon-status.json`.
+   *
+   * **Registration-time:** set it in the composition entry only. The route
+   * table and the injected script are built when the plugin mounts, so this key
+   * is intentionally absent from the settings schema (`settings.yaml`) — a
+   * settings-document change could never be honored and would point the browser
+   * at a path the server does not serve.
+   */
   statusPath?: string;
-  /** URL prefix where `base.svg` is served. Default `/dsh-web-icon-indicator`. */
+  /**
+   * URL prefix where `base.svg` is served. Default `/dsh-web-icon-indicator`.
+   *
+   * **Registration-time:** set it in the composition entry only — see
+   * {@link statusPath}.
+   */
   iconPathPrefix?: string;
   /** Minimum visibility of the asking state in milliseconds. Default 3500. */
   askingHoldMs?: number;
   /** Time the done state stays before falling back to idle, in milliseconds. Default 5000. */
   doneHoldMs?: number;
-  /** Per-state visual config. Each entry is shallow-merged over its default. */
+  /**
+   * Default icon color — the idle whale's primary color, as `#rgb` / `#rrggbb`.
+   * Absent keeps the idle state's own `colors[0]` (the behavior before this key
+   * existed). Give each DSH instance a different value to tell their browser
+   * tabs apart: it is per instance (profile / `settings.yaml`), not per tab.
+   *
+   * Folded into `states.idle.colors[0]` at resolve time, so an idle entry that
+   * only needs its default is untouched. This is the **only** idle knob the
+   * settings card offers: idle paints one color and takes no animation, so it
+   * gets no per-state row (no effect / colors / cycle). A value perceptually too
+   * close to another state's color raises an advisory warning (settings card,
+   * host log, and {@link DshWebIconIndicatorAggregate.warnings}) but is still
+   * applied; a malformed value is ignored and reported.
+   */
+  defaultColor?: string;
+  /**
+   * Per-state visual config. Each entry is shallow-merged over its default.
+   *
+   * `idle` is not editable from the settings card (its color is
+   * {@link defaultColor}); a `states.idle` entry arriving from the composition
+   * entry or a hand-written `settings.yaml` is still honored for backward
+   * compatibility — including an idle `effect` and a second color.
+   */
   states?: Partial<Record<DshWebIconStateName, DshWebIconStateConfig>>;
 }
 
@@ -91,6 +127,39 @@ export interface DshWebIconIndicatorAggregate {
    * reload). Added in 0.2.x; older browser bundles ignore it.
    */
   states: Partial<Record<DshWebIconStateName, DshWebIconStateConfig>>;
+  /**
+   * Effective default icon color (normalized to lowercase 6-digit hex), or
+   * `null` when none is configured — the status payload always carries the key.
+   * Added with the `defaultColor` key; older browser bundles ignore the extra
+   * field.
+   */
+  defaultColor: string | null;
+  /**
+   * Advisory default-color warnings, echoed so any surface can show them.
+   * Added with the `defaultColor` key; older browser bundles ignore the key.
+   */
+  warnings: DshWebIconColorWarning[];
+}
+
+/**
+ * A perceptual-distance warning about the effective default icon color.
+ * Advisory only — the configured value is still applied.
+ */
+export interface DshWebIconColorWarning {
+  /** `color-too-close` | `rainbow-overlap` | `invalid-color`. */
+  code: "color-too-close" | "rainbow-overlap" | "invalid-color";
+  /** The other state involved (absent for `invalid-color`). */
+  state?: DshWebIconStateName;
+  /** The effective default color the warning is about. */
+  base?: string;
+  /** The colliding state color (absent for `rainbow-overlap` / `invalid-color`). */
+  color?: string;
+  /** CIE76 ΔE between `base` and `color`. */
+  deltaE?: number;
+  /** `strong` below ΔE 12; `warn` below ΔE 25. */
+  level?: "strong" | "warn";
+  /** The rejected raw value (only for `invalid-color`). */
+  value?: string;
 }
 
 /**
@@ -100,7 +169,7 @@ export interface DshWebIconIndicatorAggregate {
  */
 declare const plugin: {
   name: "dsh-web-icon-indicator";
-  inject: readonly ["webServer", "timer", "agents", "fs", "sandboxPolicy"];
+  inject: readonly ["webServer", "timer", "agents", "fs"];
   config: DshWebIconIndicatorConfig;
   apply(ctx: unknown, config?: unknown): void;
   /** Settings namespace carrying the config (`web-icon-indicator`). */

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.4.2",
+  "version": "0.5.0",
   "type": "module",
   "engines": {
     "dsh": ">=0.1.2-rc.1"
@@ -13,7 +13,7 @@
     "type": "git",
     "url": "git+https://github.com/waknow/dsh-web-icon-indicator.git"
   },
-  "homepage": "https://github.com/waknow/dsh-web-icon-indicator",
+  "homepage": "https://waknow.github.io/dsh-web-icon-indicator/",
   "bugs": {
     "url": "https://github.com/waknow/dsh-web-icon-indicator/issues"
   },
@@ -51,7 +51,7 @@
     "lib",
     "icons",
     "assets",
-    "docs",
+    "test",
     "cordis.patch.yml",
     "screenshots.json",
     "CHANGELOG.md",

package/test/loader-hooks.mjs

@@ -0,0 +1,21 @@
+// Loader hooks that redirect the two @deepseek-ai peer imports of
+// lib/index.js to local zero-dependency stubs (test/stubs), so test/verify.js
+// can import and drive the REAL host plugin without a node_modules.
+// Registered from test/verify.js via module.register before importing
+// ../lib/index.js.
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const STUBS = {
+  "@deepseek-ai/schemastery": join(here, "stubs", "schemastery.mjs"),
+  "@deepseek-ai/dsh-settings": join(here, "stubs", "dsh-settings.mjs"),
+};
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier in STUBS) {
+    return { url: pathToFileURL(STUBS[specifier]).href, shortCircuit: true };
+  }
+  return nextResolve(specifier, context);
+}

package/test/stubs/dsh-settings.mjs

@@ -0,0 +1,15 @@
+// Zero-dependency stub for `@deepseek-ai/dsh-settings`, used only by
+// test/loader-hooks.mjs. Captures the installSettingsSection args into
+// globalThis so test/verify.js can assert the settings wiring and drive the
+// captured setSource/onChange hooks.
+export function settingsNamespace(name) {
+  return name;
+}
+
+export function installSettingsSection(ctx, ns, schema, entry, opts) {
+  const slot = (globalThis.__DSH_ICON_TEST__ ||= {});
+  slot.ns = ns;
+  slot.schema = schema;
+  slot.entry = entry;
+  slot.settingsOpts = opts;
+}

package/test/stubs/schemastery.mjs

@@ -0,0 +1,12 @@
+// Zero-dependency stub for `@deepseek-ai/schemastery`, used only by
+// test/loader-hooks.mjs so test/verify.js can import the REAL lib/index.js
+// without resolving the actual peer dependency. Only the surface used at
+// module top level (chainable z.object / z.array / z.string / z.number /
+// z.union / z.dict with .default()) needs to not throw; CONFIG_SCHEMA is
+// passed to the stubbed installSettingsSection and never validated.
+const z = new Proxy(function schemasteryStub() {}, {
+  get: () => z,
+  apply: () => z,
+});
+
+export default z;