dsh-tui-theme 0.7.0 → 0.7.2

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

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/lib/types/statusLine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"statusLine.d.ts","sourceRoot":"","sources":["../../src/statusLine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAkBlD,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,YAAY,CAAA;AAEpD,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED,mCAAmC;AACnC,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAA;AAsCrD;;;;;;GAMG;AACH,wBAAgB,gCAAgC,IAAI,IAAI,CAGvD;AAyGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,GAAG,IAAI,CAgIvF"}
+{"version":3,"file":"statusLine.d.ts","sourceRoot":"","sources":["../../src/statusLine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAkBlD,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,YAAY,CAAA;AAEpD,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED,mCAAmC;AACnC,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAA;AAsCrD;;;;;;GAMG;AACH,wBAAgB,gCAAgC,IAAI,IAAI,CAGvD;AAuGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,GAAG,IAAI,CAyIvF"}

package/lib/types/statusLine.js

@@ -106,8 +106,7 @@ function activeThemeName(dataDir) {
     }
     return prefCache.value;
 }
-function isPinkThemeActive(dataDir) {
-    const name = activeThemeName(dataDir);
+function isPinkTheme(name) {
     return name !== undefined && PINK_THEMES.has(name);
 }
 // ── palette colors ──────────────────────────────────────────────────────────
@@ -151,13 +150,12 @@ function readPalette(name) {
     }
     return NO_COLORS;
 }
