dsh-tui-theme 0.3.2 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@
 | 个性化 | 接缝 | 说明 |
 | --- | --- | --- |
 | **三套粉色主题** | 主题（静态资产） | `pink-night` 夜樱 / `pink-day` 昼樱 / `pink-ansi` 樱·ANSI，启动时自动装进 `~/.dsh-tui/themes/` |
-| **自动跟随背景** | 启动时序 | 检测终端/系统背景色（OSC 11，与宿主同阈值），在昼樱/夜樱间自动切换——pink 版的 auto |
+| **缓存背景跟随** | 设置 + 本地缓存 | 可选地应用已有 `theme-follow.json` 的昼樱/夜樱结果；不直接读取终端输入或发送 OSC 查询 |
 | **花符状态行** | `tuiStatus` | 输入框上方一行小装饰：✿ · 时钟 · 实时轮数（默认仅粉主题下显示） |
 | **设置面板** | `tuiSettingsSections` | `/settings` 里一个可编辑区块，改完即时生效 |
 
@@ -15,7 +15,7 @@
 
 | 主题 | 基底 | 风格 |
 | --- | --- | --- |
-| `pink-night` 夜樱 | dark | 深梅紫底、玫瑰粉强调、粉鲸鱼吉祥物，96 键全覆盖 |
+| `pink-night` 夜樱 | dark | 深梅紫底、玫瑰粉强调、粉鲸鱼吉祥物，95 键全覆盖 |
 | `pink-day` 昼樱 | light | 象牙粉底、墨梅正文、柔和玫瑰强调（已通过宿主浅色身份判定） |
 | `pink-ansi` 樱·ANSI | dark-ansi | 16 色 ANSI 回退，品牌色映射到 magenta 系 |
 
@@ -25,40 +25,54 @@
 
 ## 截图
 
-实测于 dsh-tui 0.9.0：
+实测于 dsh-tui 0.9.2：
 
 | 昼樱 `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，也不会读取终端输入。
 
-- 每次启动检测终端背景（跟随系统主题的终端会随系统深浅变化），亮 → `pink-day`，暗 → `pink-night`，写入 `~/.dsh-tui/theme.json`，与宿主 `auto` 伪主题同款行为、同一亮度阈值；
-- 检测结果缓存在 `~/.dsh-tui/theme-follow.json`，因此切换在**启动瞬间**就生效；首次开启或系统刚翻转后的那次启动可能滞后一拍（与宿主 auto “重新选择或重启后跟上”一致）；
-- 开启此功能后 `/theme` 的选择由插件接管（每次启动都会按背景覆写）；关闭它即可恢复手动选择；
+“使用已缓存的终端背景”开启后：
+
+- 启动时读取 `~/.dsh-tui/theme-follow.json` 中已有的 `light` 结果，亮 → `pink-day`，暗 → `pink-night`，并将选择写入 `~/.dsh-tui/theme.json`；
+- 不存在缓存时完全保留当前 `/theme` 选择；0.4.0 不会自行创建或刷新缓存；
+- 默认关闭。该缓存可由之前的兼容版本留下；未来 dsh-TUI 提供宿主拥有的查询接缝后，插件才会安全地恢复刷新能力；
+- 开启后该缓存会在启动时覆盖 `/theme` 的持久选择；关闭即可恢复手动选择；
 - `DSH_TUI_THEME` 环境变量仍然最优先（宿主行为，插件不覆盖环境变量）。
 
 ## 安装
 
 ```sh
 # 方式一：从 npm（已发布）
-dsh plugin --profile dsh-tui add -w dsh-tui-theme
+dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest
+
+# 方式二：本地 tarball（开发/自用；不要直接安装源码目录）
+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
+```
+
+不要以本地源码目录作为依赖安装：其开发 `node_modules` 可能与 dsh-TUI 宿主解析出不同的 Cordis/DSH framework instance，造成插件无法注册服务。
 
-# 方式二：从 GitHub
-dsh plugin --profile dsh-tui add -w github:xiaoxiaohaigui/dsh-tui-theme
+### 升级
 
-# 方式三：本地路径（开发/自用）
-dsh plugin --profile dsh-tui add -w /path/to/dsh-tui-theme
+```sh
+# npm 已发布版本：请求最新版本并刷新 profile 依赖
+dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest
 ```
 
+插件只在主题文件缺失时复制，绝不覆盖你编辑过的 `~/.dsh-tui/themes/pink-*.json`。升级若需要采用包内的新主题资产，请先备份自己的修改，再删除对应主题文件并重启 dsh-TUI 让插件重装。
+
 重启 dsh-TUI 后插件自动把三套主题复制进 `~/.dsh-tui/themes/`（**仅缺失时复制，绝不覆盖你已有的同名文件**），然后：
 
 ```sh
