dsh-tui-theme 0.7.1 → 0.7.2

package/lib/types/settingsSection.js

@@ -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
@@ -23,64 +45,74 @@ import { readFollowCache } from './autoTheme.js';
 import { parseOrnamentDraft } from './ornament.js';
 import { PLUGIN_ID } from './pluginId.js';
 import { homeDir } from './themeAssets.js';
+/** 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 const SETTINGS_NS = PLUGIN_ID;
+/** The grammar plugin-owned sections must satisfy
+ *  (`tuiSettingsSections.register`; the host only relaxes it for its own
+ *  sections, which may carry opaque Loader ids). */
+const NAMESPACE_PATTERN = /^[a-z][a-z0-9_-]*$/;
+/** The plugin's Loader entry id, when the host gives us one. */
+function loaderEntryId(ctx) {
+    const fiber = ctx.fiber;
+    const id = fiber?.entry?.options?.id;
+    return typeof id === 'string' ? id : undefined;
+}
+/**
+ * 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 function resolveSettingsNamespace(ctx) {
+    const id = loaderEntryId(ctx);
+    return id !== undefined && NAMESPACE_PATTERN.test(id) ? id : SETTINGS_NS;
+}
 /**
- * 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 function registerPinkSettings(ctx, cordis, onDoc, dataDir = joinHomeDataDir()) {
+export function registerPinkSettings(ctx, wiring, dataDir = joinHomeDataDir()) {
+    const ns = resolveSettingsNamespace(ctx);
     ctx.inject(['settings'], settingsCtx => {
         const settings = settingsCtx.settings;
-        try {
-            // dsh-settings validates the raw namespace at registration time. Keep
-            // this as a plain string so alpha.2 hosts, which removed the runtime
-            // settingsNamespace() helper, can load the plugin without a missing
-            // named export while older hosts retain the same behavior.
-            const scope = settings.register(PLUGIN_ID, z.object({
-                followSystem: z.boolean(),
-                showGlyph: z.boolean(),
-                showClock: z.boolean(),
-                showTurns: z.boolean(),
-                statusScope: z.union(['pink-only', 'all-themes']),
-                statusGlyph: z.string(),
-                statusSeparator: z.string(),
-            }));
-            const emit = (doc) => {
-                if (doc === null || typeof doc !== 'object')
-                    return;
-                const clean = {};
-                for (const [key, value] of Object.entries(doc)) {
-                    if (value !== undefined)
-                        clean[key] = value;
-                }
-                onDoc(clean);
-            };
-            // Own the watcher on the inject-scoped ledger so it survives exactly as
-            // long as this activation (scope.watch's disposer is otherwise leaked).
-            settingsCtx.effect(() => {
-                emit(scope.get());
-                return scope.watch(emit);
-            });
+        if (settings === undefined)
+            return;
+        if (typeof settings.register === 'function') {
+            registerNamespaceScope(settingsCtx, settings, wiring, ns);
+            return;
         }
-        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-theme: settings namespace registration failed: ${String(error)}`);
+        if (typeof settings.configure !== 'function') {
+            settingsCtx.logger.info('dsh-tui-theme: the settings service exposes neither the namespace registration nor the Config-derived surface; the settings card stays unavailable this session');
+            return;
         }
+        diagnoseConfigGeneration(ctx, ns, wiring.hasLiveFields);
+        configureOwnPage(ctx, settingsCtx, settings);
+        wiring.onDoc(definedOnly(wiring.readLive()));
+        watchLiveConfig(ctx, settingsCtx, wiring);
     });
     ctx.inject(['tuiSettingsSections'], sectionsCtx => {
         const sections = sectionsCtx
             .tuiSettingsSections;
         try {
-            const unregister = sections.register(sectionDefinition(cordis, dataDir));
+            const unregister = sections.register(sectionDefinition(ns, wiring.cordis, dataDir));
             sectionsCtx.effect(() => () => unregister());
         }
         catch (error) {
@@ -90,6 +122,136 @@ export function registerPinkSettings(ctx, cordis, onDoc, dataDir = joinHomeDataD
         }
     });
 }
+/** The defined-valued subset of a settings document: the ≤0.1.6 user layer and
+ *  the ≥0.1.7 live config both arrive with unset keys present but undefined. */
+function definedOnly(doc) {
+    if (doc === null || typeof doc !== 'object')
+        return {};
+    const clean = {};
+    for (const [key, value] of Object.entries(doc)) {
+        if (value !== undefined)
+            clean[key] = value;
+    }
+    return clean;
+}
+/**
+ * ≤0.1.6 generation: own the namespace and follow its scope. The schema spells
+ * out the same field set the card exposes and deliberately carries no defaults
+ * — an unset user layer must fall through to the cordis layer, which format()
+ * already displays as the effective value.
+ */
+function registerNamespaceScope(settingsCtx, settings, wiring, ns) {
+    try {
+        // Call it as a method (optional-call on the property): the provider's
+        // register() reads its own state, so a detached reference would lose
+        // `this` and throw.
+        //
+        // The namespace is passed as a plain string: dsh-settings validates the
+        // raw value at registration time, and alpha.2 hosts removed the runtime
+        // settingsNamespace() helper, so a branded value would be a missing named
+        // export there while older hosts keep the same behavior.
+        const scope = settings.register?.(ns, z.object({
+            followSystem: z.boolean(),
+            showGlyph: z.boolean(),
+            showClock: z.boolean(),
+            showTurns: z.boolean(),
+            statusScope: z.union(['pink-only', 'all-themes']),
+            statusGlyph: z.string(),
+            statusSeparator: z.string(),
+        }));
+        if (scope === undefined)
+            throw new Error('the settings service exposes no register()');
+        // Own the watcher on the inject-scoped ledger so it survives exactly as
+        // long as this activation (scope.watch's disposer is otherwise leaked).
+        const emit = (doc) => {
+            wiring.onDoc(definedOnly(doc));
+        };
+        settingsCtx.effect(() => {
+            emit(scope.get());
+            return scope.watch(emit);
+        });
+    }
+    catch (error) {
+        // Contained, but never silent: swallowing the provider's error is what
+        // made the ≥0.1.7 transition surface as a bare `命名空间未注册` badge with
+        // no line in the log to explain it.
+        settingsCtx.logger.warn(`dsh-tui-theme: settings namespace registration failed: ${String(error)}`);
+    }
+}
+/**
+ * Explain the two ways a ≥0.1.7 host can leave this card unserved, instead of
+ * letting `命名空间未注册` be the only clue (the diagnosis cost of dsh-TUI #990).
+ * Both are warnings, not failures: the row config and every other seam keep
+ * working.
+ */
+function diagnoseConfigGeneration(ctx, ns, hasLiveFields) {
+    const entryId = loaderEntryId(ctx);
+    if (entryId !== undefined && entryId !== ns) {
+        ctx.logger.warn(`dsh-tui-theme: the settings service keys namespaces by Loader entry id "${entryId}", which is not a valid section namespace — the settings card cannot be served; rename the plugin row to a lowercase kebab-case id`);
+    }
+    if (!hasLiveFields) {
+        ctx.logger.warn('dsh-tui-theme: no row-config field carries the live marker — this host cannot serve the settings card (needs a schemastery that accepts volatile fields); the row config keeps working');
+    }
+}
+/**
+ * ≥0.1.7 generation: the namespace is this profile entry and its form schema is
+ * the marked slice of `Config`, so there is nothing to register. The card is
+ * the plugin's own page, so opt out of the auto-generated one; the policy must
+ * be attached to the plugin's own fiber (the entry that owns the Config), not
+ * to the injected child.
+ */
+function configureOwnPage(ctx, settingsCtx, settings) {
+    try {
+        const dispose = settings.configure?.({ auto: false }, ctx.fiber);
+        if (typeof dispose === 'function') {
+            const stop = dispose;
+            settingsCtx.effect(() => stop);
+        }
+    }
+    catch (error) {
+        // Decorative: the card renders and saves either way; a future
+        // auto-generated page would merely duplicate it. `configure` throws when
+        // this fiber already registered a policy (a second inject pass).
+        settingsCtx.logger.info(`dsh-tui-theme: settings page policy not applied (${String(error)})`);
+    }
+}
+/**
+ * Follow the loader's live-config announcements.
+ *
+ * The *listener* registers on the plugin's own context: the loader emits
+ * `loader/volatile-update` on the Config-owning fiber and `Context.filter`
+ * delivers it to that fiber alone, which is the same reason the host's compat
+ * shim passes the Config owner rather than the injected child.
+ *
+ * Its *disposal*, however, belongs to the inject child (`owner`). This body
+ * runs once per settings-service arrival, in a fiber cordis recycles, while the
+ * plugin fiber outlives every pass: an effect owned by the plugin would let a
+ * second pass stack a second listener on top of the first (each event then
+ * re-reading the config twice). Without the event the initial read stands for
+ * the session — logged, because that means `/settings` edits would not reach
+ * the running plugin until it reloads.
+ */
+function watchLiveConfig(ctx, owner, wiring) {
+    const refresh = () => {
+        wiring.onDoc(definedOnly(wiring.readLive()));
+    };
+    const events = ctx;
+    let dispose;
+    try {
+        dispose = events.on?.('loader/volatile-update', refresh);
+    }
+    catch {
+        dispose = undefined;
+    }
+    if (typeof dispose !== 'function') {
+        ctx.logger.info('dsh-tui-theme: loader/volatile-update is unavailable; /settings edits apply at the next plugin reload');
+        return;
+    }
+    // `ctx.on` already ties the listener to the plugin fiber (cordis's own
+    // effect inside `Context.on`); this one exists for the recycled inject child,
+    // so it must run on that child's ledger rather than the plugin's.
+    owner.effect(() => dispose);
+}
 function joinHomeDataDir() {
     return join(homeDir(), '.dsh-tui');
 }
