dsh-tui-theme 0.4.0 → 0.5.0

package/README.md

@@ -15,36 +15,34 @@
 
 | 主题 | 基底 | 风格 |
 | --- | --- | --- |
-| `pink-night` 夜樱 | dark | 深梅紫底、玫瑰粉强调、粉鲸鱼吉祥物，95 键全覆盖 |
+| `pink-night` 夜樱 | dark | 暗梅底、玫瑰粉强调，95 键全覆盖 |
 | `pink-day` 昼樱 | light | 象牙粉底、墨梅正文、柔和玫瑰强调（已通过宿主浅色身份判定） |
 | `pink-ansi` 樱·ANSI | dark-ansi | 16 色 ANSI 回退，品牌色映射到 magenta 系 |
 
 三套均通过 dsh-TUI 官方校验器（零警告、全键覆盖）与 WCAG 对比度检查（正文 ≥ 11:1）。
 
-> 小知识：`pink-day` 的 `text` 写成 `rgb(61,43,51)` 而非 hex——宿主按 `text` 墨色亮度自动判定主题深浅，且只认 `rgb()` 格式。
-
 ## 截图
 
-实测于 dsh-tui 0.9.2：
+主题主界面截图实测于 dsh-tui 0.9.2；0.9.3 的 `/settings` 卡片界面见下图：
 
 | 昼樱 `pink-day` | 夜樱 `pink-night` |
 | :---: | :---: |
 | ![pink-day 主题界面](docs/screenshots/pink-day.png) | ![pink-night 主题界面](docs/screenshots/pink-night.png) |
 
-`/settings` 里的 pink-theme 区块（已缓存背景 / 花符 / 时钟 / 轮数，保存即时生效）：
+`/settings` 里的 pink-theme 区块（终端背景 / 花符 / 时钟 / 轮数 / 状态行展示，保存即时生效）：
 
 ![pink-theme 设置区块](docs/screenshots/settings.png)
 