-function paletteFor(dataDir) {
-    const name = activeThemeName(dataDir);
-    if (name === undefined || !PINK_THEMES.has(name))
+function paletteFor(themeName) {
+    if (!isPinkTheme(themeName))
         return NO_COLORS;
     const now = Date.now();
-    if (colorsCache === undefined || colorsCache.name !== name || now - colorsCache.at >= THEME_PREF_TTL_MS) {
-        colorsCache = { at: now, name, colors: readPalette(name) };
+    if (colorsCache === undefined || colorsCache.name !== themeName || now - colorsCache.at >= THEME_PREF_TTL_MS) {
+        colorsCache = { at: now, name: themeName, colors: readPalette(themeName) };
     }
     return colorsCache.colors;
 }
@@ -192,7 +190,8 @@ export function startStatusLine(ctx, getEffective) {
         // differ in how the result reaches the host.
         const renderScalar = () => {
             const eff = getEffective();
-            const cells = statusCells(eff);
+            const themeName = activeThemeName(dataDir);
+            const cells = statusCells(eff, themeName);
             const separator = sanitizeOrnament(eff.statusSeparator, SEPARATOR);
             const parts = [cells.glyph, cells.clock, cells.turns].filter((value) => value !== undefined);
             const text = parts.join(` ${separator} `);
@@ -209,14 +208,18 @@ export function startStatusLine(ctx, getEffective) {
             try {
                 if (store !== undefined) {
                     const eff = getEffective();
-                    const cells = statusCells(eff);
+                    // One pref read per render, shared by the visibility check and the
+                    // palette: the module header's "one cheap stat" invariant holds on
+                    // both paths (statusCells and paletteFor each used to re-resolve).
+                    const themeName = activeThemeName(dataDir);
+                    const cells = statusCells(eff, themeName);
                     store.push({
                         visible: cells.glyph !== undefined || cells.clock !== undefined || cells.turns !== undefined,
                         glyph: cells.glyph,
                         clock: cells.clock,
                         turns: cells.turns,
                         separator: sanitizeOrnament(eff.statusSeparator, SEPARATOR),
-                        colors: paletteFor(dataDir),
+                        colors: paletteFor(themeName),
                     });
                     return;
                 }
@@ -227,9 +230,10 @@ export function startStatusLine(ctx, getEffective) {
             }
         };
         /** The three optional cells (all undefined = the line is off: master
-         *  switch, theme scope, and the toggles fold into this one shape). */
-        function statusCells(eff) {
-            const enabled = eff.statusEnabled && (eff.statusScope === 'all-themes' || isPinkThemeActive(dataDir));
+         *  switch, theme scope, and the toggles fold into this one shape).
+         *  Takes the theme name resolved once by the caller per render. */
+        function statusCells(eff, themeName) {
+            const enabled = eff.statusEnabled && (eff.statusScope === 'all-themes' || isPinkTheme(themeName));
             if (!enabled)
                 return { glyph: undefined, clock: undefined, turns: undefined };
             return {

package/lib/types/themeAssets.d.ts

@@ -19,6 +19,10 @@ export interface ThemeInstallResult {
     readonly repaired: readonly string[];
     /** Files that could not be installed (per-file failures). */
     readonly failed: readonly string[];
+    /** Set only when the bundled directory itself was unreadable, so nothing
+     *  was attempted and no per-file entry exists. Carries the directory and
+     *  the underlying error for the caller's log. */
+    readonly sourceError?: string;
 }
 export interface BundledTheme {
     readonly file: string;

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

@@ -1 +1 @@
-{"version":3,"file":"themeAssets.d.ts","sourceRoot":"","sources":["../../src/themeAssets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAA;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAID,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,SAAS,GAAE,MAA2B,GAAG,YAAY,EAAE,CA0CxF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,MAA0B,EACrC,SAAS,GAAE,MAA2B,GACrC,kBAAkB,CAmCpB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,GAAE,MAA0B,EACrC,SAAS,GAAE,MAA2B,GACrC,MAAM,EAAE,CAuBV;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,MAA0B,EACrC,SAAS,GAAE,MAA2B,GACrC,MAAM,EAAE,CAkBV"}
+{"version":3,"file":"themeAssets.d.ts","sourceRoot":"","sources":["../../src/themeAssets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC;;qDAEiD;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAA;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAOD,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,SAAS,GAAE,MAA2B,GAAG,YAAY,EAAE,CA0CxF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,MAA0B,EACrC,SAAS,GAAE,MAA2B,GACrC,kBAAkB,CAqCpB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,GAAE,MAA0B,EACrC,SAAS,GAAE,MAA2B,GACrC,MAAM,EAAE,CAuBV;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,MAA0B,EACrC,SAAS,GAAE,MAA2B,GACrC,MAAM,EAAE,CAkBV"}

package/lib/types/themeAssets.js

@@ -15,7 +15,10 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // Same resolution order as the host's utils/paths.ts homeDir(): os.homedir()
-// first, USERPROFILE/HOME spellings as stripped-down fallbacks.
+// first, USERPROFILE/HOME spellings as stripped-down fallbacks. When all three
+// come up empty the returned '' makes every derived path resolve against the
+// process cwd — the host's own semantics, kept deliberately identical rather
+// than second-guessed here.
 export function homeDir() {
     return homedir() || process.env.USERPROFILE || process.env.HOME || '';
 }
@@ -87,8 +90,10 @@ export function installBundledThemes(targetDir = themesTargetDir(), sourceDir =
     try {
         files = readdirSync(sourceDir).filter(entry => entry.toLowerCase().endsWith('.json'));
     }
-    catch {
-        return { installed, skipped, repaired, failed: [sourceDir] };
+    catch (error) {
+        // No file was attempted, so `failed` stays empty; the directory-level
+        // reason travels separately so the caller can log a precise line.
+        return { installed, skipped, repaired, failed, sourceError: `could not read bundled themes from ${sourceDir}: ${String(error)}` };
     }
     for (const file of files) {
         const target = join(targetDir, file);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tui-theme",
-  "version": "0.7.0",
+  "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",
@@ -58,8 +59,8 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || 0.1.3-alpha.2 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.2-alpha.3 || 0.1.3-alpha.2 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || 0.1.3-alpha.2 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.2-alpha.3 || 0.1.3-alpha.2 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || 0.1.2-alpha.3 || 0.1.3-alpha.2 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || 0.1.2-alpha.3 || 0.1.3-alpha.2 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {