dsh-tui-theme 0.5.0 → 0.6.0

package/README.md

@@ -1,13 +1,14 @@
 # dsh-tui-theme 🌸
 
-[dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI) 的樱花粉主题插件。一个包带来四种个性化，全部走官方接缝：
+[dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI) 的樱花粉主题插件。一个包带来五种个性化，全部走官方接缝：
 
 | 个性化 | 接缝 | 说明 |
 | --- | --- | --- |
-| **三套粉色主题** | 主题（静态资产） | `pink-night` 夜樱 / `pink-day` 昼樱 / `pink-ansi` 樱·ANSI，启动时自动装进 `~/.dsh-tui/themes/` |
+| **三套粉色主题** | 主题运行时（dsh-TUI ≥ 0.10.0）/ 静态资产（旧宿主） | `pink-night` 夜樱 / `pink-day` 昼樱 / `pink-ansi` 樱·ANSI；新宿主优先即时注册，服务晚到时短暂回退并清理本次文件，旧宿主使用 `~/.dsh-tui/themes/` |
 | **缓存背景跟随** | 设置 + 本地缓存 | 可选地应用已有 `theme-follow.json` 的昼樱/夜樱结果；不直接读取终端输入或发送 OSC 查询 |
 | **花符状态行** | `tuiStatus` | 输入框上方一行小装饰：✿ · 时钟 · 实时轮数（默认仅粉主题下显示） |
 | **设置面板** | `tuiSettingsSections` | `/settings` 里一个可编辑区块，改完即时生效 |
+| **屏幕提示** | `tuiToast`（dsh-TUI ≥ 0.10.0） | 背景跟随结果、主题文件自愈、旧文件遮蔽提醒各弹一行短提示；旧宿主自动静默降级 |
 
 **明确不做的事**：不注册快捷键、不注册/修改任何命令、不拦截输入、不追加会话事件、不注入 system prompt。卸载即无痕（可选删除主题文件）。
 
@@ -47,6 +48,22 @@
 - 开启后该缓存会在启动时覆盖 `/theme` 的持久选择；关闭即可恢复手动选择；
 - `DSH_TUI_THEME` 环境变量仍然最优先（宿主行为，插件不覆盖环境变量）。
 
+dsh-TUI ≥ 0.10.0 上，跟随结果会以 toast 短提示呈现：真正改写了 `theme.json` 时提示「已按保存的终端背景改用 …，/reload 即时生效」（当前画面仍显示旧主题，`/reload` 或重启后生效）；在 `/settings` 里手动开启但无缓存时如实提示「没有保存的终端背景缓存」。启动基线未变化时保持安静，避免每次开机重复打扰。
+
+## 屏幕提示（toast）
+
+插件日志对 TUI 用户不可见，因此少数值得知道的事件会走宿主 toast（dsh-TUI ≥ 0.10.0 的 `tuiToast` 接缝，纯输出、不拦截任何输入；旧宿主没有该接缝，自动退回纯日志行为）：
+
+| 事件 | 提示 |
+| --- | --- |
+| 背景跟随改写了主题偏好 | ✿ 已按保存的终端背景改用 …，/reload 即时生效 |
+| 手动开启跟随且缓存与当前一致 | ✿ 已按保存的终端背景保持 … |
+| 手动开启跟随但无缓存 | ✿ 没有保存的终端背景缓存，保持当前主题（警告色） |
+| 主题文件损坏被自动修复 | ✿ 已修复损坏的主题文件：…（警告色） |
+| 旧版遗留的同名主题文件与内置版本完全相同 | ✿ … 与插件内置相同，删除后配色将随插件自动更新 |
+
+最后一条只针对与内置副本逐字节相同的文件——你手动调过色的文件永远不会被提及或删除。
+
 ## 安装
 
 ```sh
@@ -69,9 +86,11 @@ dsh plugin --profile dsh-tui add -w ./dsh-tui-theme-<版本号>.tgz
 dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest
 ```
 
