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

package/README.en.md

@@ -271,11 +271,13 @@ Then add `@nonamelego/dsh-catppuccin` to the profile's `package.json`
   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 `catppuccin-state.json` 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.
+  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

package/README.md

@@ -253,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({