dsh-theme-gallery 0.1.3 → 0.1.5

package/README.md

@@ -114,6 +114,32 @@ dsh plugin --profile web add dsh-theme-gallery
 只在你想跟源码时用它。本包**没有构建步骤**，所以不会出现"缺 `lib/` 目录"那类失败；
 它的代价是 pnpm 可能要求你为构建脚本授权（`allowBuilds`）。
 
+### 更新到新版本
+
+**先说清楚：DSH 桌面版本身不会提示第三方插件有更新**，所以「发现新版」和「执行更新」这两件事得靠下面的渠道。
+
+**怎么知道有新版本？**
+
+| 渠道 | 说明 |
+|---|---|
+| **插件市场** | 装 [DSH-Plugins-Marketplace](https://github.com/bradeGithub/DSH-Plugins-Marketplace) 后，卡片会显示 **「已装 v0.1.4 → v0.1.6」** 并给**更新**按钮 —— 目前最省事的路径 |
+| **GitHub Releases** | 在本仓库点 **Watch → Custom → Releases only**，有新版本会收到邮件 |
+| **对照版本号** | 插件面板右上角显示**你装的版本**（如 `v0.1.4`），与 [npm 页面](https://www.npmjs.com/package/dsh-theme-gallery) 上的版本号直接对照 |
+
+**怎么更新？**
+
+1. **设置 → 插件 → 添加插件** → 再填一次 `dsh-theme-gallery` → **重启**（装上 `^x.y.z` 范围内的最新版）
+2. 想要**强制拿最新**（含 0.1.x → 0.2.0 这类次版本号变更）：**先移除、再添加**
+3. 装了市场的：点卡片上的**更新**按钮
+4. Web / CLI profile：`dsh plugin --profile web add dsh-theme-gallery`
+
+**版本范围语义**：安装时会记录成 **`^0.1.4`**，即 `>=0.1.4 <0.2.0` ——
+`0.1.5` / `0.1.9` 这类补丁会在重装时自动带上；**`0.2.0` 不会**（npm 对 `0.x` 的惯例是
+把次版本号变更视为可能破坏性），那种情况按第 2 条显式重装即可。
+
+> ⚠️ 从 **Release 的 `.tgz`** 安装的用户**没有更新机制**（tgz 是一次性快照，只能重新下载）——
+> 想长期跟更新，建议用**包名安装**。
+
 ### 兼容性与权限
 
 | 项 | 说明 |

package/lib/client.js

@@ -105,6 +105,21 @@ window.__ModuleLoader__.load({
      */
     const READING = { bg: '#FFFFFF', alpha: 0.62, blur: 3, maxWidth: 640 }
 
+    /**
+     * The package version this bundle was built from.
+     *
+     * Written by `scripts/embed-themes.mjs` from package.json, because the browser
+     * half cannot read its own manifest: the client module system resolves `require`
+     * against the platform seed table and other plugins' boot-graph rows, not
+     * against this package's files. The panel shows it so a reader can compare what
+     * they have with what npm publishes.
+     *
+     * Kept honest by two checks: `scripts/publish-check.mjs` compares it with
+     * package.json, and the release workflow fails when re-running the embed step
+     * changes a tracked file.
+     */
+    const BUNDLED_VERSION = '0.1.5'
+
     /**
      * Themes this package contributes, inlined from lib/themes/*.json.
      *
@@ -1118,22 +1133,36 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * Whether the gallery shows its diagnostic line.
+     * Where the debug switch is remembered.
+     *
+     * A localStorage flag in addition to the URL fragment, because this plugin
+     * ships as a package inside the desktop app: there is no address bar to add
+     * `#theme-gallery-debug` to, so DevTools is the way in.
+     */
+    const DEBUG_KEY = 'theme-gallery:debug'
+
+    /**
+     * Whether the gallery shows its diagnostic detail lines.
+     *
+     * The raw readings — token counts, geometry, hit tests, the attempt log — are
+     * for whoever is debugging, not for whoever is picking a skin, and this is a
+     * shipped package. So they are opt-in, through either switch:
+     *
+     *   DevTools console:  localStorage.setItem('theme-gallery:debug', '1')
+     *   …or a URL with      #theme-gallery-debug
+     *   turn it off:       localStorage.removeItem('theme-gallery:debug')
      *
-     * Opt-in through the URL hash — `#theme-gallery-debug` — so the page stays
-     * clean in normal use while the one tool that actually located the token and
-     * presenter faults stays one reload away. From outside the app, "selected but
-     * nothing changed" cannot be split into "not registered", "not selected",
-     * "registered with broken tokens", or "painted over by our own CSS"; this line
-     * splits it by showing what the theme SERVICE believes next to what the
-     * document actually resolves.
-     * @returns true when the debug line should render.
+     * The switch gates DETAIL, never bad news: a line that reports a problem prints
+     * whether or not it is on (see `sceneryLineIsWarning`), because "没有报错" and
+     * "没有观测到报错" have been confused in this project before.
+     * @returns true when the detail lines should render.
      */
     function debugEnabled() {
       try {
-        return typeof window !== 'undefined'
+        if (typeof window !== 'undefined'
           && typeof window.location?.hash === 'string'
-          && window.location.hash.includes('theme-gallery-debug')
+          && window.location.hash.includes('theme-gallery-debug')) return true
+        return typeof window !== 'undefined' && window.localStorage?.getItem(DEBUG_KEY) === '1'
       } catch {
         return false
       }
@@ -1211,12 +1240,15 @@ window.__ModuleLoader__.load({
     /**
      * The one-line scenery status shown on the panel.
      *
-     * Deliberately unconditional during bring-up, and deliberately dumb: it prints
-     * the report whatever it says. The previous revision only spoke when a
-     * self-check considered something wrong, so a check that passed while the
-     * scenery was still invisible produced **silence** — the worst possible output
-     * for a diagnostic. Printing the numbers always means the reader sees the
-     * geometry even when the code's opinion of it is wrong.
+     * Deliberately dumb: it prints the report whatever it says. An earlier
+     * revision only spoke when a self-check considered something wrong, so a check
+     * that PASSED while the scenery was still invisible produced **silence** — the
+     * worst possible output for a diagnostic. Keeping the numbers means the reader
+     * sees the geometry even when the code's opinion of it is wrong.
+     *
+     * It was unconditional while the scenery was being brought up; now that the
+     * package is public the RENDER SITE decides: routine reports wait for
+     * `debugEnabled()`, while warnings and errors always print.
      * @param selected - the preference the page is showing as selected.
      * @returns the line, or null when the active theme asks for no scenery.
      */
@@ -1231,6 +1263,20 @@ window.__ModuleLoader__.load({
       }
     }
 
+    /**
+     * Whether the scenery line reports a problem rather than a routine pass.
+     *
+     * The line has three shapes: `装饰自检通过 · …` (routine), `⚠ <warning> · …`,
+     * and `装饰自检失败: …`. Only the first may hide behind the debug switch — a
+     * failure has to reach the person looking at the panel without them knowing
+     * that a switch exists.
+     * @param line - the scenery line.
+     * @returns true when the line carries a warning or an error.
+     */
+    function sceneryLineIsWarning(line) {
+      return typeof line === 'string' && (line.startsWith('⚠') || line.includes('失败'))
+    }
+
     /**
      * Render the scenery report as one line.
      * @returns the report text.
@@ -2736,6 +2782,28 @@ window.__ModuleLoader__.load({
       return BUNDLED_THEMES.find((theme) => theme.id === id)
     }
 
+    /**
+     * Read one token out of a bundled skin, resolving the pair form to the skin's own scheme.
+     *
+     * The bundled skins store most tokens as `{ light, dark }` pairs even though a skin itself is
+     * single-scheme. `flatten` collapses them for `register`; this is the same read, exposed
+     * separately because the accent diagnostic needs ONE token's declared value without building
+     * the whole registrable definition — and because that diagnostic lives at factory scope, where
+     * `flatten` (declared inside `mountGallery`) is not reachable. Reaching for it from here is the
+     * exact scope error `tests/check-scope-reach.mjs` exists to catch.
+     * @param definition - a bundled skin.
+     * @param name - the token name.
+     * @returns the declared value, or undefined when the skin has no such token.
+     */
+    function declaredToken(definition, name) {
+      const raw = definition?.tokens?.[name]
+      if (raw === undefined) return undefined
+      // Deliberately not `raw?.[…]`: a skin whose token is neither a string nor a pair is a data
+      // error, and `flatten` (the other caller) must keep failing loudly on it rather than
+      // registering an unset variable that paints nothing.
+      return typeof raw === 'string' ? raw : raw[definition.colorScheme]
+    }
+
     /**
      * Disposer of the active accent layer, when one is stacked.
      *
@@ -2748,6 +2816,20 @@ window.__ModuleLoader__.load({
      */
     let accentLayerDispose
 
+    /**
+     * The accent colour {@link accentLayerDispose} was built from.
+     *
+     * Declared here for the same reason as the disposer above: `syncAccent` both reads and writes
+     * it, and it is called during mount, so a `let` initialised later in the body would be in its
+     * temporal dead zone at the first call.
+     *
+     * It exists so that re-stacking can be skipped when the colour has not moved. Without it every
+     * `theme/change` — including ones this plugin caused and ones caused by something else —
+     * disposed and re-created the layer, which emits again.
+     * @type {string|undefined}
+     */
+    let stackedAccent
+
     /**
      * The plugin context, published for the factory-level helpers.
      *
@@ -2796,15 +2878,46 @@ window.__ModuleLoader__.load({
       // `try` swallowed it, and the accent marker silently never appeared. The module-level `ctx`
       // below is assigned at mount and read here.
       if (ctx === undefined) return
-      if (accentLayerDispose !== undefined) {
-        accentLayerDispose()
-        accentLayerDispose = undefined
-      }
-      if (typeof accent !== 'string' || accent === '') return
-      accentLayerDispose = ctx.theme.overrideTokens('theme-gallery: accent', {
-        '--dsw-alias-button-ghost-active-fill': { light: `${accent}29`, dark: `${accent}29` },
-        '--dsw-alias-button-ghost-active-border': { light: accent, dark: accent },
-        '--dsw-alias-button-ghost-active-hover': { light: `${accent}47`, dark: `${accent}47` },
+      const wanted = typeof accent === 'string' && accent !== '' ? accent : undefined
+      // ── WHY BOTH A SKIP AND THE SELF-EMIT GUARD ARE NEEDED ───────────────────────────────────
+      //
+      // `overrideTokens` and the disposer it returns BOTH emit `theme/change`, and this function
+      // is reached from `publish()`, which is itself driven by that event:
+      //
+      //     publish → syncSkin → syncAccent → overrideTokens → theme/change → publish → …
+      //
+      // Every level nests inside the previous CALL, so nothing ever yields to the event loop. The
+      // stack therefore grows until the engine refuses to grow it further and throws
+      // `RangeError: Maximum call stack size exceeded` — and because every level has its own
+      // `try/catch` (see `syncSkin`), each one logs the SAME message on the way out. That is why
+      // the console showed a flood of "could not stack the accent layer" lines rather than one
+      // error: one flood, hundreds of identical lines, each from a different depth.
+      //
+      // Fixing it takes both halves, and they are not interchangeable:
+      //
+      //   • the SKIP stops the churn — an accent that has not moved does not need a new layer, so
+      //     an unrelated `theme/change` (the shell's `adopt()`, a streamed render, another plugin)
+      //     no longer replaces the layer and causes a repaint;
+      //   • the GUARD stops the RE-ENTRY — it is what makes the `theme/change` emitted by our own
+      //     write invisible to the subscription, so the cycle cannot close even when the colour
+      //     genuinely did change.
+      //
+      // Only the guard is a correctness requirement; the skip is what keeps the layer stable. The
+      // same shape is used by `stackSkinTokens` for the palette and by `syncReadingLayer`.
+      if (wanted === stackedAccent) return
+      emitting(() => {
+        if (accentLayerDispose !== undefined) {
+          accentLayerDispose()
+          accentLayerDispose = undefined
+        }
+        stackedAccent = undefined
+        if (wanted === undefined) return
+        accentLayerDispose = ctx.theme.overrideTokens('theme-gallery: accent', {
+          '--dsw-alias-button-ghost-active-fill': { light: `${wanted}29`, dark: `${wanted}29` },
+          '--dsw-alias-button-ghost-active-border': { light: wanted, dark: wanted },
+          '--dsw-alias-button-ghost-active-hover': { light: `${wanted}47`, dark: `${wanted}47` },
+        })
+        stackedAccent = wanted
       })
     }
 
@@ -2821,8 +2934,27 @@ window.__ModuleLoader__.load({
      *
      * The service makes this checkable without any guesswork: `composeActive` folds every
      * override layer into `snapshot.active.tokens` before publishing, so the composed value is
-     * readable straight off `getTheme()`. If the layer is registered, the token IS there; if it
-     * is not, the token is absent or still the built-in value.
+     * readable straight off `getTheme()`.
+     *
+     * ── WHAT CAN AND CANNOT PROVE IT ─────────────────────────────────────────
+     *
+     * The composed VALUE is the only channel that carries information, and only when it differs
+     * from what the skin declares for that same token:
+     *
+     *  • both bundled skins already ship `button-ghost-active-*` in their own palettes, AND the
+     *    palette layer supplies them too — so the token COUNT is 67 either way. An earlier
+     *    comment here claimed a count that "does not move" disproves the layer; for these skins
+     *    it cannot move, so the claim was wrong and the count is reported for context only;
+     *  • 梦海游鱼 declares `#2B74B5` for that token but its accent is `#FFD166`, so reading back
+     *    `#FFD166` proves the accent layer composed OVER the palette — the palette alone cannot
+     *    produce it;
+     *  • 山青婷彩's accent is `#E88BB0` and it declares `#E88BB0` for the same token, so its
+     *    reading is identical whether or not the layer is there. That is a property of the SKIN,
+     *    not of the layer, and the verdict below says so instead of implying the reading proved
+     *    something.
+     *
+     * The verdict is therefore computed, never asserted: it compares the composed value with the
+     * skin's declared value and with the accent the layer was built from.
      * @returns the reading, as one segment of the panel line.
      */
     function describeAccentLayer() {
@@ -2833,16 +2965,31 @@ window.__ModuleLoader__.load({
         const active = snapshot?.active
         const tokens = active?.tokens ?? {}
         const TOKEN = '--dsw-alias-button-ghost-active-border'
-        const value = tokens[TOKEN]
+        const composed = tokens[TOKEN]
+        const definition = typeof active?.id === 'string' ? bundledTheme(active.id) : undefined
+        const declared = declaredToken(definition, TOKEN)
+        const accent = definition?.accent
         const layers = snapshot?.overrides === undefined
           ? '(服务未暴露)'
           : String(snapshot.overrides.size ?? snapshot.overrides.length ?? '?')
-        // Its OWN key count too: layers folding into `active.tokens` is the mechanism, so a
-        // token count that does not move when the layer is stacked also disproves it.
+        // Computed, not assumed — see the note above. `不可分辨` is a real answer: it says this
+        // skin's own value coincides with its accent, so this reading proves nothing either way.
+        const verdict = accent === undefined
+          ? '非本包皮肤(无法判断)'
+          : accent === declared
+            ? '不可分辨(强调色=皮肤自备值)'
+            : composed === accent
+              ? '生效(强调色压过自备值)'
+              : composed === declared
+                ? '未生效(仍是自备值)'
+                : `未知(既非强调色也非自备值)`
         return `激活层[id=${active?.id ?? '?'}`
           + ` 层数=${layers}`
-          + ` token数=${Object.keys(tokens).length}`
-          + ` ${TOKEN.replace('--dsw-alias-', '')}=${value === undefined ? '(缺失)' : String(value)}]`
+          + ` token数=${Object.keys(tokens).length}(自备同名令牌，不构成判据)`
+          + ` ${TOKEN.replace('--dsw-alias-', '')}=${composed === undefined ? '(缺失)' : String(composed)}`
+          + ` 自备=${declared === undefined ? '(无)' : String(declared)}`
+          + ` 强调色=${accent ?? '(无)'}`
+          + ` 判据=${verdict}]`
       } catch (error) {
         return `激活层[读取失败: ${String(error && error.message ? error.message : error)}]`
       }
@@ -2879,6 +3026,9 @@ window.__ModuleLoader__.load({
           ],
         })
       }
+      // Detail lines are opt-in; a line that reports a problem is not detail.
+      const scenery = sceneryLine(selected)
+      const showScenery = scenery !== null && (debugEnabled() || sceneryLineIsWarning(scenery))
       return jsxs('div', {
         className: 'tg-page',
         children: [
@@ -2888,19 +3038,21 @@ window.__ModuleLoader__.load({
               jsx('span', { className: 'tg-title', children: t('title') }),
               jsx('span', { className: 'tg-hint', children: t('hint') }),
               jsx('span', { className: 'tg-hint', children: t('count', { count: ids.length }) }),
+              // What this copy is, so a reader can compare it with the version npm
+              // publishes without digging through the profile.
+              jsx('span', { className: 'tg-hint', children: `v${BUNDLED_VERSION}` }),
             ],
           }),
           debugEnabled() ? jsx('div', { className: 'tg-debug', children: themeDiagnostics(selected) }) : null,
-          // Unconditional while the scenery is being brought up: when the active
-          // skin's decorations are not on screen, the reason has to reach the person
-          // looking at it. Shows nothing once the report says the layer is drawn and
-          // inside the column.
-          sceneryLine(selected) === null
-            ? null
-            : jsx('div', {
+          // Routine reports wait for the debug switch; warnings and errors print
+          // regardless — when the active skin's decorations are missing, the reason
+          // has to reach the person looking at the panel.
+          showScenery
+            ? jsx('div', {
               className: `tg-debug${ambientWarning(selected) === null ? '' : ' tg-warn'}`,
-              children: sceneryLine(selected),
-            }),
+              children: scenery,
+            })
+            : null,
           jsx('div', {
             className: 'tg-grid',
             children: ids.map((id) => jsx(ThemeCard, {
@@ -3692,8 +3844,10 @@ window.__ModuleLoader__.load({
        */
       function flatten(definition) {
         const tokens = {}
-        for (const [name, value] of Object.entries(definition.tokens ?? {})) {
-          tokens[name] = typeof value === 'string' ? value : value[definition.colorScheme]
+        for (const name of Object.keys(definition.tokens ?? {})) {
+          // Delegated so the pair rule has exactly ONE implementation — the accent diagnostic reads
+          // a single token through the same helper, and two copies of this rule would drift.
+          tokens[name] = declaredToken(definition, name)
         }
         return { ...definition, tokens }
       }
@@ -4068,6 +4222,17 @@ window.__ModuleLoader__.load({
       let readingTag
       /** Disposer of the active reading token layer, when one is stacked. */
       let readingLayerDispose
+      /**
+       * The lightened ground {@link readingLayerDispose} was built from.
+       *
+       * Same role as `stackedAccent`: `syncReadingLayer` writes to the theme service, and it is
+       * scheduled from a `MutationObserver` on `document.body` — so without this, every batch of
+       * DOM mutations would replace the layer, which emits `theme/change`, which repaints the
+       * shell, which mutates the DOM again. That is a loop through the microtask queue rather than
+       * through the stack, so it would burn CPU steadily instead of throwing.
+       * @type {string|undefined}
+       */
+      let stackedReading
 
       /**
        * Install the reading rule, once per plugin lifetime.
@@ -4172,19 +4337,31 @@ window.__ModuleLoader__.load({
       function syncReadingLayer() {
         if (typeof document === 'undefined') return
         const reading = document.body !== null && document.body.hasAttribute(READING_ATTRIBUTE)
-        if (!reading) {
+        // Computed before the skip test, because the skip compares VALUES. `lighten` is pure, so
+        // the same document state always yields the same pair and the comparison is exact.
+        const wanted = reading ? lighten(READING.bg, READING.alpha) : undefined
+        const wantedDark = reading
+          // Lightened ground for both palettes: a light theme wants a softer wash, a dark one a
+          // slightly raised surface. Both keep the theme's hue.
+          ? lighten(READING.bg, Math.max(0, READING.alpha - 0.2))
+          : undefined
+
+        // Both writes below emit `theme/change`, and this function is reached from a
+        // `MutationObserver` on `document.body` — the same tree the shell repaints when the theme
+        // changes. See the comment in `syncAccent` for the full shape; the short version is that
+        // an unguarded write here lets the layer drive its own trigger.
+        if (wanted === stackedReading) return
+        emitting(() => {
           if (readingLayerDispose !== undefined) {
             readingLayerDispose()
             readingLayerDispose = undefined
           }
-          return
-        }
-        // Lightened ground for both palettes: a light theme wants a softer wash,
-        // a dark one a slightly raised surface. Both keep the theme's hue.
-        const lightened = lighten(READING.bg, READING.alpha)
-        const darkLightened = lighten(READING.bg, Math.max(0, READING.alpha - 0.2))
-        readingLayerDispose = ctx.theme.overrideTokens('theme-gallery: reading', {
-          '--dsw-alias-bg-base': { light: lightened, dark: darkLightened },
+          stackedReading = undefined
+          if (wanted === undefined) return
+          readingLayerDispose = ctx.theme.overrideTokens('theme-gallery: reading', {
+            '--dsw-alias-bg-base': { light: wanted, dark: wantedDark },
+          })
+          stackedReading = wanted
         })
       }
 
@@ -4213,10 +4390,17 @@ window.__ModuleLoader__.load({
           observer.disconnect()
           if (readingTag !== undefined) readingTag.remove()
           readingTag = undefined
-          if (readingLayerDispose !== undefined) {
-            readingLayerDispose()
-            readingLayerDispose = undefined
-          }
+          // Guarded for the same reason as the writes in `syncReadingLayer`, and the remembered
+          // value is cleared with the layer: leaving it set would make that function's skip test
+          // believe a layer is still stacked after this one removed it, and it would then refuse
+          // to re-stack.
+          emitting(() => {
+            if (readingLayerDispose !== undefined) {
+              readingLayerDispose()
+              readingLayerDispose = undefined
+            }
+            stackedReading = undefined
+          })
           document.body.removeAttribute(READING_ATTRIBUTE)
           const centre = centreColumn()
           if (centre !== null) centre.style.removeProperty('--dsh-reading-width')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-theme-gallery",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A community theme gallery for DeepSeek Harness (DSH): JSON-defined skins with full-screen coverage and ported sidebar scenery, switched from the plugin's own sidebar panel — adding skins needs no code change",
   "author": "renjie2026 (https://github.com/renjie2026)",
   "license": "MIT",
@@ -61,7 +61,8 @@
     "test:scopelogic": "node tests/check-scope-reach-logic.mjs",
     "test:preview": "node scripts/build-ambient-preview.mjs",
     "test:calls": "node tests/check-undefined-calls.mjs",
-    "test": "npm run test:schema && npm run test:host && npm run test:store && npm run test:order && npm run test:tdz && npm run test:theme && npm run test:ambient && npm run test:boot && npm run test:safety && npm run test:module && npm run test:bounded && npm run test:bootpath && npm run test:scope && npm run test:scopelogic && npm run test:calls",
+    "test:emitguard": "node tests/check-self-emit-guard.mjs && node tests/check-self-emit-guard-logic.mjs",
+    "test": "npm run test:schema && npm run test:host && npm run test:store && npm run test:order && npm run test:tdz && npm run test:theme && npm run test:ambient && npm run test:boot && npm run test:safety && npm run test:module && npm run test:bounded && npm run test:bootpath && npm run test:scope && npm run test:scopelogic && npm run test:calls && npm run test:emitguard",
     "prepack": "node scripts/embed-themes.mjs",
     "publish:check": "node scripts/publish-check.mjs",
     "embed-themes": "node scripts/embed-themes.mjs",