@nonamelego/dsh-catppuccin 0.6.7 → 0.7.0

package/README.en.md

@@ -224,9 +224,14 @@ installing, launch `dsh --profile dsh-tui` and pick the theme with `/theme` —
 2. Open **Settings** and pick **Catppuccin** in the left nav (its own section, after the official ones).
 3. Under **Theme**, pick a flavour:
    **Latte** (light), **Frappé**, **Macchiato** or **Mocha** (dark).
-4. Choosing **Follow system** reverts to the official theme — it restores the preference
+4. Turn on **Follow system light/dark**: Latte on light, your chosen flavour (Mocha by default)
+   on dark, switching with the Windows light/dark setting — the native title bar and window
+   buttons follow too. The dark end is picked separately (Frappé / Macchiato / Mocha).
+5. Choosing **Turn off (official theme)** reverts to the official theme — it restores the preference
    you had before enabling Catppuccin (light / dark / follow system) instead of forcing a reset.
 
+> "Follow system" used to name step 5; since 0.7.0 the two are separate controls, as above.
+
 > **Second entrance**: open this plugin's own card on the **Plugins** page and the middle of
 > its detail page shows the **same settings** (Catppuccin theme / Glass / Check for updates /
 > Feedback & support) — both read and write one set of preferences, so either place works.

package/README.md

@@ -197,9 +197,14 @@ dsh plugin --profile dsh-tui add https://github.com/NoNameLeGo/dsh-catppuccin-th
 2. 打开 **设置**，在左侧导航里点 **Catppuccin**（官方各节之后的独立分区）。
 3. 在 **主题** 区域选择风味：
    **Latte**（浅色）、**Frappé**、**Macchiato** 或 **Mocha**（深色）。
-4. 选择 **跟随系统** 则回退到官方主题——会还原你启用 Catppuccin 之前
+4. 打开 **跟随系统深色/浅色**：浅色时用 **Latte**、深色时用你选的风味（默认 **Mocha**），
+   随 Windows 的深浅色设置自动切换——原生标题栏和窗口按钮也会一起变。
+   深色端可单独选 Frappé / Macchiato / Mocha。
+5. 选择 **关闭（官方主题）** 则回退到官方主题——会还原你启用 Catppuccin 之前
    的官方偏好（浅色 / 深色 / 跟随系统），而不是强制重置。
 
+> 「跟随系统」一词以前指第 5 步的「关闭」，0.7.0 起两个功能分开命名，见上。
+
 > **另一处入口**：在 **插件页**（Plugins）点开本插件自己的卡片，中间会出现**同一组设置**
 > （Catppuccin 主题 / 玻璃质感 / 检查更新 / 反馈与支持）——两处读写的是同一份偏好，改哪边都一样。
 > 该区域由宿主（≥ `0.2.0-rc.2` 的插件详情页）提供，更旧的版本上没有。
