dsh-tui-theme 0.6.1 → 0.7.1

package/lib/types/statusView.js

@@ -0,0 +1,126 @@
+/**
+ * Rich status view (dsh-TUI >= 0.10.1 seam: `tuiStatus.registerView`).
+ *
+ * A compact one-row host React component that renders the blossom line with
+ * colors taken from the active pink palette — the one thing the scalar
+ * `tuiStatus.set` path can never do (the host renders set() text uncolored +
+ * terminal dim).
+ *
+ * Data channel: the component subscribes to a tiny plugin-side external
+ * store via the host React's useSyncExternalStore, exactly the "owns its
+ * live data via an external store" pattern the host seam documents. The
+ * plugin pushes scalar-only snapshots (turn boundaries, the clock tick,
+ * settings edits); the component maps one snapshot to themed Text cells and
+ * never touches the filesystem, timers, or events itself — it runs on the
+ * host's render thread and must stay a pure function of its snapshot.
+ *
+ * Host kit rules honored here: the component is created with the host React
+ * instance handed in via props (single-React rule — the plugin never imports
+ * react), and `Box`/`Text` receive only layout/color props (no focus,
+ * keyboard, wheel, or ref props; no pointer handlers either — the line is
+ * pure display).
+ * @module dsh-tui-theme/statusView
+ */
+export const NO_COLORS = Object.freeze({
+    glyph: undefined,
+    text: undefined,
+    separator: undefined,
+});
+function sameSnapshot(a, b) {
+    return (a.visible === b.visible &&
+        a.glyph === b.glyph &&
+        a.clock === b.clock &&
+        a.turns === b.turns &&
+        a.separator === b.separator &&
+        a.colors.glyph === b.colors.glyph &&
+        a.colors.text === b.colors.text &&
+        a.colors.separator === b.colors.separator);
+}
+export function createStatusStore() {
+    const listeners = new Set();
+    let current = Object.freeze({
+        visible: false,
+        glyph: undefined,
+        clock: undefined,
+        turns: undefined,
+        separator: '·',
+        colors: NO_COLORS,
+    });
+    return {
+        getSnapshot: () => current,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        push(next) {
+            if (sameSnapshot(current, next))
+                return;
+            current = Object.freeze({
+                visible: next.visible,
+                glyph: next.glyph,
+                clock: next.clock,
+                turns: next.turns,
+                separator: next.separator,
+                colors: Object.freeze({
+                    glyph: next.colors.glyph,
+                    text: next.colors.text,
+                    separator: next.colors.separator,
+                }),
+            });
+            for (const listener of [...listeners]) {
+                try {
+                    listener();
+                }
+                catch {
+                    // One broken listener must not starve the others.
+                }
+            }
+        },
+        clear() {
+            listeners.clear();
+        },
+    };
+}
+/**
+ * Build the rich view component bound to one store. The returned function is
+ * a host React component: it receives `{ React, ui }` from the host on every
+ * render and maps the current snapshot to a one-row themed Box.
+ */
+export function createStatusViewComponent(store) {
+    return props => {
+        const { React, ui } = props;
+        const snapshot = React.useSyncExternalStore(store.subscribe, store.getSnapshot);
+        if (!snapshot.visible)
+            return null;
+        const cells = [];
+        if (snapshot.glyph !== undefined) {
+            cells.push({ text: snapshot.glyph, color: snapshot.colors.glyph });
+        }
+        if (snapshot.clock !== undefined) {
+            cells.push({ text: snapshot.clock, color: snapshot.colors.text });
+        }
+        if (snapshot.turns !== undefined) {
+            cells.push({ text: snapshot.turns, color: snapshot.colors.text });
+        }
+        if (cells.length === 0)
+            return null;
+        const children = [];
+        for (const [index, cell] of cells.entries()) {
+            if (index > 0) {
+                children.push(React.createElement(ui.Text, { key: `sep-${index}`, color: snapshot.colors.separator }, ` ${snapshot.separator} `));
+            }
+            children.push(React.createElement(ui.Text, { key: `cell-${index}`, color: cell.color }, cell.text));
+        }
+        return React.createElement(ui.Box, { flexDirection: 'row' }, children);
+    };
+}
+/**
+ * The registration descriptor for the rich view. The caller passes the same
+ * contribution key the scalar path uses, so the effect-ledger resource id
+ * and the headless order-test pin remain stable across both paths.
+ */
+export function statusViewDescriptor(key, component) {
+    return { key, maxRows: 1, component };
+}

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.6.1",
+  "version": "0.7.1",
   "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",
