dsh-tui-theme 0.7.1 → 0.7.2

package/README.md

@@ -117,6 +117,8 @@ dsh plugin --profile dsh-tui add -w dsh-tui-theme@latest
 
 三项装饰全关时状态行整体消失。另有仅 profile 层的开关（`cordis.patch.yml`，不出现在 /settings）：`autoInstallThemes`、`statusEnabled`。
 
+上表就是本插件的**可编辑面**：卡片字段与 `src/liveConfig.ts` 的 `LIVE_CONFIG_KEYS` 必须逐键相等（`npm run verify` 双向断言），因为 dsh-TUI ≥ 0.11（`dsh-settings` ≥ 0.1.7）的设置服务不再接受插件注册命名空间，而是把**本插件 Config 里标了 volatile 的字段**投影成表单、以 **Loader 条目 id**（默认 `dsh-tui-theme`）作命名空间；保存直接写进 profile 补丁并即时生效。老宿主（≤ 0.10.x，`dsh-settings` ≤ 0.1.6）仍走插件自己注册命名空间的旧路径，行为不变。两条路径共用同一串命名空间，因此给插件行改过 id 的用户在新宿主上会以新 id 存取设置（旧代下改动 id 也会跟着走）。
+
 ## 受宿主限制、目前无法定制的部分
 
 以下元素的颜色/形态由 dsh-TUI 宿主**硬编码**，不读取任何主题键，主题 JSON 与插件接缝都覆盖不到（dsh-TUI 0.9.3 实测）：
@@ -154,6 +156,9 @@ npm install --include=dev   # 见下方安装前提，本仓不提交 lockfile
 npm run build
 npm run verify
 npm run verify:package
+# 代际门禁：本仓 devDependency 的 dsh-settings 是旧代，脚本会明确跳过并以 0 退出；
+# 要真正验证 ≥0.1.7 的 Config 投影，把 DSH_SETTINGS_DIR 指到真机那份安装
+DSH_SETTINGS_DIR="$HOME/.dsh/profiles/node_modules/@deepseek-ai/dsh-settings" npm run verify:settings
 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
@@ -171,4 +176,5 @@ npm run verify:host
 ## 兼容性
 
 - **dsh-TUI 版本下限：0.8.8**（状态行与设置面板；0.9.3 实测）。0.10.0 及更新版本使用运行时主题注册；0.10.1 起状态行经富状态视图按主题配色（更旧宿主自动回退无色标量行）；更旧的宿主缺 `dsh-tui-extensions` 扩展面时，插件自动降级为“仅安装三套主题”，不报错。
+- **设置服务两代都支持**：`dsh-settings` ≤ 0.1.6（dsh-TUI 0.9.x/0.10.x）走插件注册命名空间 + `scope.watch`；≥ 0.1.7（dsh-TUI 0.11+，`/settings` 曾显示「命名空间未注册」）走 Config volatile 字段投影 + `loader/volatile-update` 重读。判定按能力探测，不解析版本号；两条路径的失败都会写日志而不是静默。适配依据见 `docs/decisions/2026-09-26-settings-generation-adaptation.md`。
 - Node `^22.19 || >=24`，纯 ESM，MIT。

package/docs/decisions/2026-09-26-settings-generation-adaptation.md