@@ -340,11 +345,14 @@ console.table({ backdropFilter: cs.backdropFilter, background: cs.backgroundColo
 | DSH | `>=0.1.7-rc.1`（设置页消费官方 `dsh-client-ui-primitives` 的 `SegmentedControl`，该导出自 `0.1.7-alpha.1` 起才有；旧的 `settingsScope` 通道代码保留，但 0.1.5 / 0.1.6 宿主不再声明支持） |
 | Node.js | `>=20` |
 | Profile | `web`（Web GUI 与两个桌面壳都启动 web 界面，共用本插件）；桌面端默认 profile 名为 `desktop`（已声明） |
-| 已验证的具体版本 | `0.2.1-rc.2`：官方桌面壳真机验收——插件正常启动、token 逐项生效、玻璃配方完整，**改设置真写回 `cordis.patch.yml`（修复前不写）**、重启后从文档采纳回来（[审计](docs/desktop-0.2.1-adaptation-audit.md)）；`0.2.0-rc.2`：官方桌面壳自带运行时的启动级 e2e（19/19）、真机桌面窗口像素与标题栏取色链路、`configForms` 落盘（[审计](docs/desktop-0.2.0-adaptation-audit.md)）；`0.1.7-rc.1`：真实 profile 上完成安装、启动、改设置落盘与重启恢复（[证据](docs/issue-15-settings-seam-0.1.7.md)）；`0.1.7-rc.2`：启动级 e2e 与玻璃层的真页采样（issue #16 / #17）；`0.1.5-rc.1`：按 CI 口径复跑的启动级 e2e（**历史记录**，已低于当前兼容下限） |
-
-`package.json` 的 `dsh.compatibility`（`dsh` / `dshReleases` / `dshOperations`）**只声明当前支持的三条**：
-`0.1.7-rc.1` / `0.2.0-rc.2` / `0.2.1-rc.2`（兼容下限 `>=0.1.7-rc.1`）；更早的 `0.1.5-rc.*`
-与 `0.1.7-alpha.*` 是**当时**的验证记录，不在声明内。
+| 已验证的具体版本 | `0.2.1-rc.5`：官方桌面壳真机验收——启动正常、token 逐项生效、玻璃配方完整（顶栏 / 输入卡 / dock / 菜单 / 设置壳逐面实测），`--dsw-*` 全表与前端构建产物**逐字节不变**（[审计](docs/issue-0.2.1-rc.5-adaptation-audit.md)）；`0.2.1-rc.3`：三个新 More 菜单自动继承玻璃、视图标签行与 `-95/107` 滚动补偿不冲突（[审计](docs/issue-0.2.1-rc.3-adaptation-audit.md)）；`0.2.1-rc.2`：官方桌面壳真机验收——插件正常启动、token 逐项生效、玻璃配方完整，**改设置真写回 `cordis.patch.yml`（修复前不写）**、重启后从文档采纳回来（[审计](docs/desktop-0.2.1-adaptation-audit.md)）；`0.2.0-rc.2`：官方桌面壳自带运行时的启动级 e2e（19/19）、真机桌面窗口像素与标题栏取色链路、`configForms` 落盘（[审计](docs/desktop-0.2.0-adaptation-audit.md)）；`0.1.7-rc.1`：真实 profile 上完成安装、启动、改设置落盘与重启恢复（[证据](docs/issue-15-settings-seam-0.1.7.md)）；`0.1.7-rc.2`：启动级 e2e 与玻璃层的真页采样（issue #16 / #17）；`0.1.5-rc.1`：按 CI 口径复跑的启动级 e2e（**历史记录**，已低于当前兼容下限） |
+
+`package.json` 的 `dsh.compatibility`（`dsh` / `dshReleases` / `dshOperations`）声明清单以文件为准，
+当前是 `0.1.7-rc.1` / `0.2.0-rc.2` / `0.2.1-rc.2` / `0.2.1-rc.3` / `0.2.1-rc.5`（兼容下限 `>=0.1.7-rc.1`）；
+更早的 `0.1.5-rc.*` 与 `0.1.7-alpha.*` 是**当时**的验证记录，不在声明内。
+⚠️ 商铺按「上游最新三版」窗口判定（`latest` / `next` / `alpha` 里版本号最高的那个往下数三版），
+**窗口内至少命中一条**才不会显示「兼容未声明」——所以上游每发一版都要跟，见
+`docs/issue-0.2.1-rc.5-adaptation-audit.md` §6.1。
 
 色彩覆盖以 `dsh-v0.2.0-rc.2` 的 `design-platform.css` 为基线：每方案 190 个 `--dsw-*` token（static 77 /
 alias 101 / specific 11 / 非三族 1）全覆盖，含 0.2.0 新增的 17 个 alias。

package/lib/client.js

@@ -52,7 +52,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region \0dsh-css:/home/runner/work/dsh-catppuccin-theme/dsh-catppuccin-theme/src/client/CatppuccinRow.module.css.mjs
-		const css$2 = ".AfSEaq_cubes{flex-wrap:wrap;gap:8px;display:flex}.AfSEaq_cube{box-sizing:border-box;border:.5px solid var(--dsw-alias-border-l4);border-radius:var(--dsw-radius-xl);color:var(--dsw-alias-label-primary);font:inherit;text-align:left;cursor:pointer;background:0 0;flex-direction:column;flex:118px;justify-content:center;align-items:flex-start;gap:2px;padding:12px 14px;font-size:13px;line-height:20px;display:flex}.AfSEaq_cube:hover:not(.AfSEaq_selected){background:var(--dsw-alias-interactive-bg-hover)}.AfSEaq_cube:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:2px}.AfSEaq_selected{background:var(--dsw-alias-bg-module-platform);border-color:var(--dsw-static-neutral-bluish-400)}.AfSEaq_cubeHead{align-items:center;gap:6px;display:inline-flex}.AfSEaq_swatch{border-radius:3px;flex:none;width:12px;height:12px}.AfSEaq_subtitle{color:var(--dsw-alias-label-tertiary);font-size:10px;line-height:14px}.AfSEaq_shikiRow{flex-wrap:wrap;align-items:center;gap:10px;display:flex}.AfSEaq_shikiLabel{color:var(--dsw-alias-label-secondary);font-size:12px;line-height:18px}.AfSEaq_codePreview{flex-direction:column;gap:6px;margin-top:2px;display:flex}.AfSEaq_codeSample{border:.5px solid var(--dsw-alias-border-l2);border-radius:var(--dsw-radius-sm);background:var(--dsw-alias-markdown-code-block,var(--dsw-alias-bg-layer-2));color:var(--shiki-foreground,var(--dsw-alias-label-primary));white-space:pre;margin:0;padding:8px 10px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;line-height:18px;overflow:auto}.AfSEaq_tokKeyword{color:var(--shiki-token-keyword,var(--dsw-static-blue-500))}.AfSEaq_tokFunction{color:var(--shiki-token-function,var(--dsw-static-amber-500))}.AfSEaq_tokParameter{color:var(--shiki-token-parameter,var(--dsw-alias-label-primary))}.AfSEaq_tokString{color:var(--shiki-token-string,var(--dsw-static-green-500))}.AfSEaq_tokPunct{color:var(--shiki-token-punctuation,var(--dsw-alias-label-secondary))}.AfSEaq_tokComment{color:var(--shiki-token-comment,var(--dsw-alias-label-tertiary))}.AfSEaq_overrides{flex-direction:column;gap:6px;display:flex}.AfSEaq_overrideRow{flex-wrap:wrap;align-items:center;gap:6px;display:flex}.AfSEaq_overrideInput{border:.5px solid var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-sm);height:28px;color:var(--dsw-alias-label-primary);font:inherit;background:0 0;flex:200px;padding:0 8px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px}.AfSEaq_overrideInput:focus-visible{border-color:var(--dsw-alias-state-business-primary);box-shadow:0 0 0 2px color-mix(in srgb, var(--dsw-alias-state-business-primary) 35%, transparent);outline:none}.AfSEaq_overrideValue{flex:140px}.AfSEaq_hint{color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:18px}.AfSEaq_selfStart{align-self:flex-start}";
+		const css$2 = ".AfSEaq_cubes{flex-wrap:wrap;gap:8px;display:flex}.AfSEaq_cube{box-sizing:border-box;border:.5px solid var(--dsw-alias-border-l4);border-radius:var(--dsw-radius-xl);color:var(--dsw-alias-label-primary);font:inherit;text-align:left;cursor:pointer;background:0 0;flex-direction:column;flex:118px;justify-content:center;align-items:flex-start;gap:2px;padding:12px 14px;font-size:13px;line-height:20px;display:flex}.AfSEaq_cube:hover:not(.AfSEaq_selected){background:var(--dsw-alias-interactive-bg-hover)}.AfSEaq_cube:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:2px}.AfSEaq_selected{background:var(--dsw-alias-bg-module-platform);border-color:var(--dsw-static-neutral-bluish-400)}.AfSEaq_cubeHead{align-items:center;gap:6px;display:inline-flex}.AfSEaq_swatch{border-radius:3px;flex:none;width:12px;height:12px}.AfSEaq_subtitle{color:var(--dsw-alias-label-tertiary);font-size:10px;line-height:14px}.AfSEaq_shikiRow{flex-wrap:wrap;align-items:center;gap:10px;display:flex}.AfSEaq_followRow{flex-direction:column;gap:6px;display:flex}.AfSEaq_followHead{align-items:center;gap:10px;display:flex}.AfSEaq_followLabel{color:var(--dsw-alias-label-primary);font-size:13px;line-height:20px}.AfSEaq_shikiLabel{color:var(--dsw-alias-label-secondary);font-size:12px;line-height:18px}.AfSEaq_codePreview{flex-direction:column;gap:6px;margin-top:2px;display:flex}.AfSEaq_codeSample{border:.5px solid var(--dsw-alias-border-l2);border-radius:var(--dsw-radius-sm);background:var(--dsw-alias-markdown-code-block,var(--dsw-alias-bg-layer-2));color:var(--shiki-foreground,var(--dsw-alias-label-primary));white-space:pre;margin:0;padding:8px 10px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;line-height:18px;overflow:auto}.AfSEaq_tokKeyword{color:var(--shiki-token-keyword,var(--dsw-static-blue-500))}.AfSEaq_tokFunction{color:var(--shiki-token-function,var(--dsw-static-amber-500))}.AfSEaq_tokParameter{color:var(--shiki-token-parameter,var(--dsw-alias-label-primary))}.AfSEaq_tokString{color:var(--shiki-token-string,var(--dsw-static-green-500))}.AfSEaq_tokPunct{color:var(--shiki-token-punctuation,var(--dsw-alias-label-secondary))}.AfSEaq_tokComment{color:var(--shiki-token-comment,var(--dsw-alias-label-tertiary))}.AfSEaq_overrides{flex-direction:column;gap:6px;display:flex}.AfSEaq_overrideRow{flex-wrap:wrap;align-items:center;gap:6px;display:flex}.AfSEaq_overrideInput{border:.5px solid var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-sm);height:28px;color:var(--dsw-alias-label-primary);font:inherit;background:0 0;flex:200px;padding:0 8px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px}.AfSEaq_overrideInput:focus-visible{border-color:var(--dsw-alias-state-business-primary);box-shadow:0 0 0 2px color-mix(in srgb, var(--dsw-alias-state-business-primary) 35%, transparent);outline:none}.AfSEaq_overrideValue{flex:140px}.AfSEaq_hint{color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:18px}.AfSEaq_selfStart{align-self:flex-start}";
 		const tagId$2 = "@nonamelego/dsh-catppuccin/CatppuccinRow.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId$2) + "]") === null) {
 			const tag = document.createElement("style");
@@ -67,6 +67,9 @@ window.__ModuleLoader__.load({
 			"cube": "AfSEaq_cube",
 			"cubeHead": "AfSEaq_cubeHead",
 			"cubes": "AfSEaq_cubes",
+			"followHead": "AfSEaq_followHead",
+			"followLabel": "AfSEaq_followLabel",
+			"followRow": "AfSEaq_followRow",
 			"hint": "AfSEaq_hint",
 			"overrideInput": "AfSEaq_overrideInput",
 			"overrideRow": "AfSEaq_overrideRow",
@@ -89,9 +92,11 @@ window.__ModuleLoader__.load({
 		//#region src/client/CatppuccinRow.tsx
 		/**
 		* Catppuccin flavour row — the first row of the plugin's own settings page
-		* (issue #27) and of the plugin detail card. It lists the four flavour themes
-		* plus a "follow system" (off) choice. Selecting a flavour calls the injected
-		* `select`, which switches the official ThemeRuntime and persists the choice.
+		* (issue #27) and of the plugin detail card. It lists the four flavour themes,
+		* a "follow the OS light/dark scheme" switch (issue #36 — NOT the same thing as
+		* the "off" cube, which hands the UI back to the official theme) and the
+		* "off" cube itself. Selecting a flavour calls the injected `select`, which
+		* switches the official ThemeRuntime and persists the choice.
 		* The row subscribes to `theme/change` so the highlighted flavour tracks the
 		* live preference.
 		*
@@ -126,8 +131,10 @@ window.__ModuleLoader__.load({
 		* @param props - composed slot props.
 		* @returns the row element tree.
 		*/
-		function CatppuccinRow({ t, themes, current, subscribe, select, overrides, setOverrides, shikiStyle, setShikiStyle, subscribePrefs }) {
+		function CatppuccinRow({ t, themes, current, subscribe, select, followAvailable, followSystem, setFollowSystem, followDark, setFollowDark, overrides, setOverrides, shikiStyle, setShikiStyle, subscribePrefs }) {
 			const choice = (0, react.useSyncExternalStore)(subscribe, current);
+			const following = (0, react.useSyncExternalStore)(subscribePrefs, followSystem);
+			const darkEnd = (0, react.useSyncExternalStore)(subscribePrefs, followDark);
 			const overrideMap = (0, react.useSyncExternalStore)(subscribePrefs, overrides);
 			const style = (0, react.useSyncExternalStore)(subscribePrefs, shikiStyle);
 			const [overridesOpen, setOverridesOpen] = (0, react.useState)(false);
@@ -250,6 +257,47 @@ window.__ModuleLoader__.load({
 							})
 						}, "off")]
 					}),
+					followAvailable && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: CatppuccinRow_module_css_default.followRow,
+						"data-catppuccin-follow": "",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								className: CatppuccinRow_module_css_default.followHead,
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Switch, {
+									checked: following,
+									onChange: (next) => {
+										setFollowSystem(next);
+									},
+									label: t("row.follow")
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: CatppuccinRow_module_css_default.followLabel,
+									children: t("row.follow")
+								})]
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: CatppuccinRow_module_css_default.hint,
+								children: t("row.followHint")
+							}),
+							following && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								className: CatppuccinRow_module_css_default.shikiRow,
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: CatppuccinRow_module_css_default.shikiLabel,
+									children: t("row.followDark")
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.SegmentedControl, {
+									id: "catppuccin-follow-dark",
+									label: t("row.followDark"),
+									value: darkEnd,
+									options: themes.filter((flavor) => flavor.id !== "catppuccin-latte").map((flavor) => ({
+										value: flavor.id,
+										label: flavor.label
+									})),
+									onChange: (next) => {
+										setFollowDark(next);
+									}
+								})]
+							})
+						]
+					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						className: CatppuccinRow_module_css_default.shikiRow,
 						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
