dsh-tui-theme 0.6.0 → 0.7.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tui-theme",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "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.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/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,5 @@ 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')

package/scripts/validate-themes-against-host.mjs

@@ -100,7 +100,10 @@ assert.deepEqual(
   [...allKeys].sort(),
   'compiled theme keys must match the checked-out host source',
 )
-assert.ok(allKeys.length >= 90, 'host Theme key count drifted; re-check coverage')
+// The absolute key floor from the 96-key era does not survive the 0.10.1
+// semantic refactor (73 canonical keys); per-key coverage below is the real
+// guarantee, so the count is reported instead of pinned to a hardcoded floor.
+console.log(`* host Theme key count: ${allKeys.length} (coverage asserted per key)`)
 
 const settingsKeys = [
   'promptBorder',
@@ -185,7 +188,19 @@ const cases = [
   ['pink-night', 'success', '#55303E', 3.0],
   ['pink-night', 'inactive', '#55303E', 3.0],
   ['pink-day', 'text', '#F6F3ED', 4.5],
-  ['pink-day', 'claude', '#F6F3ED', 3.0],
+  // claude drives the 5-row header display font and bold+underlined markdown
+  // headings; the sakura-day identity deliberately goes one notch lighter
+  // (#DE6E96), so the large-text floor here is 2.5 instead of 3.0. Body-text
+  // readability stays guarded by the 4.5 `text` case above.
+  ['pink-day', 'claude', '#F6F3ED', 2.5],
+  // The DEEPSEEK pixel word's gradient end (claudeBlue_FOR_SYSTEM_SPINNER,
+  // 0.10.1 `activity`) was lightened one notch with the same sakura-day
+  // family move (#DE6E96 -> #E879A0), so the gradient reads as a fade. The
+  // measured 2.47 is accepted for this decorative gradient end and guarded
+  // here at 2.4 — the floor exists to catch further lightening, not to
+  // re-litigate the accepted 0.03 gap below the 2.5 large-text floor.
+  // Decision record: docs/decisions/2026-09-12-pink-day-claude-family-lightening.md
+  ['pink-day', 'claudeBlue_FOR_SYSTEM_SPINNER', '#F6F3ED', 2.4],
   ['pink-day', 'inactive', '#F6F3ED', 2.5],
   ['pink-day', 'success', '#F6F3ED', 3.0],
   ['pink-day', 'success', '#F3D7E0', 2.5],
@@ -196,12 +211,17 @@ const cases = [
 // ratio is assertable here — the host renders whatever the user's terminal
 // palette defines. Its settings keys are still covered by the per-theme
 // key-coverage assertions above.
+// Hosts >= 0.10.1 resolve built themes to canonical keys, so era keys read
+// their canonical names there; pre-refactor hosts keep the era keys.
+const semanticKeys = 'accent' in built['pink-night']
+const semanticAliases = { claude: 'accent', claudeBlue_FOR_SYSTEM_SPINNER: 'activity' }
 for (const [theme, key, background, minimum] of cases) {
-  const foregroundRgb = parseColor(built[theme][key])
+  const probeKey = (semanticKeys && semanticAliases[key]) || key
+  const foregroundRgb = parseColor(built[theme][probeKey])
   const backgroundRgb = parseColor(background)
-  assert.notEqual(foregroundRgb, undefined, `${theme}.${key} must be parseable`)
+  assert.notEqual(foregroundRgb, undefined, `${theme}.${probeKey} must be parseable`)
   const ratio = contrast(foregroundRgb, backgroundRgb)
-  assert.ok(ratio >= minimum, `${theme}.${key} contrast ${ratio.toFixed(2)} >= ${minimum}`)
+  assert.ok(ratio >= minimum, `${theme}.${probeKey} contrast ${ratio.toFixed(2)} >= ${minimum}`)
 }
 
 console.log(`OK host theme validation: ${Object.keys(built).length} themes, ${allKeys.length - 1} keys each, settings colors covered`)

package/scripts/verify-package.mjs

@@ -44,6 +44,12 @@ for (const required of [
   'lib/types/runtimeThemes.d.ts',
   'lib/types/toast.js',
   'lib/types/toast.d.ts',
+  'lib/types/statusView.js',
+  'lib/types/statusView.d.ts',
+  'lib/types/ornament.js',
+  'lib/types/ornament.d.ts',
+  'lib/types/shadowCleanup.js',
+  'lib/types/shadowCleanup.d.ts',
   'themes/pink-night.json',
   'themes/pink-day.json',
   'themes/pink-ansi.json',