@@ -58,57 +58,57 @@
   },
   "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",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.2",
+    "@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": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-session": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-settings": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-settings": "0.1.2-alpha.3",
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@deepseek-harness-tui/dsh-tui": "0.10.0-beta.4",
+    "@deepseek-harness-tui/dsh-tui": "0.10.1",
     "@types/node": "^22.0.0",
     "tsx": "^4.23.12",
     "typescript": "^6.0.3",
-    "@deepseek-ai/dsh-llm": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-agent": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-user-questions": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-commands": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-atomic-write": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-tool-ask-user": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-skill": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-agent-instructions": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-invariants": "0.1.2-alpha.2"
+    "@deepseek-ai/dsh-llm": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-user-questions": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-user-approval": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-commands": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-atomic-write": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-tool-ask-user": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-skill": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent-instructions": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "0.1.2-alpha.3"
   },
   "overrides": {
-    "@deepseek-ai/dsh-session": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-settings": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-agent": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-user-questions": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-commands": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-atomic-write": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-tool-ask-user": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-skill": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-agent-instructions": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-invariants": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-scope": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-attachment": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-brand": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-timeout": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-code-runtime": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-fs": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-home-paths": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "0.1.2-alpha.2"
+    "@deepseek-ai/dsh-session": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-settings": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-user-questions": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-user-approval": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-commands": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-atomic-write": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-tool-ask-user": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-skill": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent-instructions": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-scope": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-attachment": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-brand": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-timeout": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-code-runtime": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-fs": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-home-paths": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-sandbox": "0.1.2-alpha.3"
   },
   "allowScripts": {
     "esbuild@0.28.2": true

package/scripts/expected-settings-contract.mjs

@@ -25,13 +25,18 @@ export const SETTINGS_FIELDS = [
   [['showClock'], 'boolean'],
   [['showTurns'], 'boolean'],
   [['statusScope'], 'select'],
+  [['statusGlyph'], 'text'],
+  [['statusSeparator'], 'text'],
 ]
 
 /** The values the statusScope select must expose, looked up by field path. */
 export const STATUS_SCOPE_FIELD_PATH = ['statusScope']
 export const STATUS_SCOPE_OPTIONS = ['pink-only', 'all-themes']
 
-/** Assert a section object (ns + fields) matches the contract. */
+/** Navigation group ids; every field must name one of them. */
+export const SETTINGS_GROUPS = ['follow', 'status-line']
+
+/** Assert a section object (ns + groups + fields) matches the contract. */
 export function assertSettingsContract(assert, section) {
   assert.equal(section.ns, SETTINGS_NAMESPACE, 'settings namespace must match')
   const actual = section.fields.map(field => [field.path, field.kind])
@@ -50,4 +55,19 @@ export function assertSettingsContract(assert, section) {
     STATUS_SCOPE_OPTIONS,
     'status scope must expose both supported select values',
   )
+  assert.deepEqual(
+    (section.groups ?? []).map(group => group.id).sort(),
+    [...SETTINGS_GROUPS].sort(),
+    'settings groups must remain compatible with the declared navigation',
+  )
+  for (const field of section.fields) {
+    assert.equal(
+      typeof field.group, 'string',
+      `field ${JSON.stringify(field.path)} must declare its navigation group`,
+    )
+    assert.equal(
+      SETTINGS_GROUPS.includes(field.group), true,
+      `field ${JSON.stringify(field.path)} names an unknown group`,
+    )
+  }
 }

package/scripts/headless-order-test.mjs

@@ -102,30 +102,35 @@ const collectBinds = () => {
         .filter(entry => entry.resource?.id === STATUS_CONTRIBUTION_KEY)
     : []
 }
+// The plugin renders its contribution through the rich view path on hosts
+// with tuiStatus.registerView (0.10.1+) and through the scalar set() path on
+// older ones — the key is the same, only the store half differs.
 const readState = () => {
   const runtime = app.get('tuiStatus')
   const settingsRuntime = app.get('tuiSettingsSections')
   const settingsHost = settingsSectionsModule.getHostSettingsSections(settingsRuntime)
+  const store = statusModule.getHostStatusStore(runtime)
   return {
     pinkBinds: collectBinds(),
-    snapshot: statusModule.getHostStatusStore(runtime)?.getSnapshot(),
+    snapshot: store?.getSnapshot(),
+    viewSnapshot: typeof store?.getViewSnapshot === 'function' ? store.getViewSnapshot() : [],
     settingsSection: settingsHost?.list().find(section => section.ns === SETTINGS_NAMESPACE),
   }
 }
 
 let state = readState()
 const deadline = Date.now() + READY_TIMEOUT_MS
-while (
-  (state.pinkBinds.length === 0 ||
-    !state.snapshot?.some?.(entry => entry.key === STATUS_CONTRIBUTION_KEY) ||
-    state.settingsSection === undefined) &&
-  Date.now() < deadline
-) {
+const contributionVisible = s =>
+  s.pinkBinds.length > 0 &&
+  (s.snapshot?.some?.(entry => entry.key === STATUS_CONTRIBUTION_KEY) === true ||
+    s.viewSnapshot?.some?.(entry => entry.key === STATUS_CONTRIBUTION_KEY) === true) &&
+  s.settingsSection !== undefined
+while (!contributionVisible(state) && Date.now() < deadline) {
   await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS))
   state = readState()
 }
 