-> 图中底栏上下文进度条的蓝色分段与 ❯ 提示符是宿主硬编码的，见下文[宿主限制](#受宿主限制目前无法定制的部分)。
+> 图中 ❯ 提示符与链接是宿主硬编码的，见下文[宿主限制](#受宿主限制目前无法定制的部分)。
 
 ## 缓存背景跟随
 
-`dsh-TUI 0.9.2` 没有向插件公开安全的终端查询接缝。为了不与宿主的 stdin/raw-mode 生命周期竞争，插件不会直接发送 OSC 11，也不会读取终端输入。
+`dsh-TUI` 没有向插件公开安全的终端查询接缝。为了不与宿主的 stdin/raw-mode 生命周期竞争，插件不会直接发送 OSC 11，也不会读取终端输入。
 
-“使用已缓存的终端背景”开启后：
+“应用上次保存的终端背景”开启后：
 
 - 启动时读取 `~/.dsh-tui/theme-follow.json` 中已有的 `light` 结果，亮 → `pink-day`，暗 → `pink-night`，并将选择写入 `~/.dsh-tui/theme.json`；
-- 不存在缓存时完全保留当前 `/theme` 选择；0.4.0 不会自行创建或刷新缓存；
+- 不存在缓存时完全保留当前 `/theme` 选择；插件不会自行创建或刷新缓存；
 - 默认关闭。该缓存可由之前的兼容版本留下；未来 dsh-TUI 提供宿主拥有的查询接缝后，插件才会安全地恢复刷新能力；
 - 开启后该缓存会在启动时覆盖 `/theme` 的持久选择；关闭即可恢复手动选择；
 - `DSH_TUI_THEME` 环境变量仍然最优先（宿主行为，插件不覆盖环境变量）。
@@ -59,7 +57,7 @@ dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest
 cd /path/to/dsh-tui-theme
 npm run build
 npm pack
-dsh plugin --profile dsh-tui add -w ./dsh-tui-theme-0.4.0.tgz
+dsh plugin --profile dsh-tui add -w ./dsh-tui-theme-<版本号>.tgz
 ```
 
 不要以本地源码目录作为依赖安装：其开发 `node_modules` 可能与 dsh-TUI 宿主解析出不同的 Cordis/DSH framework instance，造成插件无法注册服务。
@@ -71,7 +69,7 @@ dsh plugin --profile dsh-tui add -w ./dsh-tui-theme-0.4.0.tgz
 dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest
 ```
 
-插件只在主题文件缺失时复制，绝不覆盖你编辑过的 `~/.dsh-tui/themes/pink-*.json`。升级若需要采用包内的新主题资产，请先备份自己的修改，再删除对应主题文件并重启 dsh-TUI 让插件重装。
+插件只在主题文件缺失时复制，绝不覆盖你编辑过的 `~/.dsh-tui/themes/pink-*.json`。唯一的例外是已损坏的目标文件（无法解析为 JSON，例如安装中途中断留下的残文件）：插件会把它改名为 `<文件名>.corrupt-<时间戳>` 保留现场，再重新安装内置副本，并记录一条警告。升级若需要采用包内的新主题资产，请先备份自己的修改，再删除对应主题文件并重启 dsh-TUI 让插件重装。
 
 重启 dsh-TUI 后插件自动把三套主题复制进 `~/.dsh-tui/themes/`（**仅缺失时复制，绝不覆盖你已有的同名文件**），然后：
 
@@ -89,7 +87,7 @@ dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest
 
 | 字段 | 默认 | 说明 |
 | --- | --- | --- |
-| `followSystem` | `false` | 启动时应用已缓存的终端背景结果（昼樱 ↔ 夜樱）；0.4.0 不刷新缓存 |
+| `followSystem` | `false` | 启动时应用上次保存的终端背景结果（昼樱 ↔ 夜樱）；插件不刷新缓存 |
 | `showGlyph` | `true` | 花符：开 = ✿ 开头，关 = 不显示 |
 | `showClock` | `true` | 显示 HH:MM 时钟 |
 | `showTurns` | `true` | 显示当前会话轮数（`N✦`，自本次启动起计） |
@@ -99,7 +97,7 @@ dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest
 
 ## 受宿主限制、目前无法定制的部分
 
-以下元素的颜色/形态由 dsh-TUI 宿主**硬编码**，不读取任何主题键，主题 JSON 与插件接缝都覆盖不到（dsh-TUI 0.9.2 实测）：
+以下元素的颜色/形态由 dsh-TUI 宿主**硬编码**，不读取任何主题键，主题 JSON 与插件接缝都覆盖不到（dsh-TUI 0.9.3 实测）：
 
 | 元素 | 现状 | 位置（宿主源码） |
 | --- | --- | --- |
@@ -108,6 +106,7 @@ dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest
 | 进度条空余段配色 | 宿主按 `themeName === 'light'` **字符串比较**取浅色配色——自定义浅色主题（如 pink-day）不等于 `'light'`，会拿到深色空余段，在浅色终端上偏深 | `screens/StatusLine.tsx` |
 | 状态行文字颜色 | 插件状态行（tuiStatus）由宿主统一以**无色 + 终端 dim** 渲染，插件无法指定颜色（✿ 行因此继承终端默认前景色） | `screens/Chat.tsx` |
 | 输入框块状光标 | 宿主挂载期间隐藏终端原生光标（`?25l`），输入框光标由应用以**反色字符**自绘（`<Text inverse>`），颜色即主题 text/background 的反色——OSC 12 光标色只能染到不可见的原生光标，插件无法给输入光标上色（辅助功能模式 `CLAUDE_CODE_ACCESSIBILITY=1` 下原生光标才可见） | `ink/components/App.tsx`、`components/PromptInput.tsx` |
+| 正文链接 | OSC 8 超链接默认**写死的 ANSI 蓝**（`chalk.blue`）；注释说明 wrap-ansi 无法跨 OSC 8 保留主题 RGB 色，故链接色不读主题键 | `cc/hyperlink.ts` |
 | 主界面组件与布局 | 顶栏像素鲸鱼、工具卡、输入框等宿主组件不可被插件替换或改布局——平台规则（内建优先，无组件替换接缝）；主题能碰的只有颜色层 | 宿主架构约定 |
 
 这些都需要上游 dsh-TUI 修改（例如：把充能色/进度条分段色接入主题键、空余段判断改用 `isLightThemeActive()`、给输入光标增加主题键）。上游修复前，任何社区主题包都受同样约束。
@@ -136,11 +135,11 @@ DSH_TUI_SOURCE_ROOT=/path/to/dsh-TUI-source \
 npm run verify:host
 ```
 
-`verify:host` 必须显式指向待兼容的宿主 adapter 与源码；缺少其中任一项会失败，避免把跳过误报为验证成功。
+`verify:host` 必须显式指向同一版本的宿主 adapter 与源码；缺少其中任一项会失败，避免把跳过误报为验证成功。日常开发会验证两者版本一致但不固定版本号；需要锁定一次发布基线时，额外设置 `DSH_TUI_EXPECTED_VERSION=0.9.3`。
 
 主题调色板改起来最直接：编辑 `themes/*.json` 后重新 `npm run verify`，再删掉 `~/.dsh-tui/themes/` 下对应文件让插件重装。
 
 ## 兼容性
 
-- **dsh-TUI 版本下限：0.8.8**（状态行与设置面板；0.9.2 实测）。更旧的宿主缺 `dsh-tui-extensions` 扩展面时，插件自动降级为“仅安装三套主题”，不报错。
+- **dsh-TUI 版本下限：0.8.8**（状态行与设置面板；0.9.3 实测）。更旧的宿主缺 `dsh-tui-extensions` 扩展面时，插件自动降级为“仅安装三套主题”，不报错。
 - Node `^22.19 || >=24`，纯 ESM，MIT。

package/lib/types/autoTheme.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cached terminal-background follow for the pink theme pair.
  *
- * dsh-TUI v0.9.2 does not expose a plugin terminal-query seam. Plugins must
+ * dsh-TUI does not expose a plugin terminal-query seam. Plugins must
  * therefore not create their own stdin consumers or raw-mode leases: the host
  * owns both through Ink. This module only applies a previously stored result
  * before mount. A future host-owned query service can refresh that cache

package/lib/types/autoTheme.js

@@ -1,7 +1,7 @@
 /**
  * Cached terminal-background follow for the pink theme pair.
  *
- * dsh-TUI v0.9.2 does not expose a plugin terminal-query seam. Plugins must
+ * dsh-TUI does not expose a plugin terminal-query seam. Plugins must
  * therefore not create their own stdin consumers or raw-mode leases: the host
  * owns both through Ink. This module only applies a previously stored result
  * before mount. A future host-owned query service can refresh that cache

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;AAEjF,eAAO,MAAM,IAAI,kBAAkB,CAAA;AAEnC,wDAAwD;AACxD,MAAM,MAAM,MAAM,GAAG,eAAe,CAAA;AAUpC,eAAO,MAAM,MAAM,EAAE,WAAW,CAAC,MAAM,CAQrC,CAAA;AAyBF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CA2D7D"}
+{"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"}

package/lib/types/index.js

@@ -19,7 +19,8 @@ import { installBundledThemes, homeDir } from './themeAssets.js';
 import { startStatusLine } from './statusLine.js';
 import { runFollowSystem } from './autoTheme.js';
 import { registerPinkSettings } from './settingsSection.js';
-export const name = 'dsh-tui-theme';
+import { PLUGIN_ID } from './pluginId.js';
+export const name = PLUGIN_ID;
 // Explicit annotation: the inferred z.dict output references cosmokit's Dict
 // through a pnpm-virtual path, which is not portable in declaration emit
 // (TS2883). Mirrors the official plugin-template's workaround.
@@ -46,12 +47,6 @@ const DEFAULTS = {
     showTurns: true,
     statusScope: 'pink-only',
 };
-/**
- * Backstop delay for the cordis-layer follow decision on hosts without a
- * settings service (see apply). Stays under the host's own 300ms pre-mount
- * settings gate so the pref write still lands before first paint.
- */
-const FOLLOW_FALLBACK_MS = 150;
 /**
  * Wire the pink theme plugin.
  * @param ctx - Cordis context (the plugin's own activation).
@@ -72,16 +67,19 @@ export function apply(ctx, config = {}) {
     if (cordis.autoInstallThemes) {
         const result = installBundledThemes();
         for (const file of result.installed) {
-            ctx.logger.info(`dsh-tui-theme: installed bundled theme "${file}" into ~/.dsh-tui/themes/`);
+            ctx.logger.info(`${PLUGIN_ID}: installed bundled theme "${file}" into ~/.dsh-tui/themes/`);
+        }
+        for (const file of result.repaired) {
+            ctx.logger.warn(`${PLUGIN_ID}: found a corrupt "${file}" in ~/.dsh-tui/themes/, backed it up and reinstalled the bundled copy`);
         }
         for (const file of result.failed) {
-            ctx.logger.warn(`dsh-tui-theme: could not install bundled theme "${file}"`);
+            ctx.logger.warn(`${PLUGIN_ID}: could not install bundled theme "${file}"`);
         }
     }
     // The /settings user layer (settings.yaml) overrides the cordis layer and
     // lands live through scope.watch; both override the hardcoded defaults.
     let effective = cordis;
-    // Background follow applies only an existing cache. dsh-TUI v0.9.2 exposes
+    // Background follow applies only an existing cache. dsh-TUI exposes
     // no plugin terminal-query seam, so a theme plugin must not compete with
     // Ink's stdin reader or raw-mode lease. The /settings layer still determines
     // whether the cached result may control this startup.
@@ -89,24 +87,35 @@ export function apply(ctx, config = {}) {
     const dataDir = join(homeDir(), '.dsh-tui');
     const applyFollow = () => {
         runFollowSystem(dataDir, () => followActive === true, message => {
-            ctx.logger.info(`dsh-tui-theme: ${message}`);
+            ctx.logger.info(`${PLUGIN_ID}: ${message}`);
         });
     };
     registerPinkSettings(ctx, cordis, doc => {
         effective = { ...cordis, ...doc };
-        if (effective.followSystem !== followActive) {
-            followActive = effective.followSystem;
-            if (followActive) {
+        const follow = effective.followSystem === true;
+        if (followActive === undefined) {
+            // First document: align the baseline, not a switch. A value that only
+            // matches the default logs nothing; a user layer that starts enabled
+            // still applies the cache immediately.
+            followActive = follow;
+            if (follow)
+                applyFollow();
+            return;
+        }
+        if (followActive !== follow) {
+            followActive = follow;
+            if (follow) {
                 applyFollow();
             }
             else {
-                ctx.logger.info('dsh-tui-theme: follow: disabled, manual /theme choice preserved');
+                ctx.logger.info(`${PLUGIN_ID}: follow: disabled, manual /theme choice preserved`);
             }
         }
     });
-    // Cached following needs the merged settings document; without the settings
-    // seam the plugin keeps the user's existing theme choice and degrades to
-    // static assets rather than applying a profile default before that document
-    // could arrive.
+    // The follow decision is owned entirely by the /settings layer above: there
+    // is no timer or fallback path on hosts without a settings service — the
+    // plugin keeps the user's existing theme choice and degrades to static
+    // assets rather than applying a profile default before the merged document
+    // can arrive.
     startStatusLine(ctx, () => effective);
 }

package/lib/types/pluginId.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The single plugin identifier shared by every surface that names this
+ * plugin to the host: the cordis plugin name, the tuiStatus contribution
+ * key, and the /settings namespace. These are distinct roles that happen
+ * to carry one value — all three import this constant rather than repeating
+ * the literal, so a rename stays consistent and the test contract (which
+ * re-derives the value from the package name) stays meaningful.
+ * @module dsh-tui-theme/pluginId
+ */
+export declare const PLUGIN_ID = "dsh-tui-theme";
+//# sourceMappingURL=pluginId.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pluginId.d.ts","sourceRoot":"","sources":["../../src/pluginId.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,kBAAkB,CAAA"}

package/lib/types/pluginId.js

@@ -0,0 +1,10 @@
+/**
+ * The single plugin identifier shared by every surface that names this
+ * plugin to the host: the cordis plugin name, the tuiStatus contribution
+ * key, and the /settings namespace. These are distinct roles that happen
+ * to carry one value — all three import this constant rather than repeating
+ * the literal, so a rename stays consistent and the test contract (which
+ * re-derives the value from the package name) stays meaningful.
+ * @module dsh-tui-theme/pluginId
+ */
+export const PLUGIN_ID = 'dsh-tui-theme';

package/lib/types/settingsSection.d.ts

@@ -12,7 +12,7 @@
  * Both services are consumed through `ctx.inject`, not apply-time `get`
  * probes: this row may start before the host's service rows, and the inject
  * fires whenever each service actually registers.
- * @module dsh-tui-pink-theme/settingsSection
+ * @module dsh-tui-theme/settingsSection
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { StatusOptions } from './statusLine.js';

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;AAEpD,+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;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"}

package/lib/types/settingsSection.js

@@ -12,10 +12,11 @@
  * Both services are consumed through `ctx.inject`, not apply-time `get`
  * probes: this row may start before the host's service rows, and the inject
  * fires whenever each service actually registers.
- * @module dsh-tui-pink-theme/settingsSection
+ * @module dsh-tui-theme/settingsSection
  */
 import { settingsNamespace } from '@deepseek-ai/dsh-settings';
 import z from '@deepseek-ai/schemastery';
+import { PLUGIN_ID } from './pluginId.js';
 /**
  * Register the settings namespace (mirror the resolved document to the
  * caller) and, separately, the /settings section for it. Each part waits for
@@ -31,7 +32,7 @@ export function registerPinkSettings(ctx, cordis, onDoc) {
     ctx.inject(['settings'], settingsCtx => {
         const settings = settingsCtx.settings;
         try {
-            const scope = settings.register(settingsNamespace('dsh-tui-theme'), z.object({
+            const scope = settings.register(settingsNamespace(PLUGIN_ID), z.object({
                 followSystem: z.boolean(),
                 showGlyph: z.boolean(),
                 showClock: z.boolean(),
@@ -58,7 +59,7 @@ export function registerPinkSettings(ctx, cordis, onDoc) {
         catch (error) {
             // A duplicate registration (hot reload race) or a stricter host must
             // not take the plugin — or the TUI — down.
-            settingsCtx.logger.warn(`dsh-tui-pink-theme: settings namespace registration failed: ${String(error)}`);
+            settingsCtx.logger.warn(`dsh-tui-theme: settings namespace registration failed: ${String(error)}`);
         }
     });
     ctx.inject(['tuiSettingsSections'], sectionsCtx => {
@@ -71,24 +72,24 @@ export function registerPinkSettings(ctx, cordis, onDoc) {
         catch (error) {
             // A duplicate registration (hot reload race) or a stricter host must
             // not take the plugin — or the TUI — down.
-            sectionsCtx.logger.warn(`dsh-tui-pink-theme: settings section registration failed: ${String(error)}`);
+            sectionsCtx.logger.warn(`dsh-tui-theme: settings section registration failed: ${String(error)}`);
         }
     });
 }
 /** The declarative /settings block (labels bilingual, zh via descriptions). */
 function sectionDefinition(cordis) {
     return {
-        ns: 'dsh-tui-theme',
+        ns: PLUGIN_ID,
         title: 'pink-theme',
         descriptions: { zh: 'pink-theme' },
         fields: [
             {
                 path: ['followSystem'],
-                label: 'Use cached terminal background',
-                descriptions: { zh: '使用已缓存的终端背景' },
-                hint: 'Apply a previously saved terminal background result at startup. dsh-TUI 0.9.2 does not expose a safe plugin query, so this plugin does not refresh the cache.',
+                label: 'Apply saved terminal background',
+                descriptions: { zh: '应用上次保存的终端背景' },
+                hint: 'Apply a previously saved terminal background result at startup. dsh-TUI does not expose a safe plugin query, so this plugin does not refresh the cache.',
                 hintDescriptions: {
-                    zh: '启动时应用此前保存的终端背景结果。dsh-TUI 0.9.2 未提供安全的插件查询接缝，因此本插件不会刷新该缓存。',
+                    zh: '启动时应用此前保存的终端背景结果。dsh-TUI 未提供安全的插件查询接缝，因此本插件不会刷新该缓存。',
                 },
                 kind: 'boolean',
                 format: (value) => String(value ?? cordis.followSystem),

package/lib/types/statusLine.d.ts

@@ -10,7 +10,7 @@
  * pink theme is active (checked per render with the host's own theme
  * precedence, so a mid-session /theme switch takes effect on the next tick);
  * `statusScope: 'all-themes'` opts it into every other theme too.
- * @module dsh-tui-pink-theme/statusLine
+ * @module dsh-tui-theme/statusLine
  */
 import type { Context } from '@deepseek-ai/cordis';
 /** Which themes the blossom line renders under. */

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

@@ -1 +1 @@
-{"version":3,"file":"statusLine.d.ts","sourceRoot":"","sources":["../../src/statusLine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAOlD,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,YAAY,CAAA;AAEpD,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,sCAAsC;IACtC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED,mCAAmC;AACnC,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAA;AAwCrD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,GAAG,IAAI,CA8DvF"}
+{"version":3,"file":"statusLine.d.ts","sourceRoot":"","sources":["../../src/statusLine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAQlD,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,YAAY,CAAA;AAEpD,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,sCAAsC;IACtC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED,mCAAmC;AACnC,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAA;AA+CrD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,GAAG,IAAI,CA8DvF"}

package/lib/types/statusLine.js

@@ -10,13 +10,16 @@
  * pink theme is active (checked per render with the host's own theme
  * precedence, so a mid-session /theme switch takes effect on the next tick);
  * `statusScope: 'all-themes'` opts it into every other theme too.
- * @module dsh-tui-pink-theme/statusLine
+ * @module dsh-tui-theme/statusLine
  */
 import { join } from 'node:path';
 import { homeDir } from './themeAssets.js';
 import { readThemePref } from './autoTheme.js';
+import { PLUGIN_ID } from './pluginId.js';
 const GLYPH = '✿';
-const STATUS_KEY = 'dsh-tui-theme';
+// The tuiStatus contribution key (same value as the settings namespace and
+// the cordis plugin name — one literal would be three drift risks).
+const STATUS_KEY = PLUGIN_ID;
 const CLOCK_TICK_MS = 15_000;
 /** The bundled themes this garnish belongs to. */
 const PINK_THEMES = new Set(['pink-night', 'pink-day', 'pink-ansi']);
@@ -25,6 +28,11 @@ const PINK_THEMES = new Set(['pink-night', 'pink-day', 'pink-ansi']);
  * then the persisted ~/.dsh-tui/theme.json pref. The unforced path (OSC 11
  * auto-detection) only ever resolves to a builtin palette, never a pink one,
  * so "no pref" means non-pink.
+ *
+ * This deliberately mirrors the host's ThemeProvider resolution chain
+ * (`components/design-system/ThemeProvider.tsx`, baseline dsh-TUI 0.9.3);
+ * keep the two in sync if the host adds a precedence layer. If the host ever
+ * exposes a theme-query seam for plugins, prefer that over this re-read.
  */
 function activeThemeName(dataDir) {
     const env = process.env.DSH_TUI_THEME;

package/lib/types/themeAssets.d.ts

@@ -3,15 +3,20 @@
  *
  * Copies the package's themes/*.json into ~/.dsh-tui/themes/ on boot. Only
  * files that do not exist yet are written — a user's edited or same-named
- * theme file is never overwritten. Every failure is contained per file: a
- * theme garnish must never break the TUI's boot.
- * @module dsh-tui-pink-theme/themeAssets
+ * theme file is never overwritten. The one exception is a target that no
+ * longer parses as JSON (a torn write from an interrupted installation):
+ * that file is backed up under a .corrupt-<timestamp> name and replaced, so
+ * a crash can never shadow a bundled theme forever. Every failure is
+ * contained per file: a theme garnish must never break the TUI's boot.
+ * @module dsh-tui-theme/themeAssets
  */
 export interface ThemeInstallResult {
     /** Files newly written into the target directory. */
     readonly installed: readonly string[];
     /** Files already present in the target directory (left untouched). */
     readonly skipped: readonly string[];
+    /** Corrupt targets backed up and reinstalled (self-heal). */
+    readonly repaired: readonly string[];
     /** Files that could not be installed (per-file failures). */
     readonly failed: readonly string[];
 }

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

@@ -1 +1 @@
-{"version":3,"file":"themeAssets.d.ts","sourceRoot":"","sources":["../../src/themeAssets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;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,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,CA+BpB"}
+{"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"}

package/lib/types/themeAssets.js

@@ -3,11 +3,14 @@
  *
  * Copies the package's themes/*.json into ~/.dsh-tui/themes/ on boot. Only
  * files that do not exist yet are written — a user's edited or same-named
- * theme file is never overwritten. Every failure is contained per file: a
- * theme garnish must never break the TUI's boot.
- * @module dsh-tui-pink-theme/themeAssets
+ * theme file is never overwritten. The one exception is a target that no
+ * longer parses as JSON (a torn write from an interrupted installation):
+ * that file is backed up under a .corrupt-<timestamp> name and replaced, so
+ * a crash can never shadow a bundled theme forever. Every failure is
+ * contained per file: a theme garnish must never break the TUI's boot.
+ * @module dsh-tui-theme/themeAssets
  */
-import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -33,13 +36,14 @@ export function themesTargetDir() {
 export function installBundledThemes(targetDir = themesTargetDir(), sourceDir = bundledThemesDir()) {
     const installed = [];
     const skipped = [];
+    const repaired = [];
     const failed = [];
     let files;
     try {
         files = readdirSync(sourceDir).filter(entry => entry.toLowerCase().endsWith('.json'));
     }
     catch {
-        return { installed, skipped, failed: [sourceDir] };
+        return { installed, skipped, repaired, failed: [sourceDir] };
     }
     for (const file of files) {
         const target = join(targetDir, file);
@@ -53,7 +57,10 @@ export function installBundledThemes(targetDir = themesTargetDir(), sourceDir =
             }
             catch (error) {
                 if (error.code === 'EEXIST') {
-                    skipped.push(file);
+                    if (healCorruptTarget(target, text))
+                        repaired.push(file);
+                    else
+                        skipped.push(file);
                 }
                 else {
                     failed.push(file);
@@ -64,5 +71,38 @@ export function installBundledThemes(targetDir = themesTargetDir(), sourceDir =
             failed.push(file);
         }
     }
-    return { installed, skipped, failed };
+    return { installed, skipped, repaired, failed };
+}
+/**
+ * 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).
+ */
+function healCorruptTarget(target, text) {
+    let existing;
+    try {
+        existing = readFileSync(target, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    try {
+        JSON.parse(existing);
+        return false;
+    }
+    catch {
+        // Proven corrupt: fall through to backup and reinstall.
+    }
+    try {
+        renameSync(target, `${target}.corrupt-${Date.now()}`);
+        writeFileSync(target, text, { flag: 'wx' });
+        return true;
+    }
+    catch {
+        return false;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tui-theme",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Sakura-pink themes for dsh-TUI with optional cached background follow (pink-day/pink-night), a blossom status line, and a /settings section. No shortcuts, no commands.",
   "type": "module",
   "main": "lib/types/index.js",
@@ -25,9 +25,10 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "preverify": "npm run build",
     "verify": "node scripts/verify.mjs",
     "verify:package": "node scripts/verify-package.mjs",
-    "verify:host": "node scripts/headless-order-test.mjs && node --import tsx/esm scripts/validate-themes-against-host.mjs",
+    "verify:host": "npm run build && node scripts/headless-order-test.mjs && node --import tsx/esm scripts/validate-themes-against-host.mjs",
     "release:check": "npm run build && npm run verify && npm run verify:package",
     "prepack": "npm run release:check"
   },

package/scripts/expected-settings-contract.mjs

@@ -0,0 +1,53 @@
+/**
+ * The settings contract this plugin publishes to the host's /settings form:
+ * the namespace, every field's path + kind, and the select options of the
+ * status scope. Both verification scripts assert against this single copy so
+ * a field addition or reorder only needs one edit here — the assertions are
+ * order-insensitive, so reordering the fields in sectionDefinition() is not
+ * an error by itself.
+ *
+ * The namespace is derived from the package name, mirroring PLUGIN_ID in
+ * src/pluginId.ts: if the package and its registration id ever drift apart,
+ * the headless order test fails on the namespace comparison instead of
+ * silently testing the wrong section.
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export const SETTINGS_NAMESPACE = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).name
+
+/** [path, kind] pairs; compare as a set, never positionally. */
+export const SETTINGS_FIELDS = [
+  [['followSystem'], 'boolean'],
+  [['showGlyph'], 'boolean'],
+  [['showClock'], 'boolean'],
+  [['showTurns'], 'boolean'],
+  [['statusScope'], 'select'],
+]
+
+/** The values the statusScope select must expose, looked up by field path. */
+export const STATUS_SCOPE_FIELD_PATH = ['statusScope']
+export const STATUS_SCOPE_OPTIONS = ['pink-only', 'all-themes']
+
+/** Assert a section object (ns + fields) matches the contract. */
+export function assertSettingsContract(assert, section) {
+  assert.equal(section.ns, SETTINGS_NAMESPACE, 'settings namespace must match')
+  const actual = section.fields.map(field => [field.path, field.kind])
+  const expected = SETTINGS_FIELDS.map(([path, kind]) => `${JSON.stringify(path)}:${kind}`)
+  assert.deepEqual(
+    actual.map(([path, kind]) => `${JSON.stringify(path)}:${kind}`).sort(),
+    [...expected].sort(),
+    'settings fields must remain compatible with the host form contract',
+  )
+  const scopeField = section.fields.find(
+    field => JSON.stringify(field.path) === JSON.stringify(STATUS_SCOPE_FIELD_PATH),
+  )
+  assert.ok(scopeField, 'statusScope field must exist (looked up by path, not position)')
+  assert.deepEqual(
+    scopeField.options?.map(option => option.value),
+    STATUS_SCOPE_OPTIONS,
+    'status scope must expose both supported select values',
+  )
+}

package/scripts/headless-order-test.mjs

@@ -3,6 +3,10 @@
  * plugin before the extension services to exercise late service injection.
  *
  * DSH_TUI_ADAPTER_DIR must point at dsh-TUI's lib/types/dsh-adapter directory.
+ * Script-side floor: the adapter must be a built dsh-TUI >= 0.9.0 — the
+ * settings-sections module and its getHostSettingsSections probe landed there.
+ * Set DSH_TUI_EXPECTED_VERSION only when an explicit release baseline needs
+ * to be pinned; ordinary development verifies the supplied host as-is.
  */
 import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
@@ -10,6 +14,13 @@ import { join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import assert from 'node:assert/strict'
+import { assertSettingsContract, SETTINGS_NAMESPACE } from './expected-settings-contract.mjs'
+
+// The tuiStatus contribution key and the effect-ledger resource id. Deliberately
+// a separate constant from SETTINGS_NAMESPACE: they hold the same value today
+// (see src/pluginId.ts), but this assertion pins that equality while the status
+// snapshot / ledger filters below must never silently track the namespace.
+const STATUS_CONTRIBUTION_KEY = SETTINGS_NAMESPACE
 
 const pluginRoot = fileURLToPath(new URL('..', import.meta.url))
 const adapter = process.env.DSH_TUI_ADAPTER_DIR
@@ -26,7 +37,13 @@ if (!existsSync(hostPackagePath)) {
   throw new Error(`dsh-TUI package metadata not found above adapter at ${adapter}`)
 }
 const hostPackage = JSON.parse(readFileSync(hostPackagePath, 'utf8'))
-assert.equal(hostPackage.version, '0.9.2', `expected dsh-TUI adapter 0.9.2, received ${hostPackage.version}`)
+assert.match(hostPackage.version, /^\d+\.\d+\.\d+(?:[-+].+)?$/u, 'host adapter must declare a version')
+const expectedVersion = process.env.DSH_TUI_EXPECTED_VERSION
+if (expectedVersion !== undefined && expectedVersion !== '') {
+  assert.equal(hostPackage.version, expectedVersion, `expected dsh-TUI adapter ${expectedVersion}, received ${hostPackage.version}`)
+} else {
+  console.log(`* host adapter ${hostPackage.version} (no explicit version pin)`)
+}
 
 const sandbox = mkdtempSync(join(tmpdir(), 'pink-order-'))
 process.env.USERPROFILE = sandbox
@@ -36,32 +53,80 @@ const dataDir = join(sandbox, '.dsh-tui')
 mkdirSync(dataDir, { recursive: true })
 writeFileSync(join(dataDir, 'theme.json'), JSON.stringify({ theme: 'pink-night' }, null, 2))
 
+// Guard the script-side floor explicitly: settings-sections.js first shipped
+// in dsh-TUI 0.9.0, so a bare ERR_MODULE_NOT_FOUND from a dynamic import
+// would hide the real reason a host tree is too old for this test.
+const settingsSectionsPath = join(adapter, 'settings-sections.js')
+if (!existsSync(settingsSectionsPath)) {
+  throw new Error(
+    `dsh-TUI adapter at ${adapter} has no settings-sections.js; this integration test needs a host >= 0.9.0`,
+  )
+}
+
 const req = createRequire(join(adapter, 'extensions.js'))
 const { Context } = await import(pathToFileURL(req.resolve('@deepseek-ai/cordis')).href)
 const extensions = await import(pathToFileURL(join(adapter, 'extensions.js')).href)
 const ledgerModule = await import(pathToFileURL(join(adapter, 'effect-ledger.js')).href)
 const statusModule = await import(pathToFileURL(join(adapter, 'status.js')).href)
+const settingsSectionsModule = await import(pathToFileURL(settingsSectionsPath).href)
 const pink = await import(pathToFileURL(join(pluginRoot, 'lib', 'types', 'index.js')).href)
 
 const app = new Context()
 await app.plugin(ledgerModule.default)
 await app.plugin(pink)
 await app.plugin(extensions.default ?? extensions)
-await new Promise(resolve => setTimeout(resolve, 300))
+await app.plugin(settingsSectionsModule.default ?? settingsSectionsModule)
 
-const ledger = join(dataDir, 'effect-ledger.jsonl')
-const pinkBinds = existsSync(ledger)
-  ? readFileSync(ledger, 'utf8').trim().split('\n')
-      .filter(Boolean)
-      .map(line => JSON.parse(line))
-      .filter(entry => entry.resource?.id === 'dsh-tui-theme')
-  : []
-const runtime = app.get('tuiStatus')
-const snapshot = statusModule.getHostStatusStore(runtime)?.getSnapshot()
+// The late injections resolve asynchronously; poll for every observable
+// outcome instead of sleeping a fixed wall-clock delay.
+const READY_TIMEOUT_MS = 5_000
+const POLL_INTERVAL_MS = 25
+const collectBinds = () => {
+  const ledger = join(dataDir, 'effect-ledger.jsonl')
+  return existsSync(ledger)
+    ? readFileSync(ledger, 'utf8').trim().split('\n')
+        .filter(Boolean)
+        .map(line => JSON.parse(line))
+        .filter(entry => entry.resource?.id === STATUS_CONTRIBUTION_KEY)
+    : []
+}
+const readState = () => {
+  const runtime = app.get('tuiStatus')
+  const settingsRuntime = app.get('tuiSettingsSections')
+  const settingsHost = settingsSectionsModule.getHostSettingsSections(settingsRuntime)
+  return {
+    pinkBinds: collectBinds(),
+    snapshot: statusModule.getHostStatusStore(runtime)?.getSnapshot(),
+    settingsSection: settingsHost?.list().find(section => section.ns === SETTINGS_NAMESPACE),
+  }
+}
 
-assert.ok(pinkBinds.length > 0, 'plugin must bind through the late status service')
+let state = readState()
+const deadline = Date.now() + READY_TIMEOUT_MS
+while (
+  (state.pinkBinds.length === 0 ||
+    !state.snapshot?.some?.(entry => entry.key === STATUS_CONTRIBUTION_KEY) ||
+    state.settingsSection === undefined) &&
+  Date.now() < deadline
+) {
+  await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS))
+  state = readState()
+}
+
+const { pinkBinds, snapshot, settingsSection } = state
+assert.equal(
+  STATUS_CONTRIBUTION_KEY,
+  SETTINGS_NAMESPACE,
+  'the status contribution key must stay equal to the settings namespace (src/pluginId.ts)',
+)
+assert.ok(pinkBinds.length > 0, `plugin must bind through the late status service within ${READY_TIMEOUT_MS}ms`)
+assert.ok(
+  snapshot?.some?.(entry => entry.key === STATUS_CONTRIBUTION_KEY),
+  `status store must contain the plugin contribution within ${READY_TIMEOUT_MS}ms`,
+)
 assert.ok(
-  snapshot?.some?.(entry => entry.key === 'dsh-tui-theme'),
-  'status store must contain the plugin contribution',
+  settingsSection,
+  `plugin must register its /settings section through the late settings service within ${READY_TIMEOUT_MS}ms`,
 )
-console.log(`✓ headless order: ${pinkBinds.length} ledger bind(s), visible status contribution`)
+assertSettingsContract(assert, settingsSection)
+console.log(`OK headless order: ${pinkBinds.length} ledger bind(s), status contribution, settings section`)

package/scripts/validate-themes-against-host.mjs

@@ -1,14 +1,18 @@
 /**
- * Validate bundled themes against the real dsh-TUI source implementation.
+ * Validate bundled themes against matching dsh-TUI source and runtime modules.
  * DSH_TUI_SOURCE_ROOT must point at a dsh-TUI source checkout.
+ * DSH_TUI_ADAPTER_DIR must point at the matching lib/types/dsh-adapter directory.
+ * Set DSH_TUI_EXPECTED_VERSION only when an explicit release baseline needs
+ * to be pinned; ordinary development verifies the supplied host as-is.
  *
- * Run with: npx -y tsx scripts/validate-themes-against-host.mjs
+ * Run with: node --import tsx/esm scripts/validate-themes-against-host.mjs
  */
 import { existsSync, mkdtempSync, readFileSync, readdirSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import assert from 'node:assert/strict'
+import ts from 'typescript'
 
 const pluginRoot = fileURLToPath(new URL('..', import.meta.url))
 const sourceRoot = process.env.DSH_TUI_SOURCE_ROOT
@@ -28,21 +32,80 @@ if (!existsSync(hostPackagePath)) {
   throw new Error(`dsh-TUI package metadata not found at ${hostPackagePath}`)
 }
 const hostPackage = JSON.parse(readFileSync(hostPackagePath, 'utf8'))
-assert.equal(hostPackage.version, '0.9.2', `expected dsh-TUI source 0.9.2, received ${hostPackage.version}`)
+assert.match(hostPackage.version, /^\d+\.\d+\.\d+(?:[-+].+)?$/u, 'host source must declare a version')
+
+const adapter = process.env.DSH_TUI_ADAPTER_DIR
+if (adapter === undefined || adapter === '') {
+  throw new Error('DSH_TUI_ADAPTER_DIR must point at dsh-TUI lib/types/dsh-adapter for this host theme validation.')
+}
+const adapterRoot = resolve(adapter)
+const runtimeThemePath = join(adapterRoot, '..', 'theme.js')
+const runtimeCustomThemePath = join(adapterRoot, '..', 'customTheme.js')
+if (!existsSync(runtimeThemePath) || !existsSync(runtimeCustomThemePath)) {
+  throw new Error(`dsh-TUI compiled theme modules not found above adapter at ${adapterRoot}`)
+}
+const adapterPackagePath = join(adapterRoot, '..', '..', '..', 'package.json')
+if (!existsSync(adapterPackagePath)) {
+  throw new Error(`dsh-TUI package metadata not found above adapter at ${adapterRoot}`)
+}
+const adapterPackage = JSON.parse(readFileSync(adapterPackagePath, 'utf8'))
+assert.equal(
+  adapterPackage.version,
+  hostPackage.version,
+  `source ${hostPackage.version} and adapter ${adapterPackage.version} must be the same dsh-TUI version`,
+)
+const expectedVersion = process.env.DSH_TUI_EXPECTED_VERSION
+if (expectedVersion !== undefined && expectedVersion !== '') {
+  assert.equal(hostPackage.version, expectedVersion, `expected dsh-TUI ${expectedVersion}, received ${hostPackage.version}`)
+} else {
+  console.log(`* host source and adapter ${hostPackage.version} (no explicit version pin)`)
+}
 
 const sandboxHome = mkdtempSync(join(tmpdir(), 'pink-theme-host-validate-'))
 process.env.USERPROFILE = sandboxHome
 process.env.HOME = sandboxHome
 
 const themesDir = join(pluginRoot, 'themes')
-const { parseCustomTheme, buildTheme } = await import(pathToFileURL(customThemePath).href)
+const { parseCustomTheme, buildTheme } = await import(pathToFileURL(runtimeCustomThemePath).href)
 const { getTheme, isLightThemeActive, registerCustomThemeResolver } = await import(
-  pathToFileURL(themePath).href
+  pathToFileURL(runtimeThemePath).href,
 )
 
-const allKeys = Object.keys(getTheme('dark'))
+function readThemeKeysFromSource(path) {
+  const source = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true)
+  const declaration = source.statements.find(
+    statement => ts.isTypeAliasDeclaration(statement) && statement.name.text === 'Theme',
+  )
+  assert.ok(declaration && ts.isTypeLiteralNode(declaration.type), 'host Theme must remain a type literal')
+  const keys = declaration.type.members.flatMap(member => {
+    if (!ts.isPropertySignature(member) || member.name === undefined) return []
+    if (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name)) return [member.name.text]
+    return []
+  })
+  assert.ok(keys.length > 0, 'host Theme must declare at least one color key')
+  return keys
+}
+
+const allKeys = readThemeKeysFromSource(themePath)
+assert.deepEqual(
+  [...Object.keys(getTheme('dark'))].sort(),
+  [...allKeys].sort(),
+  'compiled theme keys must match the checked-out host source',
+)
 assert.ok(allKeys.length >= 90, 'host Theme key count drifted; re-check coverage')
 
+const settingsKeys = [
+  'promptBorder',
+  'selectionBg',
+  'permission',
+  'suggestion',
+  'success',
+  'inactive',
+  'subtle',
+  'warning',
+  'error',
+]
+
 function parseColor(value) {
   if (/^#[0-9A-Fa-f]{6}$/.test(value)) {
     const n = Number.parseInt(value.slice(1), 16)
@@ -86,6 +149,12 @@ for (const file of readdirSync(themesDir).filter(name => name.endsWith('.json'))
   assert.deepEqual(warnings, [], `${file} must produce zero host warnings`)
   const missing = allKeys.filter(key => key !== 'userMessageBackground' && !(key in spec.colors))
   assert.deepEqual(missing, [], `${file} must cover every Theme key`)
+  const missingSettingsKeys = settingsKeys.filter(key => !(key in spec.colors))
+  assert.deepEqual(
+    missingSettingsKeys,
+    [],
+    `${file} must cover every color used by the dsh-TUI settings cards and checkbox chips`,
+  )
 
   const theme = buildTheme(spec)
   built[spec.name] = theme
@@ -96,14 +165,29 @@ for (const [name, light] of Object.entries(expectedLight)) {
   assert.equal(isLightThemeActive(name), light, `${name} identity via resolver`)
 }
 
+// Backgrounds: the /settings section renders inside the session screen, so
+// unfocused rows sit on the theme's terminal background while a focused row
+// gets selectionBg (screens/Settings.tsx CardRow). success/inactive are the
+// checkbox chip colors there ([✓] vs [  ]).
 const cases = [
   ['pink-night', 'text', '#1E1E1E', 4.5],
   ['pink-night', 'claude', '#1E1E1E', 3.0],
   ['pink-night', 'inactive', '#1E1E1E', 2.5],
+  ['pink-night', 'success', '#1E1E1E', 4.5],
+  ['pink-night', 'success', '#55303E', 3.0],
+  ['pink-night', 'inactive', '#55303E', 3.0],
   ['pink-day', 'text', '#F6F3ED', 4.5],
   ['pink-day', 'claude', '#F6F3ED', 3.0],
   ['pink-day', 'inactive', '#F6F3ED', 2.5],
+  ['pink-day', 'success', '#F6F3ED', 3.0],
+  ['pink-day', 'success', '#F3D7E0', 2.5],
+  ['pink-day', 'inactive', '#F3D7E0', 2.5],
 ]
+// pink-ansi is intentionally absent from the contrast cases: every one of its
+// colors is an `ansi:` palette token with no pinned RGB value, so no numeric
+// ratio is assertable here — the host renders whatever the user's terminal
+// palette defines. Its settings keys are still covered by the per-theme
+// key-coverage assertions above.
 for (const [theme, key, background, minimum] of cases) {
   const foregroundRgb = parseColor(built[theme][key])
   const backgroundRgb = parseColor(background)
@@ -112,4 +196,4 @@ for (const [theme, key, background, minimum] of cases) {
   assert.ok(ratio >= minimum, `${theme}.${key} contrast ${ratio.toFixed(2)} >= ${minimum}`)
 }
 
-console.log(`✓ host theme validation: ${Object.keys(built).length} themes, ${allKeys.length - 1} keys each`)
+console.log(`OK host theme validation: ${Object.keys(built).length} themes, ${allKeys.length - 1} keys each, settings colors covered`)

package/scripts/verify-package.mjs

@@ -32,6 +32,8 @@ for (const required of [
   'lib/types/index.d.ts',
   'lib/types/autoTheme.js',
   'lib/types/autoTheme.d.ts',
+  'lib/types/pluginId.js',
+  'lib/types/pluginId.d.ts',
   'lib/types/settingsSection.js',
   'lib/types/settingsSection.d.ts',
   'lib/types/statusLine.js',
@@ -48,6 +50,7 @@ for (const required of [
   'scripts/verify-package.mjs',
   'scripts/headless-order-test.mjs',
   'scripts/validate-themes-against-host.mjs',
+  'scripts/expected-settings-contract.mjs',
 ]) {
   assert.ok(files.has(required), `published package must include ${required}`)
 }

package/scripts/verify.mjs

@@ -1,5 +1,5 @@
 /**
- * Hermetic verification for dsh-tui-pink-theme (no TTY, no real HOME).
+ * Hermetic verification for dsh-tui-theme (no TTY, no real HOME).
  *
  * Points HOME/USERPROFILE at a throwaway sandbox BEFORE importing anything
  * (the same technique the host's scripts/verify-themes.mjs uses), then:
@@ -22,6 +22,7 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { createRequire, syncBuiltinESMExports } from 'node:module'
 import assert from 'node:assert/strict'
+import { assertSettingsContract } from './expected-settings-contract.mjs'
 
 const sandboxHome = mkdtempSync(join(tmpdir(), 'pink-theme-verify-'))
 const originalThemeOverride = process.env.DSH_TUI_THEME
@@ -58,8 +59,8 @@ assert.equal(name, 'dsh-tui-theme')
 
 /** A stub Cordis-like context; every seam optional and recorded. */
 function makeStubCtx({ status, sections, settingsService } = {}) {
-  const record = { handlers: new Map(), disposers: [], statusCalls: [], sectionsCalls: [], registerCalls: [], watchers: [], warnings: [] }
-  const logger = { info: () => {}, warn: msg => record.warnings.push(String(msg)), error: () => {} }
+  const record = { handlers: new Map(), disposers: [], statusCalls: [], sectionsCalls: [], registerCalls: [], watchers: [], warnings: [], infos: [] }
+  const logger = { info: msg => record.infos.push(String(msg)), warn: msg => record.warnings.push(String(msg)), error: () => {} }
   const base = {
     logger,
     get(serviceName) {
@@ -157,11 +158,11 @@ const emit = (record, event, ...args) => {
   const latest = statusCalls.at(-1)[1]
   assert.match(latest, /^✿ · \d{2}:\d{2} · 2✦$/)
 
-  // Settings namespace registered and the section declared.
+  // Settings namespace registered and the section declaration remains within
+  // the shared host form contract.
   assert.equal(settingsRecord.registerCalls.length, 1)
   assert.equal(sectionsCalls.length, 1)
-  assert.equal(sectionsCalls[0].ns, 'dsh-tui-theme')
-  assert.equal(sectionsCalls[0].fields.length, 5)
+  assertSettingsContract(assert, sectionsCalls[0])
 
   // A committed /settings edit lands live on the next render.
   for (const watcher of settingsRecord.watchers) {
@@ -179,6 +180,7 @@ const emit = (record, event, ...args) => {
 {
   const again = installBundledThemes()
   assert.deepEqual(again.installed, [])
+  assert.deepEqual(again.repaired, [])
   assert.equal(again.skipped.length, 3)
 
   // A user-edited same-named file must survive reinstallation.
@@ -380,6 +382,97 @@ const emit = (record, event, ...args) => {
   console.log('✓ filesystem commits: failed atomic writes preserve JSON; competing theme creation skips')
 }
 
+// ── 12a. torn installation: a corrupt target is backed up and reinstalled ───
+{
+  const targetDir = join(sandboxHome, 'heal-target')
+  const sourceDir = join(pluginRoot, 'themes')
+  mkdirSync(targetDir, { recursive: true })
+
+  // A valid user file stays untouched — the never-overwrite rule wins.
+  writeFileSync(join(targetDir, 'pink-night.json'), '{ "user": true }')
+  // A torn write (crash mid-install) leaves invalid JSON behind.
+  writeFileSync(join(targetDir, 'pink-day.json'), '{ "name": "pink-day", "colors": {')
+  const heal = installBundledThemes(targetDir, sourceDir)
+  assert.deepEqual(heal.repaired, ['pink-day.json'], 'the corrupt target is reported as repaired')
+  assert.equal(heal.skipped.includes('pink-night.json'), true)
+  assert.equal(heal.failed.length, 0)
+  assert.equal(
+    JSON.parse(readFileSync(join(targetDir, 'pink-night.json'), 'utf8')).user,
+    true,
+    'valid user file untouched',
+  )
+  const reinstalled = JSON.parse(readFileSync(join(targetDir, 'pink-day.json'), 'utf8'))
+  assert.equal(reinstalled.name, 'pink-day')
+  const backups = readdirSync(targetDir).filter(entry =>
+    entry.startsWith('pink-day.json.corrupt-'),
+  )
+  assert.equal(backups.length, 1, 'the damaged file is preserved as a timestamped backup')
+  assert.equal(readFileSync(join(targetDir, backups[0]), 'utf8'), '{ "name": "pink-day", "colors": {')
+
+  // Next boot: everything parses, so no churn.
+  const steady = installBundledThemes(targetDir, sourceDir)
+  assert.deepEqual(steady.repaired, [])
+  assert.deepEqual(steady.installed, [])
+  assert.equal(steady.skipped.length, 3)
+
+  // A target the process cannot even read is not proven corrupt — keep skipping.
+  const unreadable = join(targetDir, 'pink-ansi.json')
+  const originalRead = builtinFs.readFileSync
+  try {
+    builtinFs.readFileSync = (path, ...rest) => {
+      if (String(path) === unreadable) throw new Error('EBUSY: locked')
+      return originalRead(path, ...rest)
+    }
+    syncBuiltinESMExports()
+    const blocked = installBundledThemes(targetDir, sourceDir)
+    assert.deepEqual(blocked.repaired, [])
+    assert.equal(blocked.skipped.includes('pink-ansi.json'), true)
+  } finally {
+    builtinFs.readFileSync = originalRead
+    syncBuiltinESMExports()
+  }
+  console.log('✓ torn installation: corrupt target backed up and reinstalled; user files and unreadable targets untouched')
+}
+
+// ── 12b. follow logging: the first settings doc is a baseline, not a flip ──
+{
+  // Default user layer (empty doc): no spurious "follow: disabled" line.
+  const settingsRecord = { registerCalls: [], watchers: [] }
+  const { ctx, record } = makeStubCtx({ settingsService: fakeSettingsService(settingsRecord, {}) })
+  apply(ctx)
+  assert.equal(
+    record.infos.some(message => message.includes('follow: disabled')),
+    false,
+    'a baseline doc matching the default must not log a disabled flip',
+  )
+
+  // User layer that starts enabled: the cache applies during the baseline.
+  const dataDir = join(sandboxHome, '.dsh-tui')
+  writeFileSync(join(dataDir, 'theme-follow.json'), JSON.stringify({ light: true, at: 1 }))
+  const enabledRecord = { registerCalls: [], watchers: [] }
+  const { ctx: enabledCtx, record: enabledInfo } = makeStubCtx({
+    status: fakeStatus([]),
+    sections: fakeSections([]),
+    settingsService: fakeSettingsService(enabledRecord, { followSystem: true }),
+  })
+  apply(enabledCtx)
+  assert.equal(readThemePref(dataDir), 'pink-day', 'an enabled baseline applies the cached background')
+  assert.equal(
+    enabledInfo.infos.some(message => message.includes('follow: disabled')),
+    false,
+  )
+
+  // A real toggle keeps its log.
+  for (const watcher of enabledRecord.watchers) watcher({ followSystem: false })
+  assert.equal(
+    enabledInfo.infos.filter(message => message.includes('follow: disabled')).length,
+    1,
+    'disabling follow after the baseline logs exactly once',
+  )
+  assert.equal(readThemePref(dataDir), 'pink-day', 'the manual choice stays intact')
+  console.log('✓ follow logging: baseline docs stay quiet, real toggles still log')
+}
+
 // ── 12. status injection: session handlers die with tuiStatus activation ────
 {
   const outerHandlers = new Map()