dsh-theme-gallery 0.2.0 → 0.3.0

package/lib/client.js

@@ -84,13 +84,152 @@ window.__ModuleLoader__.load({
     const BUILT_IN_LABELS = { light: '浅色', dark: '深色', system: '跟随系统' }
 
     /**
-     * Built-in ids the gallery leaves to the official Appearance row.
+     * One-line copy for the built-in cards.
      *
-     * `light` is exactly what "follow the system" resolves to on a light desktop,
-     * so offering it beside that row is duplicate UI. `dark` stays because it is a
-     * distinct choice a user may want without a full skin.
+     * The official themes declare no `description` of their own, so without this their
+     * cards would be a bare label. These two cards switch the PALETTE back to the system
+     * appearance — and they deliberately keep the previous skin's sidebar scenery on
+     * screen, which is the behaviour the second sentence advertises (see `syncAmbient`).
      */
-    const OMITTED_IDS = new Set(['light'])
+    const BUILT_IN_DESCRIPTIONS = {
+      light: '系统默认浅色外观：与「设置 → 通用 → 外观」里的浅色是同一套配色。'
+        + '先选中主题皮肤，再切换浅色/深色 会有惊喜哦',
+      dark: '系统默认深色外观：与「设置 → 通用 → 外观」里的深色是同一套配色。'
+        + '先选中主题皮肤，再切换浅色/深色 会有惊喜哦',
+      system: '跟随系统外观设置（按桌面端的浅色/深色自动决定，因此不作为卡片展示）',
+    }
+
+    /**
+     * Built-in ids the gallery does not show as a card.
+     *
+     * `system` is a preference value rather than a look of its own — it resolves to
+     * `light` or `dark` depending on the desktop — so a card for it would duplicate one
+     * of the two cards above and change meaning with the OS setting. `light` and `dark`
+     * are BOTH shown now: together they are the way back out of every skin.
+     */
+    const OMITTED_IDS = new Set(['system'])
+
+    /**
+     * Display order of the gallery's cards — larger first.
+     *
+     * These are the user's own ranking numbers, kept as one table so the order is data
+     * rather than an implicit consequence of some other list. The REGISTRY order (and
+     * with it the contribution order in `BUNDLED_THEMES`) is deliberately untouched:
+     * this table is applied to the copy the page renders, and to nothing else.
+     *
+     * A theme with no entry sorts after every ranked one and keeps its registry order
+     * among the unranked (the sort is stable), so a theme contributed by another plugin
+     * still appears on the page instead of silently vanishing.
+     */
+    const CARD_ORDER = {
+      light: 99,
+      dark: 98,
+      'ying-mu-cai-yun': 96,
+      'shan-qing-ting-cai': 95,
+      'pei-an-jie-xin': 91,
+      'meng-hai-you-yu': 80,
+      'hu-po-mao-mi': 76,
+      'hu-zi-a-huang': 75,
+    }
+
+    /**
+     * The skin this plugin puts in effect when the user has never chosen anything.
+     *
+     * Requested behaviour: installing/enabling the plugin lands on 山青婷彩 instead of the
+     * built-in white theme. Applied by the ordinary restore path, so it obeys the same
+     * global write budget and paint confirmation as a remembered skin — and it stops the
+     * moment the user makes any choice of their own, because that choice is recorded.
+     */
+    const DEFAULT_SKIN = 'shan-qing-ting-cai'
+
+    /**
+     * The two keys this plugin owns in `localStorage`.
+     *
+     * Never `ui-theme.preference`: that field is read while the boot graph is still
+     * assembling, and a skin id in it makes `buildSnapshot()` throw `theme registry lost`
+     * and refuse to start. `localStorage` is private to this plugin, so a disabled or
+     * uninstalled plugin simply stops being consulted — that is the fallback.
+     *
+     * They live at module scope because the card-click handler runs in the page component,
+     * far from `mountGallery`, and it must be able to write them BEFORE the click reaches
+     * the theme service (which publishes synchronously).
+     */
+    const SKIN_KEY = 'theme-gallery:last-skin'
+    const BUILT_IN_KEY = 'theme-gallery:built-in-choice'
+
+    /**
+     * A theme's card rank; unranked themes sort last.
+     * @param id - the theme id.
+     * @returns its rank, or -1 when the table has no entry for it.
+     */
+    function cardRank(id) {
+      const rank = CARD_ORDER[id]
+      return typeof rank === 'number' ? rank : -1
+    }
+
+    /**
+     * Order a card list for display: highest rank first.
+     *
+     * Applied to the copy the page renders, never to the array the service is given, so a
+     * theme's registration and its card position are independent concerns (and a reorder
+     * can never change which themes exist or what they contain).
+     * @param themes - theme definitions, in registry order.
+     * @returns a new array in display order.
+     */
+    function cardsInDisplayOrder(themes) {
+      return [...themes].sort((a, b) => cardRank(b.id) - cardRank(a.id))
+    }
+
+    /**
+     * Record the user's card choice BEFORE it reaches the theme service.
+     *
+     * ── WHY THE ORDER IS LOAD-BEARING ───────────────────────────────────────────
+     *
+     * `ctx.theme.setTheme()` publishes synchronously, and the publisher re-applies the
+     * remembered skin whenever the active theme is not one of ours. So a built-in card
+     * clicked after any skin had been chosen used to be undone a microtask later: the click
+     * landed, the restore read `SKIN_KEY`, and the skin came straight back. On screen the
+     * 深色 card simply did nothing.
+     *
+     * Removing `SKIN_KEY` here, before the write, is what makes a built-in choice stick.
+     * `BUILT_IN_KEY` is written so the default skin does NOT fire on the next restart and
+     * undo the choice — see `wantedSkin`.
+     *
+     * Any theme this package does not provide counts as "not a skin": another plugin's
+     * theme must win as well, for exactly the same reason.
+     * @param id - the card's theme id.
+     */
+    function rememberCardChoice(id) {
+      try {
+        if (typeof window === 'undefined') return
+        const storage = window.localStorage
+        if (storage === undefined || storage === null) return
+        if (bundledTheme(id) === undefined) {
+          storage.removeItem(SKIN_KEY)
+          storage.setItem(BUILT_IN_KEY, String(id))
+          return
+        }
+        // A skin: it is recorded by the restore once it is genuinely active, so the stale
+        // built-in marker is cleared here rather than there.
+        storage.removeItem(BUILT_IN_KEY)
+      } catch (error) {
+        console.error('[theme-gallery] could not record the card choice:', error)
+      }
+    }
+
+    /**
+     * The built-in appearance the user picked in this panel, if any.
+     * @returns the id, or null when the user never picked one here.
+     */
+    function builtInChoice() {
+      try {
+        if (typeof window === 'undefined') return null
+        const value = window.localStorage?.getItem(BUILT_IN_KEY)
+        return typeof value === 'string' && value !== '' ? value : null
+      } catch {
+        return null
+      }
+    }
 
     /** Body attribute publishing the reading state; the injected rule reads it. */
     const READING_ATTRIBUTE = 'data-dsh-theme-reading'
@@ -118,7 +257,7 @@ window.__ModuleLoader__.load({
      * package.json, and the release workflow fails when re-running the embed step
      * changes a tracked file.
      */
-    const BUNDLED_VERSION = '0.2.0'
+    const BUNDLED_VERSION = '0.3.0'
 
     /**
      * Themes this package contributes, inlined from lib/themes/*.json.
@@ -131,6 +270,582 @@ window.__ModuleLoader__.load({
      * Regenerate after editing those files: `node scripts/embed-themes.mjs`.
      */
     const BUNDLED_THEMES = [
+      {
+        "id": "hu-po-mao-mi",
+        "label": "琥珀猫咪",
+        "description": "琥珀暖光，双猫伴读 —— 原创宠物主题：两只虎斑短毛猫守着洒满阳光的窗台",
+        "colorScheme": "light",
+        "tokens": {
+          "--dsw-alias-bg-base": {
+            "light": "linear-gradient(to bottom,#FEFBF5 0%,#FBF2E3 55%,#F8EDD8 100%)",
+            "dark": "linear-gradient(to bottom,#FEFBF5 0%,#FBF2E3 55%,#F8EDD8 100%)"
+          },
+          "--dsw-alias-bg-layer-1": {
+            "light": "#FEFCF7",
+            "dark": "#FEFCF7"
+          },
+          "--dsw-alias-bg-layer-2": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-bg-layer-3": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-bg-overlay": {
+            "light": "#F3E5CD",
+            "dark": "#F3E5CD"
+          },
+          "--dsw-alias-bg-skeleton": {
+            "light": "#9C5F2414",
+            "dark": "#9C5F2414"
+          },
+          "--dsw-alias-bg-module-platform": {
+            "light": "#F3E5CD",
+            "dark": "#F3E5CD"
+          },
+          "--dsw-alias-bg-multi-select": {
+            "light": "#F3E5CD",
+            "dark": "#F3E5CD"
+          },
+          "--dsw-alias-border-l1": {
+            "light": "#9C5F240F",
+            "dark": "#9C5F240F"
+          },
+          "--dsw-alias-border-l2": {
+            "light": "#9C5F2421",
+            "dark": "#9C5F2421"
+          },
+          "--dsw-alias-border-l3": {
+            "light": "#9C5F242E",
+            "dark": "#9C5F242E"
+          },
+          "--dsw-alias-border-l4": {
+            "light": "#9C5F243D",
+            "dark": "#9C5F243D"
+          },
+          "--dsw-alias-brand-primary": {
+            "light": "#9C5F24",
+            "dark": "#9C5F24"
+          },
+          "--dsw-alias-brand-primary-invert": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-brand-text": {
+            "light": "#9C5F24",
+            "dark": "#9C5F24"
+          },
+          "--dsw-alias-label-primary": {
+            "light": "#453019",
+            "dark": "#453019"
+          },
+          "--dsw-alias-label-primary-bluish": {
+            "light": "#453019",
+            "dark": "#453019"
+          },
+          "--dsw-alias-label-secondary": {
+            "light": "#6A4E2F",
+            "dark": "#6A4E2F"
+          },
+          "--dsw-alias-label-tertiary": {
+            "light": "#8C6F4C",
+            "dark": "#8C6F4C"
+          },
+          "--dsw-alias-label-caption": {
+            "light": "#8C6F4C",
+            "dark": "#8C6F4C"
+          },
+          "--dsw-alias-label-dimmed": {
+            "light": "#B49C7F",
+            "dark": "#B49C7F"
+          },
+          "--dsw-alias-label-primary-dimmed": {
+            "light": "#6A4E2F",
+            "dark": "#6A4E2F"
+          },
+          "--dsw-alias-label-primary-foreground": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-label-primary-inverted": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-link": {
+            "light": "#CA6924",
+            "dark": "#CA6924"
+          },
+          "--dsw-alias-interactive-bg-hover": {
+            "light": "#9C5F2414",
+            "dark": "#9C5F2414"
+          },
+          "--dsw-alias-interactive-bg-active": {
+            "light": "#CA69242E",
+            "dark": "#CA69242E"
+          },
+          "--dsw-alias-interactive-bg-hover-solid": {
+            "light": "#F3E5CD",
+            "dark": "#F3E5CD"
+          },
+          "--dsw-alias-interactive-bg-hover-accent": {
+            "light": "#CA69243D",
+            "dark": "#CA69243D"
+          },
+          "--dsw-alias-button-primary-fill": {
+            "light": "#9C5F24",
+            "dark": "#9C5F24"
+          },
+          "--dsw-alias-button-primary-hover": {
+            "light": "#B0702F",
+            "dark": "#B0702F"
+          },
+          "--dsw-alias-button-primary-dimmed": {
+            "light": "#9C5F2447",
+            "dark": "#9C5F2447"
+          },
+          "--dsw-alias-button-ghost-active-fill": {
+            "light": "#CA692429",
+            "dark": "#CA692429"
+          },
+          "--dsw-alias-button-ghost-active-border": {
+            "light": "#CA6924",
+            "dark": "#CA6924"
+          },
+          "--dsw-alias-button-ghost-active-hover": {
+            "light": "#CA692447",
+            "dark": "#CA692447"
+          },
+          "--dsw-alias-button-info-fill": {
+            "light": "#B0702F",
+            "dark": "#B0702F"
+          },
+          "--dsw-alias-button-info-hover": {
+            "light": "#9C5F24",
+            "dark": "#9C5F24"
+          },
+          "--dsw-alias-button-elevated-fill": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-button-floating-fill": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-button-floating-hover": {
+            "light": "#FDF8F0",
+            "dark": "#FDF8F0"
+          },
+          "--dsw-alias-button-contrast-fill": {
+            "light": "#453019",
+            "dark": "#453019"
+          },
+          "--dsw-alias-markdown-code-block": {
+            "light": "#F7EEDF",
+            "dark": "#F7EEDF"
+          },
+          "--dsw-alias-markdown-code-block-banner": {
+            "light": "#F0E3CB",
+            "dark": "#F0E3CB"
+          },
+          "--dsw-alias-markdown-inline-code": {
+            "light": "#F3E9D6",
+            "dark": "#F3E9D6"
+          },
+          "--dsw-alias-markdown-citation": {
+            "light": "#F3E9D6",
+            "dark": "#F3E9D6"
+          },
+          "--dsw-alias-markdown-tag": {
+            "light": "#F3E9D6",
+            "dark": "#F3E9D6"
+          },
+          "--dsw-alias-markdown-placeholder": {
+            "light": "#F0E3CB",
+            "dark": "#F0E3CB"
+          },
+          "--dsw-alias-markdown-code-segment-selected": {
+            "light": "#CA692429",
+            "dark": "#CA692429"
+          },
+          "--dsw-alias-markdown-code-segment-unselected": {
+            "light": "#F7EEDF",
+            "dark": "#F7EEDF"
+          },
+          "--dsw-alias-scrollbar-bg-l1": {
+            "light": "#9C5F2429",
+            "dark": "#9C5F2429"
+          },
+          "--dsw-alias-scrollbar-bg-l2": {
+            "light": "#9C5F2438",
+            "dark": "#9C5F2438"
+          },
+          "--dsw-alias-scrollbar-hover-l1": {
+            "light": "#9C5F2452",
+            "dark": "#9C5F2452"
+          },
+          "--dsw-alias-scrollbar-hover-l2": {
+            "light": "#9C5F2466",
+            "dark": "#9C5F2466"
+          },
+          "--dsw-alias-tooltip-bg": {
+            "light": "#453019",
+            "dark": "#453019"
+          },
+          "--dsw-alias-toast-bg": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-state-error-primary": {
+            "light": "#C65B6A",
+            "dark": "#C65B6A"
+          },
+          "--dsw-alias-state-error-secondary": {
+            "light": "#DB5A6B",
+            "dark": "#DB5A6B"
+          },
+          "--dsw-alias-state-success-primary": {
+            "light": "#21A675",
+            "dark": "#21A675"
+          },
+          "--dsw-alias-state-success-secondary": {
+            "light": "#9C5F24",
+            "dark": "#9C5F24"
+          },
+          "--dsw-alias-state-success-tertiary": {
+            "light": "#CFBA9C",
+            "dark": "#CFBA9C"
+          },
+          "--dsw-alias-state-warn-primary": {
+            "light": "#B97F3A",
+            "dark": "#B97F3A"
+          },
+          "--dsw-alias-state-warn-secondary": {
+            "light": "#D9A45E",
+            "dark": "#D9A45E"
+          },
+          "--dsw-alias-state-warn-tertiary": {
+            "light": "#EFDCC0",
+            "dark": "#EFDCC0"
+          },
+          "--dsw-alias-state-warn-label": {
+            "light": "#8A5A22",
+            "dark": "#8A5A22"
+          },
+          "--dsw-alias-state-business-primary": {
+            "light": "#CA6924",
+            "dark": "#CA6924"
+          },
+          "--dsw-alias-state-business-tertiary": {
+            "light": "#E29C45",
+            "dark": "#E29C45"
+          },
+          "--dsw-specific-sidebar-fill": {
+            "light": "linear-gradient(to bottom,#FBF0DE 0%,#F5E3C6 20%,#EDD5AE 36%,#E3C593 50%,#D8B57D 62%,#CBA468 74%,#C69E5F 86%,#BB904F 100%)",
+            "dark": "linear-gradient(to bottom,#FBF0DE 0%,#F5E3C6 20%,#EDD5AE 36%,#E3C593 50%,#D8B57D 62%,#CBA468 74%,#C69E5F 86%,#BB904F 100%)"
+          }
+        },
+        "reading": {
+          "colorScheme": "light",
+          "bg": "#FFFFFF",
+          "alpha": 0.62,
+          "blur": 3,
+          "maxWidth": 640
+        },
+        "accent": "#CA6924",
+        "ambient": {
+          "kind": "humao",
+          "dust": 6
+        }
+      },
+      {
+        "id": "hu-zi-a-huang",
+        "label": "虎子阿黄",
+        "description": "麦香田园，黄犬相迎 —— 原创宠物主题：中黄田园犬「虎子阿黄」摇着尾巴守在田埂上",
+        "colorScheme": "light",
+        "tokens": {
+          "--dsw-alias-bg-base": {
+            "light": "linear-gradient(to bottom,#FEFDF6 0%,#FBF5E0 55%,#F7EFD0 100%)",
+            "dark": "linear-gradient(to bottom,#FEFDF6 0%,#FBF5E0 55%,#F7EFD0 100%)"
+          },
+          "--dsw-alias-bg-layer-1": {
+            "light": "#FEFCF4",
+            "dark": "#FEFCF4"
+          },
+          "--dsw-alias-bg-layer-2": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-bg-layer-3": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-bg-overlay": {
+            "light": "#F4EAD0",
+            "dark": "#F4EAD0"
+          },
+          "--dsw-alias-bg-skeleton": {
+            "light": "#896C3914",
+            "dark": "#896C3914"
+          },
+          "--dsw-alias-bg-module-platform": {
+            "light": "#F4EAD0",
+            "dark": "#F4EAD0"
+          },
+          "--dsw-alias-bg-multi-select": {
+            "light": "#F4EAD0",
+            "dark": "#F4EAD0"
+          },
+          "--dsw-alias-border-l1": {
+            "light": "#896C390F",
+            "dark": "#896C390F"
+          },
+          "--dsw-alias-border-l2": {
+            "light": "#896C3921",
+            "dark": "#896C3921"
+          },
+          "--dsw-alias-border-l3": {
+            "light": "#896C392E",
+            "dark": "#896C392E"
+          },
+          "--dsw-alias-border-l4": {
+            "light": "#896C393D",
+            "dark": "#896C393D"
+          },
+          "--dsw-alias-brand-primary": {
+            "light": "#896C39",
+            "dark": "#896C39"
+          },
+          "--dsw-alias-brand-primary-invert": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-brand-text": {
+            "light": "#896C39",
+            "dark": "#896C39"
+          },
+          "--dsw-alias-label-primary": {
+            "light": "#3B3018",
+            "dark": "#3B3018"
+          },
+          "--dsw-alias-label-primary-bluish": {
+            "light": "#3B3018",
+            "dark": "#3B3018"
+          },
+          "--dsw-alias-label-secondary": {
+            "light": "#5D4E2B",
+            "dark": "#5D4E2B"
+          },
+          "--dsw-alias-label-tertiary": {
+            "light": "#857451",
+            "dark": "#857451"
+          },
+          "--dsw-alias-label-caption": {
+            "light": "#857451",
+            "dark": "#857451"
+          },
+          "--dsw-alias-label-dimmed": {
+            "light": "#B2A47E",
+            "dark": "#B2A47E"
+          },
+          "--dsw-alias-label-primary-dimmed": {
+            "light": "#5D4E2B",
+            "dark": "#5D4E2B"
+          },
+          "--dsw-alias-label-primary-foreground": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-label-primary-inverted": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-link": {
+            "light": "#AE7000",
+            "dark": "#AE7000"
+          },
+          "--dsw-alias-interactive-bg-hover": {
+            "light": "#896C3914",
+            "dark": "#896C3914"
+          },
+          "--dsw-alias-interactive-bg-active": {
+            "light": "#F0C2392E",
+            "dark": "#F0C2392E"
+          },
+          "--dsw-alias-interactive-bg-hover-solid": {
+            "light": "#F4EAD0",
+            "dark": "#F4EAD0"
+          },
+          "--dsw-alias-interactive-bg-hover-accent": {
+            "light": "#F0C2393D",
+            "dark": "#F0C2393D"
+          },
+          "--dsw-alias-button-primary-fill": {
+            "light": "#896C39",
+            "dark": "#896C39"
+          },
+          "--dsw-alias-button-primary-hover": {
+            "light": "#A88462",
+            "dark": "#A88462"
+          },
+          "--dsw-alias-button-primary-dimmed": {
+            "light": "#896C3947",
+            "dark": "#896C3947"
+          },
+          "--dsw-alias-button-ghost-active-fill": {
+            "light": "#F0C23929",
+            "dark": "#F0C23929"
+          },
+          "--dsw-alias-button-ghost-active-border": {
+            "light": "#F0C239",
+            "dark": "#F0C239"
+          },
+          "--dsw-alias-button-ghost-active-hover": {
+            "light": "#F0C23947",
+            "dark": "#F0C23947"
+          },
+          "--dsw-alias-button-info-fill": {
+            "light": "#A88462",
+            "dark": "#A88462"
+          },
+          "--dsw-alias-button-info-hover": {
+            "light": "#896C39",
+            "dark": "#896C39"
+          },
+          "--dsw-alias-button-elevated-fill": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-button-floating-fill": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-button-floating-hover": {
+            "light": "#FCF8EC",
+            "dark": "#FCF8EC"
+          },
+          "--dsw-alias-button-contrast-fill": {
+            "light": "#3B3018",
+            "dark": "#3B3018"
+          },
+          "--dsw-alias-markdown-code-block": {
+            "light": "#F8F1DC",
+            "dark": "#F8F1DC"
+          },
+          "--dsw-alias-markdown-code-block-banner": {
+            "light": "#F1E7C6",
+            "dark": "#F1E7C6"
+          },
+          "--dsw-alias-markdown-inline-code": {
+            "light": "#F4EAD0",
+            "dark": "#F4EAD0"
+          },
+          "--dsw-alias-markdown-citation": {
+            "light": "#F4EAD0",
+            "dark": "#F4EAD0"
+          },
+          "--dsw-alias-markdown-tag": {
+            "light": "#F4EAD0",
+            "dark": "#F4EAD0"
+          },
+          "--dsw-alias-markdown-placeholder": {
+            "light": "#F1E7C6",
+            "dark": "#F1E7C6"
+          },
+          "--dsw-alias-markdown-code-segment-selected": {
+            "light": "#F0C23929",
+            "dark": "#F0C23929"
+          },
+          "--dsw-alias-markdown-code-segment-unselected": {
+            "light": "#F8F1DC",
+            "dark": "#F8F1DC"
+          },
+          "--dsw-alias-scrollbar-bg-l1": {
+            "light": "#896C3929",
+            "dark": "#896C3929"
+          },
+          "--dsw-alias-scrollbar-bg-l2": {
+            "light": "#896C3938",
+            "dark": "#896C3938"
+          },
+          "--dsw-alias-scrollbar-hover-l1": {
+            "light": "#896C3952",
+            "dark": "#896C3952"
+          },
+          "--dsw-alias-scrollbar-hover-l2": {
+            "light": "#896C3966",
+            "dark": "#896C3966"
+          },
+          "--dsw-alias-tooltip-bg": {
+            "light": "#3B3018",
+            "dark": "#3B3018"
+          },
+          "--dsw-alias-toast-bg": {
+            "light": "#FFFFFF",
+            "dark": "#FFFFFF"
+          },
+          "--dsw-alias-state-error-primary": {
+            "light": "#C65B6A",
+            "dark": "#C65B6A"
+          },
+          "--dsw-alias-state-error-secondary": {
+            "light": "#DB5A6B",
+            "dark": "#DB5A6B"
+          },
+          "--dsw-alias-state-success-primary": {
+            "light": "#21A675",
+            "dark": "#21A675"
+          },
+          "--dsw-alias-state-success-secondary": {
+            "light": "#896C39",
+            "dark": "#896C39"
+          },
+          "--dsw-alias-state-success-tertiary": {
+            "light": "#D1C69C",
+            "dark": "#D1C69C"
+          },
+          "--dsw-alias-state-warn-primary": {
+            "light": "#B97F3A",
+            "dark": "#B97F3A"
+          },
+          "--dsw-alias-state-warn-secondary": {
+            "light": "#D9A45E",
+            "dark": "#D9A45E"
+          },
+          "--dsw-alias-state-warn-tertiary": {
+            "light": "#EFDCC0",
+            "dark": "#EFDCC0"
+          },
+          "--dsw-alias-state-warn-label": {
+            "light": "#8A5A22",
+            "dark": "#8A5A22"
+          },
+          "--dsw-alias-state-business-primary": {
+            "light": "#F0C239",
+            "dark": "#F0C239"
+          },
+          "--dsw-alias-state-business-tertiary": {
+            "light": "#F5D46B",
+            "dark": "#F5D46B"
+          },
+          "--dsw-specific-sidebar-fill": {
+            "light": "linear-gradient(to bottom,#FAF3DC 0%,#F4EAC2 20%,#ECDFAB 36%,#E2D191 50%,#D6C078 62%,#C9AF63 74%,#C4A85F 86%,#B89B51 100%)",
+            "dark": "linear-gradient(to bottom,#FAF3DC 0%,#F4EAC2 20%,#ECDFAB 36%,#E2D191 50%,#D6C078 62%,#C9AF63 74%,#C4A85F 86%,#B89B51 100%)"
+          }
+        },
+        "reading": {
+          "colorScheme": "light",
+          "bg": "#FFFFFF",
+          "alpha": 0.62,
+          "blur": 3,
+          "maxWidth": 640
+        },
+        "accent": "#F0C239",
+        "ambient": {
+          "kind": "ahuang",
+          "dust": 5
+        }
+      },
       {
         "id": "meng-hai-you-yu",
         "label": "梦海游鱼",
@@ -1610,6 +2325,32 @@ window.__ModuleLoader__.load({
       '@keyframes dsh-amb-gc-wing{0%{transform:rotate(0deg)}40%{transform:rotate(-3.5deg)}60%{transform:rotate(2.5deg)}100%{transform:rotate(0deg)}}',
       '@keyframes dsh-amb-gc-dew{0%{opacity:.3;transform:scale(1)}100%{opacity:1;transform:scale(1.5)}}',
 
+      /* ── 琥珀猫咪 / 虎子阿黄（原创宠物场景）──────────────────────────────
+         Like the five ported scenes above: element geometry, colour and
+         per-element timing are INLINE in the scene builders, so only the
+         @keyframes live here — each prefixed (hm / hz) so they cannot collide,
+         and each defined exactly once (a duplicate would silently win). Every
+         animated vertical term stays at or below the resting baseline, because
+         the scene box clips at its own top edge. */
+      '@keyframes dsh-amb-hm-glow{from{opacity:.55}to{opacity:.85}}',
+      '@keyframes dsh-amb-hm-dust{0%{transform:translate(0,0);opacity:0}12%{opacity:.9}'
+        + '60%{transform:translate(-.5em,-3.2em);opacity:.45}100%{transform:translate(.4em,-4.6em);opacity:0}}',
+      '@keyframes dsh-amb-hm-tail{from{transform:rotate(-3deg)}to{transform:rotate(5deg)}}',
+      '@keyframes dsh-amb-hm-breathe{0%,100%{transform:scaleY(1)}50%{transform:scaleY(1.03)}}',
+      '@keyframes dsh-amb-hm-ear{0%,86%,100%{transform:rotate(0)}90%{transform:rotate(-9deg)}94%{transform:rotate(4deg)}}',
+      '@keyframes dsh-amb-hm-zzz{0%{transform:translate(0,0);opacity:0}18%{opacity:.85}'
+        + '100%{transform:translate(1.2em,-2.6em);opacity:0}}',
+      '@keyframes dsh-amb-hz-glow{from{opacity:.45}to{opacity:.75}}',
+      /* The fluff crosses the whole band and dies at the far edge; its vertical
+         wobble stays within ±1.2em so a low-seeded puff never reaches the clip. */
+      '@keyframes dsh-amb-hz-fluff{0%{transform:translate(0,0);opacity:0}7%{opacity:.95}'
+        + '30%{transform:translate(8em,-1.2em)}55%{transform:translate(14em,.7em)}'
+        + '80%{transform:translate(20em,-.9em);opacity:.75}96%{opacity:.4}'
+        + '100%{transform:translate(26em,0);opacity:0}}',
+      '@keyframes dsh-amb-hz-wag{from{transform:rotate(-9deg)}to{transform:rotate(11deg)}}',
+      '@keyframes dsh-amb-hz-grass{from{transform:rotate(-2.2deg)}to{transform:rotate(2.6deg)}}',
+      '@keyframes dsh-amb-hz-tilt{0%,40%,100%{transform:rotate(0)}55%{transform:rotate(2.4deg)}75%{transform:rotate(-1.4deg)}}',
+
       /* Respect a user who has asked the system for less motion: the scenery
          stays, the movement does not. */
       '@media (prefers-reduced-motion:reduce){#dsh-theme-ambient *{animation:none!important}}',
@@ -1619,7 +2360,7 @@ window.__ModuleLoader__.load({
     const zh = {
       title: '主题皮肤',
       hint: '点一下即切换，选中会记入设置',
-      count: '{count} 个可选主题',
+      count: '{count} 款皮肤（另有内置浅色/深色两张卡）',
       current: '当前',
       applied: '已应用',
       empty: '正在读取官方主题注册表…',
@@ -1631,7 +2372,7 @@ window.__ModuleLoader__.load({
     const en = {
       title: 'Theme skins',
       hint: 'Click to switch; the choice is remembered',
-      count: '{count} themes available',
+      count: '{count} skins (+ built-in light/dark cards)',
       current: 'Current',
       applied: 'Applied',
       empty: 'Reading the theme registry…',
@@ -1711,10 +2452,11 @@ window.__ModuleLoader__.load({
               // localizes them from its own dictionaries — so name them here
               // rather than showing a bare `light` / `dark` id.
               labels[theme.id] = theme.label || BUILT_IN_LABELS[theme.id] || theme.id
-              // A built-in theme derives its colours from the base palette rather
-              // than declaring tokens, so its card gets a plain line.
-              descriptions[theme.id] = theme.description
-                || (theme.id in BUILT_IN_LABELS ? '' : '')
+              // A built-in theme derives its colours from the base palette rather than
+              // declaring tokens, so its card gets a plain line — and it carries no
+              // description of its own, so the copy for the built-in cards is the
+              // gallery's own (`BUILT_IN_DESCRIPTIONS`).
+              descriptions[theme.id] = theme.description || BUILT_IN_DESCRIPTIONS[theme.id] || ''
               // A card's colour strip comes from the theme's own tokens, so a
               // theme authored anywhere shows its identity without extra metadata.
               const tokens = theme.tokens || {}
@@ -3279,6 +4021,328 @@ window.__ModuleLoader__.load({
         + '</div>'
     }
 
+    /**
+     * One sun-warmed haze for the two ORIGINAL pet scenes (琥珀猫咪 / 虎子阿黄).
+     *
+     * Both scenes open with the same soft light pool at the band's top, built the way
+     * dream's corner glow was taught to behave: it starts AT the edge, is dimmer than
+     * the source skies, and is masked to zero at its top so the scene box's
+     * `overflow:hidden` clip never cuts a hard line against the un-lit sidebar above.
+     * @param tint - the rgba() fill of the haze, in the theme's own family.
+     * @param keyframe - the pulse animation, `dsh-amb-hm-glow` or `dsh-amb-hz-glow`.
+     * @returns the haze markup.
+     */
+    function petHazeMarkup(tint, keyframe) {
+      return open('div', {
+        class: 'pet-haze',
+        style: `position:absolute;top:0;left:-20%;width:130%;height:52%;z-index:2;`
+          + `background:radial-gradient(ellipse at 30% 0%,${tint} 0%,rgba(255,236,200,0) 64%);`
+          + 'filter:blur(10px);'
+          + '-webkit-mask-image:linear-gradient(to bottom,transparent 0,#000 42%);'
+          + 'mask-image:linear-gradient(to bottom,transparent 0,#000 42%);'
+          + `animation:${keyframe} 9s ease-in-out infinite alternate`,
+      }) + '</div>'
+    }
+
+    /**
+     * The 琥珀猫咪 scene: a warm haze, a sunlit sill, TWO tabby shorthairs —
+     * one sitting with a slow tail sway and the odd ear twitch, one curled asleep,
+     * breathing, with tiny z's drifting off it — and amber dust motes floating
+     * through the light.
+     *
+     * This is the first ORIGINAL scene in the pack (not ported from a source
+     * system), drawn in the pack's own idiom: inline geometry in % / em, flat
+     * fills from one warm amber family, the count knob seeding the dust, and
+     * every animated transform bounded below the band's top edge — the sleeping
+     * cat breathes from its base and the z's fade out well before they could
+     * reach the clip.
+     * @param dust - how many dust motes to seed.
+     * @returns the scene markup.
+     */
+    function humaoAmbientScene(dust) {
+      const count = Math.max(0, Math.min(20, dust ?? 6))
+      let dustNodes = ''
+      for (let n = 1; n <= count; n += 1) {
+        const size = 2.5 + ((n * 5) % 4)
+        dustNodes += open('div', {
+          class: 'hm-dust',
+          style: 'position:absolute;border-radius:50%;'
+            + `left:${((n * 19) % 52) + 22}%;top:${((n * 13) % 24) + 36}%;`
+            + `width:${size}px;height:${size}px;`
+            + 'background:radial-gradient(circle,rgba(255,236,200,.95) 0%,rgba(255,214,140,0) 100%);'
+            + 'box-shadow:0 0 6px rgba(255,214,140,.75);'
+            + `animation:dsh-amb-hm-dust ${9 + ((n * 7) % 6)}s linear infinite;`
+            + `animation-delay:${-(n * 2.3)}s`,
+        }) + '</div>'
+      }
+
+      // 猫 A —— 坐姿虎斑，面朝左（第一版形态：地面绕尾、橄榄形上身、后侧三道
+      // 弧纹）。连接方式按用户指定：**不垫任何脖子形状**，头部整组（头圆 + 双耳
+      // + 五官 + 胡须 + 额头纹）作为整体下移 28、右移 2，头圆下缘直接压进身体
+      // 上缘约 7.5 个单位（肩点 (52,52) 距头心 14.1 < r15，也埋进头圆），同色
+      // 填充使接缝不可见；下巴与胸口之间留下的小凹角正是猫下巴该有的位置。
+      // 奶油色胸部椭圆按用户要求落在 (39,76)。
+      const catSit = open('svg', {
+        viewBox: '0 0 100 118',
+        style: 'display:block;width:100%;height:auto;overflow:visible',
+      })
+        + open('g', {
+          class: 'hm-tail',
+          style: 'transform-box:fill-box;transform-origin:0% 100%;'
+            + 'animation:dsh-amb-hm-tail 5.5s ease-in-out infinite alternate',
+        })
+        + open('path', {
+          d: 'M62 112 C82 115 90 103 85 90 C82 82 74 80 70 84',
+          fill: 'none', stroke: '#C98B4B', 'stroke-width': '7', 'stroke-linecap': 'round',
+        }) + '</path>'
+        + open('path', {
+          d: 'M86 92 C83 84 76 81 71 84',
+          fill: 'none', stroke: '#8A5A2B', 'stroke-width': '7', 'stroke-linecap': 'round',
+        }) + '</path>'
+        + '</g>'
+        + open('path', {
+          d: 'M30 116 C26 106 26 92 30 78 C34 64 42 56 52 52 C62 48 70 56 72 70 C74 86 72 104 66 116 Z',
+          fill: '#D9A05B',
+        }) + '</path>'
+        + open('ellipse', { cx: '39', cy: '76', rx: '10', ry: '19', fill: '#F0D6A6' }) + '</ellipse>'
+        + open('rect', { x: '32', y: '88', width: '6', height: '28', rx: '3', fill: '#E5BC7E', stroke: '#C98B4B', 'stroke-width': '1' }) + '</rect>'
+        + open('rect', { x: '42', y: '88', width: '6', height: '28', rx: '3', fill: '#E5BC7E', stroke: '#C98B4B', 'stroke-width': '1' }) + '</rect>'
+        + open('path', { d: 'M56 54 C64 58 68 64 70 72', fill: 'none', stroke: '#8A5A2B', 'stroke-width': '4', 'stroke-linecap': 'round', opacity: '0.85' }) + '</path>'
+        + open('path', { d: 'M60 74 C66 78 69 84 70 90', fill: 'none', stroke: '#8A5A2B', 'stroke-width': '4', 'stroke-linecap': 'round', opacity: '0.85' }) + '</path>'
+        + open('path', { d: 'M58 96 C63 99 66 104 67 110', fill: 'none', stroke: '#8A5A2B', 'stroke-width': '4', 'stroke-linecap': 'round', opacity: '0.85' }) + '</path>'
+        + open('path', { d: 'M34 40 L34 46 M38 39 L38 45 M30 41 L30 47', stroke: '#8A5A2B', 'stroke-width': '2', 'stroke-linecap': 'round' }) + '</path>'
+        + open('path', { d: 'M26 46 L23 31 L35 39 Z', fill: '#D9A05B' }) + '</path>'
+        + open('path', { d: 'M27.5 43 L26 35 L33 40 Z', fill: '#C97B6B', opacity: '0.75' }) + '</path>'
+        + open('g', {
+          class: 'hm-ear',
+          style: 'transform-box:fill-box;transform-origin:0% 100%;'
+            + 'animation:dsh-amb-hm-ear 7s ease-in-out infinite',
+        })
+        + open('path', { d: 'M44 42 L52 30 L50 44 Z', fill: '#D9A05B' }) + '</path>'
+        + open('path', { d: 'M46 40.5 L50.5 33.5 L48.5 41.5 Z', fill: '#C97B6B', opacity: '0.75' }) + '</path>'
+        + '</g>'
+        + open('circle', { cx: '38', cy: '54', r: '15', fill: '#D9A05B' }) + '</circle>'
+        + open('circle', { cx: '32', cy: '52', r: '2.2', fill: '#3B2A16' }) + '</circle>'
+        + open('circle', { cx: '44', cy: '52', r: '2.2', fill: '#3B2A16' }) + '</circle>'
+        + open('circle', { cx: '32.7', cy: '51.2', r: '0.7', fill: '#FFFFFF' }) + '</circle>'
+        + open('circle', { cx: '44.7', cy: '51.2', r: '0.7', fill: '#FFFFFF' }) + '</circle>'
+        + open('path', { d: 'M36 58 L40 58 L38 61 Z', fill: '#C97B6B' }) + '</path>'
+        + open('path', { d: 'M38 61 C38 63 36 64 34 64 M38 61 C38 63 40 64 42 64', fill: 'none', stroke: '#8A5A2B', 'stroke-width': '1', 'stroke-linecap': 'round' }) + '</path>'
+        + open('path', { d: 'M26 57 L14 55 M26 60 L14 62 M52 57 L62 55 M52 60 L62 62', stroke: '#B98A55', 'stroke-width': '1', 'stroke-linecap': 'round', opacity: '0.8' }) + '</path>'
+        + '</svg>'
+
+      // 猫 B —— 蜷成一团酣睡：圆头明显叠在身子右前侧（同色相接），折耳 +
+      // 闭眼 + 鼻尖胡须 + 身前露出一只奶油色前爪，尾巴沿身前绕一圈、
+      // 深色尾尖收在左侧；整体随呼吸微微起伏，头顶冒出两枚会消散的小 z。
+      const catCurled = open('svg', {
+        viewBox: '0 0 112 66',
+        style: 'display:block;width:100%;height:auto;overflow:visible',
+      })
+        + open('g', {
+          class: 'hm-breathe',
+          style: 'transform-box:fill-box;transform-origin:50% 100%;'
+            + 'animation:dsh-amb-hm-breathe 3.8s ease-in-out infinite',
+        })
+        + open('path', {
+          d: 'M6 62 C6 44 24 28 52 27 C80 26 100 40 99 53 C98 60 92 62 84 62 Z',
+          fill: '#D9A05B',
+        }) + '</path>'
+        + open('path', { d: 'M26 30 C28 38 28 48 26 57', fill: 'none', stroke: '#8A5A2B', 'stroke-width': '4', 'stroke-linecap': 'round', opacity: '0.8' }) + '</path>'
+        + open('path', { d: 'M38 28 C40 37 40 49 38 59', fill: 'none', stroke: '#8A5A2B', 'stroke-width': '4', 'stroke-linecap': 'round', opacity: '0.8' }) + '</path>'
+        + open('path', { d: 'M50 27 C52 36 52 47 51 56', fill: 'none', stroke: '#8A5A2B', 'stroke-width': '4', 'stroke-linecap': 'round', opacity: '0.8' }) + '</path>'
+        + open('path', { d: 'M6 58 C26 66 62 67 92 59', fill: 'none', stroke: '#C98B4B', 'stroke-width': '6', 'stroke-linecap': 'round' }) + '</path>'
+        + open('path', { d: 'M6 58 C12 61 18 63 24 64', fill: 'none', stroke: '#8A5A2B', 'stroke-width': '6', 'stroke-linecap': 'round' }) + '</path>'
+        + open('circle', { cx: '80', cy: '44', r: '15', fill: '#D9A05B' }) + '</circle>'
+        + open('path', { d: 'M70 33 L65 23 L75.5 28.5 Z', fill: '#D9A05B' }) + '</path>'
+        + open('path', { d: 'M88 31 L94 22 L95.5 32 Z', fill: '#D9A05B' }) + '</path>'
+        + open('path', { d: 'M70.5 30.5 L68 25 L73.5 28 Z', fill: '#C97B6B', opacity: '0.75' }) + '</path>'
+        + open('path', { d: 'M88.5 29.5 L92.5 24 L93.5 30.5 Z', fill: '#C97B6B', opacity: '0.75' }) + '</path>'
+        + open('path', { d: 'M72 45 Q75 48 78 45', fill: 'none', stroke: '#8A5A2B', 'stroke-width': '1.4', 'stroke-linecap': 'round' }) + '</path>'
+        + open('path', { d: 'M65.5 46.5 L69 46.5 L67.25 49.5 Z', fill: '#C97B6B' }) + '</path>'
+        + open('path', { d: 'M62 48.5 L54 47.5 M62 51 L55 52.5', stroke: '#B98A55', 'stroke-width': '1', 'stroke-linecap': 'round', opacity: '0.8' }) + '</path>'
+        + open('ellipse', { cx: '60', cy: '60', rx: '7', ry: '3.5', fill: '#F0D6A6', stroke: '#C98B4B', 'stroke-width': '1' }) + '</ellipse>'
+        + '</g>'
+        + '</svg>'
+        + open('span', {
+          class: 'hm-z hm-z-1',
+          style: 'position:absolute;right:12%;top:-12%;font-size:.85em;font-style:italic;'
+            + "font-family:Georgia,'Times New Roman',serif;color:#A97F4C;"
+            + 'animation:dsh-amb-hm-zzz 5s ease-in-out infinite',
+        }) + 'z</span>'
+        + open('span', {
+          class: 'hm-z hm-z-2',
+          style: 'position:absolute;right:5%;top:-22%;font-size:.65em;font-style:italic;'
+            + "font-family:Georgia,'Times New Roman',serif;color:#B98F55;"
+            + 'animation:dsh-amb-hm-zzz 5s ease-in-out infinite;animation-delay:-2.5s',
+        }) + 'z</span>'
+
+      return open('div', { class: 'hm', style: 'position:absolute;inset:0;display:block' })
+        + petHazeMarkup('rgba(255,214,140,.5)', 'dsh-amb-hm-glow')
+        + open('div', {
+          class: 'hm-sill',
+          style: 'position:absolute;left:0;right:0;bottom:0;height:12%;z-index:4;'
+            + 'background:linear-gradient(to bottom,rgba(154,95,36,0) 0%,rgba(154,95,36,.16) 40%,rgba(138,84,30,.3) 100%)',
+        })
+        + open('div', {
+          class: 'hm-sill-line',
+          style: 'position:absolute;top:0;left:0;right:0;height:1.2px;opacity:.55;'
+            + 'background:linear-gradient(90deg,transparent,rgba(255,244,220,.9),transparent)',
+        }) + '</div>'
+        + '</div>'
+        + open('div', {
+          class: 'hm-cat-sit',
+          style: 'position:absolute;left:7%;bottom:9%;width:7.5em;z-index:6',
+        }) + catSit + '</div>'
+        + open('div', {
+          class: 'hm-cat-curled',
+          style: 'position:absolute;right:6%;bottom:7%;width:8.4em;z-index:6',
+        }) + catCurled + '</div>'
+        + dustNodes
+        + '</div>'
+    }
+
+    /**
+     * The 虎子阿黄 scene: a golden haze, a field-path bank, the yellow Chinese
+     * pastoral dog himself — upright ears, a sickle tail wagging at speed, an
+     * occasional curious head tilt, a straw collar with a bell — with dry
+     * grass tufts, a ball in the theme's own 缃色, and dandelion fluff drifting
+     * across on the wind.
+     *
+     * The second ORIGINAL scene in the pack, same idiom as the cat: inline
+     * % / em geometry, one warm wheat-gold family, and every animated transform
+     * bounded below the band's top edge — the fluff fades out at the far edge
+     * instead of clipping.
+     * @param dust - how many dandelion-fluff puffs to seed.
+     * @returns the scene markup.
+     */
+    function ahuangAmbientScene(dust) {
+      const count = Math.max(0, Math.min(20, dust ?? 5))
+      let fluffNodes = ''
+      for (let n = 1; n <= count; n += 1) {
+        const size = 4 + ((n * 3) % 3)
+        fluffNodes += open('div', {
+          class: 'hz-fluff',
+          style: 'position:absolute;border-radius:50%;'
+            + `left:-6%;top:${((n * 11) % 30) + 18}%;`
+            + `width:${size}px;height:${size}px;`
+            + 'background:radial-gradient(circle,#FFFDF4 0%,rgba(255,246,214,.85) 55%,rgba(255,246,214,0) 100%);'
+            + 'box-shadow:0 0 5px rgba(255,244,200,.8);'
+            + `animation:dsh-amb-hz-fluff ${15 + ((n * 7) % 8)}s linear infinite;`
+            + `animation-delay:${-(n * 2.6)}s`,
+        }) + '</div>'
+      }
+
+      // 虎子阿黄 —— 坐姿面朝左。头与躯干同样按「必须重叠」构造：头部圆下缘
+      // 压进胸腔椭圆上缘 3 个单位，项圈画在重叠带上把脖子束出来；立耳、
+      // 镰刀尾（尾根埋进后臀圆里）快速摇摆、偶尔歪头，吐着舌头等主人。
+      const dog = open('svg', {
+        viewBox: '0 0 112 122',
+        style: 'display:block;width:100%;height:auto;overflow:visible',
+      })
+        + open('g', {
+          class: 'hz-tail',
+          style: 'transform-box:fill-box;transform-origin:0% 100%;'
+            + 'animation:dsh-amb-hz-wag .95s ease-in-out infinite alternate',
+        })
+        + open('path', {
+          d: 'M76 70 C92 66 100 50 92 36 C88 30 82 29 78 32',
+          fill: 'none', stroke: '#D8A44E', 'stroke-width': '8', 'stroke-linecap': 'round',
+        }) + '</path>'
+        + open('path', {
+          d: 'M93 37 C90 32 85 30 79 32',
+          fill: 'none', stroke: '#B97F3A', 'stroke-width': '8', 'stroke-linecap': 'round',
+        }) + '</path>'
+        + '</g>'
+        + open('circle', { cx: '72', cy: '94', r: '26', fill: '#E8B45A' }) + '</circle>'
+        + open('ellipse', { cx: '44', cy: '93', rx: '18', ry: '27', fill: '#E8B45A' }) + '</ellipse>'
+        + open('ellipse', { cx: '56', cy: '117', rx: '13', ry: '5', fill: '#E8B45A' }) + '</ellipse>'
+        + open('ellipse', { cx: '42', cy: '97', rx: '10', ry: '19', fill: '#F6E3B8' }) + '</ellipse>'
+        + open('rect', { x: '32', y: '92', width: '7.5', height: '26', rx: '3.7', fill: '#E8B45A', stroke: '#C98F35', 'stroke-width': '1' }) + '</rect>'
+        + open('rect', { x: '44', y: '92', width: '7.5', height: '26', rx: '3.7', fill: '#E8B45A', stroke: '#C98F35', 'stroke-width': '1' }) + '</rect>'
+        + open('ellipse', { cx: '35.7', cy: '117', rx: '6', ry: '3.2', fill: '#F6E3B8' }) + '</ellipse>'
+        + open('ellipse', { cx: '47.7', cy: '117', rx: '6', ry: '3.2', fill: '#F6E3B8' }) + '</ellipse>'
+        + open('path', { d: 'M31 68 C38 74 50 74 56 66', fill: 'none', stroke: '#896C39', 'stroke-width': '5', 'stroke-linecap': 'round' }) + '</path>'
+        + open('circle', { cx: '33', cy: '72.5', r: '2.6', fill: '#F0C239', stroke: '#B98A20', 'stroke-width': '0.8' }) + '</circle>'
+        + open('path', { d: 'M30.6 72.5 L35.4 72.5', stroke: '#B98A20', 'stroke-width': '0.8' }) + '</path>'
+        + open('g', {
+          class: 'hz-head',
+          style: 'transform-box:fill-box;transform-origin:60% 88%;'
+            + 'animation:dsh-amb-hz-tilt 7s ease-in-out infinite',
+        })
+        + open('path', { d: 'M28 40 C24 30 23 23 26 18 C30 21 34 28 35.5 36 Z', fill: '#D8A44E' }) + '</path>'
+        + open('path', { d: 'M48 38 C50 28 52 21 56 18 C58 23 56 30 52.5 38.5 Z', fill: '#D8A44E' }) + '</path>'
+        + open('path', { d: 'M29 36 C27 29 26.5 25 28 21.5 C30.5 24.5 32.5 29 33.5 34 Z', fill: '#C97B6B', opacity: '0.7' }) + '</path>'
+        + open('path', { d: 'M49.5 34 C51 27.5 52.5 23.5 55 21 C56 25 54.5 30 52 35.5 Z', fill: '#C97B6B', opacity: '0.7' }) + '</path>'
+        + open('circle', { cx: '42', cy: '51', r: '18', fill: '#E8B45A' }) + '</circle>'
+        + open('ellipse', { cx: '27', cy: '57', rx: '11', ry: '8.5', fill: '#F6E3B8' }) + '</ellipse>'
+        + open('ellipse', { cx: '19', cy: '53.5', rx: '3', ry: '2.4', fill: '#4A331C' }) + '</ellipse>'
+        + open('circle', { cx: '44', cy: '47', r: '2.4', fill: '#3B2A16' }) + '</circle>'
+        + open('circle', { cx: '44.8', cy: '46.2', r: '0.8', fill: '#FFFFFF' }) + '</circle>'
+        + open('path', { d: 'M22.5 61 C24.5 64.5 29.5 65.5 32.5 62.5', fill: 'none', stroke: '#8A5F2B', 'stroke-width': '1.3', 'stroke-linecap': 'round' }) + '</path>'
+        + open('path', { d: 'M24 62.5 C28 63.5 29 67.5 27 70 C25 72 22 71 22 68.5 C22 66 22.5 64 24 62.5 Z', fill: '#DE7E68' }) + '</path>'
+        + open('path', { d: 'M24.5 64 C25.5 65.5 25.8 67.5 25.2 69.5', fill: 'none', stroke: '#C05E4E', 'stroke-width': '0.9', 'stroke-linecap': 'round' }) + '</path>'
+        + '</g>'
+        + '</svg>'
+
+      const grassTuft = (left, bottom, width, zIndex) => open('div', {
+        class: 'hz-grass',
+        style: `position:absolute;${left};bottom:${bottom};width:${width};z-index:${zIndex}`,
+      })
+        + open('svg', {
+          viewBox: '0 0 60 30',
+          style: 'display:block;width:100%;height:auto;overflow:visible',
+        })
+        + open('g', {
+          class: 'hz-blades',
+          style: 'transform-box:fill-box;transform-origin:50% 100%;'
+            + 'animation:dsh-amb-hz-grass 5.2s ease-in-out infinite alternate',
+        })
+        + open('path', { d: 'M6 30 C4 22 6 14 10 8', fill: 'none', stroke: '#C2A24E', 'stroke-width': '2.6', 'stroke-linecap': 'round' }) + '</path>'
+        + open('path', { d: 'M14 30 C13 20 16 12 20 6', fill: 'none', stroke: '#B08F3E', 'stroke-width': '2.4', 'stroke-linecap': 'round' }) + '</path>'
+        + open('path', { d: 'M24 30 C24 20 27 12 32 7', fill: 'none', stroke: '#C2A24E', 'stroke-width': '2.2', 'stroke-linecap': 'round' }) + '</path>'
+        + open('path', { d: 'M36 30 C38 22 42 15 48 10', fill: 'none', stroke: '#B08F3E', 'stroke-width': '2.4', 'stroke-linecap': 'round' }) + '</path>'
+        + open('path', { d: 'M46 30 C48 24 52 18 56 14', fill: 'none', stroke: '#C2A24E', 'stroke-width': '2.2', 'stroke-linecap': 'round' }) + '</path>'
+        + '</g>'
+        + '</svg>'
+        + '</div>'
+
+      return open('div', { class: 'hz', style: 'position:absolute;inset:0;display:block' })
+        + petHazeMarkup('rgba(240,194,57,.42)', 'dsh-amb-hz-glow')
+        + open('div', {
+          class: 'hz-bank',
+          style: 'position:absolute;left:0;right:0;bottom:0;height:14%;z-index:4;'
+            + 'background:linear-gradient(to bottom,rgba(137,108,57,0) 0%,rgba(137,108,57,.16) 40%,rgba(120,92,44,.3) 100%)',
+        })
+        + open('div', {
+          class: 'hz-bank-line',
+          style: 'position:absolute;top:0;left:0;right:0;height:1.2px;opacity:.5;'
+            + 'background:linear-gradient(90deg,transparent,rgba(255,250,228,.9),transparent)',
+        }) + '</div>'
+        + '</div>'
+        + grassTuft('left:2%', '0', '4.5em', '5')
+        + grassTuft('left:17%', '1%', '3.6em', '7')
+        + grassTuft('right:3%', '0', '4.2em', '5')
+        + open('div', {
+          class: 'hz-ball',
+          style: 'position:absolute;left:14%;bottom:8%;width:1.7em;z-index:6',
+        })
+        + open('svg', {
+          viewBox: '0 0 20 20',
+          style: 'display:block;width:100%;height:auto',
+        })
+        + open('circle', { cx: '10', cy: '10', r: '9', fill: '#F0C239', stroke: '#C9A02F', 'stroke-width': '1' }) + '</circle>'
+        + open('path', { d: 'M4 4 C8 8 8 12 4 16 M16 4 C12 8 12 12 16 16', fill: 'none', stroke: '#B98A20', 'stroke-width': '1.2', 'stroke-linecap': 'round' }) + '</path>'
+        + open('ellipse', { cx: '7', cy: '6.5', rx: '2.6', ry: '1.6', fill: '#FFF3C4', opacity: '0.85' }) + '</ellipse>'
+        + '</svg>'
+        + '</div>'
+        + open('div', {
+          class: 'hz-dog',
+          style: 'position:absolute;left:32%;bottom:7%;width:8em;z-index:6',
+        }) + dog + '</div>'
+        + fluffNodes
+        + '</div>'
+    }
+
     /**
      * Apply a function on every tick until the thing it observes stops changing.
      *
@@ -3369,7 +4433,11 @@ window.__ModuleLoader__.load({
                   ? jiexinAmbientScene(options?.dust)
                   : kind === 'fengchen'
                     ? fengchenAmbientScene(options?.feathers, options?.dew)
-                    : ''
+                    : kind === 'humao'
+                      ? humaoAmbientScene(options?.dust)
+                      : kind === 'ahuang'
+                        ? ahuangAmbientScene(options?.dust)
+                        : ''
       // The builder is fed only attributes and hex values, but this is the one place
       // markup from outside this file could ever arrive, so it refuses anyway.
       if (/<script|\son[a-z]+\s*=/i.test(markup)) {
@@ -3731,11 +4799,12 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * Remove every ambient node, ownership aside.
+     * Remove every legacy ambient SEAT, ownership aside.
      *
-     * Used when no scenery should exist at all: a theme without `ambient`, or a seat
-     * whose placement can no longer be computed. Leaving a layer behind would paint one
-     * theme's scenery over the next one's.
+     * Despite the name it does NOT touch the live `.dsh-amb-control` layer: that layer is
+     * owned by `drawScene`, and it is only rewritten when a theme actually has scenery. So
+     * this call is safe on the "theme has no scenery" path, where leaving the layer in
+     * place is the INTENDED behaviour — see the note in `syncAmbient`.
      */
     function removeAllAmbientSeats() {
       if (typeof document === 'undefined') return
@@ -3858,10 +4927,21 @@ window.__ModuleLoader__.load({
     /**
      * Render the active theme's scenery into the sidebar column.
      *
-     * Idempotent: the seat is created once and its contents are replaced whenever
-     * the active theme (or its ambient config) changes, so re-running is cheap and
-     * cannot stack duplicate scenes. Themes with no `ambient` get an empty seat —
-     * the scenery belongs to the skin, so switching skins must remove it.
+     * Idempotent: the scene box is reused and its content is replaced only when the markup
+     * changes, so re-running never stacks duplicate scenes (two copies of a scene = two of
+     * every animated element, which is what produced the duplicated dragonflies).
+     *
+     * Two different "no scenery" cases, and they are NOT the same:
+     *
+     *  · switching to ANOTHER skin — the markup differs, so the box is repainted with the
+     *    new skin's artwork;
+     *  · switching to a theme that has no `ambient` at all — the BUILT-IN 浅色 / 深色 cards.
+     *    Only the legacy seats are swept; the live `.dsh-amb-control` layer is deliberately
+     *    LEFT ALONE, so the previous skin's artwork (balloons, fish, mountains…) stays on
+     *    screen over the system palette. That leftover is a feature the user asked to keep
+     *    — the built-in cards advertise it ("会有惊喜哦") and
+     *    `tests/check-boot-path.mjs` asserts it, so a later "cleanup" cannot remove it
+     *    without turning the test red.
      * @param kind - the ambient kind, or undefined for none.
      * @param options - the theme's ambient options.
      */
@@ -3934,6 +5014,18 @@ window.__ModuleLoader__.load({
       const markup = sceneMarkup(kind, options)
 
       if (markup === '') {
+        // ── THE LIVE LAYER IS NOT TOUCHED HERE, ON PURPOSE ───────────────────────
+        //
+        // This branch runs when the active theme has no scenery — i.e. after clicking one of
+        // the built-in 浅色 / 深色 cards. `removeAllAmbientSeats()` only sweeps
+        // `#dsh-theme-ambient` SEATS (a container earlier builds created); the layer that
+        // actually paints is `.dsh-amb-control`, and it is only ever rewritten by
+        // `drawScene()`. So the previous skin's artwork stays where it is.
+        //
+        // That is the user's "惊喜": pick a skin, then switch to 浅色 / 深色, and the
+        // sidebar keeps the balloons / fish / mountains while the palette goes back to the
+        // system appearance. It is asserted in `tests/check-boot-path.mjs`
+        // (「切到内置主题后装饰层保留」) — do not "fix" it by clearing the layer here.
         removeAllAmbientSeats()
         if (record) noteAmbientAttempt({ kind, column: true, band: '无装饰' })
         ambientReport = { found: true, kind: '(none)', note: '该主题无装饰' }
@@ -4511,6 +5603,14 @@ 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))
+      // ── THE HEADER COUNT IS SKINS, NOT CARDS ─────────────────────────────────
+      //
+      // The built-in 浅色 / 深色 cards are not skins — they only switch the palette back to the
+      // official appearance — so counting them here would advertise a number that disagrees
+      // with the README and with npm's description ("6 skins"). The cards are named in the
+      // same line instead, so nothing is hidden by leaving them out of the number.
+      const builtInCards = ids.filter((id) => BUILT_IN_LABELS[id] !== undefined).length
+      const skinCount = ids.length - builtInCards
       return jsxs('div', {
         className: 'tg-page',
         children: [
@@ -4519,7 +5619,7 @@ window.__ModuleLoader__.load({
             children: [
               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 }) }),
+              jsx('span', { className: 'tg-hint', children: t('count', { count: skinCount }) }),
               // 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}` }),
@@ -4534,7 +5634,11 @@ window.__ModuleLoader__.load({
               swatches: swatches[id] || [],
               selected: id === selected,
               applied: t('applied'),
-              onSelect: setTheme,
+              // The click is recorded BEFORE it is handed to the shell, because the theme
+              // service publishes synchronously and the publisher re-applies the remembered
+              // skin: a built-in card clicked after a skin used to be undone immediately.
+              // `rememberCardChoice` is what lets 浅色 / 深色 win — see its documentation.
+              onSelect: (id) => { rememberCardChoice(id); setTheme(id) },
               t,
             }, id)),
           }),
@@ -4918,8 +6022,11 @@ window.__ModuleLoader__.load({
        * handler, so the safety has to live in the CONFIGURATION CONTRACT rather than in code.
        * The one way to break it is to hand-write a skin id into `preference` — which the
        * official service would then reject at boot. Never do that.
+       *
+       * The keys themselves live at MODULE scope ({@link SKIN_KEY} / {@link BUILT_IN_KEY}):
+       * the card-click handler runs in the page component, far from this body, and it must
+       * be able to write them before the click reaches the theme service.
        */
-      const SKIN_KEY = 'theme-gallery:last-skin'
 
       /**
        * The token used to prove a skin's palette reached the document.
@@ -4952,6 +6059,45 @@ window.__ModuleLoader__.load({
         }
       }
 
+      /**
+       * Record that a skin is the active theme — the restart-time memory.
+       *
+       * Written only once the service actually reports the skin, so the key never names a
+       * skin that was merely requested and then lost. Clearing the built-in marker in the
+       * same breath keeps the two keys from disagreeing about what the user last chose.
+       * @param id - the active skin id.
+       */
+      function rememberActiveSkin(id) {
+        try {
+          if (window.localStorage.getItem(SKIN_KEY) !== id) window.localStorage.setItem(SKIN_KEY, id)
+          if (window.localStorage.getItem(BUILT_IN_KEY) !== null) window.localStorage.removeItem(BUILT_IN_KEY)
+        } catch (error) {
+          console.error('[theme-gallery] could not remember the active skin:', error)
+        }
+      }
+
+      /**
+       * The skin this plugin should be showing, or null when the user is entitled to a
+       * built-in appearance.
+       *
+       * Three-way precedence, and all three arms are load-bearing:
+       *
+       *  1. a skin the user chose — restore it, across restarts (the original feature);
+       *  2. a built-in the user chose IN THIS PANEL — null, so the restore does not fight it;
+       *  3. nothing chosen yet — the gallery's own default ({@link DEFAULT_SKIN}), which is
+       *     what makes a fresh install land on 山青婷彩 instead of the built-in white.
+       *
+       * Arm 2 is why the built-in cards work at all: without it, arm 1 keeps winning and the
+       * click is undone a moment later.
+       * @returns the skin id, or null.
+       */
+      function wantedSkin() {
+        const remembered = rememberedSkin()
+        if (remembered !== null) return remembered
+        if (builtInChoice() !== null) return null
+        return DEFAULT_SKIN
+      }
+
       /** The skin whose palette layer is currently stacked, and how to remove it. */
       let stackedSkin
       let stackedSkinDispose
@@ -5221,17 +6367,20 @@ window.__ModuleLoader__.load({
           // the presenter subscribed leaves the service reporting the skin while the page still
           // shows the built-in palette.
           if (typeof activeId === 'string' && bundledTheme(activeId) !== undefined) {
-            if (window.localStorage.getItem(SKIN_KEY) !== activeId) {
-              window.localStorage.setItem(SKIN_KEY, activeId)
-            }
+            rememberActiveSkin(activeId)
             ensureSkinPainted(activeId, activeId)
             return
           }
 
-          // The app is on a built-in theme even though a skin is remembered: the boot race lost
-          // the preference. Re-checked on every publish rather than once per session, because a
-          // single attempt can be swallowed by a presenter that is not listening yet.
-          const wanted = rememberedSkin()
+          // The app is on a built-in theme even though one of our skins is wanted: either the
+          // boot race lost the preference, or nothing has been chosen yet and the gallery's
+          // default has still to be applied. Re-checked on every publish rather than once per
+          // session, because a single attempt can be swallowed by a presenter that is not
+          // listening yet.
+          //
+          // `wantedSkin()` returns null when the user deliberately picked a built-in card, and
+          // that null is the whole fix for "点深色又被弹回皮肤" — see its documentation.
+          const wanted = wantedSkin()
           if (wanted === null) return
           ensureSkinPainted(wanted, activeId)
         } catch (error) {
@@ -5300,7 +6449,12 @@ window.__ModuleLoader__.load({
        */
       function publish(snapshot) {
         revision += 1
-        const themes = [...snapshot.themes].filter((theme) => !OMITTED_IDS.has(theme.id))
+        // DISPLAY ORDER IS APPLIED HERE, TO THE PAGE'S COPY ONLY.
+        //
+        // The registry keeps the order things were registered in, so re-ranking a card can
+        // never change which themes exist, what they contain, or the order they were
+        // contributed — `cardsInDisplayOrder` is a view over the filtered list.
+        const themes = cardsInDisplayOrder([...snapshot.themes].filter((theme) => !OMITTED_IDS.has(theme.id)))
         storeActions.sync(themes, snapshot.preference, revision)
         syncSkin(snapshot)
         syncRememberedSkin(snapshot)
@@ -5556,7 +6710,9 @@ window.__ModuleLoader__.load({
             try {
               const snapshot = ctx.theme.getTheme()
               const active = snapshot?.active?.id
-              const wanted = rememberedSkin()
+              // The default skin counts here too: on a fresh install this window is what keeps
+              // asking until 山青婷彩 is genuinely on the document, not merely requested.
+              const wanted = wantedSkin()
               if (wanted === null) {
                 done = true
               } else if (skinIsPainted(wanted)) {