-const { pinkBinds, snapshot, settingsSection } = state
+const { pinkBinds, snapshot, viewSnapshot, settingsSection } = state
 assert.equal(
   STATUS_CONTRIBUTION_KEY,
   SETTINGS_NAMESPACE,
@@ -133,7 +138,8 @@ assert.equal(
 )
 assert.ok(pinkBinds.length > 0, `plugin must bind through the late status service within ${READY_TIMEOUT_MS}ms`)
 assert.ok(
-  snapshot?.some?.(entry => entry.key === STATUS_CONTRIBUTION_KEY),
+  snapshot?.some?.(entry => entry.key === STATUS_CONTRIBUTION_KEY) ||
+    viewSnapshot?.some?.(entry => entry.key === STATUS_CONTRIBUTION_KEY),
   `status store must contain the plugin contribution within ${READY_TIMEOUT_MS}ms`,
 )
 assert.ok(
@@ -141,4 +147,21 @@ assert.ok(
   `plugin must register its /settings section through the late settings service within ${READY_TIMEOUT_MS}ms`,
 )
 assertSettingsContract(assert, settingsSection)
-console.log(`OK headless order: ${pinkBinds.length} ledger bind(s), status contribution, settings section`)
+if (typeof statusModule.getHostStatusStore(app.get('tuiStatus'))?.getViewSnapshot === 'function') {
+  const view = viewSnapshot.find(entry => entry.key === STATUS_CONTRIBUTION_KEY)
+  assert.ok(view, 'a registerView-capable host must carry the contribution as a rich view')
+  assert.equal(view.maxRows, 1, 'the rich status view requests exactly one row')
+  assert.equal(typeof view.component, 'function', 'the rich status view carries a component')
+  assert.equal(
+    snapshot.some(entry => entry.key === STATUS_CONTRIBUTION_KEY),
+    false,
+    'the two render paths are mutually exclusive: the rich path contributes no scalar text',
+  )
+  console.log('OK headless order: rich view registered (maxRows 1), ledger bind, settings section')
+} else {
+  assert.ok(
+    snapshot?.some?.(entry => entry.key === STATUS_CONTRIBUTION_KEY),
+    'a set()-only host must carry the contribution as scalar text',
+  )
+  console.log(`OK headless order: ${pinkBinds.length} ledger bind(s), status contribution, settings section`)
+}

package/scripts/runtime-themes-headless.mjs

@@ -37,36 +37,69 @@ const pluginHost = await import(pathToFileURL(join(adapter, 'plugin-host.js')).h
 const extensions = await import(pathToFileURL(join(adapter, 'extensions.js')).href)
 const themesModule = await import(pathToFileURL(join(adapter, 'themes.js')).href)
 const themeModule = await import(pathToFileURL(join(adapter, '..', 'theme.js')).href)
-const testUtils = await import(pathToFileURL(join(adapter, '..', 'test-utils.js')).href)
+// dsh-TUI >= 0.10.1 dropped test-utils.js from the npm package; fall back to a
+// manual plugin mount (same shape as headless-order-test.mjs). The admitted
+// path stays first so release-ledger bookkeeping stays asserted where the
+// admission helpers exist.
+const testUtils = existsSync(join(adapter, '..', 'test-utils.js'))
+  ? await import(pathToFileURL(join(adapter, '..', 'test-utils.js')).href)
+  : undefined
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+const mountPlugin = async app => {
+  if (testUtils === undefined) {
+    return { context: app, fiber: app.fiber, manual: true }
+  }
+  const manifest = testUtils.testManifest({ id: SETTINGS_NAMESPACE })
+  const admitted = await testUtils.mountAdmitted(app, SETTINGS_NAMESPACE, manifest)
+  return { context: admitted.context, fiber: admitted.fiber, manual: false }
+}
 const pink = await import(pathToFileURL(join(pluginRoot, 'lib', 'types', 'index.js')).href)
 const { SETTINGS_NAMESPACE } = await import(pathToFileURL(join(pluginRoot, 'scripts', 'expected-settings-contract.mjs')).href)
 
 const app = new Context()
 await app.plugin(pluginHost.default ?? pluginHost)
-const manifest = testUtils.testManifest({ id: SETTINGS_NAMESPACE })
-const admitted = await testUtils.mountAdmitted(app, SETTINGS_NAMESPACE, manifest)
-await admitted.context.plugin(pink)
+const mount = await mountPlugin(app)
+if (mount.manual) console.log('* mountAdmitted unavailable on this host; using manual plugin mount')
+await mount.context.plugin(pink)
 await app.plugin(extensions.default ?? extensions)
 
 const host = themesModule.getHostThemes(app.get('tuiThemes'))
 assert.ok(host, 'runtime theme host must be mounted')
 const deadline = Date.now() + 5_000
 while (host.getSnapshot().length !== 3 && Date.now() < deadline) {
-  await testUtils.sleep(25)
+  await sleep(25)
 }
 const snapshot = host.getSnapshot()
 assert.deepEqual(snapshot.map(entry => entry.name).sort(), ['pink-ansi', 'pink-day', 'pink-night'])
 
+// dsh-TUI >= 0.10.1 semantic-rename sentinel: the host normalizes legacy keys
+// at admission (aliases map to canonical names, retired keys are dropped),
+// while pre-0.10.1 hosts snapshot the descriptor colors verbatim.
+const semanticKeys = 'accent' in themeModule.getTheme('dark')
 for (const entry of snapshot) {
   const expected = JSON.parse(readFileSync(join(pluginRoot, 'themes', `${entry.name}.json`), 'utf8'))
   assert.equal(entry.displayName, expected.displayName)
   assert.equal(entry.base, expected.base)
-  assert.deepEqual(entry.colors, expected.colors)
-  assert.deepEqual(host.resolve(entry.name), { ...themeModule.getTheme(entry.base), ...expected.colors })
-  assert.equal(themeModule.getTheme(entry.name).claude, expected.colors.claude)
+  if (semanticKeys) {
+    assert.equal(entry.colors.accent, expected.colors.claude)
+    assert.equal(entry.colors.accentShimmer, expected.colors.claudeShimmer)
+    assert.equal(entry.colors.activity, expected.colors.claudeBlue_FOR_SYSTEM_SPINNER)
+    assert.equal(entry.colors.activityShimmer, expected.colors.claudeBlueShimmer_FOR_SYSTEM_SPINNER)
+    assert.equal(entry.colors.mascotBody, expected.colors.clawd_body)
+    assert.equal(entry.colors.inputBackground, expected.colors.clawd_background)
+    assert.equal(entry.colors.userPromptLabel, expected.colors.briefLabelYou)
+    assert.equal(entry.colors.text, expected.colors.text)
+    assert.equal('rainbow_red' in entry.colors, false, 'retired keys are dropped at admission')
+    assert.equal(host.resolve(entry.name).accent, expected.colors.claude)
+    assert.equal(themeModule.getTheme(entry.name).accent, expected.colors.claude)
+  } else {
+    assert.deepEqual(entry.colors, expected.colors)
+    assert.deepEqual(host.resolve(entry.name), { ...themeModule.getTheme(entry.base), ...expected.colors })
+    assert.equal(themeModule.getTheme(entry.name).claude, expected.colors.claude)
+  }
 }
 assert.equal(existsSync(staticThemes), false, 'runtime registration must not create static theme files')
-await testUtils.sleep(1_700)
+await sleep(1_700)
 assert.equal(existsSync(staticThemes), false, 'runtime confirmation must leave no static fallback files')
 
 const ledgerPath = join(dataDir, 'effect-ledger.jsonl')
@@ -74,11 +107,13 @@ const readLedger = () => (existsSync(ledgerPath) ? readFileSync(ledgerPath, 'utf
 const themeCreates = readLedger().filter(entry => entry.resource?.kind === 'theme' && entry.operation === 'create')
 assert.deepEqual(themeCreates.map(entry => entry.resource.id).sort(), ['pink-ansi', 'pink-day', 'pink-night'])
 
-await admitted.fiber.dispose()
-await testUtils.sleep(50)
+await mount.fiber.dispose()
+await sleep(50)
 assert.deepEqual(host.getSnapshot(), [], 'disposing the admitted plugin must release runtime themes')
-const themeReleases = readLedger().filter(entry => entry.resource?.kind === 'theme' && entry.operation === 'release')
-assert.deepEqual(themeReleases.map(entry => entry.resource.id).sort(), ['pink-ansi', 'pink-day', 'pink-night'])
+if (!mount.manual) {
+  const themeReleases = readLedger().filter(entry => entry.resource?.kind === 'theme' && entry.operation === 'release')
+  assert.deepEqual(themeReleases.map(entry => entry.resource.id).sort(), ['pink-ansi', 'pink-day', 'pink-night'])
+}
 assert.deepEqual(themeModule.getTheme('pink-night'), themeModule.getTheme('dark'), 'disposed runtime theme no longer resolves')
 console.log('OK runtime themes: 3 registered, no static files, ledger create/release, disposal clean')
 
@@ -106,23 +141,50 @@ for (const theme of ['pink-night', 'pink-day', 'pink-ansi']) {
 const deliveries = []
 const app2 = new Context()
 await app2.plugin(pluginHost.default ?? pluginHost)
-const admitted2 = await testUtils.mountAdmitted(app2, SETTINGS_NAMESPACE, manifest)
-await admitted2.context.plugin(pink)
+const mount2 = await mountPlugin(app2)
+await mount2.context.plugin(pink)
 await app2.plugin(extensions.default ?? extensions)
 toastModule.getHostToastStore(app2.get('tuiToast'))?.setSink(delivery => deliveries.push(delivery))
 
 const toastDeadline = Date.now() + 8_000
 while (deliveries.length === 0 && Date.now() < toastDeadline) {
-  await testUtils.sleep(25)
+  await sleep(25)
 }
 assert.ok(deliveries.length >= 1, 'the shadow-hint toast must reach the host sink (retry included)')
 assert.equal(deliveries[0].color, undefined, 'the shadow hint is neutral')
 for (const file of ['pink-night.json', 'pink-day.json', 'pink-ansi.json']) {
   assert.ok(deliveries[0].text.includes(file), `hint must name ${file}`)
 }
-await admitted2.fiber.dispose()
-await testUtils.sleep(50)
-console.log('OK toast: shadow hint delivered through the real tuiToast seam')
+
+// The same shadow situation additionally offers the one-shot guided cleanup
+// dialog through the real tuiDialogs seam (host-managed confirm panel).
+// Headless has no chat screen: the request parks in the dialog store, which
+// is exactly the early-boot timing the plugin relies on — the dialog becomes
+// visible as soon as the chat screen drains the store.
+const dialogsModule = await import(pathToFileURL(join(adapter, 'dialogs.js')).href)
+const dialogStore = dialogsModule.getHostDialogStore(app2.get('tuiDialogs'))
+assert.ok(dialogStore, 'the real host must expose the dialog store')
+const dialogDeadline = Date.now() + 5_000
+while (dialogStore.getSnapshot() === null && Date.now() < dialogDeadline) {
+  await sleep(25)
+}
+const dialogSnapshot = dialogStore.getSnapshot()
+assert.ok(dialogSnapshot, 'the shadow situation must offer the cleanup dialog')
+assert.equal(dialogSnapshot.kind, 'confirm')
+assert.ok(dialogSnapshot.title.includes('旧主题文件'), 'the dialog title names the cleanup')
+for (const file of ['pink-night.json', 'pink-day.json', 'pink-ansi.json']) {
+  assert.ok((dialogSnapshot.message ?? '').includes(file), `the dialog message must name ${file}`)
+}
+assert.equal(existsSync(join(dataDir2, 'themes', 'pink-night.json')), true, 'an unanswered dialog deletes nothing')
+await mount2.fiber.dispose()
+await sleep(50)
+assert.equal(dialogStore.getSnapshot(), null, 'disposing the activation settles the parked dialog')
+assert.equal(
+  existsSync(join(dataDir2, 'themes', 'pink-night.json')),
+  true,
+  'a cancelled dialog must not delete the shadow files',
+)
+console.log('OK toast: shadow hint delivered through the real tuiToast seam; cleanup dialog offered and settled')
 
 // ── Phase 3: apply-time toasts reach the sink through the seam-late retry ───
 // On a real 0.10 host the tuiToast service arrives with the extensions row,
@@ -157,15 +219,15 @@ const fakeSettings = {
 const deliveries3 = []
 const app3 = new Context()
 await app3.plugin(pluginHost.default ?? pluginHost)
-const admitted3 = await testUtils.mountAdmitted(app3, SETTINGS_NAMESPACE, manifest)
+const mount3 = await mountPlugin(app3)
 app3.provide('settings', fakeSettings)
-await admitted3.context.plugin(pink)
+await mount3.context.plugin(pink)
 await app3.plugin(extensions.default ?? extensions)
 toastModule.getHostToastStore(app3.get('tuiToast'))?.setSink(delivery => deliveries3.push(delivery))
 
 const applyToastDeadline = Date.now() + 8_000
 while (deliveries3.length < 2 && Date.now() < applyToastDeadline) {
-  await testUtils.sleep(25)
+  await sleep(25)
 }
 const healToast = deliveries3.find(delivery => delivery.text.includes('已修复'))
 assert.ok(healToast, 'the self-heal warning fired during apply must reach the host sink')
@@ -176,5 +238,80 @@ assert.ok(followToast, 'the boot-follow result fired at settings time must reach
 assert.equal(followToast.color, 'success', 'the boot-follow toast is a success')
 assert.ok(followToast.text.includes('pink-day') && followToast.text.includes('reload'), 'the follow toast names the new theme and the reload hint')
 assert.equal(JSON.parse(readFileSync(join(dataDir3, 'theme.json'), 'utf8')).theme, 'pink-day', 'the follow pref write still happened')
-await admitted3.fiber.dispose()
+await mount3.fiber.dispose()
 console.log('OK toast phase 3: apply-time self-heal and boot-follow toasts delivered on the real host')
+
+// ── Phase 4: settings namespace registers against the REAL service, late ────
+// The stub suites cover the namespace registration with fakes, and phase 3
+// stands in a minimal fake at apply time; this phase mounts a real
+// @deepseek-ai/dsh-settings SettingsProvider AFTER the plugin (and after the
+// extensions row), so the plugin's parked ['settings'] inject fires against
+// the genuine register()/scope/watch machinery. The end-to-end signal: a
+// user-layer followSystem write through the real service flips theme.json.
+const sandbox4 = mkdtempSync(join(tmpdir(), 'pink-settings-late-'))
+process.env.USERPROFILE = sandbox4
+process.env.HOME = sandbox4
+const dataDir4 = join(sandbox4, '.dsh-tui')
+mkdirSync(dataDir4, { recursive: true })
+writeFileSync(join(dataDir4, 'theme-follow.json'), JSON.stringify({ light: true, at: 1 }, null, 2))
+
+const { SettingsProvider } = await import(pathToFileURL(hostRequire.resolve('@deepseek-ai/dsh-settings')).href)
+
+/** Minimal concrete provider: in-memory storage, no file, no background IO. */
+class MemorySettingsProvider extends SettingsProvider {
+  static provide = 'settings'
+  writable = true
+  stored = {}
+  async load() {
+    return { ...this.stored }
+  }
+
+  async persist(ns, section) {
+    this.stored[ns] = { ...section }
+  }
+}
+
+const app4 = new Context()
+await app4.plugin(pluginHost.default ?? pluginHost)
+const mount4 = await mountPlugin(app4)
+await mount4.context.plugin(pink)
+await app4.plugin(extensions.default ?? extensions)
+// Deliberately last: the namespace registration can only be "late" when the
+// service arrives after everything the plugin injects at apply time.
+await app4.plugin(MemorySettingsProvider)
+
+const provider = app4.get('settings')
+assert.ok(provider, 'the real dsh-settings provider must be mounted')
+const settingsDeadline = Date.now() + 5_000
+while (provider.get(SETTINGS_NAMESPACE) === undefined && Date.now() < settingsDeadline) {
+  await sleep(25)
+}
+assert.ok(
+  provider.get(SETTINGS_NAMESPACE),
+  `the plugin namespace must register with the real service within ${5_000}ms of its late arrival`,
+)
+await provider.update(SETTINGS_NAMESPACE, { followSystem: true })
+assert.equal(
+  provider.get(SETTINGS_NAMESPACE)?.followSystem,
+  true,
+  'the real service must resolve the committed user layer for the namespace',
+)
+
+const prefPath4 = join(dataDir4, 'theme.json')
+const followDeadline = Date.now() + 5_000
+let followed = false
+while (!followed && Date.now() < followDeadline) {
+  try {
+    followed = JSON.parse(readFileSync(prefPath4, 'utf8')).theme === 'pink-day'
+  } catch {
+    // Pref not written yet.
+  }
+  if (!followed) await sleep(25)
+}
+assert.equal(
+  followed,
+  true,
+  'the user-layer follow toggle must apply the cached light background through the real service',
+)
+await mount4.fiber.dispose()
+console.log('OK settings: namespace registers late on the real dsh-settings service and drives the follow pref')