@@ -0,0 +1,61 @@
+# 决策：dsh-settings 两代适配 —— Config volatile 投影 + 命名空间跟随 Loader 条目 id
+
+- 日期：2026-09-26
+- 状态：已采纳
+- 来源：迁移清单（dsh-tui-find 仓的 `docs/decisions/2026-09-24-settings-generation-adaptation.md`，本决策是它在本仓的落地记录）；代码审查条目 T1–T3（工作区 `REVIEW.md`）
+
+## 背景
+
+**现象**：dsh-TUI 升到 0.11.0（`@deepseek-ai/dsh-settings@0.1.7-rc.1`、schemastery 3.18.4）后，`/settings` 里 **dsh-tui-theme 卡片右侧打上 `命名空间未注册` 徽标**，七个字段全部不可编辑。原实现（v0.7.1）在 `ctx.inject(['settings'])` 里调 `settings.register(PLUGIN_ID, schema)`：新代服务**没有** `register`，调用抛 `TypeError` 被 `catch {}` 静默吞掉 → 命名空间从未存在 → 徽标（`lib/types/settingsSection.js`）。
+
+**根因**：`dsh-settings` 0.1.7 换代。旧代 `SettingsProvider` 由插件用 `register(ns, schema)` 自注册命名空间；新代 `SettingsForms` 改为：
+
+- 命名空间 = **profile 条目 id**（本插件默认即 `dsh-tui-theme`，`cordis.patch.yml` 钉死）；
+- 表单 schema = 插件 **Cordis `Config`** 里标了 volatile 的字段（`volatileForm(schema)`，投影侧只读 `meta.volatile` 这份普通数据）；
+- `describe()` 只列 `volatileForm(Config)` 非空的条目；
+- 写入经 `configEditor` 落进当前 profile 的补丁，loader 就地把 volatile 引用改值并以 `entry.fiber.ctx.emit(self, 'loader/volatile-update', paths)` 广播（`Context.filter` 只投给该条目自己的 fiber）；
+- 自带卡片的插件用 `configure({ auto: false }, ctx.fiber)` 关掉自动生成页，`configure` 对同一 fiber 二次调用会 throw。
+
+另有两条硬约束：`.volatile()` 直到 **schemastery 3.18.3** 才有（本仓基线 3.18.1/3.18.2 没有）；volatile 字段在 `apply` 期是**引用不是值**（`Schema.resolve` 用 `createVolatile()` 包一层）。
+
+## 决策（本仓落地）
+
+1. **双路径按能力分支，永不解析版本号**：`typeof settings.register === 'function'` → 旧代（注册命名空间 + `scope.watch`）；否则视为新代（`configure({ auto: false }, ctx.fiber)` + 读活配置 + 订阅 `loader/volatile-update`）；两者皆无则 `info` 说明卡片本会话不可用。
+2. **可编辑集合只有一个事实来源**：`src/liveConfig.ts` 的 `LIVE_CONFIG_KEYS` 驱动 `Config` 的 volatile 标记（`src/index.ts` 的 `configFields` + `liveField`），卡片字段与它**双向对拍**（`npm run verify` 断言，`npm run verify:settings` 再对真宿主投影断言一次）。
+3. **`liveField` 两级能力探测**：先 `.volatile()`（3.18.3+，走框架自带校验），没有就把 `meta.volatile` 直接写 true（照抄 dsh-TUI #990 给自家 Config 的修法）；`meta` 被冻结时安静退化为不标记。
+4. **命名空间取 Loader 条目 id**（`resolveSettingsNamespace`）：新代 `describe()` 直接以 `entry.options.id` 当 ns 且不校验，而插件自有分区在 `tuiSettingsSections.register()` 里仍受 `^[a-z][a-z0-9_-]*$` 约束——entry id 合法时以它为准，否则回落 `PLUGIN_ID` 并 warn；两代共用同一串，卡片、旧代注册与宿主投影不可能互相错位。
+5. **apply 期 config 一律先解包**：`readConfigValues` 逐键解引用，判定按 **cosmokit 的 Volatile 协议**（`Symbol.for('cosmokit.volatile.write') in value`），`{ get }` 单键形状只作兜底。`apply` 里构造 `cordis` 层与 `readLive()` 探针都走它，杜绝把 ref 当字符串/布尔用（形状判定在 ref 多带一个普通键时就静默失效）。
+6. **失败不再静默**：旧代注册失败 warn（原为裸 `catch {}`，正是这次「无日志可查」的来源）；新代下 entry id 不可用、或一个 live 字段都没有（`hasLiveConfigFields`）时各给一条可诊断的 warn；缺 `loader/volatile-update` 时 `info` 说明「改动下次加载才生效」。
+7. **新增代际验证入口**：`npm run verify:settings`（`scripts/verify-settings-generation.mjs`）——对真实安装的 dsh-settings 判定世代；≥0.1.7 时用**真实的** `volatileForm`/`projectForm`/`isVolatilePath` 对构建产物 `lib/types/` 跑 20 条投影断言，旧代明确报告「无需验证」并以 0 退出（CI 安全，已挂进 CI verify 档与 `release:check`）。
+8. **`settings.register` 必须按方法调用**（`settings.register?.(...)`，可选调用保留 receiver）：真 provider 的 `register()` 读自身状态，摘成局部变量再调用会丢 `this` 抛错——这条由 `verify:host` 的真实 provider 相位咬出，已补进 `scripts/verify.mjs` 的假服务（`this === undefined` 即抛）作为回归。
+
+## 本仓特有的取舍
+
+- **可编辑面 = 7 键**：`followSystem` / `showGlyph` / `statusGlyph` / `showClock` / `showTurns` / `statusSeparator` / `statusScope`，与卡片字段逐一对应。`autoInstallThemes` / `statusEnabled` **有意不标 live**：它们是仅 profile 层的开关（README 已写明不出现在 /settings），标了反而会出现「可编辑但无 UI」的错位。
+- 新代下 setter 的取值来自插件自己的行配置，因此首帧 `onDoc` 携带的是**全量已解析配置**（含 schema 默认值），与旧代「只有用户层」的形状不同；`index.ts` 的 `{ ...cordis, ...doc }` 合并对两者都成立，`followActive` 的基线语义不变。
+- `configure` 的 owner 必须是 **Config 所属的插件 fiber**（`apply` 的 `ctx.fiber`），`loader/volatile-update` 也注册在插件自身 context 上（loader 只投给被更新条目的 fiber）；两者都挂在 inject 子 ctx 的 effect 上做清理。
+
+## 替代方案
+
+- **抬高 peer 下限到 ≥0.1.7、只支持新代**：把 0.9.x/0.10.x 用户挡在门外，与既有双宿主兼容策略冲突——否决。
+- **放弃卡片、让新代自动生成页面**（不调 `configure`）：字段标签/分组/中英文案/hint 全丢，且与已注册的卡片重复——否决。
+- **逐字段手写 `.volatile()`、不设 `LIVE_CONFIG_KEYS`**：卡片与 schema 的对应关系无人守，漂移即静默死卡——否决。
+- **只探测 `.volatile()`、不做 meta 兜底**：3.18.1/3.18.2 上标记静默失效，整套设置页变死（#990 的病根）——否决。
+- **按 #991 的方式在标记失败时启动即报错**：第三方插件会把 TUI 启动一起带走——改为 warn + 验证脚本兜底。
+
+## 影响
+
+- 收益：dsh-TUI 0.11/新代设置服务下卡片恢复可编辑、保存即生效；0.9.x/0.10.x 行为不变；三类静默失败（注册被吞、标记失效、命名空间错位）各自有 warn、脚本与测试兜底。
+- 成本：新增 `src/liveConfig.ts`；`settingsSection.ts` 多一条世代分支；`verify.mjs` 多 3 个场景；多一个代际脚本随包分发。
+- 风险：
+  - 宿主 `loader/volatile-update` 语义再变 → 症状是「保存后不生效」，`verify:settings` 的重读断言会先红。
+  - schemastery 未来把 `.volatile()` 改名 **且** 冻结 `meta` → 标记彻底失效，`verify:settings` 的「live 标记存在」断言会红。
+  - 直接写 `meta.volatile` 绕过框架的 volatile 校验；本仓只在**扁平** Config（标的是叶子）上用它。
+  - 旧代下给插件行改过 id 的用户，`settings.yaml` 里旧 `dsh-tui-theme` 一节不再生效（键跟随新 id）；默认安装 id 不变，且新代本来就以 entry id 为身份——接受并在此记录。
+- 真机确认（2026-09-26）：`verify:settings` 对真机 `0.1.7-rc.1` + schemastery 3.18.4 的 20 条断言全绿；构建产物装进本机 `dsh-tui` profile（原 0.7.1 目录整目录备份、profile 依赖声明未改），`dsh --profile dsh-tui --dump-config` 条目 id 与卡片 `ns` 一致；**用户肉眼确认 `/settings` 里 pink-theme 卡片已无 `命名空间未注册` 徽标**（见 `REVIEW.md` T4）。
+
+## 关联
+
+- 迁移清单与上游动向：dsh-tui-find `docs/decisions/2026-09-24-settings-generation-adaptation.md`（含 dsh-TUI [#990](https://github.com/ccch1mneyyy/dsh-TUI/issues/990) / [PR #991](https://github.com/ccch1mneyyy/dsh-TUI/pull/991)）
+- 相关代码：`src/liveConfig.ts`、`src/settingsSection.ts`、`src/index.ts`
+- 相关脚本：`scripts/verify-settings-generation.mjs`（`npm run verify:settings`）、`scripts/verify.mjs` 场景 2d/2e/2f

package/lib/types/index.d.ts

@@ -7,7 +7,9 @@
  * - 缓存背景跟随：安全应用已有的终端背景缓存，在昼樱/夜樱间切换；
  *   dsh-TUI 未提供插件终端查询接缝时，不直接读写 stdin、raw mode 或 OSC 11；
  * - 接缝十一（状态行）：输入框上方一行小装饰（✿ · 时钟 · 本轮轮数）；
- * - 接缝六（设置区块）：/settings 里一个可编辑面板，即时生效。
+ * - 接缝六（设置区块）：/settings 里一个可编辑面板，即时生效；宿主设置服务
+ *   换代后（dsh-settings ≥0.1.7，dsh-TUI ≥0.11）面板改由本插件 Config 里标了
+ *   live 的字段投影，命名空间取 Loader 条目 id（liveConfig.ts / settingsSection.ts）。
  *
  * 遵循 #183 纪律：所有宿主服务用 ctx.inject 软探测，缺席即静默降级；
  * 插件缺失或宿主较旧时行为退化为“什么都没发生”，绝不拖垮启动。

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;AAMlD,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAKjF,eAAO,MAAM,IAAI,kBAAY,CAAA;AAE7B,wDAAwD;AACxD,MAAM,MAAM,MAAM,GAAG,eAAe,CAAA;AAUpC,eAAO,MAAM,MAAM,EAAE,WAAW,CAAC,MAAM,CAUrC,CAAA;AAoBF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CAoK7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMlD,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAMjF,eAAO,MAAM,IAAI,kBAAY,CAAA;AAE7B,wDAAwD;AACxD,MAAM,MAAM,MAAM,GAAG,eAAe,CAAA;AAgCpC,eAAO,MAAM,MAAM,EAAE,WAAW,CAAC,MAAM,CAOtC,CAAA;AAoBD;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CAmL7D"}

package/lib/types/index.js

@@ -7,7 +7,9 @@
  * - 缓存背景跟随：安全应用已有的终端背景缓存，在昼樱/夜樱间切换；
  *   dsh-TUI 未提供插件终端查询接缝时，不直接读写 stdin、raw mode 或 OSC 11；
  * - 接缝十一（状态行）：输入框上方一行小装饰（✿ · 时钟 · 本轮轮数）；
- * - 接缝六（设置区块）：/settings 里一个可编辑面板，即时生效。
+ * - 接缝六（设置区块）：/settings 里一个可编辑面板，即时生效；宿主设置服务
+ *   换代后（dsh-settings ≥0.1.7，dsh-TUI ≥0.11）面板改由本插件 Config 里标了
+ *   live 的字段投影，命名空间取 Loader 条目 id（liveConfig.ts / settingsSection.ts）。
  *
  * 遵循 #183 纪律：所有宿主服务用 ctx.inject 软探测，缺席即静默降级；
  * 插件缺失或宿主较旧时行为退化为“什么都没发生”，绝不拖垮启动。
@@ -22,17 +24,14 @@ import { runFollowSystem } from './autoTheme.js';
 import { registerPinkSettings } from './settingsSection.js';
 import { startShadowCleanup } from './shadowCleanup.js';
 import { startToastRelay } from './toast.js';
+import { hasLiveConfigFields, isLiveConfigKey, liveField, readConfigValues } from './liveConfig.js';
 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.
-//
-// statusEnabled / autoInstallThemes stay cordis-config knobs only (invisible
-// in /settings): turning the garnish off entirely is what uninstalling is
-// for, per user feedback. followSystem defaults off for generic installs;
-// the shipped cordis.patch.yml opts this deployment in.
-export const Config = z.object({
+/** The row-config fields in declaration order. The live marking is applied
+ *  afterwards from `LIVE_CONFIG_KEYS` (liveConfig.ts) so the /settings card's
+ *  editable set and the marked set cannot drift apart — scripts/verify.mjs
+ *  asserts both directions of that parity. */
+const configFields = {
     autoInstallThemes: z.boolean().default(true),
     statusEnabled: z.boolean().default(true),
     followSystem: z.boolean().default(false),
@@ -42,7 +41,25 @@ export const Config = z.object({
     showClock: z.boolean().default(true),
     showTurns: z.boolean().default(true),
     statusScope: z.union(['pink-only', 'all-themes']).default('pink-only'),
-});
+};
+// 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.
+//
+// statusEnabled / autoInstallThemes stay cordis-config knobs only (invisible
+// in /settings, and therefore not marked live): turning the garnish off
+// entirely is what uninstalling is for, per user feedback. followSystem
+// defaults off for generic installs; the shipped cordis.patch.yml opts this
+// deployment in.
+//
+// On a `dsh-settings` ≥0.1.7 host the marked fields below ARE the /settings
+// form schema (the namespace is the profile entry id); on ≤0.1.6 hosts they
+// are ordinary config values and the card's values come from the namespace
+// registration instead.
+export const Config = z.object(Object.fromEntries(Object.entries(configFields).map(([key, field]) => [
+    key,
+    isLiveConfigKey(key) ? liveField(field) : field,
+])));
 const DEFAULTS = {
     autoInstallThemes: true,
     statusEnabled: true,
@@ -60,18 +77,22 @@ const DEFAULTS = {
  * @param config - Validated plugin config (schema defaults applied).
  */
 export function apply(ctx, config = {}) {
+    // A `dsh-settings` ≥0.1.7 host hands every marked field to apply as a live
+    // ref, not as the value it stands for (liveConfig.ts); unwrap before any
+    // read, here and in the readLive() probe the settings wiring re-runs.
+    const live = readConfigValues(config);
     // The cordis.yml layer: schema defaults plus explicit ?? fallbacks so a
     // bare composition still resolves every knob.
     const cordis = {
-        autoInstallThemes: config.autoInstallThemes ?? DEFAULTS.autoInstallThemes,
-        statusEnabled: config.statusEnabled ?? DEFAULTS.statusEnabled,
-        followSystem: config.followSystem ?? DEFAULTS.followSystem,
-        statusGlyph: config.statusGlyph ?? DEFAULTS.statusGlyph,
-        statusSeparator: config.statusSeparator ?? DEFAULTS.statusSeparator,
-        showGlyph: config.showGlyph ?? DEFAULTS.showGlyph,
-        showClock: config.showClock ?? DEFAULTS.showClock,
-        showTurns: config.showTurns ?? DEFAULTS.showTurns,
-        statusScope: config.statusScope ?? DEFAULTS.statusScope,
+        autoInstallThemes: live.autoInstallThemes ?? DEFAULTS.autoInstallThemes,
+        statusEnabled: live.statusEnabled ?? DEFAULTS.statusEnabled,
+        followSystem: live.followSystem ?? DEFAULTS.followSystem,
+        statusGlyph: live.statusGlyph ?? DEFAULTS.statusGlyph,
+        statusSeparator: live.statusSeparator ?? DEFAULTS.statusSeparator,
+        showGlyph: live.showGlyph ?? DEFAULTS.showGlyph,
+        showClock: live.showClock ?? DEFAULTS.showClock,
+        showTurns: live.showTurns ?? DEFAULTS.showTurns,
+        statusScope: live.statusScope ?? DEFAULTS.statusScope,
     };
     // User-visible one-liners for the few events worth surfacing (the plugin
     // logger is invisible to a TUI user). Hosts without the 0.10 toast seam
@@ -189,27 +210,34 @@ export function apply(ctx, config = {}) {
             }
         });
     };
-    registerPinkSettings(ctx, cordis, doc => {
-        effective = { ...cordis, ...doc };
-        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(false);
-            return;
-        }
-        if (followActive !== follow) {
-            followActive = follow;
-            if (follow) {
-                applyFollow(true);
+    registerPinkSettings(ctx, {
+        cordis,
+        // The live row config: on ≥0.1.7 hosts the loader rewrites these refs in
+        // place, so re-reading after `loader/volatile-update` yields the edit.
+        readLive: () => readConfigValues(config),
+        hasLiveFields: hasLiveConfigFields(Config),
+        onDoc: doc => {
+            effective = { ...cordis, ...doc };
+            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(false);
+                return;
             }
-            else {
-                ctx.logger.info(`${PLUGIN_ID}: follow: disabled, manual /theme choice preserved`);
+            if (followActive !== follow) {
+                followActive = follow;
+                if (follow) {
+                    applyFollow(true);
+                }
+                else {
+                    ctx.logger.info(`${PLUGIN_ID}: follow: disabled, manual /theme choice preserved`);
+                }
             }
-        }
+        },
     }, dataDir);
     // 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

package/lib/types/liveConfig.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The live-editable slice of the plugin's row config — the support the
+ * `dsh-settings` ≥0.1.7 generation needs (dsh-TUI 0.11+) while the ≤0.1.6
+ * generation keeps working unchanged.
+ *
+ * Two host generations read the same {@link Config} differently, and both must
+ * keep working (docs/decisions/… in the dsh-tui-find repo,
+ * `2026-09-24-settings-generation-adaptation.md`, is the reference record):
+ *
+ * - `dsh-settings` ≤0.1.6 (dsh-TUI 0.9.x/0.10.x): the `/settings` namespace is
+ *   registered by the plugin and its form values come from that registration
+ *   schema (settingsSection.ts). The row config is a frozen value.
+ * - `dsh-settings` ≥0.1.7 (dsh-TUI 0.11+): there is no registration API — the
+ *   namespace is the profile entry id and the form schema is *this* schema
+ *   projected onto the fields carrying the volatile marker. Those fields then
+ *   reach `apply` as live refs whose value the loader rewrites in place, so
+ *   every read goes through {@link readConfigValues} first.
+ *
+ * `.volatile()` landed in schemastery 3.18.3 while this plugin's baseline is
+ * 3.18.1/3.18.2, hence the capability probe in {@link liveField} — never a
+ * version parse. A plugin that misses the transition still boots, still
+ * registers its card, and simply renders `命名空间未注册`; a card field whose
+ * Config key is not marked renders `（未设置）` forever. Both are silent, which
+ * is why the marking is driven by one exported key list (the card↔schema
+ * parity is asserted in scripts/verify.mjs and
+ * scripts/verify-settings-generation.mjs).
+ *
+ * @module dsh-tui-theme/liveConfig
+ */
+/**
+ * Keys the `/settings` card owns, and therefore the keys the host may edit
+ * live. On `dsh-settings` ≥0.1.7 these are exactly the fields the plugin's
+ * form projects, so the card's field paths, this list and the marked fields
+ * must stay equal — a card field outside the list would render editable yet
+ * never be served (the host's own status-bar `cost` field shows that failure
+ * mode as `（未设置）` forever), and a marked key without a field would be
+ * live-editable with no UI. `autoInstallThemes` / `statusEnabled` are
+ * deliberately absent: they stay cordis-config knobs (README §配置).
+ */
+export declare const LIVE_CONFIG_KEYS: readonly ["followSystem", "showGlyph", "statusGlyph", "showClock", "showTurns", "statusSeparator", "statusScope"];
+/** Whether one row-config key is part of the card's editable set. */
+export declare function isLiveConfigKey(key: string): boolean;
+/**
+ * Mark one schema field live-editable when the host can project it.
+ *
+ * Two capability steps, never a version parse:
+ *
+ * 1. `.volatile()` — schemastery 3.18.3+; returns a marked clone and runs the
+ *    framework's own volatile validation, so it is preferred wherever it
+ *    exists.
+ * 2. `meta.volatile = true` — the settings projection only reads that plain
+ *    meta field, so writing it directly works on the 3.18.1/3.18.2 baselines
+ *    too. This is the fallback dsh-TUI shipped for its own Config after issue
+ *    #990 (its `editableConfig` silently no-opped on older schemastery and the
+ *    whole settings page went dead on a 0.1.7 host).
+ *
+ * Calling `.volatile()` twice throws, so the marker is applied exactly once,
+ * from the single {@link LIVE_CONFIG_KEYS} list. A schemastery that froze its
+ * `meta` leaves the field unmarked (a dead card, but no boot failure — the
+ * host's own choice for third-party plugins).
+ */
+export declare function liveField<T>(field: T): T;
+/**
+ * Read a row config down to plain values.
+ *
+ * On `dsh-settings` ≥0.1.7 (schemastery ≥3.18.3) the loader hands every
+ * volatile field to `apply` as a live ref — a frozen object carrying the
+ * cosmokit Volatile protocol whose value the loader rewrites in place — so
+ * reading the config object again after `loader/volatile-update` yields the
+ * edited values (settingsSection.ts rides exactly that). Structural, not an
+ * import: the refs are cosmokit's Volatile protocol and cosmokit is not a
+ * dependency of this plugin. The row config is flat, so one unwrap level per
+ * key is enough; a nested knob would need a recursive walk here.
+ */
+export declare function readConfigValues<T extends object>(config: T | undefined): T;
+/**
+ * Whether a row-config schema carries the live marker anywhere — exactly what
+ * a `dsh-settings` ≥0.1.7 host needs to serve this plugin's `/settings` page
+ * (`volatileForm()` returns undefined without it and the entry never reaches
+ * `describe()`, which the TUI renders as `命名空间未注册`).
+ *
+ * Read structurally: the schemastery 3.18.1/3.18.2 types this repo builds
+ * against do not expose `.dict` on the schema type, and the caller owns the
+ * schema. settingsSection.ts warns with this when a new-generation host cannot
+ * serve the card, instead of leaving a bare badge as the only clue.
+ */
+export declare function hasLiveConfigFields(schema: unknown): boolean;
+//# sourceMappingURL=liveConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"liveConfig.d.ts","sourceRoot":"","sources":["../../src/liveConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,mHAQnB,CAAA;AAEV,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAYxC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,CAAC,CAI3E;AAiCD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAI5D"}

package/lib/types/liveConfig.js

@@ -0,0 +1,151 @@
+/**
+ * The live-editable slice of the plugin's row config — the support the
+ * `dsh-settings` ≥0.1.7 generation needs (dsh-TUI 0.11+) while the ≤0.1.6
+ * generation keeps working unchanged.
+ *
+ * Two host generations read the same {@link Config} differently, and both must
+ * keep working (docs/decisions/… in the dsh-tui-find repo,
+ * `2026-09-24-settings-generation-adaptation.md`, is the reference record):
+ *
+ * - `dsh-settings` ≤0.1.6 (dsh-TUI 0.9.x/0.10.x): the `/settings` namespace is
+ *   registered by the plugin and its form values come from that registration
+ *   schema (settingsSection.ts). The row config is a frozen value.
+ * - `dsh-settings` ≥0.1.7 (dsh-TUI 0.11+): there is no registration API — the
+ *   namespace is the profile entry id and the form schema is *this* schema
+ *   projected onto the fields carrying the volatile marker. Those fields then
+ *   reach `apply` as live refs whose value the loader rewrites in place, so
+ *   every read goes through {@link readConfigValues} first.
+ *
+ * `.volatile()` landed in schemastery 3.18.3 while this plugin's baseline is
+ * 3.18.1/3.18.2, hence the capability probe in {@link liveField} — never a
+ * version parse. A plugin that misses the transition still boots, still
+ * registers its card, and simply renders `命名空间未注册`; a card field whose
+ * Config key is not marked renders `（未设置）` forever. Both are silent, which
+ * is why the marking is driven by one exported key list (the card↔schema
+ * parity is asserted in scripts/verify.mjs and
+ * scripts/verify-settings-generation.mjs).
+ *
+ * @module dsh-tui-theme/liveConfig
+ */
+/**
+ * Keys the `/settings` card owns, and therefore the keys the host may edit
+ * live. On `dsh-settings` ≥0.1.7 these are exactly the fields the plugin's
+ * form projects, so the card's field paths, this list and the marked fields
+ * must stay equal — a card field outside the list would render editable yet
+ * never be served (the host's own status-bar `cost` field shows that failure
+ * mode as `（未设置）` forever), and a marked key without a field would be
+ * live-editable with no UI. `autoInstallThemes` / `statusEnabled` are
+ * deliberately absent: they stay cordis-config knobs (README §配置).
+ */
+export const LIVE_CONFIG_KEYS = [
+    'followSystem',
+    'showGlyph',
+    'statusGlyph',
+    'showClock',
+    'showTurns',
+    'statusSeparator',
+    'statusScope',
+];
+/** Whether one row-config key is part of the card's editable set. */
+export function isLiveConfigKey(key) {
+    return LIVE_CONFIG_KEYS.includes(key);
+}
+/**
+ * Mark one schema field live-editable when the host can project it.
+ *
+ * Two capability steps, never a version parse:
+ *
+ * 1. `.volatile()` — schemastery 3.18.3+; returns a marked clone and runs the
+ *    framework's own volatile validation, so it is preferred wherever it
+ *    exists.
+ * 2. `meta.volatile = true` — the settings projection only reads that plain
+ *    meta field, so writing it directly works on the 3.18.1/3.18.2 baselines
+ *    too. This is the fallback dsh-TUI shipped for its own Config after issue
+ *    #990 (its `editableConfig` silently no-opped on older schemastery and the
+ *    whole settings page went dead on a 0.1.7 host).
+ *
+ * Calling `.volatile()` twice throws, so the marker is applied exactly once,
+ * from the single {@link LIVE_CONFIG_KEYS} list. A schemastery that froze its
+ * `meta` leaves the field unmarked (a dead card, but no boot failure — the
+ * host's own choice for third-party plugins).
+ */
+export function liveField(field) {
+    const candidate = field;
+    if (typeof candidate.volatile === 'function')
+        return candidate.volatile();
+    const meta = candidate.meta;
+    if (typeof meta === 'object' && meta !== null) {
+        try {
+            meta.volatile = true;
+        }
+        catch {
+            return field;
+        }
+    }
+    return field;
+}
+/**
+ * Read a row config down to plain values.
+ *
+ * On `dsh-settings` ≥0.1.7 (schemastery ≥3.18.3) the loader hands every
+ * volatile field to `apply` as a live ref — a frozen object carrying the
+ * cosmokit Volatile protocol whose value the loader rewrites in place — so
+ * reading the config object again after `loader/volatile-update` yields the
+ * edited values (settingsSection.ts rides exactly that). Structural, not an
+ * import: the refs are cosmokit's Volatile protocol and cosmokit is not a
+ * dependency of this plugin. The row config is flat, so one unwrap level per
+ * key is enough; a nested knob would need a recursive walk here.
+ */
+export function readConfigValues(config) {
+    const plain = {};
+    for (const [key, value] of Object.entries(config ?? {}))
+        plain[key] = readRef(value);
+    return plain;
+}
+/**
+ * The cosmokit Volatile brand, read by name so it matches the host's own copy
+ * across module instances (`cosmokit/src/volatile.ts`). Absent from the
+ * schemastery 3.18.1/3.18.2 generations this plugin also supports — probing it
+ * is a plain symbol lookup, never a version parse, and the shape fallback
+ * below still covers a hand-rolled ref.
+ */
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write');
+/**
+ * Unwrap one live config ref, if that is what it is.
+ *
+ * The protocol brand (`cosmokit.volatile.write` in the value, exactly what
+ * `isVolatile` checks) is authoritative and is probed FIRST: a real ref may
+ * legitimately carry more than the `get` key, and the shape heuristic below
+ * would then hand the ref object itself to the caller, which reads it as "not
+ * a string/boolean" and silently falls back to the documented default — no
+ * warning, no error. The shape check stays as a fallback for a ref built
+ * without the brand.
+ */
+function readRef(value) {
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const ref = value;
+    const branded = VOLATILE_WRITE in value;
+    if (!branded) {
+        const keys = Object.keys(value);
+        if (keys.length !== 1 || keys[0] !== 'get')
+            return value;
+    }
+    return typeof ref.get === 'function' ? readRef(ref.get()) : value;
+}
+/**
+ * Whether a row-config schema carries the live marker anywhere — exactly what
+ * a `dsh-settings` ≥0.1.7 host needs to serve this plugin's `/settings` page
+ * (`volatileForm()` returns undefined without it and the entry never reaches
+ * `describe()`, which the TUI renders as `命名空间未注册`).
+ *
+ * Read structurally: the schemastery 3.18.1/3.18.2 types this repo builds
+ * against do not expose `.dict` on the schema type, and the caller owns the
+ * schema. settingsSection.ts warns with this when a new-generation host cannot
+ * serve the card, instead of leaving a bare badge as the only clue.
+ */
+export function hasLiveConfigFields(schema) {
+    const dict = schema
+        ?.dict;
+    return Object.values(dict ?? {}).some(field => field?.meta?.volatile === true);
+}

package/lib/types/settingsSection.d.ts

@@ -2,12 +2,34 @@
  * /settings integration (seam six: tuiSettingsSections over the dsh settings
  * service).
  *
- * Registers the `pink-theme` settings namespace and a declarative editing
- * section for it. Storage, schema validation, and layered resolution stay on
- * the dsh settings service; the TUI only renders. Fields carry no schema
- * defaults on purpose — an unset user layer must fall through to the cordis
- * config layer (mirrors the host's own lang/fullscreen fields), and format()
- * displays the effective value instead of a misleading blank.
+ * Registers a declarative editing section for the plugin's settings and, on
+ * hosts that still have the registration API, the settings namespace itself.
+ * Storage, schema validation, and layered resolution stay on the dsh settings
+ * service; the TUI only renders. Fields carry no schema defaults on purpose —
+ * an unset user layer must fall through to the cordis config layer (mirrors
+ * the host's own lang/fullscreen fields), and format() displays the effective
+ * value instead of a misleading blank.
+ *
+ * Two generations, branched by capability (never by version),
+ * `dsh-settings`'s 0.1.7 break being the reason
+ * (docs/decisions/2026-09-24-settings-generation-adaptation.md):
+ *
+ * - **≤0.1.6** (dsh-TUI 0.9.x/0.10.x) — `settings.register(ns, schema)` owns
+ *   the namespace. The card's paths resolve against the scope schema declared
+ *   here, and `scope.watch` pushes edits into the plugin.
+ * - **≥0.1.7** (dsh-TUI 0.11+) — there is no registration API at all
+ *   (`SettingsForms` projects each profile entry's *Config* instead). The
+ *   namespace is this plugin's profile entry id (see
+ *   {@link resolveSettingsNamespace}) and the form schema is `Config` filtered
+ *   to its volatile fields (liveConfig.ts). Edits land in the profile patch,
+ *   the loader rewrites those same refs in place, and
+ *   `loader/volatile-update` announces it; this module re-reads the live config
+ *   on that event. The card stays ours, so the auto-generated page is turned
+ *   off with `configure({ auto: false })`.
+ *
+ * A miss in either direction is silent and user-visible only as a card that
+ * renders but never saves (≤0.1.6) or a `命名空间未注册` badge (≥0.1.7) — hence
+ * the branch below warns instead of swallowing the failure.
  *
  * The section splits into two navigation groups (背景跟随 / 状态行). The two
  * text fields (glyph, separator) validate their drafts with parse(): an
@@ -26,18 +48,54 @@ export type PinkSettingsDoc = StatusOptions & {
     /** Apply a cached terminal background: pink-day <-> pink-night. */
     followSystem?: boolean;
 };
+/** The settings namespace this plugin owns by default, and the fallback when
+ *  the Loader entry id is unusable. On ≥0.1.7 hosts the *entry id* is the
+ *  namespace the host keys by, so the effective value is
+ *  {@link resolveSettingsNamespace}: a default install lands on exactly this
+ *  string (`cordis.patch.yml` pins `id: dsh-tui-theme`), and it stays the name
+ *  the README documents for settings storage. */
+export declare const SETTINGS_NS = "dsh-tui-theme";
+/**
+ * The namespace this plugin's settings live under: the Loader entry id when it
+ * satisfies the section grammar, {@link SETTINGS_NS} otherwise.
+ *
+ * A `dsh-settings` ≥0.1.7 host keys namespaces by the Loader entry id
+ * (`SettingsForms.describe()` → `entry.options.id`), so keying the card off
+ * anything else breaks the moment the row is renamed — the fragility dsh-TUI
+ * #990 records, where even the host's own section had to stop hard-coding its
+ * name. Both generations resolve to the same string here, so the card, the
+ * legacy registration and the host's projection cannot disagree.
+ */
+export declare function resolveSettingsNamespace(ctx: Context): string;
+/** Everything the wiring needs from the plugin's own activation. */
+export interface PinkSettingsWiring {
+    /** The cordis-config layer (the effective value format() falls back to for
+     *  still-unset fields). */
+    readonly cordis: StatusOptions & {
+        followSystem?: boolean;
+    };
+    /** Current plain values of the plugin's own row config. On ≥0.1.7 hosts the
+     *  loader rewrites the live refs in place, so calling this again after
+     *  `loader/volatile-update` yields the edited values. */
+    readLive(): PinkSettingsDoc;
+    /** Whether the row-config schema carries the live marker
+     *  (`hasLiveConfigFields(Config)`); diagnostics only. */
+    readonly hasLiveFields: boolean;
+    /** Receives the defined-valued subset of the settings doc — the initial one
+     *  and every later edit. */
+    onDoc(doc: PinkSettingsDoc): void;
+}
 /**
- * Register the settings namespace (mirror the resolved document to the
- * caller) and, separately, the /settings section for it. Each part waits for
- * its own service; neither is required for the other.
+ * Register the /settings section and, on hosts that still have the
+ * registration API, the settings namespace behind it. Each part waits for its
+ * own service; neither is required for the other.
  *
- * @param ctx - The plugin's own activation context.
- * @param cordis - The cordis-config layer (shown as the effective value for
- *   still-unset fields).
- * @param onDoc - Called with the defined-valued subset of the settings doc,
- *   initially and on every committed edit.
+ * @param ctx - The plugin's own activation context: the Config owner the
+ *   ≥0.1.7 page policy and the volatile-update listener must attach to (their
+ *   disposers ride the inject child, which is what a service reload recycles).
+ * @param wiring - The value source and sink for the card.
  * @param dataDir - The host data directory (~/.dsh-tui), read by the
  *   followSystem field's format() to surface the cached follow state.
  */
-export declare function registerPinkSettings(ctx: Context, cordis: StatusOptions, onDoc: (doc: PinkSettingsDoc) => void, dataDir?: string): void;
+export declare function registerPinkSettings(ctx: Context, wiring: PinkSettingsWiring, dataDir?: string): void;
 //# sourceMappingURL=settingsSection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"settingsSection.d.ts","sourceRoot":"","sources":["../../src/settingsSection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAIpD,+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;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,EACrC,OAAO,GAAE,MAA0B,GAClC,IAAI,CA0DN"}
+{"version":3,"file":"settingsSection.d.ts","sourceRoot":"","sources":["../../src/settingsSection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAIpD,+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;AAkBD;;;;;iDAKiD;AACjD,eAAO,MAAM,WAAW,kBAAY,CAAA;AAcpC;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAG7D;AAED,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC;+BAC2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IAC3D;;6DAEyD;IACzD,QAAQ,IAAI,eAAe,CAAA;IAC3B;6DACyD;IACzD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B;gCAC4B;IAC5B,KAAK,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAAA;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE,MAA0B,GAClC,IAAI,CAqCN"}