@@ -577,6 +625,21 @@ window.__ModuleLoader__.load({
 			"catppuccin-macchiato",
 			"catppuccin-mocha"
 		];
+		/**
+		* The LIGHT end of "follow the OS" (issue #36). Latte is the only light
+		* flavour Catppuccin ships, so the light half is a constant instead of a
+		* setting — a picker here would offer exactly one real option.
+		*/
+		const FOLLOW_LIGHT_FLAVOR = "catppuccin-latte";
+		/** The flavours the follow mode may use for its DARK end. Only the three dark
+		*  flavours: Latte here would paint a light palette into the dark half. */
+		const FOLLOW_DARK_FLAVORS = [
+			"catppuccin-frappe",
+			"catppuccin-macchiato",
+			"catppuccin-mocha"
+		];
+		/** Shipped follow-mode dark end: Mocha, Catppuccin's most common dark pick. */
+		const DEFAULT_FOLLOW_DARK = "catppuccin-mocha";
 		/** Shipped glass defaults — the single source of truth; the client glass layer
 		*  (`src/client/glass/glass-layer.ts`) derives its knob defaults from here. */
 		const DEFAULT_GLASS = {
@@ -599,6 +662,8 @@ window.__ModuleLoader__.load({
 			return {
 				version: 1,
 				flavor: "off",
+				followSystem: false,
+				followDark: DEFAULT_FOLLOW_DARK,
 				glass: { ...DEFAULT_GLASS },
 				autoCheck: true,
 				updateChannel: DEFAULT_UPDATE_CHANNEL,
@@ -650,6 +715,10 @@ window.__ModuleLoader__.load({
 			const flavor = raw.flavor;
 			if (typeof flavor === "string" && CATPPUCCIN_THEME_IDS.includes(flavor)) state.flavor = flavor;
 			else if (flavor === "off") state.flavor = "off";
+			const followDark = raw.followDark;
+			state.followDark = typeof followDark === "string" && FOLLOW_DARK_FLAVORS.includes(followDark) ? followDark : DEFAULT_FOLLOW_DARK;
+			state.followSystem = raw.followSystem === true;
+			if (state.flavor === "off") state.followSystem = false;
 			const glass = typeof raw.glass === "object" && raw.glass !== null ? raw.glass : {};
 			state.glass.enabled = glass.enabled === true;
 			state.glass.mode = glass.mode === "compat" ? "compat" : "mica";
@@ -671,12 +740,14 @@ window.__ModuleLoader__.load({
 		*  "no durable state yet" apart from "an explicit default choice". */
 		function isDefaultState(state) {
 			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 && state.glass.gap === expected.glass.gap && state.glass.glowStrength === expected.glass.glowStrength && state.glass.glowSize === expected.glass.glowSize && state.glass.glow === expected.glass.glow && state.autoCheck === expected.autoCheck && state.updateChannel === expected.updateChannel && Object.keys(state.overrides).length === 0 && state.shikiStyle === expected.shikiStyle;
+			return state.flavor === expected.flavor && state.followSystem === expected.followSystem && state.followDark === expected.followDark && 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 && state.glass.gap === expected.glass.gap && state.glass.glowStrength === expected.glass.glowStrength && state.glass.glowSize === expected.glass.glowSize && state.glass.glow === expected.glass.glow && state.autoCheck === expected.autoCheck && state.updateChannel === expected.updateChannel && Object.keys(state.overrides).length === 0 && state.shikiStyle === expected.shikiStyle;
 		}
 		/** Drop the synthetic `version` field: full state → settings-document section. */
 		function settingsSectionFromState(state) {
 			return {
 				flavor: state.flavor,
+				followSystem: state.followSystem,
+				followDark: state.followDark,
 				glass: { ...state.glass },
 				autoCheck: state.autoCheck,
 				updateChannel: state.updateChannel,
@@ -699,7 +770,7 @@ window.__ModuleLoader__.load({
 		/** 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 && a.glass.gap === b.glass.gap && a.glass.glowStrength === b.glass.glowStrength && a.glass.glowSize === b.glass.glowSize && a.glass.glow === b.glass.glow && a.autoCheck === b.autoCheck && a.updateChannel === b.updateChannel && a.shikiStyle === b.shikiStyle && sameOverrides(a.overrides, b.overrides);
+			return a.flavor === b.flavor && a.followSystem === b.followSystem && a.followDark === b.followDark && 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 && a.glass.gap === b.glass.gap && a.glass.glowStrength === b.glass.glowStrength && a.glass.glowSize === b.glass.glowSize && a.glass.glow === b.glass.glow && a.autoCheck === b.autoCheck && a.updateChannel === b.updateChannel && a.shikiStyle === b.shikiStyle && sameOverrides(a.overrides, b.overrides);
 		}
 		/**
 		* Replay the local changes a window made BEFORE the durable channel became
@@ -754,6 +825,8 @@ window.__ModuleLoader__.load({
 				}
 			};
 			carry("flavor");
+			carry("followSystem");
+			carry("followDark");
 			carryGlass("enabled");
 			carryGlass("mode");
 			carryGlass("blur");
@@ -2211,7 +2284,10 @@ window.__ModuleLoader__.load({
 			"page.title": "Catppuccin 外观设置",
 			"row.title": "Catppuccin 主题",
 			"row.description": "Latte / Frappé / Macchiato / Mocha 四款配色，一键切换。",
-			"row.off": "跟随系统",
+			"row.off": "关闭（官方主题）",
+			"row.follow": "跟随系统深色/浅色",
+			"row.followHint": "浅色时用 Latte，深色时用下方选中的风味；跟随 Windows 的深浅色设置切换，原生标题栏与窗口按钮一起变。深色端默认 Mocha。",
+			"row.followDark": "深色端风味",
 			"row.helpLabel": "关于 Catppuccin 主题",
 			"row.help": "Catppuccin 社区出品的四款配色：Latte（浅色）、Frappé / Macchiato / Mocha（深色）。选择后立即生效并持久保存。",
 			"row.shikiStyle": "代码高亮风格",
@@ -2306,7 +2382,10 @@ window.__ModuleLoader__.load({
 			"page.title": "Catppuccin appearance",
 			"row.title": "Catppuccin theme",
 			"row.description": "Latte / Frappé / Macchiato / Mocha, one click away.",
-			"row.off": "Follow system",
+			"row.off": "Turn off (official theme)",
+			"row.follow": "Follow system light/dark",
+			"row.followHint": "Latte on light, the flavour picked below on dark; switches with the Windows light/dark setting, native title bar and window buttons included. The dark end defaults to Mocha.",
+			"row.followDark": "Dark-end flavour",
 			"row.helpLabel": "About the Catppuccin theme",
 			"row.help": "Four palettes from the Catppuccin community: Latte (light), Frappé / Macchiato / Mocha (dark). Applies instantly and persists.",
 			"row.shikiStyle": "Code highlight style",
@@ -2401,7 +2480,10 @@ window.__ModuleLoader__.load({
 			"page.title": "Catppuccin 外観設定",
 			"row.title": "Catppuccin テーマ",
 			"row.description": "Latte / Frappé / Macchiato / Mocha の4色をワンクリックで切替。",
-			"row.off": "システムに従う",
+			"row.off": "オフ（標準テーマ）",
+			"row.follow": "システムのライト/ダークに追従",
+			"row.followHint": "ライトは Latte、ダークは下で選んだフレーバー。Windows のライト/ダーク設定に合わせて切り替わり、ネイティブのタイトルバーとウィンドウボタンも追従します。ダーク側の既定は Mocha。",
+			"row.followDark": "ダーク側のフレーバー",
 			"row.helpLabel": "Catppuccin テーマについて",
 			"row.help": "Catppuccin コミュニティの4色: Latte（ライト）、Frappé / Macchiato / Mocha（ダーク）。選択直後に反映され、保存されます。",
 			"row.shikiStyle": "コードハイライト",
@@ -2496,7 +2578,10 @@ window.__ModuleLoader__.load({
 			"page.title": "Catppuccin 모양 설정",
 			"row.title": "Catppuccin 테마",
 			"row.description": "Latte / Frappé / Macchiato / Mocha 네 가지 배색, 한 번의 클릭으로 전환.",
-			"row.off": "시스템 팔로우",
+			"row.off": "끄기(기본 테마)",
+			"row.follow": "시스템 밝기/어둡기 따르기",
+			"row.followHint": "밝을 때는 Latte, 어두울 때는 아래에서 고른 플레이버. Windows 밝기 설정에 따라 전환되며 기본 제목 표시줄과 창 버튼도 함께 바뀝니다. 어두운 쪽 기본값은 Mocha.",
+			"row.followDark": "어두운 쪽 플레이버",
 			"row.helpLabel": "Catppuccin 테마 정보",
 			"row.help": "Catppuccin 커뮤니티의 네 가지 배색: Latte(밝음), Frappé / Macchiato / Mocha(어두움). 선택 즉시 적용되고 저장됩니다.",
 			"row.shikiStyle": "코드 하이라이트",
@@ -2591,7 +2676,10 @@ window.__ModuleLoader__.load({
 			"page.title": "Aspecto de Catppuccin",
 			"row.title": "Tema Catppuccin",
 			"row.description": "Latte / Frappé / Macchiato / Mocha, a un clic.",
-			"row.off": "Seguir al sistema",
+			"row.off": "Desactivar (tema oficial)",
+			"row.follow": "Seguir el modo claro/oscuro del sistema",
+			"row.followHint": "Latte en claro y el sabor elegido abajo en oscuro; cambia con el ajuste de Windows, incluidos la barra de título nativa y los botones de la ventana. El extremo oscuro es Mocha por defecto.",
+			"row.followDark": "Sabor del extremo oscuro",
 			"row.helpLabel": "Acerca del tema Catppuccin",
 			"row.help": "Cuatro paletas de la comunidad Catppuccin: Latte (claro), Frappé / Macchiato / Mocha (oscuro). Se aplican al instante y se guardan.",
 			"row.shikiStyle": "Estilo de resaltado",
@@ -2686,7 +2774,10 @@ window.__ModuleLoader__.load({
 			"page.title": "Apparence Catppuccin",
 			"row.title": "Thème Catppuccin",
 			"row.description": "Latte / Frappé / Macchiato / Mocha, en un clic.",
-			"row.off": "Suivre le système",
+			"row.off": "Désactiver (thème officiel)",
+			"row.follow": "Suivre le clair/sombre du système",
+			"row.followHint": "Latte en clair, la saveur choisie ci-dessous en sombre ; bascule avec le réglage Windows, barre de titre native et boutons de fenêtre compris. L’extrémité sombre est Mocha par défaut.",
+			"row.followDark": "Saveur de l’extrémité sombre",
 			"row.helpLabel": "À propos du thème Catppuccin",
 			"row.help": "Quatre palettes de la communauté Catppuccin : Latte (clair), Frappé / Macchiato / Mocha (sombre). Application immédiate et persistante.",
 			"row.shikiStyle": "Style de coloration",
@@ -2781,7 +2872,10 @@ window.__ModuleLoader__.load({
 			"page.title": "Catppuccin-Darstellung",
 			"row.title": "Catppuccin-Design",
 			"row.description": "Latte / Frappé / Macchiato / Mocha, mit einem Klick.",
-			"row.off": "System folgen",
+			"row.off": "Aus (offizielles Theme)",
+			"row.follow": "System-Hell/Dunkel folgen",
+			"row.followHint": "Latte bei Hell, die unten gewählte Variante bei Dunkel; wechselt mit der Windows-Einstellung, inklusive nativer Titelleiste und Fensterknöpfe. Das dunkle Ende ist standardmäßig Mocha.",
+			"row.followDark": "Variante fürs dunkle Ende",
 			"row.helpLabel": "Über das Catppuccin-Design",
 			"row.help": "Vier Paletten der Catppuccin-Community: Latte (hell), Frappé / Macchiato / Mocha (dunkel). Wirkt sofort und wird gespeichert.",
 			"row.shikiStyle": "Code-Hervorhebung",
@@ -4002,6 +4096,16 @@ window.__ModuleLoader__.load({
 					path: ["flavor"],
 					value: section.flavor
 				},
+				{
+					op: "set",
+					path: ["followSystem"],
+					value: section.followSystem
+				},
+				{
+					op: "set",
+					path: ["followDark"],
+					value: section.followDark
+				},
 				{
 					op: "set",
 					path: ["glass", "enabled"],
@@ -4193,6 +4297,10 @@ window.__ModuleLoader__.load({
 		const OVERRIDES_KEY = "dsh.catppuccin.overrides";
 		/** localStorage key carrying the shiki style preference (item M). */
 		const SHIKI_STYLE_KEY = "dsh.catppuccin.shikiStyle";
+		/** localStorage key carrying the follow-the-OS flag (issue #36). */
+		const FOLLOW_SYSTEM_KEY = "dsh.catppuccin.followSystem";
+		/** localStorage key carrying the follow-mode dark half (issue #36). */
+		const FOLLOW_DARK_KEY = "dsh.catppuccin.followDark";
 		/** Accepted flavour values — the four registered theme ids plus `off`. These
 		*  MUST stay in sync with the registered themes (guarded by
 		*  tests/palettes.spec.ts) because the persisted value is the theme id. */
@@ -4337,6 +4445,35 @@ window.__ModuleLoader__.load({
 				localStorage.setItem(SHIKI_STYLE_KEY, value);
 			} catch {}
 		}
+		/** Read the persisted follow-the-OS flag (issue #36; absent means off). */
+		function readFollowSystem() {
+			try {
+				return localStorage.getItem(FOLLOW_SYSTEM_KEY) === "true";
+			} catch {
+				return false;
+			}
+		}
+		/** Persist the follow-the-OS flag. */
+		function writeFollowSystem(value) {
+			try {
+				localStorage.setItem(FOLLOW_SYSTEM_KEY, String(value));
+			} catch {}
+		}
+		/** Read the follow-mode dark half (only the three dark flavours are legal). */
+		function readFollowDark() {
+			try {
+				const raw = localStorage.getItem(FOLLOW_DARK_KEY);
+				return raw !== null && FOLLOW_DARK_FLAVORS.includes(raw) ? raw : DEFAULT_FOLLOW_DARK;
+			} catch {
+				return DEFAULT_FOLLOW_DARK;
+			}
+		}
+		/** Persist the follow-mode dark half. */
+		function writeFollowDark(value) {
+			try {
+				localStorage.setItem(FOLLOW_DARK_KEY, value);
+			} catch {}
+		}
 		/**
 		* Does this host ship the menu blur that makes a translucent menu surface work?
 		*
@@ -4490,6 +4627,8 @@ window.__ModuleLoader__.load({
 			const buildLocalState = () => ({
 				version: 1,
 				flavor: readFlavor(),
+				followSystem: readFollowSystem() && readFlavor() !== "off",
+				followDark: readFollowDark(),
 				glass: glass.getRemoteState(),
 				autoCheck: readAutoCheck(),
 				updateChannel: readUpdateChannel(),
@@ -4506,7 +4645,99 @@ window.__ModuleLoader__.load({
 				conflictCount += 1;
 				for (const listener of conflictListeners) listener();
 			};
+			const FOLLOW_LAYER_SOURCE = PACKAGE_NAME;
+			/** Disposer of the currently stacked follow layer (`undefined` = no layer). */
+			let followLayerDispose;
+			/** Content signature of the stacked layer, so a no-op refresh does not
+			*  republish (every `overrideTokens` call emits `theme/change`). */
+			let followLayerSignature;
+			/** Theme-id → shiki/flavour key ("catppuccin-latte" → "latte"). */
+			const flavorKey = (flavor) => flavor.themeId.replace("catppuccin-", "");
+			/** Whether this host serves `overrideTokens` at all. Hosts before that API
+			*  cannot follow the OS; the row hides the control instead of offering a
+			*  switch that would do nothing. */
+			const followSupported = () => typeof theme.overrideTokens === "function";
+			/** Follow mode is wanted AND possible. `off` always wins: turning the plugin
+			*  off must not leave a layer painting Catppuccin tokens. */
+			const followWanted = () => followSupported() && readFollowSystem() && readFlavor() !== "off";
+			/**
+			* The two halves of the follow layer.
+			*
+			* Precedence per token mirrors `registerThemeFor`: flavour tokens < shiki <
+			* host-shape menu patch < user overrides (later wins). A user override is
+			* scheme-agnostic by contract, so the SAME value goes into both halves.
+			* A token present in only one flavour falls back to the other half's value so
+			* every entry stays a well-formed `{ light, dark }` pair (`overrideTokens`
+			* throws on a bare string).
+			* @returns the layer, or null when a flavour table is missing.
+			*/
+			const followLayerTokens = () => {
+				const light = flavorInfo(FOLLOW_LIGHT_FLAVOR);
+				const dark = flavorInfo(readFollowDark());
+				if (light === void 0 || dark === void 0) return null;
+				const shiki = readShikiStyle();
+				const lightShiki = SHIKI_TOKENS[flavorKey(light)][shiki];
+				const darkShiki = SHIKI_TOKENS[flavorKey(dark)][shiki];
+				const menu = menuSurfaceFor(hostHasMenuBlur());
+				const overrides = readOverrides();
+				const names = /* @__PURE__ */ new Set([
+					...Object.keys(light.tokens),
+					...Object.keys(dark.tokens),
+					...Object.keys(lightShiki),
+					...Object.keys(darkShiki),
+					...Object.keys(menu),
+					...Object.keys(overrides)
+				]);
+				const pairs = {};
+				for (const name of names) {
+					const lightValue = overrides[name] ?? menu[name] ?? lightShiki[name] ?? light.tokens[name];
+					const darkValue = overrides[name] ?? menu[name] ?? darkShiki[name] ?? dark.tokens[name];
+					if (lightValue === void 0 && darkValue === void 0) continue;
+					pairs[name] = {
+						light: lightValue ?? darkValue,
+						dark: darkValue ?? lightValue
+					};
+				}
+				return pairs;
+			};
+			/** Remove the follow layer (idempotent). */
+			const disposeFollowLayer = () => {
+				if (followLayerDispose === void 0) return;
+				followLayerDispose();
+				followLayerDispose = void 0;
+				followLayerSignature = void 0;
+			};
+			/**
+			* Stack (or refresh, or retire) the follow layer.
+			*
+			* MUST be called outside a `theme/change` dispatch: `overrideTokens`
+			* publishes, and a synchronous publish from inside a dispatch lets the
+			* presenter apply the OUTER (stale) snapshot last — the issue #10 trap, same
+			* reason `scheduleRestore` defers.
+			*/
+			const syncFollowLayer = () => {
+				if (!followWanted()) {
+					disposeFollowLayer();
+					return;
+				}
+				const tokens = followLayerTokens();
+				if (tokens === null) {
+					disposeFollowLayer();
+					return;
+				}
+				const signature = JSON.stringify(tokens);
+				if (followLayerDispose !== void 0 && signature === followLayerSignature) return;
+				const dispose = theme.overrideTokens(FOLLOW_LAYER_SOURCE, tokens);
+				followLayerDispose?.();
+				followLayerDispose = dispose;
+				followLayerSignature = signature;
+			};
 			const reapplyThemePrefs = () => {
+				if (followWanted()) {
+					syncFollowLayer();
+					return;
+				}
+				disposeFollowLayer();
 				const active = theme.getTheme().preference;
 				const flavor = flavorInfo(active);
 				if (flavor === void 0) return;
@@ -4591,6 +4822,28 @@ window.__ModuleLoader__.load({
 				applyRestoredPreference = (id) => {
 					commitTheme(id, false);
 				};
+				let followSyncPending = false;
+				const scheduleFollowSync = () => {
+					if (followSyncPending) return;
+					followSyncPending = true;
+					queueMicrotask(() => {
+						followSyncPending = false;
+						if (!followWanted()) {
+							disposeFollowLayer();
+							return;
+						}
+						syncFollowLayer();
+						const preference = theme.getTheme().preference;
+						if (preference === "system") {
+							clearBootPalette();
+							return;
+						}
+						if (builtinPickWins(preference, liveBuiltinPick)) return;
+						try {
+							commitTheme("system", false);
+						} catch {}
+					});
+				};
 				let restorePending = false;
 				let pendingDesired;
 				const scheduleRestore = (desired) => {
@@ -4614,8 +4867,14 @@ window.__ModuleLoader__.load({
 					});
 				};
 				const applyDesired = () => {
-					rememberBuiltinPreference(theme.getTheme().preference);
+					const follow = followWanted();
+					if (!follow) rememberBuiltinPreference(theme.getTheme().preference);
 					const desired = readFlavor();
+					if (follow) {
+						scheduleFollowSync();
+						return;
+					}
+					if (followLayerDispose !== void 0) scheduleFollowSync();
 					if (desired === "off") {
 						const preference = theme.getTheme().preference;
 						if (readExplicitFlavorOff()) {
@@ -4635,7 +4894,17 @@ window.__ModuleLoader__.load({
 				applyDesired();
 				const disposer = ctx.on("theme/change", applyDesired);
 				const onStorage = (event) => {
+					if (event.key === "dsh.catppuccin.followSystem" || event.key === "dsh.catppuccin.followDark") {
+						emitPrefs();
+						applyDesired();
+						return;
+					}
 					if (event.key !== "dsh.catppuccin.flavor") return;
+					if (followWanted()) {
+						emitPrefs();
+						applyDesired();
+						return;
+					}
 					const next = readFlavor();
 					if (next !== "off") {
 						ensureThemeRegistered(next);
@@ -4765,11 +5034,48 @@ window.__ModuleLoader__.load({
 					accent: flavor.accent
 				})),
 				current: () => {
+					if (readFollowSystem() && readFlavor() !== "off") return readFlavor();
 					const pref = theme.getTheme().preference;
 					return flavorFromThemeId(pref);
 				},
 				subscribe: (listener) => ctx.on("theme/change", listener),
+				followAvailable: followSupported(),
+				followSystem: () => readFollowSystem(),
+				setFollowSystem: (enabled) => {
+					if (!followSupported()) return;
+					if (enabled) {
+						if (readFlavor() === "off") writeFlavor(readFollowDark());
+						writeFollowSystem(true);
+						syncFollowLayer();
+						try {
+							if (applyRestoredPreference !== void 0) applyRestoredPreference("system");
+							else theme.setTheme("system");
+						} catch {}
+					} else {
+						writeFollowSystem(false);
+						disposeFollowLayer();
+						const target = readFlavor();
+						if (target !== "off") try {
+							if (applyRestoredPreference !== void 0) applyRestoredPreference(target);
+							else theme.setTheme(target);
+						} catch {}
+					}
+					emitPrefs();
+					queuePersist();
+				},
+				followDark: () => readFollowDark(),
+				setFollowDark: (dark) => {
+					if (!FOLLOW_DARK_FLAVORS.includes(dark)) return;
+					writeFollowDark(dark);
+					if (followWanted()) syncFollowLayer();
+					emitPrefs();
+					queuePersist();
+				},
 				select: (choice) => {
+					if (readFollowSystem()) {
+						writeFollowSystem(false);
+						disposeFollowLayer();
+					}
 					if (choice === "off") {
 						writeFlavor("off");
 						try {
@@ -4935,6 +5241,8 @@ window.__ModuleLoader__.load({
 		exports.AUTO_CHECK_KEY = AUTO_CHECK_KEY;
 		exports.CATPPUCCIN_FLAVOR_VALUES = CATPPUCCIN_FLAVOR_VALUES;
 		exports.FLAVOR_STORAGE_KEY = FLAVOR_STORAGE_KEY;
+		exports.FOLLOW_DARK_KEY = FOLLOW_DARK_KEY;
+		exports.FOLLOW_SYSTEM_KEY = FOLLOW_SYSTEM_KEY;
 		exports.NS = NS;
 		exports.OVERRIDES_KEY = OVERRIDES_KEY;
 		exports.RESTORE_STORAGE_KEY = RESTORE_STORAGE_KEY;
@@ -4951,6 +5259,8 @@ window.__ModuleLoader__.load({
 		exports.readAutoCheck = readAutoCheck;
 		exports.readExplicitFlavorOff = readExplicitFlavorOff;
 		exports.readFlavor = readFlavor;
+		exports.readFollowDark = readFollowDark;
+		exports.readFollowSystem = readFollowSystem;
 		exports.readOverrides = readOverrides;
 		exports.readRestoredPreference = readRestoredPreference;
 		exports.readShikiStyle = readShikiStyle;
@@ -4958,6 +5268,8 @@ window.__ModuleLoader__.load({
 		exports.rememberBuiltinPreference = rememberBuiltinPreference;
 		exports.writeAutoCheck = writeAutoCheck;
 		exports.writeFlavor = writeFlavor;
+		exports.writeFollowDark = writeFollowDark;
+		exports.writeFollowSystem = writeFollowSystem;
 		exports.writeOverrides = writeOverrides;
 		exports.writeShikiStyle = writeShikiStyle;
 		exports.writeUpdateChannel = writeUpdateChannel;