dsh-tui-theme 0.3.2 → 0.5.0

package/lib/types/index.js

@@ -4,8 +4,8 @@
  * 个性化全部走既有接缝，不注册快捷键、不注册命令、不拦截任何输入：
  * - 接缝四（主题）：内置三套粉色 JSON（pink-night / pink-day / pink-ansi），
  *   启动时复制进 ~/.dsh-tui/themes/（仅缺失时，绝不覆盖用户已有文件）；
- * - 自动跟随：检测终端/系统背景色（OSC 11，与宿主同阈值），在昼樱/夜樱
- *   间自动切换——pink 版的 auto；
+ * - 缓存背景跟随：安全应用已有的终端背景缓存，在昼樱/夜樱间切换；
+ *   dsh-TUI 未提供插件终端查询接缝时，不直接读写 stdin、raw mode 或 OSC 11；
  * - 接缝十一（状态行）：输入框上方一行小装饰（✿ · 时钟 · 本轮轮数）；
  * - 接缝六（设置区块）：/settings 里一个可编辑面板，即时生效。
  *
@@ -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,56 +67,55 @@ 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 honors the MERGED knob (cordis layer overlaid by the
-    // /settings user layer), so the decision cannot be taken synchronously at
-    // apply(): the user layer is only readable once the settings service
-    // answers. The settings callback still fires before the host's React tree
-    // mounts (the host gates its own mount on the same service, probed
-    // against 0.9.0), so the pref write decides this boot exactly like a sync
-    // write would, and toggling followSystem in /settings re-decides live.
+    // 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.
     let followActive;
     const dataDir = join(homeDir(), '.dsh-tui');
-    // Live gate for in-flight detections: a reply that lands after the user
-    // turned follow off must not rewrite the pref.
-    const followEnabled = () => followActive === true;
-    const startFollow = () => {
-        runFollowSystem(dataDir, followEnabled, message => {
-            ctx.logger.info(`dsh-tui-theme: ${message}`);
+    const applyFollow = () => {
+        runFollowSystem(dataDir, () => followActive === true, message => {
+            ctx.logger.info(`${PLUGIN_ID}: ${message}`);
         });
     };
     registerPinkSettings(ctx, cordis, doc => {
         effective = { ...cordis, ...doc };
-        if (effective.followSystem !== followActive) {
-            followActive = effective.followSystem;
-            if (followActive) {
-                startFollow();
+        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`);
             }
         }
     });
-    // Degradation backstop for hosts that never provide a settings service:
-    // the inject callback never fires there, so the cordis-layer decision
-    // applies instead. The delay lets any pending service registration (and
-    // its callback) land first — it no-ops once followActive is settled, and
-    // stays inside the host's own 300ms pre-mount settings gate either way.
-    const fallbackTimer = setTimeout(() => {
-        if (followActive === undefined && cordis.followSystem) {
-            followActive = true;
-            startFollow();
-        }
-    }, FOLLOW_FALLBACK_MS);
-    fallbackTimer.unref?.();
-    ctx.effect(() => () => clearTimeout(fallbackTimer));
+    // 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';
@@ -20,7 +20,7 @@ import type { StatusOptions } from './statusLine.js';
 export type PinkSettingsDoc = StatusOptions & {
     /** Install bundled theme JSONs on boot (cordis-config layer only). */
     autoInstallThemes?: boolean;
-    /** Follow the terminal/system background: pink-day ↔ pink-night. */
+    /** Apply a cached terminal background: pink-day <-> pink-night. */
     followSystem?: boolean;
 };
 /**

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,oEAAoE;IACpE,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: 'Follow terminal background',
-                descriptions: { zh: '跟随终端背景' },
-                hint: 'Auto-switch between Pink Day and Pink Night by terminal/system background. First enabling or a background flip applies from the next boot.',
+                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: '按终端/系统背景色在昼樱与夜樱间自动切换。首次开启或背景刚翻转后，自下次启动生效。',
+                    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;
@@ -92,14 +100,14 @@ export function startStatusLine(ctx, getEffective) {
                 // Display garnish only: a rendering hiccup must never travel upward.
             }
         };
-        ctx.on('session/event', (session, event) => {
+        statusCtx.on('session/event', (session, event) => {
             current = session;
             if (event?.type === 'turn/end') {
                 turns.set(session, (turns.get(session) ?? 0) + 1);
             }
             render();
         });
-        ctx.on('session/disposed', session => {
+        statusCtx.on('session/disposed', session => {
             turns.delete(session);
             if (current === session)
                 current = undefined;

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,CA2BpB"}
+{"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 { existsSync, 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,30 +36,73 @@ 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);
         try {
-            const target = join(targetDir, file);
-            if (existsSync(target)) {
-                skipped.push(file);
-                continue;
-            }
             const text = readFileSync(join(sourceDir, file), 'utf8');
             JSON.parse(text); // our own asset, but never write a corrupt file out
             mkdirSync(targetDir, { recursive: true });
-            writeFileSync(target, text);
-            installed.push(file);
+            try {
+                writeFileSync(target, text, { flag: 'wx' });
+                installed.push(file);
+            }
+            catch (error) {
+                if (error.code === 'EEXIST') {
+                    if (healCorruptTarget(target, text))
+                        repaired.push(file);
+                    else
+                        skipped.push(file);
+                }
+                else {
+                    failed.push(file);
+                }
+            }
         }
         catch {
             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,7 +1,7 @@
 {
   "name": "dsh-tui-theme",
-  "version": "0.3.2",
-  "description": "Sakura-pink themes for dsh-TUI with terminal-background auto-follow (pink-day/pink-night), a blossom status line, and a /settings section. No shortcuts, no commands.",
+  "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",
   "types": "lib/types/index.d.ts",
@@ -17,6 +17,7 @@
     "lib",
     "themes",
     "docs",
+    "scripts",
     "cordis.patch.yml"
   ],
   "engines": {
@@ -25,7 +26,11 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "preverify": "npm run build",
-    "verify": "node scripts/verify.mjs"
+    "verify": "node scripts/verify.mjs",
+    "verify:package": "node scripts/verify-package.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"
   },
   "license": "MIT",
   "author": "xiaoxiaohaigui",
@@ -51,19 +56,19 @@
       "patch": "./cordis.patch.yml"
     }
   },
-  "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
-  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.1.1-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6 || ^0.1.1-rc.1"
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6 || ^0.1.1-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.1.1-rc.1",
     "@deepseek-ai/dsh-settings": "^0.1.0-rc.6 || ^0.1.1-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1",
     "@types/node": "^22.0.0",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3"
   }
 }

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',
+  )
+}