@nonamelego/dsh-catppuccin 0.4.2 → 0.5.0-beta.0

package/README.en.md

@@ -0,0 +1,304 @@
+<h3 align="center">
+	<img src="https://raw.githubusercontent.com/catppuccin/catppuccin/main/assets/logos/exports/1544x1544_circle.png" width="100" alt="Logo"/><br/>
+	<img src="https://raw.githubusercontent.com/catppuccin/catppuccin/main/assets/misc/transparent.png" height="30" width="0px"/>
+	Catppuccin for <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a>
+	<img src="https://raw.githubusercontent.com/catppuccin/catppuccin/main/assets/misc/transparent.png" height="30" width="0px"/>
+</h3>
+
+<p align="center">
+	<a href="https://github.com/NoNameLeGo/dsh-catppuccin-theme/stargazers"><img src="https://img.shields.io/github/stars/NoNameLeGo/dsh-catppuccin-theme?colorA=363a4f&colorB=b7bdf8&style=for-the-badge"></a>
+	<a href="https://github.com/NoNameLeGo/dsh-catppuccin-theme/issues"><img src="https://img.shields.io/github/issues/NoNameLeGo/dsh-catppuccin-theme?colorA=363a4f&colorB=f5a97f&style=for-the-badge"></a>
+	<a href="https://github.com/NoNameLeGo/dsh-catppuccin-theme/contributors"><img src="https://img.shields.io/github/contributors/NoNameLeGo/dsh-catppuccin-theme?colorA=363a4f&colorB=a6da95&style=for-the-badge"></a>
+	<a href="https://www.npmjs.com/package/@nonamelego/dsh-catppuccin"><img src="https://img.shields.io/npm/v/@nonamelego/dsh-catppuccin?colorA=363a4f&colorB=a6da95&style=for-the-badge"></a>
+	<a href="https://www.npmjs.com/package/@nonamelego/dsh-catppuccin"><img src="https://img.shields.io/npm/dt/@nonamelego/dsh-catppuccin?colorA=363a4f&colorB=f5a97f&style=for-the-badge"></a>
+</p>
+
+**English** | [中文](README.md)
+
+> A theme & glassmorphism plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — Catppuccin flavours for the **Web GUI**, **DSH Desktop** and **dsh-TUI**, plus a switchable frosted-glass skin. Listed on [Awesome DSH Plugin](https://awesome-dsh-plugin.com/p/NoNameLeGo__dsh-catppuccin-theme/).
+
+## Contents
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Previews](#previews)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Glassmorphism](#glassmorphism)
+- [Development](#development)
+- [🙋 FAQ](#-faq)
+- [💝 Credits](#-credits)
+
+<p align="center">
+	<img src="assets/previews/combined.png" width="100%" alt="DeepSeek Harness under the four Catppuccin flavours"/>
+	<br/><br/>
+	<img src="assets/previews/glass-combined.png" width="100%" alt="Glass skin · Latte & Mocha"/>
+</p>
+
+## Introduction
+
+A [Catppuccin](https://github.com/catppuccin/catppuccin) theme plugin for
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — one package that fits
+the **Web GUI** (`dsh web`), **DSH Desktop** and **dsh-TUI** alike: full recolouring plus a
+glass skin on Web / Desktop, and the four official theme palettes auto-synced to the TUI.
+
+It ships all four Catppuccin flavours — **Latte**, **Frappé**, **Macchiato**, **Mocha** —
+remapping the whole interface to the matching palette, with a **Catppuccin** row right below
+**Settings → General → Appearance** for one-click switching. Your choice is persisted and
+restored after restarts.
+
+It also includes an optional **glassmorphism** skin: the top bar, sidebar, composer,
+stats line, trajectory view, chat bubbles and the new-session button become frosted-glass
+cards, with adjustable blur, frost and backdrop brightness. Glass colours follow the active
+Catppuccin theme automatically.
+
+## Features
+
+- 🎨 Four themes: Latte (light), Frappé / Macchiato / Mocha (dark)
+- 🧩 Registered into the official theme system, on a par with the built-in light / dark / system themes
+- 🎯 Full-UI colour coverage — not just one or two accent colours
+- ⚙️ One-click switch in Settings, persisted and restored across restarts
+- 🌐 Bilingual UI (Chinese / English, follows the system language)
+- 🪟 **Glass skin**: frosted glass for the top bar / sidebar / composer / stats line /
+  trajectory view / chat bubbles / new-session button, one-click toggle in Settings;
+  mica & compatibility modes, adjustable blur, frost and backdrop brightness
+  (interaction reference: [DSH-Transparent-UI-Plugin](https://github.com/WYH66666666/DSH-Transparent-UI-Plugin))
+- 🌫️ **Glass details**: gradient blur bands at the top/bottom page edges, a floating glass
+  rail when the sidebar is collapsed, a solid background in the theme's own base colour —
+  content softens as it scrolls under the panes
+- 🎨 Glass colours follow the current Catppuccin theme
+- 🔄 **Update check**: one-click "Check for updates" in Settings compares the latest npm
+  version and gives you a copyable upgrade command
+- 💻 **dsh-TUI terminal themes**: one command installs into dsh-TUI; the four themes sync to
+  `~/.dsh-tui/themes/` automatically (see [Installation · dsh-TUI](#dsh-tui-terminal-themes))
+
+## Previews
+
+Actual screenshots from a local GUI (the header image is a diagonal blend of the four):
+
+<details>
+<summary>🌻 Latte (light)</summary>
+<img src="assets/previews/latte.png"/>
+</details>
+<details>
+<summary>🪴 Frappé (dark)</summary>
+<img src="assets/previews/frappe.png"/>
+</details>
+<details>
+<summary>🌺 Macchiato (dark)</summary>
+<img src="assets/previews/macchiato.png"/>
+</details>
+<details>
+<summary>🌿 Mocha (dark)</summary>
+<img src="assets/previews/mocha.png"/>
+</details>
+
+### Glass skin (Mica mode)
+
+The frosted-glass effect in light (Latte) and dark (Mocha): the top bar, sidebar,
+chat bubbles, composer and stats line are all glass cards; messages soften as they scroll
+past the page edges; the background is the theme's solid base colour:
+
+<details>
+<summary>🌻 Latte (light glass)</summary>
+<img src="assets/previews/glass-latte.png"/>
+</details>
+<details>
+<summary>🌿 Mocha (dark glass)</summary>
+<img src="assets/previews/glass-mocha.png"/>
+</details>
+
+## Installation
+
+### Option 1: from npm (recommended)
+
+```sh
+dsh plugin --profile web add @nonamelego/dsh-catppuccin
+```
+
+Restart `dsh web` after installing — `dsh plugin` adds it to the profile's bundles.
+Use the profile name of your choice in place of `web` (e.g. `headless`).
+
+**[DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop)**: the desktop build's
+active profile is named `desktop`, so run:
+
+```sh
+dsh plugin --profile desktop add @nonamelego/dsh-catppuccin
+```
+
+Run it in the DSH terminal of the desktop app (`dsh plugin` defaults to the active profile).
+Installing from the repo works the same way: `dsh plugin --profile desktop add https://github.com/NoNameLeGo/dsh-catppuccin-theme`.
+
+### Option 2: from the repository
+
+```sh
+dsh plugin --profile web add https://github.com/NoNameLeGo/dsh-catppuccin-theme
+```
+
+When installing from git, pnpm may ask you to allow build scripts — follow pnpm's prompt
+and add the package to the profile's `pnpm-workspace.yaml` `allowBuilds`, then run it again.
+
+### dsh-TUI (terminal) themes
+
+The same package covers the TUI. Install it into the dsh-tui profile:
+
+```sh
+dsh plugin --profile dsh-tui add @nonamelego/dsh-catppuccin
+```
+
+Installing from the repository works the same way (use the git form while the npm release
+is pending). The package ships a tiny theme-sync plugin row
+(`dsh-catppuccin-tui-themes`, no service dependencies): on every dsh-TUI start it syncs the
+four theme JSONs to `~/.dsh-tui/themes/`, so upgrades pick up the new palettes. After
+installing, launch `dsh --profile dsh-tui` and pick the theme with `/theme` —
+**Catppuccin Latte / Frappé / Macchiato / Mocha**, or jump straight to it with
+`/theme catppuccin-mocha` (your choice persists across restarts).
+
+> 💡 Already installed the plugin for the Web GUI and also use dsh-TUI? No need to install
+> it twice: every Web start auto-syncs the themes to `~/.dsh-tui/themes/` (only when the
+> directory already exists).
+
+> 📁 Prefer not to install the package? Copy `themes/*.json` into
+> `~/.dsh-tui/themes/` (Windows: `%USERPROFILE%\.dsh-tui\themes\`) by hand — you just won't
+> get updates automatically.
+
+> ⚠️ `catppuccin-*.json` belongs to this plugin and is overwritten on sync; rename the files
+> if you want custom themes.
+
+> 💡 TUI themes only style the TUI itself — the terminal background is up to your terminal.
+> Pairing it with the matching Catppuccin flavour (see the
+> [Catppuccin ports list](https://github.com/catppuccin/catppuccin#-ports)) looks best.
+
+## Usage
+
+1. Open the Web GUI (default `http://127.0.0.1:3080`), or the DSH Desktop app.
+2. Go to **Settings → General**.
+3. Find the **Catppuccin** row below **Appearance** and pick a flavour:
+   **Latte** (light), **Frappé**, **Macchiato** or **Mocha** (dark).
+4. Choosing **Follow system** reverts to the official theme — it restores the preference
+   you had before enabling Catppuccin (light / dark / follow system) instead of forcing a reset.
+
+### Glass skin
+
+Right below the **Catppuccin theme** row in **Settings → General** you'll find the **Glass** row:
+
+- **Master switch**: on — the top bar, sidebar, composer, stats line and trajectory view
+  become frosted glass; off — the UI reverts to stock instantly (no refresh needed).
+- **Mode**: **Mica** turns the interface into floating frosted cards; **Compatibility** keeps
+  the stock layout and swaps only the material.
+- **Presets**: **Clear / Standard / Frosted** one-click presets; fine-tune with the sliders
+  afterwards (a preset lights up when the current knob values match it).
+- **Blur** (0–40 px) and **Frost** (0–100%): the blur radius and opacity of the glass.
+- **Backdrop brightness**: dark mode darkens 0–50, light mode brightens 50–100 (50 = as-is),
+  mixed straight into the solid background.
+
+Glass colours follow the active theme live; all settings persist across restarts.
+
+### Check for plugin updates
+
+In **Settings → General**, right below the **Glass** row:
+
+- Clicking **Check for updates** compares the latest npm version with the installed one:
+  up to date → shows the current version; newer → shows the new version plus a copyable
+  upgrade command (the profile name is detected automatically, falling back to `web`).
+- Locally linked / source installs (`link:` / `file:` / git) don't show an npm upgrade
+  command — you'll be told to `git pull` or rebuild instead.
+- Channel policy: stable builds follow the `latest` tag; prereleases follow both `latest`
+  and `beta` (the upgrade command automatically carries `@beta`). Offline or network
+  failures show the reason and offer a retry.
+
+## Glassmorphism
+
+**Glassmorphism** is a visual style in which panels look like frosted glass — translucent
+fills, backdrop blur (`backdrop-filter: blur()`), and glass details (rim, inner highlight,
+soft shadow) — letting the content behind show through, softened.
+
+What this plugin does:
+
+- **Seven glass areas**: top bar, sidebar, composer, stats line, trajectory view, chat
+  bubbles and the new-session button; in Mica mode they become rounded floating cards and
+  chat content scrolls *under* the glass, blurred; the collapsed sidebar becomes a
+  floating rail at the edge of the chat area;
+- **Page-edge gradient blur**: a blur band at the top and bottom of the viewport so
+  messages are softened as they melt past the edges (borrowed from
+  [DSH-Transparent-UI-Plugin](https://github.com/WYH66666666/DSH-Transparent-UI-Plugin)'s
+  Aqua skin);
+- **Theme-following colours**: Latte is light glass, Mocha dark glass — switching flavours
+  recolours instantly. The page ground is the theme's solid colour; the brightness knob
+  mixes white/black straight into it;
+- **One-click toggle**: off restores the stock UI exactly; uninstalling the plugin leaves
+  nothing behind.
+
+## Development
+
+```sh
+pnpm install
+pnpm typecheck   # tsc --noEmit type check
+pnpm test        # vitest palette-coverage tests
+pnpm build       # tsdown build -> lib/index.js (host) + lib/client.js (browser)
+```
+
+Palettes are produced by a generator script — after editing
+`scripts/generate-palettes.mjs`, rerun:
+
+```sh
+node scripts/generate-palettes.mjs
+```
+
+The changelog draft is generated from your conventional commits (bilingual `EN:` support
+in commit bodies):
+
+```sh
+pnpm changelog:gen            # print the draft since the last tag
+pnpm changelog:gen -- --write # write it into the [Unreleased] section
+```
+
+### Local link debugging
+
+Clone the repo, link it into a profile and add it to the bundles (use your own paths):
+
+```sh
+pnpm --dir C:\Users\LeGo\.dsh\profiles\web add link:D:\Vibe-Coding\dsh-catppuccin
+```
+
+Then add `@nonamelego/dsh-catppuccin` to the profile's `package.json`
+`dsh.profile.bundles` and restart `dsh web`. For DSH Desktop use
+`~/.dsh/profiles/desktop` instead.
+
+## 🙋 FAQ
+
+- **Q: "Why don't I see the Catppuccin themes in the Appearance row?"**\
+  A: The stock Appearance row only lists the built-in light / dark / follow-system
+  preferences. The four flavours live in the **Catppuccin** row right below it.
+- **Q: "How is my theme choice remembered?"**
+  A: The choice persists in DSH's official settings document (the `catppuccin` namespace,
+  stored under the DSH home, shared across every DSH instance on the machine), with
+  localStorage as an in-browser cache and cross-tab sync. So plain `dsh web`,
+  `dsh web --port <custom>`, and **DSH Desktop** (which boots on a fresh random loopback
+  port every launch) all restore the preference automatically. The glass switch and every
+  knob persist the same way. Since 0.5.0, a legacy `catppuccin-state.json` is migrated
+  into the settings document once on first launch (the file is kept as a rollback copy).
+- **Q: "How do I know if this plugin has a new version?"**
+  A: Settings → General → **Check Catppuccin plugin updates** compares against npm in one
+  click and gives a copyable upgrade command; or run
+  `dsh plugin --profile web update @nonamelego/dsh-catppuccin` manually (re-`add` the
+  latest version works too). In [DSH Desktop](https://github.com/anywhere-labs/deepseek-harness-desktop),
+  use `desktop` as the profile name, or just run `dsh plugin update` in the app's DSH terminal.
+
+## 💝 Credits
+
+- [Catppuccin](https://github.com/catppuccin/catppuccin) for the palettes and port templates
+- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) for the plugin system
+- [DSH-Transparent-UI-Plugin](https://github.com/WYH66666666/DSH-Transparent-UI-Plugin)
+  for the glass-skin interaction and implementation reference (mica / compatibility modes,
+  blur / frost / brightness knobs)
+
+&nbsp;
+
+<p align="center">
+	<img src="https://raw.githubusercontent.com/catppuccin/catppuccin/main/assets/footers/gray0_ctp_on_line.svg?sanitize=true" />
+</p>
+
+<p align="center">
+	Copyright &copy; 2021-present <a href="https://github.com/catppuccin/catppuccin" target="_blank">Catppuccin Org</a>
+</p>

package/README.md

@@ -13,6 +13,8 @@
 	<a href="https://www.npmjs.com/package/@nonamelego/dsh-catppuccin"><img src="https://img.shields.io/npm/dt/@nonamelego/dsh-catppuccin?colorA=363a4f&colorB=f5a97f&style=for-the-badge"></a>
 </p>
 
+**中文** | [English](README.en.md)
+
 ## 目录
 
 - [简介](#简介)
@@ -251,11 +253,12 @@ pnpm --dir C:\Users\LeGo\.dsh\profiles\web add link:D:\Vibe-Coding\dsh-catppucci
   A: 官方外观行只列出内置的浅色/深色/跟随系统偏好。四个主题在它正下方的
   **Catppuccin** 行里。
 - Q: **_"我的主题选择是怎么记住的？"_**
-  A: 选择持久保存在 DSH home 下的 `catppuccin-state.json`（同一台机器的
-  DSH 共享这份偏好），浏览器 localStorage 作为即时缓存与多标签页同步。
-  因此普通 `dsh web`、`dsh web --port` 自定义端口，以及 **DSH Desktop**
-  （每次启动用随机回环端口）都能跨重启自动恢复；玻璃质感开关与各旋钮同样
-  持久保存。
+  A: 选择持久保存在 DSH 的官方 settings 文档（`catppuccin` namespace，存于
+  DSH home 下，同一台机器的 DSH 共享这份偏好），浏览器 localStorage 作为
+  即时缓存与多标签页同步。因此普通 `dsh web`、`dsh web --port` 自定义端口，
+  以及 **DSH Desktop**（每次启动用随机回环端口）都能跨重启自动恢复；玻璃质感
+  开关与各旋钮同样持久保存。0.5.0 起旧版 `catppuccin-state.json` 会在首次
+  启动时一次性迁移进 settings 文档（文件保留作回退）。
 - Q: **_"怎么知道这个插件有没有新版本？"_**
   A: 设置 → 常规 → **检查 Catppuccin 插件更新** 一键检测本插件在 npm 上的最新版本，
   发现新版会给出可复制的升级命令；也可以随时手动执行

package/lib/client.js

@@ -1037,8 +1037,9 @@ window.__ModuleLoader__.load({
 				observer.disconnect();
 			};
 		}
-		/** Host route answering the durable state (GET reads, PUT writes). */
-		const STATE_ROUTE_PATH = "/catppuccin/state";
+		/** Settings namespace both halves address: Host registers it, Client binds
+		*  it through `ctx.settingsScope` (see `src/settings-catppuccin.ts`). */
+		const CATPPUCCIN_SETTINGS_NS = "catppuccin";
 		/** The four registered Catppuccin theme ids. MUST stay in sync with the
 		*  `themeId` of `CATPPUCCIN_FLAVORS` in `src/client/palettes.ts` — guarded by
 		*  `tests/state.spec.ts` — because the persisted flavour value IS the theme id. */
@@ -1098,6 +1099,23 @@ window.__ModuleLoader__.load({
 			const expected = defaultState();
 			return state.flavor === expected.flavor && state.glass.enabled === expected.glass.enabled && state.glass.mode === expected.glass.mode && state.glass.blur === expected.glass.blur && state.glass.frost === expected.glass.frost && state.glass.brightness === expected.glass.brightness;
 		}
+		/** Drop the synthetic `version` field: full state → settings-document section. */
+		function settingsSectionFromState(state) {
+			return {
+				flavor: state.flavor,
+				glass: { ...state.glass }
+			};
+		}
+		/** Lift a settings-document section back into the full state-shaped contract
+		*  (re-sanitized so a hand-edited document can never poison the plugin). */
+		function stateFromSettingsSection(section) {
+			return sanitizeState(section);
+		}
+		/** Whether two settings sections are field-for-field equal (used to skip
+		*  redundant mirror writes and to recognize the Host echoing our own write). */
+		function settingsSectionsEqual(a, b) {
+			return a.flavor === b.flavor && a.glass.enabled === b.glass.enabled && a.glass.mode === b.glass.mode && a.glass.blur === b.glass.blur && a.glass.frost === b.glass.frost && a.glass.brightness === b.glass.brightness;
+		}
 		//#endregion
 		//#region src/client/glass/glass-layer.ts
 		/** html attribute selecting the glass layer: CSS hooks and page effects. */
@@ -1927,75 +1945,98 @@ window.__ModuleLoader__.load({
 		//#endregion
 		//#region src/client/state-sync.ts
 		/**
-		* Browser half of the durable Catppuccin state — a thin wrapper over the
-		* Host's `/catppuccin/state` route (same-origin relative fetch, so it works on
-		* DSH Desktop's per-launch random loopback port). The Host file is the source
-		* of truth; this module adds the fetch wrapper plus a debounced trailing
-		* writer so rapid knob drags coalesce into a single PUT. Every failure is
-		* non-fatal: the plugin keeps working from browser localStorage alone.
+		* Bind the Catppuccin namespace on this context. The scope derives from the
+		* shared document mirror (no wire read of its own) and its life is bound to
+		* the calling fiber, so binding never blocks on the settings transport.
 		*/
-		/** Read the durable state from the Host file (same-origin GET). */
-		async function readDurableStateRemote() {
-			try {
-				const response = await fetch(STATE_ROUTE_PATH, { headers: { accept: "application/json" } });
-				if (!response.ok) return {
-					available: false,
-					state: null
-				};
-				const payload = await response.json();
-				if (payload.ok !== true) return {
-					available: false,
-					state: null
-				};
-				return {
-					available: true,
-					state: payload.state === null || payload.state === void 0 ? null : sanitizeState(payload.state)
-				};
-			} catch {
-				return {
-					available: false,
-					state: null
-				};
-			}
+		function bindCatppuccinScope(ctx) {
+			return ctx.settingsScope.bind({ namespace: CATPPUCCIN_SETTINGS_NS });
 		}
-		/** Write the durable state to the Host file (same-origin PUT). */
-		async function persistDurableState(state) {
+		/** Whether the scope is usable for durable persistence: the document is
+		*  resolved (`ready`) and the Host persistence is active (`host`). A `memory`
+		*  scope (non-loopback pages / absent transport) or a not-yet-ready one is
+		*  NOT usable — the caller keeps localStorage as the only store. */
+		function isScopeUsable(snapshot) {
+			return snapshot.status === "ready" && snapshot.mode === "host";
+		}
+		/** The local state contract (with the synthetic `version`) for a usable
+		*  scope snapshot; `null` while the section is not resolved. */
+		function durableStateFromSnapshot(snapshot) {
+			if (!isScopeUsable(snapshot) || snapshot.value === void 0) return null;
+			return stateFromSettingsSection(snapshot.value);
+		}
+		/** One atomic mutation covering the whole local state (revision-fenced).
+		*  Writing every field keeps the section self-contained — a partial write
+		*  could otherwise leave a knob stuck on a stale override after a document
+		*  edit elsewhere. */
+		function stateToMutateOps(state) {
+			const section = settingsSectionFromState(state);
+			return [
+				{
+					op: "set",
+					path: ["flavor"],
+					value: section.flavor
+				},
+				{
+					op: "set",
+					path: ["glass", "enabled"],
+					value: section.glass.enabled
+				},
+				{
+					op: "set",
+					path: ["glass", "mode"],
+					value: section.glass.mode
+				},
+				{
+					op: "set",
+					path: ["glass", "blur"],
+					value: section.glass.blur
+				},
+				{
+					op: "set",
+					path: ["glass", "frost"],
+					value: section.glass.frost
+				},
+				{
+					op: "set",
+					path: ["glass", "brightness"],
+					value: section.glass.brightness
+				}
+			];
+		}
+		/** Persist the local state through the scope as one atomic mutation.
+		*  Resolves `true` when the write was issued. */
+		async function persistStateToScope(scope, state) {
 			try {
-				return (await fetch(STATE_ROUTE_PATH, {
-					method: "PUT",
-					headers: {
-						accept: "application/json",
-						"content-type": "application/json"
-					},
-					body: JSON.stringify(sanitizeState(state))
-				})).ok;
+				await scope.mutate(stateToMutateOps(state));
+				return true;
 			} catch {
 				return false;
 			}
 		}
 		let pendingTimer;
-		let pendingGetState;
+		let pendingWrite;
 		/**
 		* Debounced trailing persist: after a burst of changes (a slider drag emits a
-		* stream of snapshot updates) the latest state is written to the Host once,
-		* a short beat after the last change. Pass an accessor so the snapshot is
-		* taken at flush time, never stale.
+		* stream of snapshot updates) the write happens once, a short beat after the
+		* last change. Pass an accessor so the state snapshot is taken at flush time,
+		* never stale.
 		*/
-		function scheduleDurablePersist(getState, delayMs = 300) {
+		function scheduleDurablePersist(write, delayMs = 300) {
 			if (pendingTimer !== void 0) window.clearTimeout(pendingTimer);
-			pendingGetState = getState;
+			pendingWrite = write;
 			pendingTimer = window.setTimeout(() => {
 				pendingTimer = void 0;
-				const state = pendingGetState;
-				pendingGetState = void 0;
-				if (state !== void 0) persistDurableState(state()).catch(() => {});
+				const run = pendingWrite;
+				pendingWrite = void 0;
+				if (run !== void 0) Promise.resolve().then(run).catch(() => {});
 			}, delayMs);
 		}
 		/** Drop any queued persist (plugin unload / page teardown). */
 		function cancelDurablePersist() {
 			if (pendingTimer !== void 0) window.clearTimeout(pendingTimer);
 			pendingTimer = void 0;
-			pendingGetState = void 0;
+			pendingWrite = void 0;
 		}
 		//#endregion
 		//#region \0dsh-css:/home/runner/work/dsh-catppuccin-theme/dsh-catppuccin-theme/src/client/glass/glass.module.css.mjs
@@ -2086,11 +2127,13 @@ window.__ModuleLoader__.load({
 			if (preference !== "light" && preference !== "dark") return false;
 			return preference === livePick;
 		}
-		/** Required services: slots + locale (settings rows) and theme (register + switch). */
+		/** Required services: slots + locale (settings rows), theme (register +
+		*  switch), and the settings scope (durable persistence). */
 		const inject = [
 			"slots",
 			"locale",
-			"theme"
+			"theme",
+			"settingsScope"
 		];
 		/**
 		* Register the Catppuccin dictionaries, the four flavour themes, and the
@@ -2121,11 +2164,16 @@ window.__ModuleLoader__.load({
 				};
 			}, "catppuccin: flavour themes");
 			const glass = new GlassLayer(ctx);
+			const scope = bindCatppuccinScope(ctx);
 			const buildLocalState = () => ({
 				version: 1,
 				flavor: readFlavor(),
 				glass: glass.getRemoteState()
 			});
+			const persistLocal = () => {
+				if (!isScopeUsable(scope.getSnapshot())) return;
+				persistStateToScope(scope, buildLocalState());
+			};
 			ctx.effect(() => {
 				let liveBuiltinPick = null;
 				const originalSetTheme = theme.setTheme;
@@ -2155,22 +2203,26 @@ window.__ModuleLoader__.load({
 				};
 				window.addEventListener("storage", onStorage);
 				const offGlass = glass.subscribe(() => {
-					scheduleDurablePersist(buildLocalState);
+					scheduleDurablePersist(persistLocal);
 				});
-				let cancelled = false;
-				readDurableStateRemote().then((result) => {
-					if (cancelled) return;
-					if (!result.available) return;
-					if (result.state === null) {
-						if (!isDefaultState(buildLocalState())) scheduleDurablePersist(buildLocalState);
+				const applyScopeSnapshot = () => {
+					const snapshot = scope.getSnapshot();
+					const state = durableStateFromSnapshot(snapshot);
+					if (state === null) return;
+					const local = buildLocalState();
+					if (snapshot.user === void 0) {
+						if (!isDefaultState(local)) scheduleDurablePersist(persistLocal);
 						return;
 					}
-					writeFlavor(result.state.flavor);
-					glass.applyRemote(result.state.glass);
+					if (settingsSectionsEqual(settingsSectionFromState(local), settingsSectionFromState(state))) return;
+					writeFlavor(state.flavor);
+					glass.applyRemote(state.glass);
 					applyDesired();
-				});
+				};
+				applyScopeSnapshot();
+				const offScope = scope.subscribe(applyScopeSnapshot);
 				return () => {
-					cancelled = true;
+					offScope();
 					offGlass();
 					disposer();
 					window.removeEventListener("storage", onStorage);
@@ -2193,14 +2245,14 @@ window.__ModuleLoader__.load({
 					if (choice === "off") {
 						writeFlavor("off");
 						theme.setTheme(readRestoredPreference());
-						scheduleDurablePersist(buildLocalState);
+						scheduleDurablePersist(persistLocal);
 						return;
 					}
 					const flavor = flavorInfo(choice);
 					if (!flavor) return;
 					writeFlavor(flavor.themeId);
 					theme.setTheme(flavor.themeId);
-					scheduleDurablePersist(buildLocalState);
+					scheduleDurablePersist(persistLocal);
 				}
 			});
 			ctx.slots.inject("settings.general.item", () => ctx.slots.register({