-插件只在主题文件缺失时复制，绝不覆盖你编辑过的 `~/.dsh-tui/themes/pink-*.json`。唯一的例外是已损坏的目标文件（无法解析为 JSON，例如安装中途中断留下的残文件）：插件会把它改名为 `<文件名>.corrupt-<时间戳>` 保留现场，再重新安装内置副本，并记录一条警告。升级若需要采用包内的新主题资产，请先备份自己的修改，再删除对应主题文件并重启 dsh-TUI 让插件重装。
+在 dsh-TUI ≥ 0.10.0 中，三套主题通过 `ctx.tuiThemes` 运行时注册：调色板随插件即时生效，正常挂载时不写入用户目录，主题选择器显示中文 `displayName`。若服务晚到，插件会先同步回退到静态路径，并在确认运行时服务后删除本次写入且仍未被改写的文件。旧宿主使用静态文件路径：插件只在主题文件缺失时复制，绝不覆盖你编辑过的 `~/.dsh-tui/themes/pink-*.json`。唯一的例外是已损坏的目标文件（无法解析为 JSON，例如安装中途中断留下的残文件）：插件会把它改名为 `<文件名>.corrupt-<时间戳>` 保留现场，再重新安装内置副本，记录一条警告，并在支持 toast 的宿主上弹一条屏幕提示。
+
+从旧宿主升级后，若希望改用运行时托管，请先备份并删除 `~/.dsh-tui/themes/pink-{night,day,ansi}.json`；插件不会自动删除用户文件。遗留文件若与内置副本完全相同，插件会在运行时托管确认时弹一条一次性提醒，指出哪些文件正在遮蔽配色更新。
 
-重启 dsh-TUI 后插件自动把三套主题复制进 `~/.dsh-tui/themes/`（**仅缺失时复制，绝不覆盖你已有的同名文件**），然后：
+旧宿主重启 dsh-TUI 后插件会把三套主题复制进 `~/.dsh-tui/themes/`（**仅缺失时复制，绝不覆盖你已有的同名文件**）；0.10.0 及更新宿主则直接使用运行时注册，然后：
 
 ```sh
 # 在 dsh-TUI 里
@@ -135,11 +154,11 @@ DSH_TUI_SOURCE_ROOT=/path/to/dsh-TUI-source \
 npm run verify:host
 ```
 
-`verify:host` 必须显式指向同一版本的宿主 adapter 与源码；缺少其中任一项会失败，避免把跳过误报为验证成功。日常开发会验证两者版本一致但不固定版本号；需要锁定一次发布基线时，额外设置 `DSH_TUI_EXPECTED_VERSION=0.9.3`。
+`verify:host` 默认使用开发依赖中的 dsh-TUI（当前为 0.10.0-beta.4）进行零配置验证；需要验证旧版或发布基线时，再显式指向同一版本的宿主 adapter 与源码。需要锁定版本时，额外设置 `DSH_TUI_EXPECTED_VERSION`。
 
 主题调色板改起来最直接：编辑 `themes/*.json` 后重新 `npm run verify`，再删掉 `~/.dsh-tui/themes/` 下对应文件让插件重装。
 
 ## 兼容性
 
-- **dsh-TUI 版本下限：0.8.8**（状态行与设置面板；0.9.3 实测）。更旧的宿主缺 `dsh-tui-extensions` 扩展面时，插件自动降级为“仅安装三套主题”，不报错。
+- **dsh-TUI 版本下限：0.8.8**（状态行与设置面板；0.9.3 实测）。0.10.0 及更新版本使用运行时主题注册；更旧的宿主缺 `dsh-tui-extensions` 扩展面时，插件自动降级为“仅安装三套主题”，不报错。
 - Node `^22.19 || >=24`，纯 ESM，MIT。

package/lib/types/autoTheme.d.ts

@@ -29,11 +29,24 @@ export declare function themeForBackground(light: boolean): string;
  * preference committed successfully.
  */
 export declare function applyCachedFollow(dataDir: string): string | undefined;
+/** What one follow application actually did (log and toast both derive from it). */
+export type FollowOutcome = {
+    kind: 'applied';
+    theme: string;
+    changed: boolean;
+} | {
+    kind: 'unavailable';
+};
 /**
  * Apply a previously detected background without touching terminal I/O. A
  * future host-owned terminal query service may refresh theme-follow.json; this
  * plugin intentionally does not access stdin, stdout, or raw mode directly.
+ *
+ * The structured outcome lets the entry point keep one source of truth for
+ * the log line and the user-visible toast: `changed` distinguishes a real
+ * preference write (the live TUI still shows the previous palette until
+ * /reload or a restart) from a no-op confirmation.
  */