@@ -111,9 +273,9 @@ function followCacheDate(at) {
     return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
 }
 /** The declarative /settings block (labels bilingual, zh via descriptions). */
-function sectionDefinition(cordis, dataDir) {
+function sectionDefinition(ns, cordis, dataDir) {
     return {
-        ns: PLUGIN_ID,
+        ns,
         title: 'pink-theme',
         descriptions: { zh: 'pink-theme' },
         groups: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tui-theme",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "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",
@@ -28,8 +28,9 @@
     "preverify": "npm run build",
     "verify": "node scripts/verify.mjs",
     "verify:package": "node scripts/verify-package.mjs",
+    "verify:settings": "node scripts/verify-settings-generation.mjs",
     "verify:host": "npm run build && node scripts/headless-order-test.mjs && node scripts/runtime-themes-headless.mjs && node --import tsx/esm scripts/validate-themes-against-host.mjs",
-    "release:check": "npm run build && npm run verify && npm run verify:package",
+    "release:check": "npm run build && npm run verify && npm run verify:package && npm run verify:settings",
     "prepack": "npm run release:check"
   },
   "license": "MIT",

package/scripts/verify-package.mjs

@@ -41,6 +41,8 @@ for (const required of [
   'lib/types/pluginId.d.ts',
   'lib/types/settingsSection.js',
   'lib/types/settingsSection.d.ts',
+  'lib/types/liveConfig.js',
+  'lib/types/liveConfig.d.ts',
   'lib/types/statusLine.js',
   'lib/types/statusLine.d.ts',
   'lib/types/themeAssets.js',
@@ -63,6 +65,7 @@ for (const required of [
   'docs/screenshots/settings.png',
   'scripts/verify.mjs',
   'scripts/verify-package.mjs',
+  'scripts/verify-settings-generation.mjs',
   'scripts/headless-order-test.mjs',
   'scripts/runtime-themes-headless.mjs',
   'scripts/validate-themes-against-host.mjs',

package/scripts/verify-settings-generation.mjs

@@ -0,0 +1,306 @@
+/**
+ * Verify the plugin against a real `@deepseek-ai/dsh-settings` install of the
+ * ≥0.1.7 generation — the Config-derived forms the `/settings` screen reads.
+ *
+ * Why this exists: 0.1.7 removed the namespace-registration API entirely and
+ * projects each profile entry's Cordis Config instead. A plugin that misses the
+ * transition still boots, still registers its card, and simply renders
+ * `命名空间未注册`; a card field whose Config key is not marked volatile renders
+ * `（未设置）` forever. Both are silent, so they get a gate — the reference
+ * record is docs/decisions/2026-09-24-settings-generation-adaptation.md (in the
+ * dsh-tui-find repo), whose migration checklist this script implements for
+ * dsh-tui-theme.
+ *
+ * What it checks (against the built `lib/types/`, not the sources):
+ *   1. `volatileForm(Config)` is non-empty and holds exactly the live keys
+ *      (the entry is listed by `describe()` only when it is);
+ *   2. every live key is writable through the `isVolatilePath` gate;
+ *   3. the card's field paths equal the live keys — the parity that keeps a
+ *      field from rendering editable while nothing serves it;
+ *   4. `projectForm` over a resolved row config yields a value for every live
+ *      knob (all of them carry defaults, so nothing may read `（未设置）`);
+ *   5. the wiring against a real-shaped service (no `register`, has
+ *      `configure`): page policy opts out of the auto page on the plugin's own
+ *      fiber, the initial value comes from the live config, and a
+ *      `loader/volatile-update` re-read sees edited values.
+ *
+ * Usage:
+ *   npm run build && node scripts/verify-settings-generation.mjs
+ *   node scripts/verify-settings-generation.mjs --settings <dir>
+ *   DSH_SETTINGS_DIR=<dir> node scripts/verify-settings-generation.mjs
+ *
+ * `<dir>` is a `@deepseek-ai/dsh-settings` package directory, e.g. the one a
+ * real profile resolves:
+ *   %USERPROFILE%\.dsh\profiles\node_modules\@deepseek-ai\dsh-settings
+ *
+ * Generation detection is behavioural, never a version parse: a legacy
+ * install (≤0.1.6) is reported as "nothing to verify here" and exits 0 — its
+ * path is covered by scripts/verify.mjs. So a green run with the repo's own
+ * (legacy) dependency means "the new-generation path was not exercised", not
+ * "verified"; point DSH_SETTINGS_DIR at a real 0.1.7+ install to gate it.
+ * Exit code 1 on any failed check.
+ *
+ * The probe runs from a scratch directory inside the settings tree's own
+ * `node_modules`, so the plugin's bare import (`@deepseek-ai/schemastery`)
+ * resolves exactly as it does at runtime there — the marking only happens on a
+ * schemastery that knows `.volatile()` (3.18.3+), and that is the host's copy,
+ * not this repo's. The directory is removed on the way out.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const repoRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+
+function parseArgs(argv) {
+  let settings
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--settings') {
+      if (argv[i + 1] === undefined) throw new Error('--settings needs a directory argument')
+      settings = argv[++i]
+    } else {
+      throw new Error(`unknown option: ${argv[i]}`)
+    }
+  }
+  return { settings }
+}
+
+/** Where the settings package lives: --settings, then DSH_SETTINGS_DIR, then
+ *  this repo's own tree. */
+function resolveSettingsDir(explicit) {
+  const candidate =
+    explicit ?? process.env['DSH_SETTINGS_DIR'] ?? join(repoRoot, 'node_modules', '@deepseek-ai', 'dsh-settings')
+  if (!existsSync(join(candidate, 'package.json'))) {
+    throw new Error(
+      `no @deepseek-ai/dsh-settings at ${candidate}\n` +
+        'pass --settings <dir> or set DSH_SETTINGS_DIR (a real profile resolves it under ' +
+        '<DSH_HOME>/profiles/node_modules/@deepseek-ai/dsh-settings)',
+    )
+  }
+  return candidate
+}
+
+const failures = []
+function check(label, ok, detail = '') {
+  console.log(`${ok ? 'ok  ' : 'FAIL'} ${label}${detail === '' ? '' : ` — ${detail}`}`)
+  if (!ok) failures.push(label)
+}
+function note(text) {
+  console.log(`  · ${text}`)
+}
+
+const { settings: explicitSettings } = parseArgs(process.argv.slice(2))
+const settingsDir = resolveSettingsDir(explicitSettings)
+const version = JSON.parse(readFileSync(join(settingsDir, 'package.json'), 'utf8')).version
+console.log(`* @deepseek-ai/dsh-settings ${version} (${settingsDir})`)
+
+// Generation detection: the Config-derived surface needs `lib/types/schema.js`
+// (volatileForm/projectForm/isVolatilePath) and there must be no
+// namespace-registration class to fall back on.
+const schemaModule = join(settingsDir, 'lib', 'types', 'schema.js')
+const lib = await import(pathToFileURL(join(settingsDir, 'lib', 'index.js')).href)
+const provider =
+  lib.SettingsForms ??
+  lib.default ??
+  Object.values(lib).find(value => typeof value === 'function' && value.prototype !== undefined)
+const legacyRegister = typeof provider?.prototype?.register === 'function'
+if (!existsSync(schemaModule) || legacyRegister) {
+  console.log('* ≤0.1.6 generation (namespace registration): nothing to verify here.')
+  console.log('  The plugin\'s legacy path is covered by scripts/verify.mjs.')
+  console.log('  Point DSH_SETTINGS_DIR at a real ≥0.1.7 install to exercise the Config-derived path.')
+  process.exit(0)
+}
+console.log('* ≥0.1.7 generation (Config-derived forms): verifying the plugin card against it.')
+
+const buildDir = join(repoRoot, 'lib', 'types')
+for (const file of ['index.js', 'liveConfig.js', 'settingsSection.js']) {
+  if (!existsSync(join(buildDir, file))) {
+    throw new Error(`lib/types/${file} is missing — run \`npm run build\` first`)
+  }
+}
+
+// Scratch dir inside the settings tree's node_modules: bare specifiers resolve
+// from there exactly as the plugin's own copy would at runtime.
+const probeRoot = join(dirname(dirname(settingsDir)), `.dsh-tui-theme-settings-probe-${process.pid}`)
+try {
+  rmSync(probeRoot, { recursive: true, force: true })
+  mkdirSync(probeRoot, { recursive: true })
+  cpSync(buildDir, join(probeRoot, 'types'), { recursive: true })
+
+  const plugin = name => import(pathToFileURL(join(probeRoot, 'types', name)).href)
+  const helper = name => import(pathToFileURL(join(settingsDir, 'lib', 'types', name)).href)
+
+  const { Config } = await plugin('index.js')
+  const { LIVE_CONFIG_KEYS, hasLiveConfigFields, readConfigValues } = await plugin('liveConfig.js')
+  const { registerPinkSettings, resolveSettingsNamespace, SETTINGS_NS } = await plugin('settingsSection.js')
+  const { volatileForm, projectForm, plainConfig, isVolatilePath } = await helper('schema.js')
+
+  // The host's own schemastery: 3.18.3+ parses marked fields into live refs.
+  const hostRequire = createRequire(join(settingsDir, 'lib', 'index.js'))
+  const z = (await import(pathToFileURL(hostRequire.resolve('@deepseek-ai/schemastery')).href)).default
+  const volatileCapable = typeof z?.string?.().volatile === 'function'
+
+  const liveKeys = [...LIVE_CONFIG_KEYS].sort()
+  const form = volatileForm(Config)
+  check('a live marker exists on the shipped Config', hasLiveConfigFields(Config))
+  check('volatileForm(Config) is non-empty (describe() lists the entry)', form !== undefined)
+  const formKeys = Object.keys(form?.dict ?? {}).sort()
+  check(
+    'live keys == form-projected keys',
+    JSON.stringify(formKeys) === JSON.stringify(liveKeys),
+    formKeys.join(', '),
+  )
+  check('every live key passes the write gate', LIVE_CONFIG_KEYS.every(key => isVolatilePath(Config, [key])))
+
+  // The namespace follows the Loader entry id on this generation (dsh-TUI
+  // #990's fragility: the host keys by entry id, so a renamed row must move
+  // the card with it) and falls back to the constant for an unusable id.
+  const withEntry = id => ({ fiber: { entry: { options: { id } } } })
+  check(
+    'namespace follows the Loader entry id',
+    resolveSettingsNamespace(withEntry('custom-theme')) === 'custom-theme',
+    resolveSettingsNamespace(withEntry('custom-theme')),
+  )
+  check(
+    'namespace falls back for an unusable entry id',
+    resolveSettingsNamespace(withEntry('Custom.TUI')) === SETTINGS_NS,
+  )
+  check('namespace defaults to the constant without a Loader entry', resolveSettingsNamespace({}) === SETTINGS_NS)
+
+  // Every live knob carries a schema default here, so the projection must
+  // serve a value for each one (the `（未设置）` symptom is a defaulted field
+  // missing from the form).
+  const unset = projectForm(form, plainConfig(Config({})))
+  const unsetMissing = LIVE_CONFIG_KEYS.filter(key => unset[key] === undefined)
+  check('every live knob is served (no （未设置）)', unsetMissing.length === 0, unsetMissing.join(', '))
+
+  const rowConfig = Config({
+    followSystem: true,
+    statusGlyph: '❀',
+    statusSeparator: '✦',
+    showGlyph: true,
+    showClock: false,
+    showTurns: true,
+    statusScope: 'all-themes',
+  })
+  const view = projectForm(form, plainConfig(rowConfig))
+  check(
+    'user values survive the projection',
+    view.statusGlyph === '❀' &&
+      view.statusSeparator === '✦' &&
+      view.showClock === false &&
+      view.statusScope === 'all-themes' &&
+      view.followSystem === true,
+    JSON.stringify(view),
+  )
+
+  if (volatileCapable) {
+    check(
+      'the host sends marked fields as live refs',
+      typeof rowConfig.statusGlyph === 'object' && rowConfig.statusGlyph !== null,
+    )
+    check('apply-time config resolves through live refs', readConfigValues(rowConfig).statusGlyph === '❀')
+  } else {
+    note('this host schemastery has no .volatile(): values stay plain; meta marking still projects')
+  }
+
+  // The wiring, against a service shaped like the real one: no `register`, a
+  // per-instance page policy, and the values coming from the live Config.
+  const warns = []
+  const cards = []
+  const configured = []
+  const applied = []
+  let refresh
+  const service = {
+    configure: (presentation, owner) => {
+      configured.push({ presentation, owner })
+      return () => {}
+    },
+    describe: () => [],
+    update: async () => {},
+    mutate: async () => {},
+  }
+  const sections = {
+    register: section => {
+      cards.push(section)
+      return () => {}
+    },
+  }
+  const logger = { warn: message => warns.push(String(message)), info: () => {}, error: () => {} }
+  const child = dep => ({
+    [dep]: dep === 'settings' ? service : sections,
+    effect: factory => factory(),
+    logger,
+  })
+  const ctx = {
+    get: key => (key === 'tuiSettingsSections' ? sections : undefined),
+    effect: factory => factory(),
+    inject: (deps, callback) => {
+      for (const dep of deps) callback(child(dep))
+    },
+    on: (event, listener) => {
+      check('listens on loader/volatile-update', event === 'loader/volatile-update', event)
+      refresh = listener
+      return () => {}
+    },
+    // The plugin's own fiber, as the Loader reports it: the namespace source
+    // and the owner the page policy must attach to.
+    fiber: { entry: { options: { id: SETTINGS_NS } } },
+    logger,
+  }
+
+  const live = { current: rowConfig }
+  registerPinkSettings(
+    ctx,
+    {
+      cordis: { statusGlyph: '✿', statusSeparator: '·', showGlyph: true, showClock: true, showTurns: true, statusScope: 'pink-only', statusEnabled: true, followSystem: false },
+      readLive: () => readConfigValues(live.current),
+      hasLiveFields: hasLiveConfigFields(Config),
+      onDoc: doc => applied.push(doc),
+    },
+    join(probeRoot, 'data'),
+  )
+
+  check('the card takes the Loader entry id as its namespace', cards[0]?.ns === SETTINGS_NS, String(cards[0]?.ns))
+  check('no namespace registration is attempted', typeof service.register === 'undefined')
+  check(
+    'page policy opts out of the auto page on the plugin fiber',
+    configured.length === 1 &&
+      configured[0].presentation.auto === false &&
+      configured[0].owner === ctx.fiber,
+  )
+  const cardPaths = (cards[0]?.fields ?? []).map(field => field.path.join('.')).sort()
+  check('card fields == live keys', JSON.stringify(cardPaths) === JSON.stringify(liveKeys), cardPaths.join(', '))
+  check('initial value comes from the live config', applied.at(-1)?.statusGlyph === '❀')
+  check('a healthy ≥0.1.7 host logs no warning', warns.length === 0, warns.join(' | '))
+
+  const edited = Config({
+    followSystem: false,
+    statusGlyph: '🌸',
+    statusSeparator: '·',
+    showGlyph: false,
+    showClock: true,
+    showTurns: false,
+    statusScope: 'pink-only',
+  })
+  // Model the loader's in-place rewrite: the plugin re-reads the same object.
+  for (const key of Object.keys(edited)) live.current[key] = edited[key]
+  refresh?.()
+  check(
+    'a volatile update re-reads the edited config',
+    applied.at(-1)?.statusGlyph === '🌸' &&
+      applied.at(-1)?.showGlyph === false &&
+      applied.at(-1)?.showClock === true &&
+      applied.at(-1)?.followSystem === false,
+    JSON.stringify(applied.at(-1)),
+  )
+} finally {
+  rmSync(probeRoot, { recursive: true, force: true })
+}
+
+if (failures.length > 0) {
+  console.error(`\n${failures.length} check(s) failed`)
+  process.exit(1)
+}
+console.log('\nall checks passed')