@@ -75,7 +89,7 @@ dsh plugin --profile dsh-tui add -w /path/to/dsh-tui-theme
 
 | 字段 | 默认 | 说明 |
 | --- | --- | --- |
-| `followSystem` | 部署默认开 | 跟随终端背景：昼樱 ↔ 夜樱自动切换 |
+| `followSystem` | `false` | 启动时应用已缓存的终端背景结果（昼樱 ↔ 夜樱）；0.4.0 不刷新缓存 |
 | `showGlyph` | `true` | 花符：开 = ✿ 开头，关 = 不显示 |
 | `showClock` | `true` | 显示 HH:MM 时钟 |
 | `showTurns` | `true` | 显示当前会话轮数（`N✦`，自本次启动起计） |
@@ -85,7 +99,7 @@ dsh plugin --profile dsh-tui add -w /path/to/dsh-tui-theme
 
 ## 受宿主限制、目前无法定制的部分
 
-以下元素的颜色/形态由 dsh-TUI 宿主**硬编码**，不读取任何主题键，主题 JSON 与插件接缝都覆盖不到（dsh-TUI 0.9.0 实测）：
+以下元素的颜色/形态由 dsh-TUI 宿主**硬编码**，不读取任何主题键，主题 JSON 与插件接缝都覆盖不到（dsh-TUI 0.9.2 实测）：
 
 | 元素 | 现状 | 位置（宿主源码） |
 | --- | --- | --- |
@@ -101,21 +115,32 @@ dsh plugin --profile dsh-tui add -w /path/to/dsh-tui-theme
 ## 卸载
 
 ```sh
-dsh plugin --profile dsh-tui remove -w dsh-tui-theme    # 移除插件
-rm ~/.dsh-tui/themes/pink-{night,day,ansi}.json         # 可选：删除主题文件
-rm ~/.dsh-tui/theme-follow.json                         # 可选：删除跟随缓存
+# 先在 dsh-TUI 内切换到非 pink-* 主题，例如：
+/theme auto
+
+# 再移除插件和可选的本地主题资产
+dsh plugin --profile dsh-tui remove -w dsh-tui-theme
+rm ~/.dsh-tui/themes/pink-{night,day,ansi}.json
+rm ~/.dsh-tui/theme-follow.json
 ```
 
 ## 开发
 
 ```sh
-npm install && npm run build # tsc -> lib/types/
-npm run verify               # 沙盒测试（临时 HOME + 伪造 TTY，不碰真实 ~/.dsh-tui）
+npm install
+npm run build
+npm run verify
+npm run verify:package
+DSH_TUI_ADAPTER_DIR=/path/to/dsh-TUI/lib/types/dsh-adapter \
+DSH_TUI_SOURCE_ROOT=/path/to/dsh-TUI-source \
+npm run verify:host
 ```
 
+`verify:host` 必须显式指向待兼容的宿主 adapter 与源码；缺少其中任一项会失败，避免把跳过误报为验证成功。
+
 主题调色板改起来最直接：编辑 `themes/*.json` 后重新 `npm run verify`，再删掉 `~/.dsh-tui/themes/` 下对应文件让插件重装。
 
 ## 兼容性
 
-- **dsh-TUI 版本下限：0.8.8**（全功能，含状态行与设置面板；0.9.0 实测）。更旧的宿主缺 `dsh-tui-extensions` 扩展面时，插件自动降级为“仅安装三套主题 + 背景跟随”，不报错。
+- **dsh-TUI 版本下限：0.8.8**（状态行与设置面板；0.9.2 实测）。更旧的宿主缺 `dsh-tui-extensions` 扩展面时，插件自动降级为“仅安装三套主题”，不报错。
 - Node `^22.19 || >=24`，纯 ESM，MIT。