-export declare function runFollowSystem(dataDir: string, isCurrent: () => boolean, log: (message: string) => void): void;
+export declare function runFollowSystem(dataDir: string, isCurrent: () => boolean, report: (outcome: FollowOutcome) => void): void;
 export {};
 //# sourceMappingURL=autoTheme.d.ts.map

package/lib/types/autoTheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"autoTheme.d.ts","sourceRoot":"","sources":["../../src/autoTheme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,UAAU,WAAW;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,EAAE,EAAE,MAAM,CAAA;CACX;AAsCD,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGjE;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGxE;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMrE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,OAAO,EACxB,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC7B,IAAI,CASN"}
+{"version":3,"file":"autoTheme.d.ts","sourceRoot":"","sources":["../../src/autoTheme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,UAAU,WAAW;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,EAAE,EAAE,MAAM,CAAA;CACX;AAsCD,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGjE;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGxE;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMrE;AAED,oFAAoF;AACpF,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAA;AAE3B;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,OAAO,EACxB,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,GACvC,IAAI,CAUN"}

package/lib/types/autoTheme.js

@@ -84,17 +84,22 @@ export function applyCachedFollow(dataDir) {
  * Apply a previously detected background without touching terminal I/O. A
  * future host-owned terminal query service may refresh theme-follow.json; this
  * plugin intentionally does not access stdin, stdout, or raw mode directly.
+ *
+ * The structured outcome lets the entry point keep one source of truth for
+ * the log line and the user-visible toast: `changed` distinguishes a real
+ * preference write (the live TUI still shows the previous palette until
+ * /reload or a restart) from a no-op confirmation.
  */
-export function runFollowSystem(dataDir, isCurrent, log) {
+export function runFollowSystem(dataDir, isCurrent, report) {
     if (!isCurrent())
         return;
+    const before = readThemePref(dataDir);
     const applied = applyCachedFollow(dataDir);
     if (!isCurrent())
         return;
     if (applied === undefined) {
-        log('follow: cached background unavailable or preference write failed; keeping current choice');
-    }
-    else {
-        log(`follow: applied cached background (${applied})`);
+        report({ kind: 'unavailable' });
+        return;
     }
+    report({ kind: 'applied', theme: applied, changed: before !== applied });
 }

package/lib/types/index.d.ts

@@ -3,7 +3,7 @@
  *
  * 个性化全部走既有接缝，不注册快捷键、不注册命令、不拦截任何输入：
  * - 接缝四（主题）：内置三套粉色 JSON（pink-night / pink-day / pink-ansi），
- *   启动时复制进 ~/.dsh-tui/themes/（仅缺失时，绝不覆盖用户已有文件）；
+ *   新宿主通过运行时服务注册，旧宿主同步复制进 ~/.dsh-tui/themes/（仅缺失时）；
  * - 缓存背景跟随：安全应用已有的终端背景缓存，在昼樱/夜樱间切换；
  *   dsh-TUI 未提供插件终端查询接缝时，不直接读写 stdin、raw mode 或 OSC 11；
  * - 接缝十一（状态行）：输入框上方一行小装饰（✿ · 时钟 · 本轮轮数）；

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAGjF,eAAO,MAAM,IAAI,kBAAY,CAAA;AAE7B,wDAAwD;AACxD,MAAM,MAAM,MAAM,GAAG,eAAe,CAAA;AAUpC,eAAO,MAAM,MAAM,EAAE,WAAW,CAAC,MAAM,CAQrC,CAAA;AAkBF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CA0E7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMlD,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAIjF,eAAO,MAAM,IAAI,kBAAY,CAAA;AAE7B,wDAAwD;AACxD,MAAM,MAAM,MAAM,GAAG,eAAe,CAAA;AAUpC,eAAO,MAAM,MAAM,EAAE,WAAW,CAAC,MAAM,CAQrC,CAAA;AAkBF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CA+I7D"}

package/lib/types/index.js

@@ -3,7 +3,7 @@
  *
  * 个性化全部走既有接缝，不注册快捷键、不注册命令、不拦截任何输入：
  * - 接缝四（主题）：内置三套粉色 JSON（pink-night / pink-day / pink-ansi），
- *   启动时复制进 ~/.dsh-tui/themes/（仅缺失时，绝不覆盖用户已有文件）；
+ *   新宿主通过运行时服务注册，旧宿主同步复制进 ~/.dsh-tui/themes/（仅缺失时）；
  * - 缓存背景跟随：安全应用已有的终端背景缓存，在昼樱/夜樱间切换；
  *   dsh-TUI 未提供插件终端查询接缝时，不直接读写 stdin、raw mode 或 OSC 11；
  * - 接缝十一（状态行）：输入框上方一行小装饰（✿ · 时钟 · 本轮轮数）；
@@ -15,10 +15,12 @@
  */
 import { join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { installBundledThemes, homeDir } from './themeAssets.js';
+import { installBundledThemes, homeDir, removeBundledThemes, findShadowedBundledThemes } from './themeAssets.js';
+import { startRuntimeThemes } from './runtimeThemes.js';
 import { startStatusLine } from './statusLine.js';
 import { runFollowSystem } from './autoTheme.js';
 import { registerPinkSettings } from './settingsSection.js';
+import { startToastRelay } from './toast.js';
 import { PLUGIN_ID } from './pluginId.js';
 export const name = PLUGIN_ID;
 // Explicit annotation: the inferred z.dict output references cosmokit's Dict
@@ -64,7 +66,21 @@ export function apply(ctx, config = {}) {
         showTurns: config.showTurns ?? DEFAULTS.showTurns,
         statusScope: config.statusScope ?? DEFAULTS.statusScope,
     };
-    if (cordis.autoInstallThemes) {
+    // User-visible one-liners for the few events worth surfacing (the plugin
+    // logger is invisible to a TUI user). Hosts without the 0.10 toast seam
+    // degrade to the log-only behavior of previous releases.
+    const sendToast = startToastRelay(ctx);
+    // New hosts own the palette in memory. Install synchronously first so an old
+    // host can resolve a persisted theme during its first render. If a runtime
+    // service appears afterwards, remove only files written by this activation
+    // before registering the in-memory palettes.
+    let runtimeConfirmed = false;
+    const ownedStaticFiles = new Set();
+    const installStatic = () => {
+        if (runtimeConfirmed)
+            return;
+        if (!cordis.autoInstallThemes)
+            return;
         const result = installBundledThemes();
         for (const file of result.installed) {
             ctx.logger.info(`${PLUGIN_ID}: installed bundled theme "${file}" into ~/.dsh-tui/themes/`);
@@ -75,6 +91,46 @@ export function apply(ctx, config = {}) {
         for (const file of result.failed) {
             ctx.logger.warn(`${PLUGIN_ID}: could not install bundled theme "${file}"`);
         }
+        for (const file of [...result.installed, ...result.repaired])
+            ownedStaticFiles.add(file);
+        if (result.repaired.length > 0) {
+            sendToast(`✿ 已修复损坏的主题文件：${result.repaired.join('、')}`, 'warning');
+        }
+    };
+    const markRuntimeAvailable = () => {
+        const firstConfirmation = !runtimeConfirmed;
+        runtimeConfirmed = true;
+        if (ownedStaticFiles.size > 0) {
+            removeBundledThemes([...ownedStaticFiles]);
+            ownedStaticFiles.clear();
+        }
+        // Same-named static files win over runtime registrations. User-edited
+        // files stay unmentioned; files byte-identical to the bundled copy add
+        // nothing but permanently block palette updates, so point them out once.
+        if (!firstConfirmation)
+            return;
+        const shadowed = findShadowedBundledThemes();
+        if (shadowed.length > 0) {
+            ctx.logger.info(`${PLUGIN_ID}: legacy static files shadow the runtime registry: ${shadowed.join(', ')}`);
+            sendToast(`✿ ${shadowed.join('、')} 与插件内置相同，删除后配色将随插件自动更新`);
+        }
+    };
+    let runtimePresent = false;
+    try {
+        runtimePresent = ctx.get('tuiThemes', false) !== undefined;
+    }
+    catch {
+        runtimePresent = false;
+    }
+    if (runtimePresent) {
+        startRuntimeThemes(ctx, markRuntimeAvailable);
+    }
+    else {
+        installStatic();
+        ctx.effect(() => () => {
+            ownedStaticFiles.clear();
+        });
+        startRuntimeThemes(ctx, markRuntimeAvailable);
     }
     // The /settings user layer (settings.yaml) overrides the cordis layer and
     // lands live through scope.watch; both override the hardcoded defaults.
@@ -85,9 +141,28 @@ export function apply(ctx, config = {}) {
     // whether the cached result may control this startup.
     let followActive;
     const dataDir = join(homeDir(), '.dsh-tui');
-    const applyFollow = () => {
-        runFollowSystem(dataDir, () => followActive === true, message => {
-            ctx.logger.info(`${PLUGIN_ID}: ${message}`);
+    const applyFollow = (userInitiated) => {
+        runFollowSystem(dataDir, () => followActive === true, outcome => {
+            if (outcome.kind === 'unavailable') {
+                ctx.logger.info(`${PLUGIN_ID}: follow: cached background unavailable or preference write failed; keeping current choice`);
+                // Startup baselines stay quiet: the follow feature has no cache
+                // producer on modern hosts, and an identical warning every boot
+                // would be noise, not feedback. An explicit toggle-on deserves the
+                // honest answer that nothing was applied.
+                if (userInitiated) {
+                    sendToast('✿ 没有保存的终端背景缓存，保持当前主题', 'warning');
+                }
+                return;
+            }
+            ctx.logger.info(`${PLUGIN_ID}: follow: applied cached background (${outcome.theme})`);
+            if (outcome.changed) {
+                // A real pref write: the live TUI resolved its palette from the
+                // previous pref, so the new choice needs /reload or a restart.
+                sendToast(`✿ 已按保存的终端背景改用 ${outcome.theme}，/reload 即时生效`, 'success');
+            }
+            else if (userInitiated) {
+                sendToast(`✿ 已按保存的终端背景保持 ${outcome.theme}`, 'success');
+            }
         });
     };
     registerPinkSettings(ctx, cordis, doc => {
@@ -99,13 +174,13 @@ export function apply(ctx, config = {}) {
             // still applies the cache immediately.
             followActive = follow;
             if (follow)
-                applyFollow();
+                applyFollow(false);
             return;
         }
         if (followActive !== follow) {
             followActive = follow;
             if (follow) {
-                applyFollow();
+                applyFollow(true);
             }
             else {
                 ctx.logger.info(`${PLUGIN_ID}: follow: disabled, manual /theme choice preserved`);

package/lib/types/runtimeThemes.d.ts

@@ -0,0 +1,9 @@
+/** Runtime theme registration for dsh-TUI 0.10.0 and newer. */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Register every bundled palette through the host runtime seam. The optional
+ * callback is used by the entry point to remove its legacy static fallback as
+ * soon as the service becomes available.
+ */
+export declare function startRuntimeThemes(ctx: Context, onAvailable?: () => void): void;
+//# sourceMappingURL=runtimeThemes.d.ts.map

package/lib/types/runtimeThemes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeThemes.d.ts","sourceRoot":"","sources":["../../src/runtimeThemes.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAQlD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CA+B/E"}

package/lib/types/runtimeThemes.js

@@ -0,0 +1,39 @@
+/** Runtime theme registration for dsh-TUI 0.10.0 and newer. */
+import { readBundledThemes } from './themeAssets.js';
+/**
+ * Register every bundled palette through the host runtime seam. The optional
+ * callback is used by the entry point to remove its legacy static fallback as
+ * soon as the service becomes available.
+ */
+export function startRuntimeThemes(ctx, onAvailable) {
+    ctx.inject(['tuiThemes'], themesCtx => {
+        onAvailable?.();
+        const themes = themesCtx.tuiThemes;
+        const disposers = [];
+        for (const bundled of readBundledThemes()) {
+            try {
+                const dispose = themes.register({
+                    name: bundled.name,
+                    ...(bundled.displayName === undefined ? {} : { displayName: bundled.displayName }),
+                    base: bundled.base,
+                    colors: bundled.colors,
+                }, themesCtx);
+                if (typeof dispose === 'function')
+                    disposers.push(dispose);
+            }
+            catch (error) {
+                themesCtx.logger.warn(`dsh-tui-theme: runtime theme registration failed for "${bundled.name}": ${String(error)}`);
+            }
+        }
+        themesCtx.effect(() => () => {
+            for (const dispose of disposers.splice(0)) {
+                try {
+                    dispose();
+                }
+                catch {
+                    // A host teardown may already have removed the registry.
+                }
+            }
+        });
+    });
+}

package/lib/types/settingsSection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settingsSection.d.ts","sourceRoot":"","sources":["../../src/settingsSection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAGpD,+EAA+E;AAC/E,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG;IAC5C,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,GACpC,IAAI,CAoDN"}
+{"version":3,"file":"settingsSection.d.ts","sourceRoot":"","sources":["../../src/settingsSection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAGpD,+EAA+E;AAC/E,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG;IAC5C,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,GACpC,IAAI,CAwDN"}

package/lib/types/settingsSection.js

@@ -14,7 +14,6 @@
  * fires whenever each service actually registers.
  * @module dsh-tui-theme/settingsSection
  */
-import { settingsNamespace } from '@deepseek-ai/dsh-settings';
 import z from '@deepseek-ai/schemastery';
 import { PLUGIN_ID } from './pluginId.js';
 /**
@@ -32,7 +31,11 @@ export function registerPinkSettings(ctx, cordis, onDoc) {
     ctx.inject(['settings'], settingsCtx => {
         const settings = settingsCtx.settings;
         try {
-            const scope = settings.register(settingsNamespace(PLUGIN_ID), z.object({
+            // dsh-settings validates the raw namespace at registration time. Keep
+            // this as a plain string so alpha.2 hosts, which removed the runtime
+            // settingsNamespace() helper, can load the plugin without a missing
+            // named export while older hosts retain the same behavior.
+            const scope = settings.register(PLUGIN_ID, z.object({
                 followSystem: z.boolean(),
                 showGlyph: z.boolean(),
                 showClock: z.boolean(),

package/lib/types/themeAssets.d.ts

@@ -20,11 +20,20 @@ export interface ThemeInstallResult {
     /** Files that could not be installed (per-file failures). */
     readonly failed: readonly string[];
 }
+export interface BundledTheme {
+    readonly file: string;
+    readonly name: string;
+    readonly displayName?: string;
+    readonly base: 'light' | 'dark' | 'dark-ansi';
+    readonly colors: Record<string, string>;
+}
 export declare function homeDir(): string;
 /** The package's bundled themes/ directory (sibling of the built lib/). */
 export declare function bundledThemesDir(): string;
 /** The host's user-theme directory (~/.dsh-tui/themes). */
 export declare function themesTargetDir(): string;
+/** Read bundled descriptors for hosts that support runtime theme registration. */
+export declare function readBundledThemes(sourceDir?: string): BundledTheme[];
 /**
  * Install every bundled theme JSON that the target directory is missing.
  * @param targetDir - Destination directory (defaults to ~/.dsh-tui/themes).
@@ -32,4 +41,18 @@ export declare function themesTargetDir(): string;
  * @returns Per-file outcome. Never throws.
  */
 export declare function installBundledThemes(targetDir?: string, sourceDir?: string): ThemeInstallResult;
+/**
+ * Remove files that this activation installed when a runtime theme service
+ * becomes available. A byte-for-byte check preserves edits made in the small
+ * window between installation and runtime confirmation.
+ */
+export declare function removeBundledThemes(files: readonly string[], targetDir?: string, sourceDir?: string): string[];
+/**
+ * Bundled theme files present in the target directory byte-for-byte
+ * identical to the bundled copy. On runtime-theme hosts such files shadow
+ * the registry while adding nothing, so the entry point can point them out
+ * once. User-edited or foreign same-named files are never reported — the
+ * never-overwrite rule keeps them, and no toast may nag about them.
+ */
+export declare function findShadowedBundledThemes(targetDir?: string, sourceDir?: string): string[];
 //# sourceMappingURL=themeAssets.d.ts.map

package/lib/types/themeAssets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"themeAssets.d.ts","sourceRoot":"","sources":["../../src/themeAssets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAID,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,MAA0B,EACrC,SAAS,GAAE,MAA2B,GACrC,kBAAkB,CAiCpB"}
+{"version":3,"file":"themeAssets.d.ts","sourceRoot":"","sources":["../../src/themeAssets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAA;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAID,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,SAAS,GAAE,MAA2B,GAAG,YAAY,EAAE,CA0CxF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,MAA0B,EACrC,SAAS,GAAE,MAA2B,GACrC,kBAAkB,CAmCpB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,GAAE,MAA0B,EACrC,SAAS,GAAE,MAA2B,GACrC,MAAM,EAAE,CAuBV;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,MAA0B,EACrC,SAAS,GAAE,MAA2B,GACrC,MAAM,EAAE,CAkBV"}

package/lib/types/themeAssets.js

@@ -10,7 +10,7 @@
  * contained per file: a theme garnish must never break the TUI's boot.
  * @module dsh-tui-theme/themeAssets
  */
-import { mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -27,6 +27,51 @@ export function bundledThemesDir() {
 export function themesTargetDir() {
     return join(homeDir(), '.dsh-tui', 'themes');
 }
+/** Read bundled descriptors for hosts that support runtime theme registration. */
+export function readBundledThemes(sourceDir = bundledThemesDir()) {
+    let files;
+    try {
+        files = readdirSync(sourceDir).filter(entry => entry.toLowerCase().endsWith('.json'));
+    }
+    catch (error) {
+        console.warn(`dsh-tui-theme: could not read bundled themes from ${sourceDir}: ${String(error)}`);
+        return [];
+    }
+    const themes = [];
+    for (const file of files) {
+        try {
+            const value = JSON.parse(readFileSync(join(sourceDir, file), 'utf8'));
+            const name = value.name;
+            const base = value.base;
+            const colors = value.colors;
+            if (typeof name !== 'string' ||
+                !/^[a-z][a-z0-9_-]*(?::[a-z][a-z0-9_-]*)?$/u.test(name) ||
+                (base !== 'light' && base !== 'dark' && base !== 'dark-ansi') ||
+                colors === null ||
+                typeof colors !== 'object' ||
+                Array.isArray(colors)) {
+                throw new Error('invalid theme descriptor');
+            }
+            const normalizedColors = {};
+            for (const [key, color] of Object.entries(colors)) {
+                if (typeof color !== 'string')
+                    throw new Error(`invalid color for ${key}`);
+                normalizedColors[key] = color;
+            }
+            themes.push({
+                file,
+                name,
+                ...(typeof value.displayName === 'string' ? { displayName: value.displayName } : {}),
+                base,
+                colors: normalizedColors,
+            });
+        }
+        catch (error) {
+            console.warn(`dsh-tui-theme: skipping bundled theme ${file}: ${String(error)}`);
+        }
+    }
+    return themes;
+}
 /**
  * Install every bundled theme JSON that the target directory is missing.
  * @param targetDir - Destination directory (defaults to ~/.dsh-tui/themes).
@@ -57,8 +102,11 @@ export function installBundledThemes(targetDir = themesTargetDir(), sourceDir =
             }
             catch (error) {
                 if (error.code === 'EEXIST') {
-                    if (healCorruptTarget(target, text))
+                    const healed = healCorruptTarget(target, text);
+                    if (healed === 'repaired')
                         repaired.push(file);
+                    else if (healed === 'failed')
+                        failed.push(file);
                     else
                         skipped.push(file);
                 }
@@ -73,14 +121,73 @@ export function installBundledThemes(targetDir = themesTargetDir(), sourceDir =
     }
     return { installed, skipped, repaired, failed };
 }
+/**
+ * Remove files that this activation installed when a runtime theme service
+ * becomes available. A byte-for-byte check preserves edits made in the small
+ * window between installation and runtime confirmation.
+ */
+export function removeBundledThemes(files, targetDir = themesTargetDir(), sourceDir = bundledThemesDir()) {
+    const removed = [];
+    for (const file of files) {
+        try {
+            const bundled = readFileSync(join(sourceDir, file), 'utf8');
+            const target = join(targetDir, file);
+            if (readFileSync(target, 'utf8') !== bundled)
+                continue;
+            unlinkSync(target);
+            removed.push(file);
+        }
+        catch {
+            // Runtime registration must remain best-effort if a file disappears or
+            // the target directory becomes unavailable during teardown.
+        }
+    }
+    if (removed.length > 0) {
+        try {
+            if (readdirSync(targetDir).length === 0)
+                rmdirSync(targetDir);
+        }
+        catch {
+            // An empty directory is only a cosmetic artifact; leave it in place if
+            // it was removed concurrently or is no longer empty.
+        }
+    }
+    return removed;
+}
+/**
+ * Bundled theme files present in the target directory byte-for-byte
+ * identical to the bundled copy. On runtime-theme hosts such files shadow
+ * the registry while adding nothing, so the entry point can point them out
+ * once. User-edited or foreign same-named files are never reported — the
+ * never-overwrite rule keeps them, and no toast may nag about them.
+ */
+export function findShadowedBundledThemes(targetDir = themesTargetDir(), sourceDir = bundledThemesDir()) {
+    const shadowed = [];
+    let files;
+    try {
+        files = readdirSync(sourceDir).filter(entry => entry.toLowerCase().endsWith('.json'));
+    }
+    catch {
+        return shadowed;
+    }
+    for (const file of files) {
+        try {
+            if (readFileSync(join(targetDir, file), 'utf8') === readFileSync(join(sourceDir, file), 'utf8')) {
+                shadowed.push(file);
+            }
+        }
+        catch {
+            // Missing or unreadable target: not a shadow.
+        }
+    }
+    return shadowed;
+}
 /**
  * Self-heal an existing target that fails to parse as JSON — the leftover of
  * a torn write from an interrupted installation. The damaged file is kept as
- * <target>.corrupt-<timestamp> and the bundled copy installed fresh. Returns
- * false (leave untouched) when the target is valid JSON (a user file the
- * never-overwrite rule protects), unreadable (unreadable is not proven
- * corrupt), or when the backup/replace itself fails (degrade to the plain
- * silent skip).
+ * <target>.corrupt-<timestamp>-<pid>-<random> and the bundled copy installed
+ * fresh. Returns `skipped` when the target is valid JSON or unreadable, and
+ * `failed` when the corrupt target was moved but replacement could not finish.
  */
 function healCorruptTarget(target, text) {
     let existing;
@@ -88,21 +195,28 @@ function healCorruptTarget(target, text) {
         existing = readFileSync(target, 'utf8');
     }
     catch {
-        return false;
+        return 'skipped';
     }
     try {
         JSON.parse(existing);
-        return false;
+        return 'skipped';
     }
     catch {
         // Proven corrupt: fall through to backup and reinstall.
     }
+    let backup;
+    try {
+        backup = `${target}.corrupt-${Date.now()}-${process.pid}-${Math.random().toString(16).slice(2)}`;
+        renameSync(target, backup);
+    }
+    catch {
+        return 'skipped';
+    }
     try {
-        renameSync(target, `${target}.corrupt-${Date.now()}`);
         writeFileSync(target, text, { flag: 'wx' });
-        return true;
+        return 'repaired';
     }
     catch {
-        return false;
+        return 'failed';
     }
 }

package/lib/types/toast.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Toast relay for the plugin-facing transient-notification seam
+ * (dsh-TUI 0.10: `ctx.tuiToast`).
+ *
+ * The plugin's own logger output is invisible to a TUI user, so the few
+ * events worth surfacing — a follow-system pref write, a repaired theme
+ * file, a shadowing legacy static install — go through the host's toast
+ * surface instead. Sending is fire-and-forget: hosts without the seam
+ * (dsh-TUI < 0.10) never fire the inject and every send is a silent no-op,
+ * exactly like the other soft-probed seams.
+ *
+ * The host registers its toast sink late (the dsh-tui row applies after the
+ * extensions row, and both may trail this plugin), so a toast dropped for
+ * having no sink is retried on a short schedule before giving up. The
+ * tuiToast service itself arrives with the extensions row, so a send fired
+ * before the seam even exists waits on the same schedule. Retries are
+ * bounded, unref'd, and cleared with the activation; a toast lost to a host
+ * rate limit is not worth fighting — the next real event re-reports.
+ * @module dsh-tui-theme/toast
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Host toast color vocabulary (neutral when omitted). */
+export type ToastColor = 'success' | 'warning' | 'error';
+/** Send one transient notification; resolves to whether it was delivered. */
+export type ToastSend = (text: string, color?: ToastColor) => boolean;
+/**
+ * @internal Shrink the retry schedule for hermetic tests (verify.mjs only;
+ * not part of the plugin's behavioral contract).
+ */
+export declare function setToastRetryDelaysForTests(delays: readonly number[]): void;
+/**
+ * Start the toast relay. Returns a sender that is callable immediately and
+ * from any later context (settings watches, timers): `show()` binds through
+ * the service's own activation, so unlike `tuiStatus.set` it takes no
+ * identity argument — but the service object itself must still be read
+ * inside the inject (same rule as every other seam).
+ * @param ctx - The plugin's own activation context.
+ */
+export declare function startToastRelay(ctx: Context): ToastSend;
+//# sourceMappingURL=toast.d.ts.map

package/lib/types/toast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toast.d.ts","sourceRoot":"","sources":["../../src/toast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,0DAA0D;AAC1D,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;AAUxD,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,KAAK,OAAO,CAAA;AAMrE;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAoDvD"}