package/cordis.patch.yml

@@ -1,15 +1,15 @@
 # Bundle patch for dsh-tui-theme: insert the plugin as a profile row.
 # The plugin only consumes optional seams (themes dir, tuiStatus,
 # tuiSettingsSections, settings) and never registers shortcuts or commands.
-# followSystem opts this deployment into background-follow (the schema
-# default is off for generic installs).
+# followSystem stays off until dsh-TUI exposes a plugin-safe terminal query.
+# Existing caches can still be applied when users explicitly enable it.
 - insert:
     - id: dsh-tui-theme
       name: 'dsh-tui-theme'
       config:
         autoInstallThemes: true
         statusEnabled: true
-        followSystem: true
+        followSystem: false
         showGlyph: true
         showClock: true
         showTurns: true

package/lib/types/autoTheme.d.ts

@@ -1,21 +1,14 @@
 /**
- * Terminal-background follow: the pink pair's `auto`.
+ * Cached terminal-background follow for the pink theme pair.
  *
- * The host's `auto` pseudo-theme resolves builtin light/dark via an OSC 11
- * query at mount and keeps the result in memory only — user themes cannot
- * ride it. This module gives pink-day/pink-night the same behavior from the
- * plugin side:
- *
- * - the caller wires this from the settings inject callback (see index.ts):
- *   that fires before the React tree mounts and reads ~/.dsh-tui/theme.json,
- *   so the cached detection still decides this boot;
- * - a fresh OSC 11 query then refreshes the cache for the next boot. The
- *   very first enabling (or a system flip between boots) lands one boot
- *   late — the same cadence as the host's own "re-select auto or restart".
+ * dsh-TUI v0.9.2 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
+ * without changing the preference format used here.
  *
  * The pref write mirrors the host's writeThemePref byte-for-byte
- * ({"theme": name}, 2-space indent) and the light test mirrors the host's
- * luminance threshold so both sides always agree on light/dark.
+ * ({"theme": name}, 2-space indent).
  * @module dsh-tui-theme/autoTheme
  */
 interface FollowCache {
@@ -26,48 +19,21 @@ interface FollowCache {
 export declare function readThemePref(dataDir: string): string | undefined;
 /** Persist the theme pref in the host's exact format. */
 export declare function writeThemePref(name: string, dataDir: string): boolean;
-/** The cached detection, if one exists. */
+/** The cached terminal-background result, if a prior compatible writer stored one. */
 export declare function readFollowCache(dataDir: string): FollowCache | undefined;
-/**
- * Map a detected background to this pair's theme name.
- * @param light - True for a light terminal background.
- */
+/** Map a cached background to this pair's theme name. */
 export declare function themeForBackground(light: boolean): string;
 /**
- * Apply the follow behavior synchronously from cache: writes the resolved
- * theme name into the pref when it differs. Safe before mount — pure fs.
- * @param dataDir - The host data directory (~/.dsh-tui).
- * @returns The applied theme name, or undefined when no cache exists yet.
+ * Apply the cached follow behavior synchronously before mount. It returns the
+ * resolved name only when the existing preference already matched or the new
+ * preference committed successfully.
  */
 export declare function applyCachedFollow(dataDir: string): string | undefined;
 /**
- * Query the terminal background (OSC 11) and refresh the cache + pref.
- * Best effort: no TTY, an unresponsive terminal, or a parse failure just
- * leaves the previous state intact. Runs before the host's own stdin
- * parsing is mounted; raw mode is restored to whatever it was.
- *
- * Keystroke safety: the 'data' listener consumes every byte of the window
- * (the terminal multiplexes replies and keypresses on one stream). Anything
- * that is not part of the OSC 11 reply is re-emitted through stdin.emit on
- * teardown, so input typed mid-window reaches the host parser intact.
- * @param dataDir - The host data directory (~/.dsh-tui).
- * @param isActive - Live follow gate: a false return (follow turned off
- *   mid-window) makes finish() skip the pref write — off preserves the
- *   manual choice even for an in-flight detection.
- * @param stdout - Injectable for tests.
- * @param stdin - Injectable for tests.
- * @param setTimeoutFn - Injectable for tests.
- * @returns The detected light-ness, or undefined when unavailable.
- */
-export declare function refreshDetectedBackground(dataDir: string, isActive?: () => boolean, stdout?: NodeJS.WriteStream, stdin?: NodeJS.ReadStream, setTimeoutFn?: typeof setTimeout): Promise<boolean | undefined>;
-/**
- * The whole follow sequence for apply(): cached value now (pre-mount),
- * fresh detection for the next boot.
- * @param dataDir - The host data directory (~/.dsh-tui).
- * @param isActive - Live follow gate, re-queried when an in-flight reply
- *   lands (follow may be switched off in /settings during the window).
- * @param log - Info sink for the applied/refreshed outcomes.
+ * 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.
  */
-export declare function runFollowSystem(dataDir: string, isActive: () => boolean, log: (message: string) => void): void;
+export declare function runFollowSystem(dataDir: string, isCurrent: () => boolean, log: (message: string) => 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;;;;;;;;;;;;;;;;;;;GAmBG;AAqBH,UAAU,WAAW;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,EAAE,EAAE,MAAM,CAAA;CACX;AA4BD,+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,2CAA2C;AAC3C,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGxE;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQrE;AAcD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,OAAoB,EACpC,MAAM,GAAE,MAAM,CAAC,WAA4B,EAC3C,KAAK,GAAE,MAAM,CAAC,UAA0B,EACxC,YAAY,GAAE,OAAO,UAAuB,GAC3C,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAgF9B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,OAAO,EACvB,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC7B,IAAI,CAYN"}
+{"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"}

package/lib/types/autoTheme.js

@@ -1,39 +1,21 @@
 /**
- * Terminal-background follow: the pink pair's `auto`.
+ * Cached terminal-background follow for the pink theme pair.
  *
- * The host's `auto` pseudo-theme resolves builtin light/dark via an OSC 11
- * query at mount and keeps the result in memory only — user themes cannot
- * ride it. This module gives pink-day/pink-night the same behavior from the
- * plugin side:
- *
- * - the caller wires this from the settings inject callback (see index.ts):
- *   that fires before the React tree mounts and reads ~/.dsh-tui/theme.json,
- *   so the cached detection still decides this boot;
- * - a fresh OSC 11 query then refreshes the cache for the next boot. The
- *   very first enabling (or a system flip between boots) lands one boot
- *   late — the same cadence as the host's own "re-select auto or restart".
+ * dsh-TUI v0.9.2 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
+ * without changing the preference format used here.
  *
  * The pref write mirrors the host's writeThemePref byte-for-byte
- * ({"theme": name}, 2-space indent) and the light test mirrors the host's
- * luminance threshold so both sides always agree on light/dark.
+ * ({"theme": name}, 2-space indent).
  * @module dsh-tui-theme/autoTheme
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-/** The pair this feature switches between (light terminal → day). */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+/** The pair this feature switches between (light terminal -> day). */
 const LIGHT_THEME = 'pink-day';
 const DARK_THEME = 'pink-night';
-const QUERY = '\x1b]11;?\x07';
-// OSC 11 reply: rgb:RRRR/GGGG/BBBB with 1-4 hex digits per channel, BEL or
-// ST terminated.
-const REPLY = /\x1b\]11;rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})(?:\x07|\x1b\\)/;
-// DA1 sentinel: every terminal since VT100 answers CSI c. The host's own
-// terminal-querier uses this to avoid timeouts — a DA1 reply arriving before
-// any OSC 11 reply proves the terminal will never answer OSC 11, so the
-// window closes immediately instead of running out the full timeout.
-const DA1_QUERY = '\x1b[c';
-const DA1_REPLY = /\x1b\[\?[0-9;]*c/;
-const DETECT_TIMEOUT_MS = 400;
 function prefPath(dir) {
     return join(dir, 'theme.json');
 }
@@ -49,12 +31,20 @@ function readJsonSync(path) {
     }
 }
 function writeJsonSync(path, value) {
+    const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
     try {
-        mkdirSync(join(path, '..'), { recursive: true });
-        writeFileSync(path, JSON.stringify(value, null, 2));
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(temporary, JSON.stringify(value, null, 2), { flag: 'wx' });
+        renameSync(temporary, path);
         return true;
     }
     catch {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            // The filesystem is already failing; a stale temp file is harmless.
+        }
         return false;
     }
 }
@@ -67,170 +57,44 @@ export function readThemePref(dataDir) {
 export function writeThemePref(name, dataDir) {
     return writeJsonSync(prefPath(dataDir), { theme: name });
 }
-/** The cached detection, if one exists. */
+/** The cached terminal-background result, if a prior compatible writer stored one. */
 export function readFollowCache(dataDir) {
     const cached = readJsonSync(cachePath(dataDir));
     return typeof cached?.light === 'boolean' ? cached : undefined;
 }
-function writeFollowCache(light, dataDir) {
-    writeJsonSync(cachePath(dataDir), { light, at: Date.now() });
-}
-/**
- * Map a detected background to this pair's theme name.
- * @param light - True for a light terminal background.
- */
+/** Map a cached background to this pair's theme name. */
 export function themeForBackground(light) {
     return light ? LIGHT_THEME : DARK_THEME;
 }
 /**
- * Apply the follow behavior synchronously from cache: writes the resolved
- * theme name into the pref when it differs. Safe before mount — pure fs.
- * @param dataDir - The host data directory (~/.dsh-tui).
- * @returns The applied theme name, or undefined when no cache exists yet.
+ * Apply the cached follow behavior synchronously before mount. It returns the
+ * resolved name only when the existing preference already matched or the new
+ * preference committed successfully.
  */
 export function applyCachedFollow(dataDir) {
     const cached = readFollowCache(dataDir);
     if (cached === undefined)
         return undefined;
     const target = themeForBackground(cached.light);
-    if (readThemePref(dataDir) !== target) {
-        writeThemePref(target, dataDir);
-    }
-    return target;
-}
-/** Scale a 1-4 digit hex OSC channel to 8-bit. */
-function channel8(hex) {
-    const value = parseInt(hex, 16);
-    if (hex.length >= 3)
-        return Math.round(value / (16 ** hex.length - 1) * 255);
-    return value * (hex.length === 2 ? 1 : 17);
-}
-/** The host's luminance test (ThemeProvider.isLightBackground). */
-function isLightBackground(r, g, b) {
-    return 0.299 * r + 0.587 * g + 0.114 * b > 140;
+    if (readThemePref(dataDir) === target)
+        return target;
+    return writeThemePref(target, dataDir) ? target : undefined;
 }
 /**
- * Query the terminal background (OSC 11) and refresh the cache + pref.
- * Best effort: no TTY, an unresponsive terminal, or a parse failure just
- * leaves the previous state intact. Runs before the host's own stdin
- * parsing is mounted; raw mode is restored to whatever it was.
- *
- * Keystroke safety: the 'data' listener consumes every byte of the window
- * (the terminal multiplexes replies and keypresses on one stream). Anything
- * that is not part of the OSC 11 reply is re-emitted through stdin.emit on
- * teardown, so input typed mid-window reaches the host parser intact.
- * @param dataDir - The host data directory (~/.dsh-tui).
- * @param isActive - Live follow gate: a false return (follow turned off
- *   mid-window) makes finish() skip the pref write — off preserves the
- *   manual choice even for an in-flight detection.
- * @param stdout - Injectable for tests.
- * @param stdin - Injectable for tests.
- * @param setTimeoutFn - Injectable for tests.
- * @returns The detected light-ness, or undefined when 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.
  */
-export function refreshDetectedBackground(dataDir, isActive = () => true, stdout = process.stdout, stdin = process.stdin, setTimeoutFn = setTimeout) {
-    return new Promise(resolve => {
-        if (stdout.isTTY !== true || stdin.isTTY !== true) {
-            resolve(undefined);
-            return;
-        }
-        const wasRaw = stdin.isRaw === true;
-        try {
-            stdin.setRawMode?.(true);
-        }
-        catch {
-            resolve(undefined);
-            return;
-        }
-        let buffer = '';
-        let settled = false;
-        // Push the window's leftover bytes back for the host's input parser.
-        // unshift() returns them to the stream's internal buffer, which both the
-        // host's pull-mode 'readable' pump (mounted later) and any flowing-mode
-        // 'data' listener consume; the emit() fallback covers a torn-down stream
-        // where unshift refuses to work. Keystrokes typed during detection used
-        // to be silently dropped here. latin1 is byte-exact.
-        const replayLeftover = (leftover) => {
-            if (leftover === '')
-                return;
-            try {
-                stdin.unshift(Buffer.from(leftover, 'latin1'));
-            }
-            catch {
-                try {
-                    stdin.emit('data', Buffer.from(leftover, 'latin1'));
-                }
-                catch {
-                    // Best effort: input preservation must never throw from a detector.
-                }
-            }
-        };
-        const finish = (light, leftover) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            stdin.removeListener('data', onData);
-            replayLeftover(leftover);
-            try {
-                stdin.setRawMode?.(wasRaw);
-            }
-            catch {
-                // Stream already torn down — nothing to restore.
-            }
-            if (light !== undefined && isActive()) {
-                writeFollowCache(light, dataDir);
-                const target = themeForBackground(light);
-                if (readThemePref(dataDir) !== target) {
-                    writeThemePref(target, dataDir);
-                }
-            }
-            resolve(light);
-        };
-        const onData = (chunk) => {
-            buffer += typeof chunk === 'string' ? chunk : chunk.toString('latin1');
-            const match = REPLY.exec(buffer);
-            if (match !== null) {
-                const light = isLightBackground(channel8(match[1] ?? ''), channel8(match[2] ?? ''), channel8(match[3] ?? ''));
-                const leftover = buffer.slice(0, match.index) + buffer.slice(match.index + match[0].length);
-                finish(light, leftover);
-                return;
-            }
-            // DA1 arrived before any OSC 11 reply: this terminal skips OSC 11
-            // entirely (host querier pattern) — stop waiting. Bytes after the DA1
-            // reply can only be input, so they come along.
-            const da1 = DA1_REPLY.exec(buffer);
-            if (da1 !== null) {
-                const leftover = buffer.slice(0, da1.index) + buffer.slice(da1.index + da1[0].length);
-                finish(undefined, leftover);
-            }
-        };
-        const timer = setTimeoutFn(() => finish(undefined, buffer), DETECT_TIMEOUT_MS);
-        if (stdin.isPaused())
-            stdin.resume();
-        stdin.on('data', onData);
-        stdout.write(QUERY + DA1_QUERY);
-    });
-}
-/**
- * The whole follow sequence for apply(): cached value now (pre-mount),
- * fresh detection for the next boot.
- * @param dataDir - The host data directory (~/.dsh-tui).
- * @param isActive - Live follow gate, re-queried when an in-flight reply
- *   lands (follow may be switched off in /settings during the window).
- * @param log - Info sink for the applied/refreshed outcomes.
- */
-export function runFollowSystem(dataDir, isActive, log) {
+export function runFollowSystem(dataDir, isCurrent, log) {
+    if (!isCurrent())
+        return;
     const applied = applyCachedFollow(dataDir);
-    if (applied !== undefined && existsSync(prefPath(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})`);
     }
-    void refreshDetectedBackground(dataDir, isActive).then(light => {
-        if (light === undefined) {
-            log('follow: terminal background unavailable, keeping current choice');
-        }
-        else {
-            log(`follow: detected ${light ? 'light' : 'dark'} terminal → ${themeForBackground(light)}`);
-        }
-    });
 }

package/lib/types/index.d.ts

@@ -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 里一个可编辑面板，即时生效。
  *

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,CAsE7D"}
+{"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"}

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 里一个可编辑面板，即时生效。
  *
@@ -81,20 +81,14 @@ export function apply(ctx, config = {}) {
     // 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 v0.9.2 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 => {
+    const applyFollow = () => {
+        runFollowSystem(dataDir, () => followActive === true, message => {
             ctx.logger.info(`dsh-tui-theme: ${message}`);
         });
     };
@@ -103,25 +97,16 @@ export function apply(ctx, config = {}) {
         if (effective.followSystem !== followActive) {
             followActive = effective.followSystem;
             if (followActive) {
-                startFollow();
+                applyFollow();
             }
             else {
                 ctx.logger.info('dsh-tui-theme: 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));
+    // 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.
     startStatusLine(ctx, () => effective);
 }

package/lib/types/settingsSection.d.ts

@@ -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;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"}