Merge remote-tracking branch 'origin/master' into xtr/agent-loop-message-machine

# Conflicts:
#	docs/event-producer-consumer.md

packages/client/connection/src/client/fixture.ts

@@ -641,6 +641,59 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
         emitHost({ type: 'host/workspace-changed', workspace: { ...created } })
         return ok(request, { workspace: { ...created }, created: true })
       },
+      rename: (request) => {
+        const { workspaceId, title } = request.payload
+        const workspace = workspaces.find(w => w.workspaceId === workspaceId)
+        if (workspace === undefined) {
+          return err(request, {
+            code: 'workspace-not-found',
+            message: `no workspace ${workspaceId}`,
+            details: { workspaceId },
+          })
+        }
+        const trimmed = title.trim()
+        if (trimmed !== workspace.title) {
+          if (workspaces.some(w => w.workspaceId !== workspaceId && w.title === trimmed)) {
+            return err(request, {
+              code: 'workspace-name-conflict',
+              message: `workspace name '${trimmed}' is already in use`,
+              details: { name: trimmed },
+            })
+          }
+          workspace.title = trimmed
+          workspace.updatedAt = new Date().toISOString()
+          emitHost({ type: 'host/workspace-changed', workspace: { ...workspace } })
+        }
+        return ok(request, { workspace: { ...workspace } })
+      },
+      insertSessionBefore: (request) => {
+        const { workspaceId, sessionId, beforeSessionId } = request.payload
+        const workspace = workspaces.find(w => w.workspaceId === workspaceId)
+        if (workspace === undefined) {
+          return err(request, {
+            code: 'workspace-not-found',
+            message: `no workspace ${workspaceId}`,
+            details: { workspaceId },
+          })
+        }
+        if (!workspace.sessionIds.includes(sessionId)
+          || (beforeSessionId !== undefined && !workspace.sessionIds.includes(beforeSessionId))) {
+          return err(request, {
+            code: 'workspace-move-invalid',
+            message: `session or anchor is not accounted by workspace ${workspaceId}`,
+            details: { workspaceId, sessionId, ...beforeSessionId === undefined ? {} : { beforeSessionId } },
+          })
+        }
+        const without = workspace.sessionIds.filter(id => id !== sessionId)
+        const at = beforeSessionId === undefined ? without.length : without.indexOf(beforeSessionId)
+        const sessionIds = [...without.slice(0, at), sessionId, ...without.slice(at)]
+        if (!sessionIds.every((id, index) => id === workspace.sessionIds[index])) {
+          workspace.sessionIds = sessionIds
+          workspace.updatedAt = new Date().toISOString()
+          emitHost({ type: 'host/workspace-changed', workspace: { ...workspace } })
+        }
+        return ok(request, { workspace: { ...workspace } })
+      },
     },
     events: {
       async *mux(_request, signal) {
@@ -757,6 +810,8 @@ export class FixtureApiClient extends AbstractApiClient {
       case 'host.describe': return this.api.host.describe(request)
       case 'workspace.list': return this.api.workspace.list(request)
       case 'workspace.create': return this.api.workspace.create(request)
+      case 'workspace.rename': return this.api.workspace.rename(request)
+      case 'workspace.insertSessionBefore': return this.api.workspace.insertSessionBefore(request)
     }
   }
 

packages/client/connection/tests/fake-api.ts

@@ -77,6 +77,12 @@ export class FakeApiClient implements IApiClient {
       workspace: { workspaceId: 'fk-ws' as never, path: '/f/ws', title: 'ws', sessionIds: [], createdAt: '0', updatedAt: '0' },
       created: true,
     }))),
+    rename: (payload: unknown) => this.record('workspace.rename', payload, Promise.resolve(ok({
+      workspace: { workspaceId: 'fk-ws' as never, path: '/f/ws', title: 'ws', sessionIds: [], createdAt: '0', updatedAt: '0' },
+    }))),
+    insertSessionBefore: (payload: unknown) => this.record('workspace.insertSessionBefore', payload, Promise.resolve(ok({
+      workspace: { workspaceId: 'fk-ws' as never, path: '/f/ws', title: 'ws', sessionIds: [], createdAt: '0', updatedAt: '0' },
+    }))),
   }
 
   /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */

packages/client/connection/tests/fixture.spec.ts

@@ -311,6 +311,60 @@ describe('createFixtureApi', () => {
     expect(rootPath.result.value.workspace.title).toBe('/')
   })
 
+  it('workspace.rename covers not-found, conflict, no-op, and the changed frame', async () => {
+    const api = createFixtureApi()
+    const abort = new AbortController()
+    const seen: HostFrame[] = []
+    const consuming = (async () => {
+      for await (const envelope of api.events.host(req({}), abort.signal)) {
+        seen.push(envelope.payload)
+        if (seen.length >= 2) abort.abort()
+      }
+    })()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    const wsid = 'fx-ws-fixture' as WorkspaceId
+    const missing = await api.workspace.rename(req({ workspaceId: 'fx-ws-void' as WorkspaceId, title: 'x' }))
+    expect(missing.result).toMatchObject({ ok: false, error: { code: 'workspace-not-found', details: { workspaceId: 'fx-ws-void' } } })
+
+    await api.workspace.create(req({ name: 'occupied' }))
+    const conflict = await api.workspace.rename(req({ workspaceId: wsid, title: ' occupied ' }))
+    expect(conflict.result).toMatchObject({ ok: false, error: { code: 'workspace-name-conflict', details: { name: 'occupied' } } })
+
+    const noop = await api.workspace.rename(req({ workspaceId: wsid, title: ' fixture ' }))
+    if (!noop.result.ok) throw new Error('no-op rename failed')
+    expect(noop.result.value.workspace.title).toBe('fixture')
+
+    const renamed = await api.workspace.rename(req({ workspaceId: wsid, title: 'renamed' }))
+    if (!renamed.result.ok) throw new Error('rename failed')
+    expect(renamed.result.value.workspace.title).toBe('renamed')
+    await consuming
+    // Only the create and the effective rename emit frames; the no-op stays silent.
+    expect(seen.map(f => f.type)).toEqual(['host/workspace-changed', 'host/workspace-changed'])
+  })
+
+  it('workspace.insertSessionBefore moves, appends, no-ops, and rejects invalid ids', async () => {
+    const api = createFixtureApi()
+    const wsid = 'fx-ws-fixture' as WorkspaceId
+    const missing = await api.workspace.insertSessionBefore(req({ workspaceId: 'fx-ws-void' as WorkspaceId, sessionId: sid('fx-alpha') }))
+    expect(missing.result).toMatchObject({ ok: false, error: { code: 'workspace-not-found' } })
+    const ghost = await api.workspace.insertSessionBefore(req({ workspaceId: wsid, sessionId: sid('fx-ghost') }))
+    expect(ghost.result).toMatchObject({ ok: false, error: { code: 'workspace-move-invalid', details: { sessionId: 'fx-ghost' } } })
+    const badAnchor = await api.workspace.insertSessionBefore(req({ workspaceId: wsid, sessionId: sid('fx-alpha'), beforeSessionId: sid('fx-ghost') }))
+    expect(badAnchor.result).toMatchObject({ ok: false, error: { code: 'workspace-move-invalid', details: { beforeSessionId: 'fx-ghost' } } })
+
+    const moved = await api.workspace.insertSessionBefore(req({ workspaceId: wsid, sessionId: sid('fx-gamma'), beforeSessionId: sid('fx-beta') }))
+    if (!moved.result.ok) throw new Error('move failed')
+    expect(moved.result.value.workspace.sessionIds).toEqual(['fx-alpha', 'fx-gamma', 'fx-beta'])
+    const appended = await api.workspace.insertSessionBefore(req({ workspaceId: wsid, sessionId: sid('fx-alpha') }))
+    if (!appended.result.ok) throw new Error('append failed')
+    expect(appended.result.value.workspace.sessionIds).toEqual(['fx-gamma', 'fx-beta', 'fx-alpha'])
+    const before = appended.result.value.workspace.updatedAt
+    const noop = await api.workspace.insertSessionBefore(req({ workspaceId: wsid, sessionId: sid('fx-alpha') }))
+    if (!noop.result.ok) throw new Error('no-op move failed')
+    expect(noop.result.value.workspace.sessionIds).toEqual(['fx-gamma', 'fx-beta', 'fx-alpha'])
+    expect(noop.result.value.workspace.updatedAt).toBe(before)
+  })
+
   it('session.create({workspaceId}) lands on the account and unknown ids error', async () => {
     const api = createFixtureApi()
     const abort = new AbortController()
@@ -558,6 +612,15 @@ describe('FixtureApiClient (protocol-level fake carrier)', () => {
     const workspace = await client.workspace.create({ name: 'via-client' })
     if (!workspace.result.ok) throw new Error('workspace create failed')
     expect(workspace.result.value.workspace.title).toBe('via-client')
+    const wsid = workspace.result.value.workspace.workspaceId
+    const renamed = await client.workspace.rename({ workspaceId: wsid, title: 'via-client-2' })
+    if (!renamed.result.ok) throw new Error('workspace rename failed')
+    expect(renamed.result.value.workspace.title).toBe('via-client-2')
+    const attached = await client.sessions.create({ workspaceId: wsid })
+    if (!attached.result.ok) throw new Error('attached create failed')
+    const moved = await client.workspace.insertSessionBefore({ workspaceId: wsid, sessionId: attached.result.value.sessionId })
+    if (!moved.result.ok) throw new Error('workspace move failed')
+    expect(moved.result.value.workspace.sessionIds).toEqual([attached.result.value.sessionId])
   })
 
   it('maps empty, prompt-reject, and workspace-first query scenarios', async () => {

packages/client/i18n/README.md

@@ -1,16 +0,0 @@
-# @deepseek-ai/dsh-client-i18n
-
-i18n plugin: I18nService (ns×locale dictionaries, bind(ns)→t with a stable function identity, locale store). Contract: api-contracts v3 §8.
-
-## Model Experience
-
-None, as the i18n registry serves browser UI copy; nothing here reaches a model request.
-
-#### KV Cache effect
-
-None; this package neither assembles nor sends a provider request.
-
-## Known Limitations and Deferred Work
-
-- **zh/en ship as empty structures** — the existing UI copy is inline Chinese; extraction into dictionaries is deferred repo-wide work, so `bind(ns)` consumers today mostly receive key-echo fallbacks.
-- **Locale switching re-renders the whole tree** — accepted as a low-frequency operation; no per-namespace subscription granularity.

packages/client/i18n/src/client/index.ts

@@ -1,108 +0,0 @@
-/**
- * Browser-side locale registry. Bound translation functions retain stable
- * identity for injected consumers.
- */
-import type { Context } from 'cordis'
-// Snapshot stores are framework-neutral; React consumers bind hooks at their
-// rendering boundary.
-import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { en } from '../locales/en.ts'
-import { zh } from '../locales/zh.ts'
-
-/** Translate a key with optional params. */
-export type Translate = (key: string, params?: Record<string, unknown>) => string
-
-/** Locale dictionary: flat key to template string ({name} placeholders). */
-export type LocaleDict = Record<string, string>
-
-declare module 'cordis' {
-  interface Context {
-    i18n: I18nService
-  }
-}
-
-/** Fallback locale consulted after the active locale misses. */
-export const FALLBACK_LOCALE = 'zh'
-
-/** Shared namespace for shell-level texts. */
-export const COMMON_NS = 'common'
-
-/**
- * Dictionary registry plus locale switch. Lookup chain per key: active locale
- * -> zh fallback -> the key itself (missing text stays visible, fail loud in
- * the UI rather than blank).
- */
-export class I18nService {
-  private dicts = new Map<string, Map<string, LocaleDict>>()
-  private bound = new Map<string, Translate>()
-  private localeStore = createSnapshotStore<string>(FALLBACK_LOCALE)
-
-  /**
-   * Register a dictionary for a namespace and locale. Duplicate (ns, locale)
-   * throws (single occupant; a namespace's texts have one owner).
-   * @param ns - namespace.
-   * @param locale - locale tag (zh/en to start).
-   * @param dict - dictionary.
-   * @returns disposer (idempotent).
-   */
-  register(ns: string, locale: string, dict: LocaleDict): () => void {
-    let locales = this.dicts.get(ns)
-    if (!locales) {
-      locales = new Map()
-      this.dicts.set(ns, locales)
-    }
-    if (locales.has(locale)) throw new Error(`i18n namespace "${ns}" already has locale "${locale}"`)
-    locales.set(locale, dict)
-    return () => {
-      const owner = this.dicts.get(ns)
-      if (owner?.get(locale) === dict) owner.delete(locale)
-    }
-  }
-
-  /**
-   * Bind a namespace to a translate function. The returned reference is
-   * stable per namespace (repeat binds return the same function), so it can
-   * ride inject surfaces without breaking memoization.
-   * @param ns - namespace.
-   * @returns the translate function (reads the locale store at call time).
-   */
-  bind(ns: string): Translate {
-    let t = this.bound.get(ns)
-    if (!t) {
-      t = (key, params) => this.translate(ns, key, params)
-      this.bound.set(ns, t)
-      return t
-    }
-    return t
-  }
-
-  /** Active locale store (switching re-renders the tree; low frequency). */
-  get locale(): SnapshotStore<string> {
-    return this.localeStore
-  }
-
-  private translate(ns: string, key: string, params?: Record<string, unknown>): string {
-    const locales = this.dicts.get(ns)
-    const template = locales?.get(this.localeStore.getSnapshot())?.[key]
-      ?? locales?.get(FALLBACK_LOCALE)?.[key]
-      ?? key
-    if (!params) return template
-    return template.replace(/\{(\w+)\}/g, (match, name: string) =>
-      name in params ? String(params[name]) : match)
-  }
-}
-
-/** Required services (none; the loader passes the export surface as an object plugin). */
-export const inject: string[] = []
-
-/**
- * Client plugin body: provide the i18n service with base dictionaries.
- * @param ctx - client cordis context.
- */
-export function apply(ctx: Context): void {
-  const i18n = new I18nService()
-  i18n.register(COMMON_NS, 'zh', zh)
-  i18n.register(COMMON_NS, 'en', en)
-  ctx.provide('i18n', i18n)
-}

packages/client/i18n/tests/i18n.spec.ts

@@ -1,53 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { I18nService } from '@deepseek-ai/dsh-client-i18n/client'
-
-describe('I18nService', () => {
-  it('translates from the active locale with zh fallback then key passthrough', () => {
-    const i18n = new I18nService()
-    i18n.register('ns', 'zh', { hello: '你好', onlyZh: '仅中文' })
-    i18n.register('ns', 'en', { hello: 'Hello' })
-    const t = i18n.bind('ns')
-    expect(i18n.locale.getSnapshot()).toBe('zh')
-    expect(t('hello')).toBe('你好')
-    i18n.locale.set('en')
-    expect(t('hello')).toBe('Hello')
-    expect(t('onlyZh')).toBe('仅中文')
-    expect(t('missing.key')).toBe('missing.key')
-  })
-
-  it('interpolates {name} params and leaves unknown placeholders intact', () => {
-    const i18n = new I18nService()
-    i18n.register('ns', 'zh', { greet: '你好，{name}！第 {n} 次', partial: '{known} 与 {unknown}' })
-    const t = i18n.bind('ns')
-    expect(t('greet', { name: '世界', n: 2 })).toBe('你好，世界！第 2 次')
-    expect(t('partial', { known: 'A' })).toBe('A 与 {unknown}')
-    expect(t('greet')).toBe('你好，{name}！第 {n} 次')
-  })
-
-  it('bind returns a stable reference per namespace', () => {
-    const i18n = new I18nService()
-    expect(i18n.bind('a')).toBe(i18n.bind('a'))
-    expect(i18n.bind('a')).not.toBe(i18n.bind('b'))
-  })
-
-  it('duplicate (ns, locale) throws; disposer unregisters and is idempotent', () => {
-    const i18n = new I18nService()
-    const dispose = i18n.register('ns', 'zh', { k: 'v1' })
-    expect(() => i18n.register('ns', 'zh', { k: 'v2' })).toThrow('already has locale')
-    dispose()
-    dispose()
-    const t = i18n.bind('ns')
-    expect(t('k')).toBe('k')
-    i18n.register('ns', 'zh', { k: 'v2' })
-    expect(t('k')).toBe('v2')
-  })
-
-  it('locale store is subscribable (snapshot store contract)', () => {
-    const i18n = new I18nService()
-    let notified = 0
-    i18n.locale.subscribe(() => { notified += 1 })
-    i18n.locale.set('en')
-    expect(i18n.locale.getSnapshot()).toBe('en')
-    expect(notified).toBe(1)
-  })
-})

packages/client/i18n/tests/invariant.spec.ts

@@ -1,30 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
-import { apply as nodeApply } from '@deepseek-ai/dsh-client-i18n'
-import { apply as clientApply, COMMON_NS, I18nService, inject } from '@deepseek-ai/dsh-client-i18n/client'
-import * as I18nInvariant from '@deepseek-ai/dsh-client-i18n/invariant'
-import InvariantService from '@deepseek-ai/dsh-invariants'
-
-describe('invariant companion', () => {
-  it('registers under the package name with an empty installer', async () => {
-    const ctx = new Context()
-    await ctx.plugin(InvariantService, { enabled: true })
-    await expect(ctx.plugin(I18nInvariant).await()).resolves.toBeDefined()
-  })
-
-  it('node-half apply is a no-op host placeholder', () => {
-    nodeApply()
-    expect(true).toBe(true) // reaching here without throw is the contract
-  })
-
-  it('client apply provides ctx.i18n seeded with the zh/en common namespace', async () => {
-    expect(inject).toEqual([])
-    const ctx = new Context()
-    await ctx.plugin({ inject, apply: clientApply }).await()
-    const i18n = ctx.get('i18n')
-    expect(i18n).toBeInstanceOf(I18nService)
-    // Seeded dictionaries occupy the (ns, locale) seats even while empty.
-    expect(() => (i18n as I18nService).register(COMMON_NS, 'zh', {})).toThrow('already has locale')
-    expect(() => (i18n as I18nService).register(COMMON_NS, 'en', {})).toThrow('already has locale')
-  })
-})

packages/client/i18n/tsdown.config.ts

@@ -1,3 +0,0 @@
-import { clientBundle } from '../tsdown.client.ts'
-
-export default clientBundle('@deepseek-ai/dsh-client-i18n', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/client/locale/README.md

@@ -0,0 +1,16 @@
+# @deepseek-ai/dsh-client-locale
+
+Locale plugin: LocaleService — the browser locale preference (`zh`/`en`, persisted under `dsh.locale`, getter/setter with `locale/change` snapshots) plus the ns×locale dictionary registry (`bind(ns)`→t with a stable function identity; lookup chain active → zh → key).
+
+## Model Experience
+
+None, as the locale registry serves browser UI copy; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Only the Settings surface is translated** — other pages keep inline copy; repo-wide extraction into dictionaries is deferred.
+- **Locale switching re-renders subscribed consumers only** — sections not wired to `locale/change` keep their rendered text until remount.

packages/client/locale/package.json

@@ -1,6 +1,6 @@
 {
-  "name": "@deepseek-ai/dsh-client-i18n",
-  "description": "i18n plugin: I18nService (ns x locale dictionaries, bind(ns) -> t, locale store); zh/en skeleton",
+  "name": "@deepseek-ai/dsh-client-locale",
+  "description": "Locale plugin: LocaleService (zh/en preference with getter/setter/change event + persistence; ns x locale dictionaries, bind(ns) -> t); registers the Language settings row",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -23,21 +23,29 @@
     "./package.json": "./package.json"
   },
   "dshClient": {
-    "inject": [],
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime"
+    ],
     "platform": "web",
     "immediately": true
   },
   "license": "BSD-3-Clause",
-  "dependencies": {
-    "@deepseek-ai/dsh-client-runtime": "workspace:^"
-  },
   "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
-    "cordis": "^4.0.0-rc.7"
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
   },
   "files": [
     "lib/index.js",
@@ -46,5 +54,9 @@
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
-  ]
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }

packages/client/locale/src/client/LanguageRow.module.css

@@ -0,0 +1,47 @@
+/* Language row (figma 'Setting-Cell': gap 8, pad 16/0, hairline separator;
+ * the section column removes the separator on its last child). */
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 16px 0;
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+}
+
+.rowText {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding-right: 48px;
+}
+
+.title {
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Selector pill (figma 'Selector': h36 r18, fill #F5F6F7, pad 0/14, gap 12). */
+.selector {
+  display: inline-flex;
+  align-items: center;
+  gap: 12px;
+  height: 36px;
+  padding: 0 14px;
+  border: none;
+  border-radius: 18px;
+  background: var(--dsw-alias-bg-module-platform);
+  font: inherit;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+  cursor: pointer;
+}
+
+.chevron {
+  flex: none;
+}

packages/client/locale/src/client/LanguageRow.tsx

@@ -0,0 +1,68 @@
+/**
+ * Language preference row registered into the General section item slot
+ * (figma 501:30011 'Setting-Cell'): title + selector pill opening the locale
+ * menu. Registered by this package — the locale feature owns its own
+ * settings surface.
+ */
+import { useState } from 'react'
+import type { PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
+import { IconChevronDownOutline14, Menu } from '@deepseek-ai/dsh-client-ui-primitives'
+import type {} from './settings-contract.ts'
+import type { createLanguageRowStore } from './settings-store.ts'
+import css from './LanguageRow.module.css'
+
+/** Injected business face: namespace-bound translate + the preference write. */
+export interface LanguageRowInjected {
+  /** Translate a `settings.locale` dictionary key to the active-locale text. */
+  t: (key: string) => string
+  /** Switch the active locale (a registered locale id). */
+  setLocale: (id: string) => void
+}
+
+/** Full component props: runtime share + store share + injected face. */
+export type LanguageRowComponentProps =
+  PropsRuntime<'settings.general.item'> & PropsStore<ReturnType<typeof createLanguageRowStore>> & LanguageRowInjected
+
+/**
+ * Render the Language row.
+ * @param props - composed slot props.
+ * @returns the row element tree.
+ */
+export function LanguageRow({ t, setLocale, useStore }: LanguageRowComponentProps) {
+  const active = useStore(s => s.active)
+  const options = useStore(s => s.options)
+  const [open, setOpen] = useState(false)
+  const activeLabel = options.find(o => o.id === active)?.label ?? active
+
+  return (
+    <div className={css.row}>
+      <div className={css.rowText}>
+        <div className={css.title}>{t('language.title')}</div>
+      </div>
+      <Menu
+        open={open}
+        onClose={() => { setOpen(false) }}
+        items={options.map(o => ({ id: o.id, label: o.label }))}
+        selectedId={active}
+        onSelect={(id) => {
+          setLocale(id)
+          setOpen(false)
+        }}
+        align="end"
+        portal
+        anchor={(
+          <button
+            type="button"
+            className={css.selector}
+            aria-haspopup="menu"
+            aria-expanded={open}
+            onClick={() => { setOpen(v => !v) }}
+          >
+            {activeLabel}
+            <IconChevronDownOutline14 className={css.chevron} />
+          </button>
+        )}
+      />
+    </div>
+  )
+}

packages/client/locale/src/client/index.ts

@@ -0,0 +1,248 @@
+/**
+ * Browser-side locale registry. Bound translation functions retain stable
+ * identity for injected consumers. The plugin also registers the Language
+ * preference row into the settings General section — the locale feature owns
+ * its own settings surface.
+ */
+import type { Context } from 'cordis'
+import { deferRegistration, type BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import { en } from '../locales/en.ts'
+import { zh } from '../locales/zh.ts'
+import type { LanguageRowInjected } from './LanguageRow.tsx'
+import { LanguageRow } from './LanguageRow.tsx'
+import { createLanguageRowStore } from './settings-store.ts'
+
+export type { LanguageRowComponentProps, LanguageRowInjected } from './LanguageRow.tsx'
+export type { LanguageOptionRow, LanguageRowState } from './settings-store.ts'
+export type { SettingsGeneralItemOwnerProps } from './settings-contract.ts'
+
+/** Translate a key with optional params. */
+export type Translate = (key: string, params?: Record<string, unknown>) => string
+
+/** Locale dictionary: flat key to template string ({name} placeholders). */
+export type LocaleDict = Record<string, string>
+
+/** Locale identifier: the two shipped locales. */
+export type LocaleId = 'zh' | 'en'
+
+/** One selectable locale: id plus its self-described display name. */
+export interface LocaleDefinition {
+  /** Locale id (persisted; the setLocale argument). */
+  id: LocaleId
+  /** Display name in its own language (中文 / English). */
+  label: string
+}
+
+/** Immutable locale state published on every change. */
+export interface LocaleSnapshot {
+  /** Active locale id. */
+  active: LocaleId
+  /** Selectable locales in display order. */
+  locales: readonly LocaleDefinition[]
+  /** Monotonic change counter (registry or active changes). */
+  revision: number
+}
+
+declare module 'cordis' {
+  interface Context {
+    locale: LocaleService
+  }
+  interface Events {
+    /**
+     * Locale state changed (active locale switched or registry updated).
+     * @param snapshot - Current immutable locale snapshot.
+     * @mode emit
+     */
+    'locale/change'(snapshot: LocaleSnapshot): void
+  }
+}
+
+/** Fallback locale consulted after the active locale misses (also the default). */
+export const FALLBACK_LOCALE: LocaleId = 'zh'
+
+/** Shared namespace for shell-level texts. */
+export const COMMON_NS = 'common'
+
+/** Namespace owning this feature's settings-row copy. */
+export const SETTINGS_NS = 'settings.locale'
+
+/** localStorage key holding the persisted locale id. */
+export const STORAGE_KEY = 'dsh.locale'
+
+/** The two shipped locales. */
+const LOCALES: readonly LocaleDefinition[] = Object.freeze([
+  { id: 'zh', label: '中文' },
+  { id: 'en', label: 'English' },
+])
+
+/**
+ * Dictionary registry plus locale preference. Lookup chain per key: active
+ * locale -> zh fallback -> the key itself (missing text stays visible, fail
+ * loud in the UI rather than blank). Reads go through {@link getLocale};
+ * writes only through {@link setLocale}; continuous sync only through the
+ * `locale/change` event.
+ */
+export class LocaleService {
+  private dicts = new Map<string, Map<string, LocaleDict>>()
+  private bound = new Map<string, Translate>()
+  private snapshot: LocaleSnapshot
+  private readonly ctx: Context
+
+  /**
+   * @param ctx - owning context (change events are emitted on it).
+   */
+  constructor(ctx: Context) {
+    this.ctx = ctx
+    this.snapshot = Object.freeze({ active: restorePreference(), locales: LOCALES, revision: 0 })
+  }
+
+  /**
+   * Read the current immutable locale snapshot.
+   * @returns the current snapshot (stable reference until the next change).
+   */
+  getLocale(): LocaleSnapshot {
+    return this.snapshot
+  }
+
+  /**
+   * Switch the active locale — the only preference write entry. Persists the
+   * id and emits `locale/change`.
+   * @param id - a registered locale id; unknown ids throw.
+   */
+  setLocale(id: string): void {
+    const match = this.snapshot.locales.find(l => l.id === id)
+    if (match === undefined) throw new Error(`locale "${id}" is not registered`)
+    if (this.snapshot.active === match.id) return
+    this.snapshot = Object.freeze({
+      active: match.id,
+      locales: this.snapshot.locales,
+      revision: this.snapshot.revision + 1,
+    })
+    persistPreference(match.id)
+    this.ctx.emit('locale/change', this.snapshot)
+  }
+
+  /**
+   * Register a dictionary for a namespace and locale. Duplicate (ns, locale)
+   * throws (single occupant; a namespace's texts have one owner).
+   * @param ns - namespace.
+   * @param locale - locale tag (zh/en to start).
+   * @param dict - dictionary.
+   * @returns disposer (idempotent).
+   */
+  register(ns: string, locale: string, dict: LocaleDict): () => void {
+    let locales = this.dicts.get(ns)
+    if (!locales) {
+      locales = new Map()
+      this.dicts.set(ns, locales)
+    }
+    if (locales.has(locale)) throw new Error(`locale namespace "${ns}" already has locale "${locale}"`)
+    locales.set(locale, dict)
+    return () => {
+      const owner = this.dicts.get(ns)
+      if (owner?.get(locale) === dict) owner.delete(locale)
+    }
+  }
+
+  /**
+   * Bind a namespace to a translate function. The returned reference is
+   * stable per namespace (repeat binds return the same function), so it can
+   * ride inject surfaces without breaking memoization.
+   * @param ns - namespace.
+   * @returns the translate function (reads the active locale at call time).
+   */
+  bind(ns: string): Translate {
+    let t = this.bound.get(ns)
+    if (!t) {
+      t = (key, params) => this.translate(ns, key, params)
+      this.bound.set(ns, t)
+      return t
+    }
+    return t
+  }
+
+  private translate(ns: string, key: string, params?: Record<string, unknown>): string {
+    const locales = this.dicts.get(ns)
+    const template = locales?.get(this.snapshot.active)?.[key]
+      ?? locales?.get(FALLBACK_LOCALE)?.[key]
+      ?? key
+    if (!params) return template
+    return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+      name in params ? String(params[name]) : match)
+  }
+}
+
+/** Read the persisted locale id; unknown or unreadable values fall back to zh. */
+function restorePreference(): LocaleId {
+  // Non-browser runs (node e2e booting the client tree) have no localStorage.
+  if (typeof localStorage === 'undefined') return FALLBACK_LOCALE
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY)
+    if (stored === 'zh' || stored === 'en') return stored
+  } catch {
+    // Storage access can throw (privacy mode); the default below covers it.
+  }
+  return FALLBACK_LOCALE
+}
+
+/** Persist the locale id; storage failures are non-fatal (preference resets next boot). */
+function persistPreference(id: LocaleId): void {
+  if (typeof localStorage === 'undefined') return
+  try {
+    localStorage.setItem(STORAGE_KEY, id)
+  } catch {
+    // Storage access can throw (privacy mode / quota); the preference simply
+    // does not survive the session.
+  }
+}
+
+/** Required services: the slot registry (the feature registers its own settings row). */
+export const inject = ['slots']
+
+/**
+ * Client plugin body: provide the locale service with base dictionaries and
+ * register the feature-owned Language preference row into the General
+ * section's item slot (a feature owns its settings surface).
+ * @param ctx - client cordis context.
+ */
+export function apply(ctx: ClientContext): void {
+  const locale = new LocaleService(ctx)
+  locale.register(COMMON_NS, 'zh', zh)
+  locale.register(COMMON_NS, 'en', en)
+  locale.register(SETTINGS_NS, 'zh', { 'language.title': '语言' })
+  locale.register(SETTINGS_NS, 'en', { 'language.title': 'Language' })
+  ctx.provide('locale', locale)
+
+  const store = createLanguageRowStore()
+  let bound: BoundActions<typeof store> | undefined
+  const sync = (snapshot: LocaleSnapshot): void => {
+    bound?.sync(
+      snapshot.active,
+      snapshot.locales.map(l => ({ id: l.id, label: l.label })),
+      snapshot.revision,
+    )
+  }
+  ctx.on('locale/change', sync)
+  const injected = (actions: BoundActions<typeof store>): LanguageRowInjected => {
+    bound = actions
+    // Re-sync from the getter so no event is lost between registration and
+    // first render (the store's revision guard drops stale duplicates).
+    sync(locale.getLocale())
+    return {
+      t: locale.bind(SETTINGS_NS),
+      setLocale: (id) => { locale.setLocale(id) },
+    }
+  }
+  ctx.effect(() => {
+    const deferred = deferRegistration(ctx.slots, 'settings.general.item', LanguageRow, () =>
+      ctx.slots.register({
+        name: 'settings.general.item',
+        id: 'language',
+        order: 0,
+        store,
+        inject: injected,
+      }, LanguageRow))
+    return () => { deferred.dispose() }
+  }, 'locale: language settings row registration')
+}

packages/client/locale/src/client/settings-contract.ts

@@ -0,0 +1,26 @@
+/**
+ * The `settings.general.item` slot type — one preference row inside the
+ * settings General section, contributed by the feature plugin that owns the
+ * preference (locale → Language, ui-theme → Appearance). Options: `id` (row
+ * key), `order` (row position). Rows draw their own internals (row layout,
+ * separators via CSS); the section column only stacks them.
+ *
+ * TYPE HOME RATIONALE: the slot is declared at runtime by
+ * ui-settings-general's General entry, but its type lives here — this
+ * package is the common dependency of every item registrant (any settings
+ * row carries copy, so every registrant already depends on locale), whereas
+ * the declarer's own contract is unreachable for locale/ui-theme without a
+ * reference cycle.
+ */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /** One preference row inside the settings General section (see module JSDoc). */
+    'settings.general.item': { kind: 'list'; scope: 'root'; owner: SettingsGeneralItemOwnerProps }
+  }
+}
+
+/** Owner share of a General preference row (the section supplies nothing). */
+export interface SettingsGeneralItemOwnerProps {
+  /** Marker field: item owner props are intentionally empty. */
+  children?: never
+}

packages/client/locale/src/client/settings-store.ts

@@ -0,0 +1,47 @@
+/**
+ * Language row slot store: a mirror of the locale service snapshot. The
+ * plugin's apply-world change listener is the only writer; the row component
+ * reads via props.useStore.
+ */
+import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** One selectable locale row (id + self-described label). */
+export interface LanguageOptionRow {
+  /** Locale id (the setLocale argument). */
+  id: string
+  /** Display name in its own language (中文 / English). */
+  label: string
+}
+
+/** Store state mirrored from the locale snapshot. */
+export interface LanguageRowState {
+  /** Active locale id. */
+  active: string
+  /** Selectable locales in display order. */
+  options: LanguageOptionRow[]
+  /** Service revision; -1 until first sync so revision 0 lands as a change. */
+  revision: number
+}
+
+/** Declared action shape giving the exported factory a stable return type. */
+type LanguageRowActions = {
+  sync: (draft: LanguageRowState, active: string, options: LanguageOptionRow[], revision: number) => void
+}
+
+/**
+ * Declares the Language row state and write surface.
+ * @returns the store handle.
+ */
+export function createLanguageRowStore(): EngineStoreHandle<LanguageRowState, LanguageRowActions> {
+  return defineStore({
+    init: (): LanguageRowState => ({ active: '', options: [], revision: -1 }),
+    actions: {
+      sync: (d, active: string, options: LanguageOptionRow[], revision: number) => {
+        if (revision <= d.revision) return
+        d.active = active
+        d.options = options
+        d.revision = revision
+      },
+    },
+  })
+}

packages/client/locale/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

packages/client/locale/src/index.ts

@@ -1,4 +1,4 @@
 /** Host loader entry for the browser implementation exported from `./client`. */
 
-/** Host plugin body — no host-side behavior for the i18n plugin. */
+/** Host plugin body — no host-side behavior for the locale plugin. */
 export function apply(): void {}

packages/client/locale/src/invariant.ts

@@ -1,16 +1,16 @@
 /**
- * Package-owned invariant companion for `@deepseek-ai/dsh-client-i18n`.
- * @module @deepseek-ai/dsh-client-i18n/invariant
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-locale`.
+ * @module @deepseek-ai/dsh-client-locale/invariant
  */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
-const PACKAGE_NAME = '@deepseek-ai/dsh-client-i18n'
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-locale'
 
 /** Cordis companion plugin name. */
-export const name = 'client-i18n-invariant'
+export const name = 'client-locale-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 

packages/client/locale/tests/apply.spec.ts

@@ -0,0 +1,116 @@
+/** locale apply wiring: service + dictionaries provision, declaration-aware
+ * Language row registration, snapshot projection into the row store, and
+ * recovery after an HMR collapse of the declaring entry. */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { apply, inject, SETTINGS_NS } from '@deepseek-ai/dsh-client-locale/client'
+import type { LanguageRowInjected, LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import { LanguageRow } from '../src/client/LanguageRow.tsx'
+import type { createLanguageRowStore } from '../src/client/settings-store.ts'
+
+const SLOT = 'settings.general.item'
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  return { ctx, slots: ctx.get('slots') as SlotsService }
+}
+
+/** Stand in for the settings shell: declare the General item slot from root. */
+function declareItems(slots: SlotsService): () => void {
+  return slots.register(
+    { name: 'root', children: { [SLOT]: { kind: 'list', scope: 'root' } } } as never,
+    () => null,
+  )
+}
+
+/** Mirror the framework's inject choreography: bake a real instance from the
+ * declared handle and hand its actions to the entry's inject factory. */
+function faceOf(slots: SlotsService) {
+  const entry = slots.entries(SLOT).find(e => e.component === LanguageRow)!
+  const handle = entry.store as ReturnType<typeof createLanguageRowStore>
+  const instance = handle.create()
+  const face = (entry.inject as unknown as (a: typeof instance.actions) => LanguageRowInjected)(instance.actions)
+  return { entry, instance, face }
+}
+
+describe('locale apply', () => {
+  it('declares the slot service', () => {
+    expect(inject).toEqual(['slots'])
+  })
+
+  it('provides the service with base + settings dictionaries and registers the row (declaration before or after apply)', async () => {
+    const before = await bench()
+    declareItems(before.slots)
+    await before.ctx.plugin({ inject: [...inject], apply }).await()
+    const locale = before.ctx.get('locale') as LocaleService
+    // Base dictionaries are registered: the (ns, locale) seats are occupied.
+    expect(() => locale.register('common', 'zh', {})).toThrow('already has locale')
+    expect(() => locale.register('common', 'en', {})).toThrow('already has locale')
+    expect(locale.bind(SETTINGS_NS)('language.title')).toBe('语言')
+    const entry = before.slots.entries(SLOT).find(e => e.component === LanguageRow)!
+    expect(entry.options).toMatchObject({ id: 'language', order: 0 })
+
+    const after = await bench()
+    const fiber = after.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(after.slots.entries(SLOT)).toHaveLength(0)
+    declareItems(after.slots)
+    await Promise.resolve()
+    expect(after.slots.entries(SLOT).some(e => e.component === LanguageRow)).toBe(true)
+  })
+
+  it('projects service snapshots into the row store and routes face writes back', async () => {
+    const b = await bench()
+    declareItems(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const locale = b.ctx.get('locale') as LocaleService
+    // An event ahead of any inject hits the unbound-actions arm.
+    locale.setLocale('en')
+
+    const { instance, face } = faceOf(b.slots)
+    // The inject-time re-sync sealed the init window: the mirror is current.
+    expect(instance.getSnapshot().active).toBe('en')
+    expect(instance.getSnapshot().options.map(o => o.id)).toEqual(['zh', 'en'])
+    expect(face.t('language.title')).toBe('Language')
+
+    face.setLocale('zh')
+    expect(locale.getLocale().active).toBe('zh')
+    expect(instance.getSnapshot().active).toBe('zh')
+    expect(face.t('language.title')).toBe('语言')
+  })
+
+  it('recovers after an HMR collapse of the declaring entry (stale disposer must not block)', async () => {
+    const b = await bench()
+    const host = declareItems(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    expect(b.slots.entries(SLOT)).toHaveLength(1)
+
+    // Collapse: the declarer dies, the cascade removes our entry while the
+    // apply closure still holds its (now stale) disposer.
+    host()
+    expect(b.slots.entries(SLOT)).toHaveLength(0)
+
+    declareItems(b.slots)
+    await Promise.resolve()
+    expect(b.slots.entries(SLOT).some(e => e.component === LanguageRow)).toBe(true)
+  })
+
+  it('teardown removes the row; teardown without a declaration is quiet', async () => {
+    const b = await bench()
+    declareItems(b.slots)
+    const fiber = b.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(b.slots.entries(SLOT)).toHaveLength(1)
+    await fiber.dispose()
+    expect(b.slots.entries(SLOT)).toHaveLength(0)
+
+    // Never-declared bench: the effect disposer's dispose arm stays undefined.
+    const quiet = await bench()
+    const f2 = quiet.ctx.plugin({ inject: [...inject], apply })
+    await f2.await()
+    await f2.dispose()
+    expect(quiet.slots.entries(SLOT)).toHaveLength(0)
+  })
+})

packages/client/locale/tests/invariant.spec.ts

@@ -0,0 +1,34 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { apply as nodeApply } from '@deepseek-ai/dsh-client-locale'
+import { apply as clientApply, COMMON_NS, LocaleService, inject } from '@deepseek-ai/dsh-client-locale/client'
+import * as LocaleInvariant from '@deepseek-ai/dsh-client-locale/invariant'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(LocaleInvariant).await()).resolves.toBeDefined()
+  })
+
+  it('node-half apply is a no-op host placeholder', () => {
+    nodeApply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+
+  it('client apply provides ctx.locale seeded with the zh/en common namespace', async () => {
+    // The feature registers its own Language settings row, hence the slots edge.
+    expect(inject).toEqual(['slots'])
+    const ctx = new Context()
+    new SlotsService(ctx)
+    await ctx.plugin({ inject, apply: clientApply }).await()
+    const locale = ctx.get('locale')
+    expect(locale).toBeInstanceOf(LocaleService)
+    // Seeded dictionaries occupy the (ns, locale) seats even while empty.
+    expect(() => (locale as LocaleService).register(COMMON_NS, 'zh', {})).toThrow('already has locale')
+    expect(() => (locale as LocaleService).register(COMMON_NS, 'en', {})).toThrow('already has locale')
+  })
+})

packages/client/locale/tests/language-row.spec.tsx

@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+/** LanguageRow behavior: selector pill shows the active locale, the menu
+ * opens/closes, and selection drives setLocale. */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { createSnapshotStore, type SessionListState, type WorkspaceListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import { LanguageRow } from '../src/client/LanguageRow.tsx'
+import type { LanguageRowComponentProps } from '../src/client/LanguageRow.tsx'
+import { createLanguageRowStore } from '../src/client/settings-store.ts'
+
+afterEach(cleanup)
+
+const OPTIONS = [{ id: 'zh', label: '中文' }, { id: 'en', label: 'English' }]
+
+/** Empty global standard-kit hooks (the row reads neither). */
+function emptySessions() {
+  const store = createSnapshotStore<SessionListState>(
+    { ids: [], byId: {}, current: undefined, intent: undefined, phase: 'ready' })
+  return bindSnapshotSelector(store)
+}
+function emptyWorkspaces() {
+  const store = createSnapshotStore<WorkspaceListState>({
+    items: [], intent: undefined, state: 'idle', phase: 'ready', error: null,
+    baselinesReady: true, recentWorkspaceId: undefined,
+  })
+  return bindSnapshotSelector(store)
+}
+
+function mount(active = 'en') {
+  // Real store instance — the sanctioned zero-machinery path for tests.
+  const store = createLanguageRowStore().create()
+  store.actions.sync(active, OPTIONS, 0)
+  const setLocale = vi.fn()
+  const props: LanguageRowComponentProps = {
+    useSessions: emptySessions(),
+    useWorkspaces: emptyWorkspaces(),
+    useStore: bindSnapshotSelector(store),
+    actions: store.actions,
+    t: (key: string) => key === 'language.title' ? 'Language' : key,
+    setLocale,
+  }
+  render(<LanguageRow {...props} />)
+  return { store, setLocale }
+}
+
+describe('LanguageRow', () => {
+  it('shows the title and the active locale label on the selector pill', () => {
+    mount('en')
+    expect(screen.getByText('Language')).toBeDefined()
+    const trigger = screen.getByRole('button', { name: /English/ })
+    expect(trigger.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('opens the menu, selects a locale, and closes', () => {
+    const b = mount('en')
+    const trigger = screen.getByRole('button', { name: /English/ })
+    fireEvent.click(trigger)
+    expect(trigger.getAttribute('aria-expanded')).toBe('true')
+    fireEvent.click(screen.getByRole('menuitem', { name: '中文' }))
+    expect(b.setLocale).toHaveBeenCalledWith('zh')
+    expect(trigger.getAttribute('aria-expanded')).toBe('false')
+    expect(screen.queryByRole('menuitem', { name: '中文' })).toBeNull()
+  })
+
+  it('closes on outside pointerdown without selecting', () => {
+    const b = mount('en')
+    fireEvent.click(screen.getByRole('button', { name: /English/ }))
+    expect(screen.getByRole('menuitem', { name: '中文' })).toBeDefined()
+    fireEvent.pointerDown(document.body)
+    expect(screen.queryByRole('menuitem', { name: '中文' })).toBeNull()
+    expect(b.setLocale).not.toHaveBeenCalled()
+  })
+
+  it('follows store changes; an unknown active id falls back to the id itself', () => {
+    const b = mount('en')
+    act(() => { b.store.actions.sync('zh', OPTIONS, 1) })
+    expect(screen.getByRole('button', { name: /中文/ })).toBeDefined()
+    act(() => { b.store.actions.sync('fr', OPTIONS, 2) })
+    expect(screen.getByRole('button', { name: /fr/ })).toBeDefined()
+  })
+})

packages/client/locale/tests/locale.spec.ts

@@ -0,0 +1,102 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import type { LocaleSnapshot } from '@deepseek-ai/dsh-client-locale/client'
+import { LocaleService, STORAGE_KEY } from '@deepseek-ai/dsh-client-locale/client'
+
+const make = (): { ctx: Context; svc: LocaleService; events: LocaleSnapshot[] } => {
+  const ctx = new Context()
+  const events: LocaleSnapshot[] = []
+  ctx.on('locale/change', (snapshot) => { events.push(snapshot) })
+  return { ctx, svc: new LocaleService(ctx), events }
+}
+
+describe('LocaleService', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('translates through the active-locale -> zh -> key chain', () => {
+    const { svc } = make()
+    svc.register('ns', 'zh', { hello: '你好', onlyZh: '仅中文' })
+    svc.register('ns', 'en', { hello: 'Hello' })
+    const t = svc.bind('ns')
+    expect(svc.getLocale().active).toBe('zh')
+    expect(t('hello')).toBe('你好')
+    svc.setLocale('en')
+    expect(t('hello')).toBe('Hello')
+    expect(t('onlyZh')).toBe('仅中文')
+    expect(t('missing.key')).toBe('missing.key')
+  })
+
+  it('interpolates {name} params and leaves unknown placeholders intact', () => {
+    const { svc } = make()
+    svc.register('ns', 'zh', { greet: '你好，{name}！第 {n} 次', partial: '{known} 与 {unknown}' })
+    const t = svc.bind('ns')
+    expect(t('greet', { name: '世界', n: 2 })).toBe('你好，世界！第 2 次')
+    expect(t('partial', { known: 'A' })).toBe('A 与 {unknown}')
+  })
+
+  it('bind returns a stable per-namespace function identity', () => {
+    const { svc } = make()
+    expect(svc.bind('a')).toBe(svc.bind('a'))
+    expect(svc.bind('a')).not.toBe(svc.bind('b'))
+  })
+
+  it('rejects duplicate (ns, locale) and disposer only removes its own dict', () => {
+    const { svc } = make()
+    const dispose = svc.register('ns', 'zh', { k: 'v1' })
+    expect(() => svc.register('ns', 'zh', { k: 'v2' })).toThrow('already has locale')
+    dispose()
+    const t = svc.bind('ns')
+    expect(t('k')).toBe('k')
+    svc.register('ns', 'zh', { k: 'v2' })
+    expect(t('k')).toBe('v2')
+    dispose()
+    expect(t('k')).toBe('v2')
+  })
+
+  it('setLocale persists, republishes an immutable snapshot, and no-ops on same value', () => {
+    const { svc, events } = make()
+    svc.setLocale('en')
+    expect(svc.getLocale().active).toBe('en')
+    expect(localStorage.getItem(STORAGE_KEY)).toBe('en')
+    expect(events).toHaveLength(1)
+    expect(events[0]).toBe(svc.getLocale())
+    expect(events[0]!.revision).toBe(1)
+    svc.setLocale('en')
+    expect(events).toHaveLength(1)
+  })
+
+  it('throws on unknown locale ids', () => {
+    const { svc } = make()
+    expect(() => { svc.setLocale('fr') }).toThrow('not registered')
+  })
+
+  it('restores a persisted locale and falls back to zh on garbage', () => {
+    localStorage.setItem(STORAGE_KEY, 'en')
+    expect(make().svc.getLocale().active).toBe('en')
+    localStorage.setItem(STORAGE_KEY, 'fr')
+    expect(make().svc.getLocale().active).toBe('zh')
+  })
+
+  it('runs without localStorage (node boots): defaults on read, no-op on write', () => {
+    vi.stubGlobal('localStorage', undefined)
+    try {
+      const { svc } = make()
+      expect(svc.getLocale().active).toBe('zh')
+      svc.setLocale('en')
+      expect(svc.getLocale().active).toBe('en')
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('exposes the two shipped locales with self-described labels', () => {
+    const { svc } = make()
+    expect(svc.getLocale().locales).toEqual([
+      { id: 'zh', label: '中文' },
+      { id: 'en', label: 'English' },
+    ])
+  })
+})

packages/client/locale/tests/settings-store.spec.ts

@@ -0,0 +1,30 @@
+/** Language row store: snapshot-mirror action and the revision guard. */
+import { describe, expect, it } from 'vitest'
+import { createLanguageRowStore } from '../src/client/settings-store.ts'
+
+const OPTIONS = [{ id: 'zh', label: '中文' }, { id: 'en', label: 'English' }]
+
+describe('createLanguageRowStore', () => {
+  it('init shape: empty mirror with revision at -1', () => {
+    const store = createLanguageRowStore().create()
+    expect(store.getSnapshot()).toEqual({ active: '', options: [], revision: -1 })
+  })
+
+  it('sync mirrors the snapshot and advances the revision', () => {
+    const store = createLanguageRowStore().create()
+    store.actions.sync('zh', OPTIONS, 0)
+    expect(store.getSnapshot()).toEqual({ active: 'zh', options: OPTIONS, revision: 0 })
+    store.actions.sync('en', OPTIONS, 1)
+    expect(store.getSnapshot().active).toBe('en')
+    expect(store.getSnapshot().revision).toBe(1)
+  })
+
+  it('revision guard drops stale and duplicate writes', () => {
+    const store = createLanguageRowStore().create()
+    store.actions.sync('en', OPTIONS, 5)
+    store.actions.sync('zh', OPTIONS, 4)
+    store.actions.sync('zh', OPTIONS, 5)
+    expect(store.getSnapshot().active).toBe('en')
+    expect(store.getSnapshot().revision).toBe(5)
+  })
+})

packages/client/locale/tsconfig.json

@@ -9,10 +9,16 @@
   ],
   "references": [
     {
-      "path": "../../../vendor/cordis"
+      "path": "../runtime"
     },
     {
-      "path": "../runtime"
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../../vendor/cordis"
     },
     {
       "path": "../../support/invariants"

packages/client/locale/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-locale', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/client/runtime/src/client/workspaces/manager.ts

@@ -1,7 +1,7 @@
 /** Workspace baseline, incremental-frame, and unary-action owner. */
 
 import type {
-  HostFrame, IApiClient, RpcError, RpcRequest, RpcResult, WorkspaceView,
+  HostFrame, IApiClient, RpcError, RpcRequest, RpcResult, SessionId, WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { mergeOrderedBaseline } from '../ordered-baseline.ts'
@@ -143,6 +143,40 @@ export class WorkspaceManager {
     return result
   }
 
+  /**
+   * Rename a Workspace, then publish its returned snapshot without waiting
+   * for the changed frame.
+   * @param workspaceId - target workspace.
+   * @param title - new display title.
+   * @returns the wire result.
+   */
+  async rename(workspaceId: WorkspaceId, title: string): Promise<RpcResult<{ workspace: WorkspaceView }>> {
+    const { result } = await this.api.workspace.rename({ workspaceId, title })
+    if (result.ok) this.upsert(result.value.workspace)
+    return result
+  }
+
+  /**
+   * Move a session within its Workspace's manual order, then publish the
+   * returned snapshot without waiting for the changed frame.
+   * @param workspaceId - owning workspace.
+   * @param sessionId - accounted session to move.
+   * @param beforeSessionId - accounted anchor to insert before; omitted appends.
+   * @returns the wire result.
+   */
+  async insertSessionBefore(
+    workspaceId: WorkspaceId,
+    sessionId: SessionId,
+    beforeSessionId?: SessionId,
+  ): Promise<RpcResult<{ workspace: WorkspaceView }>> {
+    const { result } = await this.api.workspace.insertSessionBefore({
+      workspaceId, sessionId,
+      ...beforeSessionId === undefined ? {} : { beforeSessionId },
+    })
+    if (result.ok) this.upsert(result.value.workspace)
+    return result
+  }
+
   /**
    * Host-frame entry. Non-workspace frames are ignored so the runtime can
    * fan one host stream out to both object managers.
@@ -189,6 +223,11 @@ export class WorkspaceManager {
   private upsert(view: WorkspaceView, identity?: Workspace): void {
     this.refreshFrames?.push(view)
     const index = this.items.findIndex(item => item.getSnapshot().view?.workspaceId === view.workspaceId)
+    // Mutation responses and changed frames race (two carriers, no ordering):
+    // reject a snapshot strictly older than the installed projection so a
+    // late unary response cannot roll back a newer frame.
+    const installed = index === -1 ? undefined : this.items[index]?.getSnapshot().view
+    if (installed !== undefined && Date.parse(view.updatedAt) < Date.parse(installed.updatedAt)) return
     if (identity !== undefined) {
       this.items = index === -1
         ? [identity, ...this.items]

packages/client/runtime/src/client/workspaces/service.ts

@@ -2,7 +2,7 @@
 
 import type { Context } from 'cordis'
 import type {
-  IApiClient, RpcError, WorkspaceId, WorkspaceView,
+  IApiClient, RpcError, SessionId, WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
@@ -100,6 +100,35 @@ export class WorkspacesService {
     return result.value.workspace
   }
 
+  /**
+   * Rename a Workspace.
+   * @param workspaceId - target workspace.
+   * @param title - new display title (trimmed non-empty by the Host).
+   * @returns the renamed Workspace view.
+   */
+  async rename(workspaceId: WorkspaceId, title: string): Promise<WorkspaceView> {
+    const result = await this.manager.rename(workspaceId, title)
+    if (!result.ok) throw new Error(`workspace rename failed: ${result.error.code}: ${result.error.message}`)
+    return result.value.workspace
+  }
+
+  /**
+   * Move a session within its Workspace's manual order (DOM-insertBefore-like).
+   * @param workspaceId - owning workspace.
+   * @param sessionId - accounted session to move.
+   * @param beforeSessionId - accounted anchor to insert before; omitted appends.
+   * @returns the updated Workspace view.
+   */
+  async insertSessionBefore(
+    workspaceId: WorkspaceId,
+    sessionId: SessionId,
+    beforeSessionId?: SessionId,
+  ): Promise<WorkspaceView> {
+    const result = await this.manager.insertSessionBefore(workspaceId, sessionId, beforeSessionId)
+    if (!result.ok) throw new Error(`workspace move failed: ${result.error.code}: ${result.error.message}`)
+    return result.value.workspace
+  }
+
   /**
    * Refresh the workspace baseline, reusing an in-flight pull.
    * @returns completion of the current or newly started workspace baseline pull.

packages/client/runtime/tests/fake-api.ts

@@ -92,9 +92,18 @@ export class FakeApiClient implements IApiClient {
   onWorkspaceCreate: (payload: unknown) => Promise<RpcResponse<{ workspace: WorkspaceView; created: boolean }>> =
     () => Promise.resolve(ok({ workspace: fakeWorkspace('fk-ws'), created: true }))
 
+  onWorkspaceRename: (payload: unknown) => Promise<RpcResponse<{ workspace: WorkspaceView }>> =
+    () => Promise.resolve(ok({ workspace: fakeWorkspace('fk-ws') }))
+
+  onWorkspaceInsertSessionBefore: (payload: unknown) => Promise<RpcResponse<{ workspace: WorkspaceView }>> =
+    () => Promise.resolve(ok({ workspace: fakeWorkspace('fk-ws') }))
+
   readonly workspace: IApiClient['workspace'] = {
     list: (payload: unknown) => this.record('workspace.list', payload, this.onWorkspaceList(payload)),
     create: (payload: unknown) => this.record('workspace.create', payload, this.onWorkspaceCreate(payload)),
+    rename: (payload: unknown) => this.record('workspace.rename', payload, this.onWorkspaceRename(payload)),
+    insertSessionBefore: (payload: unknown) =>
+      this.record('workspace.insertSessionBefore', payload, this.onWorkspaceInsertSessionBefore(payload)),
   }
 
   /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */

packages/client/tsdown.client.ts

@@ -33,7 +33,7 @@ export const INLINE_SAFE = /^@deepseek-ai\/dsh-(host-apiproxy|session|llm|tools|
  * Documented TEMPORARY exemption, not a platform module (hence not in
  * platform.ts): the snapshot-store engine (createSnapshotStore/defineStore/
  * shallowEqual) lives in runtime pending its promotion-time rehoming, and
- * five importers (i18n, ui-layout, ui-conversation ×3) ride this single
+ * five importers (locale, ui-layout, ui-conversation ×3) ride this single
  * exemption. At runtime the lazy CJS table answers the require natively:
  * runtime is an immediately-tier row, its factory is registered before any
  * dependent bundle materializes. TODO(webload/store-rehome): remove with the

packages/client/ui-conversation/package.json

@@ -24,7 +24,7 @@
   },
   "dshClient": {
     "inject": [
-      "@deepseek-ai/dsh-client-i18n",
+      "@deepseek-ai/dsh-client-locale",
       "@deepseek-ai/dsh-client-runtime",
       "@deepseek-ai/dsh-client-ui-layout"
     ],

packages/client/ui-conversation/tests/apply-inject.spec.tsx

@@ -99,7 +99,7 @@ async function bench() {
   ctx.provide('workspaces', workspacesFake)
   const layoutFake = { openDetails: vi.fn(), closeDetails: vi.fn() }
   ctx.provide('layout', layoutFake)
-  ctx.provide('i18n', { bind: () => (key: string) => key })
+  ctx.provide('locale', { bind: () => (key: string) => key })
 
   // The AppFrame role: the three conversation-package slots must be declared
   // by a live entry before apply can contribute into them (the stand-in

packages/client/ui-conversation/tests/chat-apply.spec.tsx

@@ -48,7 +48,7 @@ async function bench() {
     sendSession: vi.fn(),
   })
   ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
-  ctx.provide('i18n', { bind: () => (key: string) => key })
+  ctx.provide('locale', { bind: () => (key: string) => key })
 
   // Declared by ui-layout's root entry in production; a stand-in root
   // occupant declares them here so the contributions land (it consumes

packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx

@@ -93,7 +93,7 @@ async function bench(nodes: ToolResultNode[]) {
     sendSession: vi.fn(),
   })
   ctx.provide('layout', layout)
-  ctx.provide('i18n', { bind: () => (key: string) => key })
+  ctx.provide('locale', { bind: () => (key: string) => key })
 
   slots.install(createSlotRenderer())
   slots.register({
@@ -212,7 +212,7 @@ describe('registrant load-order seam', () => {
       sendSession: vi.fn(),
     })
     ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
-    ctx.provide('i18n', { bind: () => (key: string) => key })
+    ctx.provide('locale', { bind: () => (key: string) => key })
     slots.register({
       name: 'root',
       children: {

packages/client/ui-conversation/tsconfig.json

@@ -27,7 +27,7 @@
       "path": "../ui-layout"
     },
     {
-      "path": "../i18n"
+      "path": "../locale"
     },
     {
       "path": "../../support/invariants"

packages/client/ui-layout/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-client-ui-layout
 
-Shell plugin: three-column AppFrame (drag handles and concession chain) plus the `ctx.layout` panel-geometry service; it registers into the runtime-owned `root` slot and declares `sidebar`, `conversation`, `details`, and `conversation.empty`. The sidebar is fixed-width (only details shrinks, then auto-closes); a closed sidebar retains a 56px control rail while details closes to zero width.
+Shell plugin: three-column AppFrame (drag handles and concession chain) plus the `ctx.layout` panel-geometry service; it registers into the runtime-owned `root` slot and declares `sidebar`, `conversation`, `details`, and `conversation.empty`. The sidebar is fixed-width (only details shrinks, then auto-closes); a closed sidebar retains a 56px control rail while details closes to zero width. The package also seats the theme presenter: it consumes resolved `ctx.theme` snapshots and projects them onto `document.body` (`data-ds-dark-theme` from the active color scheme plus the theme's alias tokens as inline variables).
 
 AppFrame reads the runtime Session projection: `baselinesReady` selects loading, a page-local `SessionListState.intent` selects the empty composer, and a connected Session renders through `SessionProvider`. The conversation and empty-state owner shares are empty; each registrant obtains business data from standard hooks and actions from its own inject face. The sidebar owner share contains only `collapsed` and `width`; navigation actions belong to sidebar's own injected service face.
 

packages/client/ui-layout/package.json

@@ -24,7 +24,8 @@
   },
   "dshClient": {
     "inject": [
-      "@deepseek-ai/dsh-client-runtime"
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-ui-theme"
     ],
     "platform": "web"
   },
@@ -36,13 +37,16 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-theme": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7",
     "react": "^18.2.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",
     "cordis": "^4.0.0-rc.7",

packages/client/ui-layout/src/client/index.ts

@@ -4,13 +4,16 @@
  * four child slots (declaration = exclusive render authority), seats the
  * layout store (panel geometry), and wires the panel-action service face.
  * ctx.layout is the cross-plugin panel-action seam; navigation state lives
- * with the runtime sessions service.
+ * with the runtime sessions service. A second effect seats the theme
+ * presenter, which projects ctx.theme snapshots onto document.body.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-client-ui-theme/client'
 import type { PanelActions } from './service.ts'
 import { AppFrame } from './AppFrame.tsx'
 import { createLayoutStore } from './stores.ts'
 import { LayoutService } from './service.ts'
+import { ThemePresenter } from './theme-presenter.ts'
 
 // Contract surface only (export-convergence rule: cross-package consumers
 // keep a symbol exported; test-only/package-internal symbols live off /src).
@@ -62,7 +65,7 @@ export interface DetailsOwnerProps {}
 export interface EmptyOwnerProps { children?: never }
 
 /** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
-export const inject = ['slots']
+export const inject = ['slots', 'theme']
 
 /**
  * Client plugin body: provide ctx.layout, then one register() call — AppFrame
@@ -98,4 +101,16 @@ export function apply(ctx: ClientContext): void {
       void disposeService()
     }
   }, 'ui-layout: service + root registration')
+
+  // Theme presentation: pure DOM writes from resolved snapshots — initial
+  // state through the getter once, then event-driven only; no React path.
+  ctx.effect(() => {
+    const presenter = new ThemePresenter()
+    presenter.apply(ctx.theme.getTheme())
+    const off = ctx.on('theme/change', (snapshot) => { presenter.apply(snapshot) })
+    return () => {
+      off()
+      presenter.dispose()
+    }
+  }, 'ui-layout: theme presenter')
 }

packages/client/ui-layout/src/client/theme-presenter.ts

@@ -0,0 +1,43 @@
+/**
+ * Global theme DOM applier: projects the resolved ThemeSnapshot onto
+ * document.body — the `data-ds-dark-theme` palette switch plus the active
+ * theme's alias-token overrides as inline CSS variables. Pure DOM writes, no
+ * React involvement; the presenter only ever retracts what it wrote itself,
+ * so foreign body attributes and inline styles survive apply/dispose.
+ */
+import type { ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
+
+/** Body attribute selecting the dark base palette in the token stylesheets. */
+export const DARK_ATTRIBUTE = 'data-ds-dark-theme'
+
+/** Applies theme snapshots to document.body; one instance per plugin fiber. */
+export class ThemePresenter {
+  /** Token names this presenter wrote in the last apply (its retraction set). */
+  private appliedTokens: string[] = []
+
+  /**
+   * Project a snapshot onto the body: switch the palette attribute from
+   * `active.colorScheme` (never the id — `system` is resolved upstream) and
+   * replace the previously applied token variables with `active.tokens`.
+   * @param snapshot - resolved theme snapshot from ctx.theme.
+   */
+  apply(snapshot: ThemeSnapshot): void {
+    const body = document.body
+    if (snapshot.active.colorScheme === 'dark') body.setAttribute(DARK_ATTRIBUTE, '')
+    else body.removeAttribute(DARK_ATTRIBUTE)
+    for (const name of this.appliedTokens) body.style.removeProperty(name)
+    this.appliedTokens = []
+    for (const [name, value] of Object.entries(snapshot.active.tokens)) {
+      body.style.setProperty(name, value)
+      this.appliedTokens.push(name)
+    }
+  }
+
+  /** Retract everything this presenter wrote: the palette attribute and all applied token variables. */
+  dispose(): void {
+    const body = document.body
+    body.removeAttribute(DARK_ATTRIBUTE)
+    for (const name of this.appliedTokens) body.style.removeProperty(name)
+    this.appliedTokens = []
+  }
+}

packages/client/ui-layout/tests/apply.spec.ts

@@ -9,6 +9,8 @@
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import { apply as themeApply, inject as themeInject, ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
 import { apply, inject, LayoutService } from '@deepseek-ai/dsh-client-ui-layout/client'
 import { apply as nodeApply } from '@deepseek-ai/dsh-client-ui-layout'
 import * as invariant from '@deepseek-ai/dsh-client-ui-layout/invariant'
@@ -16,13 +18,17 @@ import * as invariant from '@deepseek-ai/dsh-client-ui-layout/invariant'
 async function bench() {
   const ctx = new Context()
   const slotsFiber = ctx.plugin(SlotsService)
+  // Theme now injects ['slots', 'locale'] (it registers its Appearance
+  // settings row); seat a real locale service so the theme fiber activates.
+  ctx.provide('locale', new LocaleService(ctx))
+  await ctx.plugin({ inject: themeInject, apply: themeApply }).await()
   await slotsFiber.await()
   return { ctx, slots: ctx.get('slots') as SlotsService }
 }
 
 describe('ui-layout client apply', () => {
   it('declares its service dependencies', () => {
-    expect(inject).toEqual(['slots'])
+    expect(inject).toEqual(['slots', 'theme'])
   })
 
   it('provides ctx.layout and registers AppFrame into root with the four child declarations', async () => {
@@ -53,6 +59,23 @@ describe('ui-layout client apply', () => {
     expect(actions.toggleSidebar).toHaveBeenCalledOnce()
   })
 
+  it('theme presenter applies the initial snapshot, follows theme/change, and unwinds on dispose', async () => {
+    const { ctx } = await bench()
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    // Initial getter application: jsdom has no matchMedia, system resolves light.
+    expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(false)
+    const theme = ctx.get('theme') as ThemeService
+    theme.setTheme('dark')
+    expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(true)
+    await fiber.dispose()
+    expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(false)
+    // Listener is off: further theme changes no longer reach the body.
+    theme.setTheme('light')
+    theme.setTheme('dark')
+    expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(false)
+  })
+
   it('teardown unwinds the service, the root registration, and the child declarations', async () => {
     const { ctx, slots } = await bench()
     const fiber = ctx.plugin({ inject: [...inject], apply })

packages/client/ui-layout/tests/theme-presenter.spec.ts

@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+// ThemePresenter behavior account: the palette attribute follows
+// active.colorScheme only, token variables replace the previous apply's set,
+// and dispose retracts everything the presenter wrote.
+
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
+import { DARK_ATTRIBUTE, ThemePresenter } from '@deepseek-ai/dsh-client-ui-layout/src/client/theme-presenter.ts'
+
+function snapshot(colorScheme: 'light' | 'dark', tokens: Record<string, string> = {}): ThemeSnapshot {
+  // The presenter must key off colorScheme, not the id — keep them distinct.
+  const active = { id: `${colorScheme}-test`, colorScheme, tokens }
+  return { preference: colorScheme, active, themes: [active], revision: 1 }
+}
+
+beforeEach(() => {
+  document.body.removeAttribute(DARK_ATTRIBUTE)
+  document.body.removeAttribute('style')
+})
+
+describe('ThemePresenter', () => {
+  it('light scheme leaves the dark attribute absent', () => {
+    const presenter = new ThemePresenter()
+    presenter.apply(snapshot('light'))
+    expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(false)
+  })
+
+  it('dark scheme sets the attribute; switching back to light removes it', () => {
+    const presenter = new ThemePresenter()
+    presenter.apply(snapshot('dark'))
+    expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(true)
+    presenter.apply(snapshot('light'))
+    expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(false)
+  })
+
+  it('applies tokens as inline variables and clears the previous set on theme change', () => {
+    const presenter = new ThemePresenter()
+    presenter.apply(snapshot('dark', { '--dsw-alias-bg': '#111', '--dsw-alias-fg': '#eee' }))
+    expect(document.body.style.getPropertyValue('--dsw-alias-bg')).toBe('#111')
+    expect(document.body.style.getPropertyValue('--dsw-alias-fg')).toBe('#eee')
+    presenter.apply(snapshot('light', { '--dsw-alias-bg': '#fff' }))
+    expect(document.body.style.getPropertyValue('--dsw-alias-bg')).toBe('#fff')
+    // The old theme's extra variable is gone, not merged.
+    expect(document.body.style.getPropertyValue('--dsw-alias-fg')).toBe('')
+  })
+
+  it('dispose removes the attribute and every applied variable, sparing foreign inline styles', () => {
+    document.body.style.setProperty('--foreign', 'kept')
+    const presenter = new ThemePresenter()
+    presenter.apply(snapshot('dark', { '--dsw-alias-bg': '#111' }))
+    presenter.dispose()
+    expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(false)
+    expect(document.body.style.getPropertyValue('--dsw-alias-bg')).toBe('')
+    expect(document.body.style.getPropertyValue('--foreign')).toBe('kept')
+  })
+})

packages/client/ui-layout/tsconfig.json

@@ -11,9 +11,15 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../locale"
+    },
     {
       "path": "../ui-slots"
     },
+    {
+      "path": "../ui-theme"
+    },
     {
       "path": "../ui-primitives"
     },

packages/client/ui-models/README.md

@@ -0,0 +1,15 @@
+# @deepseek-ai/dsh-client-ui-models
+
+Models settings section plugin: registers the `models` nav entry into `settings.section` with an intentionally empty content column — model management lands in a later phase.
+
+## Model Experience
+
+None, as the section renders an empty browser UI column; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Content column is empty by design** — provider list, editing form, and activation flow are deferred until the model-management service exists.

packages/client/ui-models/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-models",
+  "description": "Models feature plugin: registers its Settings section (nav entry, empty content column; model management lands later)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-ui-settings",
+      "@deepseek-ai/dsh-client-locale"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}

packages/client/ui-models/src/client/ModelsSection.tsx

@@ -0,0 +1,13 @@
+/**
+ * Models settings section: an intentionally empty content column — the nav
+ * entry exists so the section slot composition is visible; model management
+ * lands in a later phase.
+ */
+
+/**
+ * Render the (empty) Models section content column.
+ * @returns null — no content this phase.
+ */
+export function ModelsSection() {
+  return null
+}

packages/client/ui-models/src/client/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Models settings section plugin, browser half. Registers the `models` nav
+ * entry into the shell-declared `settings.section` list slot; the content
+ * column is intentionally empty until model management lands. Export
+ * discipline: packages/client/AGENTS.md.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only: pulls the shell's SlotMap merge (the 'settings.section' entry).
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+// Type-only: pulls the locale plugin's Context merge (ctx.locale).
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import { ModelsSection } from './ModelsSection.tsx'
+
+/**
+ * Required services (cordis fiber inject). The target slot is declared by
+ * ui-settings' apply, whose activation order relative to this one is NOT
+ * constrained; registration goes through declaration-aware deferral.
+ */
+export const inject = ['slots', 'locale']
+
+/**
+ * Register the Models section once the `settings.section` declaration is on
+ * the ledger.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => {
+    const disposers = [
+      ctx.locale.register('settings.models', 'zh', { nav: '模型' }),
+      ctx.locale.register('settings.models', 'en', { nav: 'Models' }),
+    ]
+    return () => { for (const dispose of disposers) dispose() }
+  }, 'ui-models: nav copy dictionaries')
+  ctx.effect(() => {
+    const deferred = deferRegistration(ctx.slots, 'settings.section', ModelsSection, () =>
+      ctx.slots.register({
+        name: 'settings.section',
+        id: 'models',
+        order: 10,
+        label: ctx.locale.bind('settings.models')('nav'),
+      }, ModelsSection))
+    // Nav labels are registrant-localized: refresh on locale change so the
+    // ledger carries fresh text (the version bump re-renders the shell).
+    const offLocale = ctx.on('locale/change', () => { deferred.refresh() })
+    return () => {
+      offLocale()
+      deferred.dispose()
+    }
+  }, 'ui-models: settings section registration')
+}

packages/client/ui-models/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

packages/client/ui-models/src/index.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser implementation exported from `./client`. */
+
+/** Host plugin body — no host-side behavior for the models settings plugin. */
+export function apply(): void {}

packages/client/ui-models/src/invariant.ts

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-models`.
+ * @module @deepseek-ai/dsh-client-ui-models/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-models'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-models-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a nav-entry-only section plugin rendering a fixed
+ * empty content column — it emits no cordis events and owns no cross-plugin
+ * mutable relation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/client/ui-models/tests/apply.spec.ts

@@ -0,0 +1,95 @@
+/** Models section registration: declaration-aware deferral, locale re-registration, and HMR recovery. */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import { apply, inject } from '@deepseek-ai/dsh-client-ui-models/client'
+import { ModelsSection } from '../src/client/ModelsSection.tsx'
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  const locale = new LocaleService(ctx)
+  ctx.provide('locale', locale)
+  return { ctx, slots: ctx.get('slots') as SlotsService, locale }
+}
+
+function declare(slots: SlotsService): () => void {
+  return slots.register(
+    { name: 'root', children: { 'settings.section': { kind: 'list', scope: 'root' } } } as never,
+    () => null,
+  )
+}
+
+describe('ui-models apply', () => {
+  it('declares the services it uses', () => {
+    expect(inject).toEqual(['slots', 'locale'])
+  })
+
+  it('registers the models nav entry for declarations before or after apply', async () => {
+    const before = await bench()
+    declare(before.slots)
+    await before.ctx.plugin({ inject: [...inject], apply }).await()
+    const entry = before.slots.entries('settings.section')[0]!
+    expect(entry.component).toBe(ModelsSection)
+    expect(entry.options).toEqual({ id: 'models', order: 10, label: '模型' })
+
+    const after = await bench()
+    await after.ctx.plugin({ inject: [...inject], apply }).await()
+    expect(after.slots.entries('settings.section')).toHaveLength(0)
+    declare(after.slots)
+    await Promise.resolve()
+    expect(after.slots.entries('settings.section')[0]!.component).toBe(ModelsSection)
+    // The self-inflicted ledger notifications hit the duplicate guard.
+    expect(after.slots.entries('settings.section')).toHaveLength(1)
+  })
+
+  it('re-registers with fresh label text on locale change', async () => {
+    const b = await bench()
+    declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    b.locale.setLocale('en')
+    expect(b.slots.entries('settings.section')[0]!.options.label).toBe('Models')
+    b.locale.setLocale('zh')
+    expect(b.slots.entries('settings.section')[0]!.options.label).toBe('模型')
+  })
+
+  it('locale change while the slot is undeclared stays a no-op', async () => {
+    const b = await bench()
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    b.locale.setLocale('en')
+    expect(b.slots.entries('settings.section')).toHaveLength(0)
+    b.locale.setLocale('zh')
+  })
+
+  it('re-registers after an HMR collapse re-declares the slot (stale disposer must not block)', async () => {
+    const b = await bench()
+    const redeclare = declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    expect(b.slots.entries('settings.section')).toHaveLength(1)
+    // Declarer unload: the cascade removes our entry while our local
+    // disposer variable goes stale.
+    redeclare()
+    expect(b.slots.entries('settings.section')).toHaveLength(0)
+    declare(b.slots)
+    await Promise.resolve()
+    expect(b.slots.entries('settings.section')[0]!.component).toBe(ModelsSection)
+    // The locale path also recovers through the same ledger re-check.
+    b.locale.setLocale('en')
+    expect(b.slots.entries('settings.section')[0]!.options.label).toBe('Models')
+    b.locale.setLocale('zh')
+  })
+
+  it('registers the zh/en nav dictionaries and disposes everything with the fiber', async () => {
+    const b = await bench()
+    declare(b.slots)
+    const fiber = b.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(b.locale.bind('settings.models')('nav')).toBe('模型')
+    await fiber.dispose()
+    expect(b.slots.entries('settings.section')).toHaveLength(0)
+    // The (ns, locale) seats are free again — the dictionary disposers ran.
+    expect(() => b.locale.register('settings.models', 'zh', {})).not.toThrow()
+    expect(() => b.locale.register('settings.models', 'en', {})).not.toThrow()
+  })
+})

packages/client/ui-models/tests/invariant.spec.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as ModelsInvariant from '@deepseek-ai/dsh-client-ui-models/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import { ModelsSection } from '../src/client/ModelsSection.tsx'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(ModelsInvariant).await()).resolves.toBeDefined()
+  })
+
+  it('node-half apply is a no-op host placeholder', async () => {
+    const { apply } = await import('@deepseek-ai/dsh-client-ui-models')
+    apply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+
+  it('the section content column is intentionally empty this phase', () => {
+    expect(ModelsSection()).toBeNull()
+  })
+})

packages/client/ui-models/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-settings"
+    },
+    {
+      "path": "../locale"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/client/ui-models/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-models', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/client/ui-primitives/src/HoverCard.module.css

@@ -0,0 +1,22 @@
+/* Block, not inline-flex: consumers wrap full-width list rows and an
+ * inline wrapper would shrink them; the card still measures this rect. */
+.root {
+  position: relative;
+  display: block;
+}
+
+/* Preview card (figma session hover card): 244 wide, r12, pad 12/16, the
+ * menu card's elevation. Surface is #2C2C2E in both themes (figma value,
+ * light/dark identical), so a component-level variable, not a theme token. */
+.card {
+  --dsw-hovercard-bg: #2C2C2E;
+  position: fixed;
+  z-index: 100;
+  box-sizing: border-box;
+  width: 244px;
+  padding: 12px 16px;
+  border-radius: 12px;
+  background: var(--dsw-hovercard-bg);
+  box-shadow: var(--dsw-shadow-lv3);
+  pointer-events: none;
+}

packages/client/ui-primitives/src/HoverCard.tsx

@@ -0,0 +1,112 @@
+// HoverCard: delayed hover-preview card portaled to document.body.
+// Same portal mechanics as Menu: the wrapper span supplies the anchor rect,
+// the card is fixed-positioned at its right edge and repositions on
+// scroll/resize while open. Display-only — the card ignores pointer events
+// and closes the instant the pointer leaves the anchor (no close delay).
+
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import css from './HoverCard.module.css'
+
+/**
+ * Render an anchor with a hover-triggered preview card.
+ * @param props.anchor - the hover target (rendered in place inside a wrapper span).
+ * @param props.content - card content (display-only, no pointer interaction).
+ * @param props.openDelayMs - hover dwell before the card shows (default 500).
+ * @param props.disabled - suppress opening; turning true closes an open card.
+ * @returns anchor wrapper with the conditional portaled card.
+ */
+export function HoverCard({ anchor, content, openDelayMs = 500, disabled = false }: {
+  anchor: ReactNode
+  content: ReactNode
+  openDelayMs?: number
+  disabled?: boolean
+}) {
+  const rootRef = useRef<HTMLSpanElement>(null)
+  const cardRef = useRef<HTMLDivElement>(null)
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const [open, setOpen] = useState(false)
+  const [pos, setPos] = useState<{ left: number; top: number } | null>(null)
+
+  const clearTimer = () => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current)
+      timerRef.current = null
+    }
+  }
+
+  // Owner disabling mid-hover (menu opened, drag started) closes immediately.
+  useEffect(() => {
+    if (!disabled) return
+    clearTimer()
+    setOpen(false)
+  }, [disabled])
+
+  useEffect(() => clearTimer, [])
+
+  // Fixed-position from the anchor rect before paint; track the anchor while
+  // open (capture-phase scroll catches nested panes), as in Menu portal mode.
+  useLayoutEffect(() => {
+    if (!open) { setPos(null); return }
+    const place = () => {
+      const wrapper = rootRef.current
+      /* v8 ignore next -- the ref is attached before the layout effect runs and the listeners die with it. */
+      if (wrapper === null) return
+      const r = wrapper.getBoundingClientRect()
+      const h = cardRef.current?.offsetHeight ?? 0
+      const top = r.top + h > window.innerHeight - 8 ? window.innerHeight - h - 8 : r.top
+      setPos({ left: r.right + 8, top })
+    }
+    place()
+    window.addEventListener('scroll', place, true)
+    window.addEventListener('resize', place)
+    return () => {
+      window.removeEventListener('scroll', place, true)
+      window.removeEventListener('resize', place)
+    }
+  }, [open])
+
+  // The first placement ran before the card mounted (height read 0): once the
+  // card's real height is measurable, correct the bottom-edge clamp. The
+  // correction converges — a clamped top satisfies the guard, so it runs once.
+  useLayoutEffect(() => {
+    if (!open || pos === null) return
+    /* v8 ignore next -- the card is mounted whenever pos is set, so the ref is attached here. */
+    const h = cardRef.current?.offsetHeight ?? 0
+    if (pos.top + h > window.innerHeight - 8) {
+      setPos({ left: pos.left, top: window.innerHeight - h - 8 })
+    }
+  }, [open, pos])
+
+  const card = open && pos !== null && (
+    <div ref={cardRef} className={css.card} style={pos}>
+      {content}
+    </div>
+  )
+
+  return (
+    <span
+      ref={rootRef}
+      className={css.root}
+      onPointerEnter={() => {
+        if (disabled) return
+        clearTimer()
+        timerRef.current = setTimeout(() => { setOpen(true) }, openDelayMs)
+      }}
+      onPointerLeave={() => {
+        clearTimer()
+        setOpen(false)
+      }}
+      // Any press inside the anchor (row click, menu trigger) dismisses the
+      // card immediately, without waiting for the owner to flip `disabled`.
+      onPointerDownCapture={() => {
+        clearTimer()
+        setOpen(false)
+      }}
+    >
+      {anchor}
+      {card !== false && createPortal(card, document.body)}
+    </span>
+  )
+}

packages/client/ui-primitives/src/Menu.module.css

@@ -30,11 +30,13 @@
 
 /* Portal mode: fixed in the viewport, coordinates supplied inline from the
  * anchor rect (side/align resolved in JS, the in-place offset rules above
- * don't apply). */
+ * don't apply). Portaled lists must layer above modal overlays (z 1000) —
+ * an anchor inside a dialog still expects its menu on top. */
 .portal {
   position: fixed;
   top: auto;
   left: auto;
+  z-index: 1100;
 }
 
 /* Open above the anchor (empty-state workspace chip: figma 122:9481). */
@@ -109,6 +111,27 @@
   background: transparent;
 }
 
+/* Destructive row: error text/icon, danger hover fill. */
+.danger {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.danger .itemIcon {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.danger:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover-danger);
+}
+
+/* Heading row: non-interactive small grey text, padding aligned with items. */
+.label {
+  padding: 8px 10px;
+  font-size: 12px;
+  line-height: 16px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
 /* Separator cell (figma 122:9481): py 4 / px 2 around the hairline. */
 .separator {
   height: 1px;

packages/client/ui-primitives/src/Menu.tsx

@@ -4,6 +4,7 @@
 // the anchor rect, for anchors inside overflow-clipping containers (sidebar).
 // The owner controls `open`; outside-click closing uses one document listener
 // active only while open. Submenus open on hover/focus inside the same root.
+// Entries also cover non-interactive `label` headings and `danger` rows.
 
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
@@ -19,6 +20,8 @@ export interface MenuItem {
   disabled?: boolean
   /** Leading icon (figma .Menu_cell gap 8). */
   icon?: ReactNode
+  /** Destructive row: error-colored text/icon and danger hover fill. */
+  danger?: boolean
   /** Nested card opened to the right on hover/focus. */
   submenu?: readonly MenuItem[]
 }
@@ -29,13 +32,24 @@ export interface MenuSeparator {
   id: string
 }
 
-/** One primary-menu entry: a row or a separator. */
-export type MenuEntry = MenuItem | MenuSeparator
+/** Non-interactive heading row above a group of items. */
+export interface MenuLabel {
+  type: 'label'
+  id: string
+  text: string
+}
+
+/** One primary-menu entry: a row, a separator, or a heading label. */
+export type MenuEntry = MenuItem | MenuSeparator | MenuLabel
 
 function isSeparator(entry: MenuEntry): entry is MenuSeparator {
   return 'type' in entry && entry.type === 'separator'
 }
 
+function isLabel(entry: MenuEntry): entry is MenuLabel {
+  return 'type' in entry && entry.type === 'label'
+}
+
 /**
  * Render an anchored dropdown menu.
  * @param props.open - whether the list is showing (owner-controlled).
@@ -50,6 +64,8 @@ function isSeparator(entry: MenuEntry): entry is MenuSeparator {
  * from the anchor rect (repositions on scroll/resize while open). Use when an
  * ancestor's overflow clipping would crop the in-place list; default false
  * keeps the pure-CSS in-place behavior.
+ * @param props.closeOnPointerLeave - close the list when the pointer leaves
+ * it (default false keeps it open until outside click/Escape/selection).
  * @param props.getAnchorRect - portal mode only: supply the anchor rect
  * directly (e.g. from a host-owned trigger button) instead of measuring the
  * Menu's own wrapper span. Required when the wrapper isn't itself laid out at
@@ -58,7 +74,7 @@ function isSeparator(entry: MenuEntry): entry is MenuSeparator {
  * scroll/resize; return null to skip placement for that frame.
  * @returns anchor wrapper with the conditional list.
  */
-export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align = 'start', side = 'bottom', portal = false, getAnchorRect, className }: {
+export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align = 'start', side = 'bottom', portal = false, closeOnPointerLeave = false, getAnchorRect, className }: {
   open: boolean
   anchor: ReactNode
   items: readonly MenuEntry[]
@@ -68,6 +84,7 @@ export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align
   align?: 'start' | 'end'
   side?: 'bottom' | 'top'
   portal?: boolean
+  closeOnPointerLeave?: boolean
   getAnchorRect?: () => DOMRect | null
   className?: string
 }) {
@@ -135,11 +152,19 @@ export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align
       className={clsx(css.list, portal && css.portal, side === 'top' && !portal && css.sideTop, align === 'end' && !portal && css.alignEnd)}
       style={fixedPos ?? undefined}
       role="menu"
+      onPointerLeave={closeOnPointerLeave ? () => { onClose() } : undefined}
+      // React portals bubble synthetic events through the REACT tree: without
+      // this stop, an item click re-fires the anchor row's own onClick
+      // (open/toggle) after onSelect.
+      onClick={(e) => { e.stopPropagation() }}
     >
           {items.map(entry => {
             if (isSeparator(entry)) {
               return <div key={entry.id} className={css.separator} role="separator" />
             }
+            if (isLabel(entry)) {
+              return <div key={entry.id} className={css.label} role="presentation">{entry.text}</div>
+            }
             const hasSub = entry.submenu !== undefined && entry.submenu.length > 0
             const subOpen = hasSub && openSubmenuId === entry.id
             return (
@@ -152,7 +177,7 @@ export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align
                 <button
                   type="button"
                   role="menuitem"
-                  className={clsx(css.item, entry.id === selectedId && css.selected)}
+                  className={clsx(css.item, entry.id === selectedId && css.selected, entry.danger === true && css.danger)}
                   disabled={entry.disabled}
                   aria-haspopup={hasSub ? 'menu' : undefined}
                   aria-expanded={hasSub ? subOpen : undefined}

packages/client/ui-primitives/src/icons/index.tsx

@@ -583,3 +583,90 @@ export const IconTreeCorner8x10 = ({ size = 10, className }: IconProps) => (
     <path d="M0 0L-0.5 0L-0.5 7L0 7L0.5 7L0.5 0L0 0ZM3 10L3 10.5L8 10.5L8 10L8 9.5L3 9.5L3 10ZM0 7L-0.5 7C-0.5 8.933 1.067 10.5 3 10.5L3 10L3 9.5C1.61929 9.5 0.5 8.38071 0.5 7L0 7Z" fill="currentColor"/>
   </svg>
 )
+
+/** ic_ds_light_outline_16 */
+export const IconLightOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M11.3496 8C11.3496 6.14985 9.85015 4.65039 8 4.65039C6.14985 4.65039 4.65039 6.14985 4.65039 8C4.65039 9.85015 6.14985 11.3496 8 11.3496C9.85015 11.3496 11.3496 9.85015 11.3496 8ZM12.6504 8C12.6504 10.5681 10.5681 12.6504 8 12.6504C5.43188 12.6504 3.34961 10.5681 3.34961 8C3.34961 5.43188 5.43188 3.34961 8 3.34961C10.5681 3.34961 12.6504 5.43188 12.6504 8Z"
+      fill="currentColor"
+    />
+    <path d="M8.65039 0.5V2.5H7.34961V0.5H8.65039Z" fill="currentColor" />
+    <path d="M8.65039 13.5V15.5H7.34961V13.5H8.65039Z" fill="currentColor" />
+    <path
+      d="M3.15808 2.24035L4.57229 3.65456L3.6525 4.57435L2.23829 3.16014L3.15808 2.24035Z"
+      fill="currentColor"
+    />
+    <path
+      d="M12.3505 11.4327L13.7647 12.8469L12.8449 13.7667L11.4307 12.3525L12.3505 11.4327Z"
+      fill="currentColor"
+    />
+    <path
+      d="M2.24537 12.8469L3.65958 11.4327L4.57937 12.3525L3.16516 13.7667L2.24537 12.8469Z"
+      fill="currentColor"
+    />
+    <path
+      d="M11.4377 3.65455L12.852 2.24033L13.7718 3.16012L12.3575 4.57434L11.4377 3.65455Z"
+      fill="currentColor"
+    />
+    <path d="M0.5 7.35461H2.5V8.6554H0.5L0.5 7.35461Z" fill="currentColor" />
+    <path d="M13.5 7.35461H15.5V8.6554H13.5V7.35461Z" fill="currentColor" />
+  </svg>
+)
+
+/** ic_ds_dark_outline_16 */
+export const IconDarkOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M13.2764 9.52324C12.5607 9.97754 11.7177 10.242 10.7812 10.242C8.11386 10.2419 5.95042 8.07997 5.9502 5.41289C5.9502 4.48128 6.21453 3.61071 6.67188 2.87285C4.30332 3.4658 2.54992 5.60845 2.5498 8.16093C2.5498 11.1712 4.99103 13.6102 8 13.6102C10.5383 13.6102 12.6709 11.8724 13.2764 9.52324ZM7.05078 5.41289C7.051 7.47224 8.72116 9.1423 10.7812 9.14238C11.9248 9.14238 12.887 8.63397 13.5781 7.8084C13.7266 7.63106 13.9701 7.56547 14.1875 7.64433C14.4049 7.72329 14.5497 7.9297 14.5498 8.16093C14.5498 11.7766 11.6161 14.7098 8 14.7098C4.38402 14.7098 1.4502 11.7792 1.4502 8.16093C1.45033 4.54322 4.3812 1.61015 8 1.61015C8.23027 1.61015 8.43585 1.75352 8.51562 1.96953C8.59536 2.18554 8.53241 2.42829 8.35742 2.57793C7.55573 3.26311 7.05078 4.27876 7.05078 5.41289Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_followsystem_outline_16 */
+export const IconFollowsystemOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path d="M12.1665 13.5811V14.7803H3.66651V13.5811H12.1665Z" fill="currentColor" />
+    <path
+      d="M13.4453 7.02379C13.4453 6.04702 13.4452 5.3616 13.3887 4.83434C13.3333 4.31828 13.2302 4.02378 13.0723 3.80309C12.9446 3.62475 12.7877 3.46883 12.6094 3.34117C12.3887 3.18328 12.0942 3.08007 11.5781 3.02477C11.0508 2.96829 10.3655 2.96715 9.38867 2.96715H6.61035C5.63359 2.96715 4.94816 2.96827 4.4209 3.02477C3.90486 3.0801 3.61034 3.18321 3.38965 3.34117C3.21143 3.46878 3.05534 3.62487 2.92774 3.80309C2.76977 4.02377 2.66667 4.3183 2.61133 4.83434C2.55483 5.3616 2.55371 6.04702 2.55371 7.02379C2.55371 8.0006 2.55485 8.68596 2.61133 9.21324C2.66663 9.72936 2.76983 10.0238 2.92774 10.2445C3.0554 10.4228 3.21131 10.5797 3.38965 10.7074C3.61034 10.8654 3.90484 10.9685 4.4209 11.0238C4.94816 11.0803 5.63359 11.0804 6.61035 11.0804H9.38867C10.3654 11.0804 11.0508 11.0803 11.5781 11.0238C12.0941 10.9685 12.3887 10.8652 12.6094 10.7074C12.7877 10.5797 12.9446 10.4229 13.0723 10.2445C13.2301 10.0238 13.3334 9.72927 13.3887 9.21324C13.4452 8.68596 13.4453 8.00058 13.4453 7.02379ZM14.6455 7.02379C14.6455 7.97428 14.646 8.73509 14.5811 9.34117C14.5149 9.95828 14.3756 10.4858 14.0479 10.9437C13.8436 11.229 13.5938 11.4788 13.3086 11.683C12.8507 12.0108 12.3232 12.15 11.7061 12.2162C11.1 12.2811 10.3391 12.2806 9.38867 12.2806H6.61035C5.66018 12.2806 4.89991 12.2811 4.29395 12.2162C3.67684 12.15 3.14935 12.0108 2.69141 11.683C2.40613 11.4788 2.15639 11.229 1.95215 10.9437C1.62436 10.4858 1.4841 9.95828 1.41797 9.34117C1.35305 8.73511 1.35449 7.97424 1.35449 7.02379C1.35449 6.07366 1.35308 5.31333 1.41797 4.70738C1.4841 4.09028 1.62436 3.56279 1.95215 3.10485C2.15638 2.81956 2.40613 2.56982 2.69141 2.36559C3.14935 2.03779 3.67684 1.89753 4.29395 1.83141C4.8999 1.76652 5.66022 1.76793 6.61035 1.76793H9.38867C10.3391 1.76793 11.1 1.76649 11.7061 1.83141C12.3232 1.89753 12.8507 2.03779 13.3086 2.36559C13.5939 2.56982 13.8436 2.81957 14.0479 3.10485C14.3756 3.56279 14.5149 4.09028 14.5811 4.70738C14.646 5.31335 14.6455 6.07362 14.6455 7.02379Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_data_outline_16 */
+export const IconDataOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M12.0997 8.54554C12.2905 8.54989 12.3541 8.58056 12.4535 8.74614L12.8849 9.46387C12.9851 9.63071 13.0464 9.66013 13.2388 9.66447H14.1138C14.3417 9.66448 14.3512 9.66937 14.4686 9.86507L14.892 10.5717C14.9942 10.7422 14.9948 10.8247 14.892 10.9961L14.4756 11.6906C14.3741 11.8677 14.3694 11.9379 14.4756 12.115L14.892 12.8096C14.9942 12.9801 14.9947 13.0625 14.892 13.234L14.4686 13.9406C14.3643 14.1028 14.3063 14.1354 14.1138 14.1412H13.2388C13.0465 14.1456 12.985 14.1752 12.8849 14.3418L12.4535 15.0595C12.353 15.2195 12.2895 15.2558 12.0997 15.2601H11.2237C10.9962 15.2601 10.9871 15.2548 10.8699 15.0595L10.4384 14.3418C10.3383 14.175 10.2767 14.1456 10.0846 14.1412H9.2096C9.01854 14.1355 8.95761 14.1006 8.85477 13.9406L8.43139 13.234C8.32562 13.0576 8.33148 12.9862 8.43139 12.8096L8.84771 12.115C8.95165 11.9416 8.94659 11.863 8.84771 11.6906L8.43139 10.9961C8.32767 10.8232 8.33411 10.7437 8.43139 10.5717L8.85477 9.86507C8.95447 9.69891 9.01875 9.67017 9.2096 9.66447H10.0846C10.2741 9.66441 10.3414 9.62547 10.4384 9.46387L10.8699 8.74614C10.987 8.55106 10.9963 8.54554 11.2237 8.54554H12.0997ZM11.6612 10.232C11.3326 10.7798 10.8155 11.0948 10.1743 11.106C10.4443 11.61 10.4425 12.1976 10.1743 12.6987C10.803 12.7096 11.3391 13.0359 11.6612 13.5727C11.9855 13.0323 12.5131 12.7098 13.148 12.6987C12.879 12.196 12.8789 11.6086 13.148 11.106C12.5076 11.0948 11.9894 10.7794 11.6612 10.232Z"
+      fill="currentColor"
+    />
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M7.51205 0.790627C9.19055 0.790649 10.7401 1.0691 11.892 1.54364C12.4664 1.78029 12.9719 2.07885 13.3436 2.4408C13.7171 2.80467 13.9916 3.27253 13.9918 3.82384V7.90442C13.6067 7.69532 13.1907 7.53597 12.7529 7.43366V5.66454C12.4928 5.82898 12.2028 5.97601 11.892 6.10405C10.74 6.57865 9.19071 6.85706 7.51205 6.85706C5.8337 6.85703 4.285 6.57852 3.13309 6.10405C2.82215 5.97593 2.53164 5.8291 2.27121 5.66454V7.4135C2.27134 7.75678 2.6066 8.27106 3.62502 8.73405C4.58641 9.17097 5.95762 9.45591 7.50499 9.45681C7.24582 9.83133 7.03684 10.2434 6.88706 10.6826C5.44388 10.6162 4.12516 10.3216 3.11192 9.86104C2.81708 9.72698 2.53185 9.56866 2.27121 9.38928V11.2542C2.27158 11.5974 2.60697 12.1109 3.62502 12.5737C4.41933 12.9347 5.4937 13.1898 6.71569 13.2693C6.80349 13.7128 6.9513 14.1345 7.14814 14.5273C5.60324 14.4862 4.18593 14.1889 3.11192 13.7007C2.01039 13.1998 1.03366 12.3814 1.03333 11.2542V3.82384C1.03352 3.27273 1.30721 2.80461 1.68049 2.4408C2.05211 2.07893 2.55887 1.78026 3.13309 1.54364C4.28492 1.06926 5.83393 0.790683 7.51205 0.790627ZM7.51205 2.02851C5.95492 2.02857 4.57354 2.29079 3.60486 2.68979C3.11958 2.88977 2.76667 3.11253 2.5454 3.32788C2.32671 3.54101 2.2714 3.7089 2.27121 3.82384C2.27121 3.93882 2.32624 4.10625 2.5454 4.3198C2.76667 4.53527 3.11927 4.75781 3.60486 4.9579C4.5736 5.35699 5.95467 5.61914 7.51205 5.61918C9.06942 5.61918 10.4505 5.35695 11.4192 4.9579C11.9051 4.75773 12.2584 4.53536 12.4797 4.3198C12.6988 4.10627 12.7529 3.93882 12.7529 3.82384C12.7527 3.70889 12.6984 3.54104 12.4797 3.32788C12.2584 3.11239 11.9049 2.88989 11.4192 2.68979C10.4505 2.29079 9.06925 2.02853 7.51205 2.02851Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_List_Pen_outline_16 */
+export const IconListPenOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path d="M10.8239 3.54733V4.78443H4.63437V3.54733H10.8239Z" fill="currentColor" />
+    <path d="M10.8239 6.12629V7.36338H4.63437V6.12629H10.8239Z" fill="currentColor" />
+    <path d="M9.073 8.70524V9.94234H4.63437V8.70524H9.073Z" fill="currentColor" />
+    <path
+      d="M9.13321 0.573526C10.0076 0.573525 10.7179 0.572522 11.285 0.63397C11.8645 0.696791 12.3743 0.831648 12.8193 1.1548C13.0776 1.34246 13.3056 1.57047 13.4933 1.82875C13.8164 2.2737 13.9513 2.7836 14.0141 3.36303C14.0755 3.93015 14.0745 4.64049 14.0745 5.51485V6.1757L12.7327 7.5629V5.51485C12.7327 4.61092 12.732 3.9862 12.6803 3.5081C12.6298 3.0427 12.5379 2.79497 12.4083 2.61654C12.3033 2.47211 12.176 2.34472 12.0315 2.23977C11.8531 2.11016 11.6054 2.01823 11.14 1.96777C10.6618 1.91601 10.0372 1.91539 9.13321 1.91539H6.32658C5.42262 1.91539 4.79796 1.91604 4.31983 1.96777C3.85451 2.01819 3.60672 2.11029 3.42827 2.23977C3.28392 2.34465 3.15643 2.47223 3.0515 2.61654C2.9219 2.79496 2.82997 3.04274 2.7795 3.5081C2.72774 3.9862 2.72712 4.61092 2.72712 5.51485V10.023C2.72712 10.9273 2.72773 11.5525 2.7795 12.0307C2.82992 12.4959 2.92205 12.7429 3.0515 12.9213C3.15645 13.0657 3.28384 13.1931 3.42827 13.2981C3.60676 13.4277 3.85408 13.5206 4.31983 13.5711C4.79797 13.6228 5.42259 13.6234 6.32658 13.6234H6.87057L5.57707 14.9593C5.03527 14.9556 4.57031 14.9467 4.17476 14.9039C3.59508 14.841 3.08558 14.7063 2.64048 14.383C2.38215 14.1953 2.15422 13.9684 1.96653 13.7101C1.64319 13.2649 1.50851 12.7546 1.4457 12.1748C1.38432 11.6076 1.38525 10.8974 1.38525 10.023V5.51485C1.38525 4.64049 1.38426 3.93015 1.4457 3.36303C1.50853 2.78363 1.64341 2.27368 1.96653 1.82875C2.15417 1.57059 2.38228 1.34239 2.64048 1.1548C3.08544 0.831805 3.59533 0.696762 4.17476 0.63397C4.74193 0.572552 5.45218 0.573525 6.32658 0.573526H9.13321Z"
+      fill="currentColor"
+    />
+    <path d="M14.2193 14.9553H10.0124L11.3744 13.6134H14.2193V14.9553Z" fill="currentColor" />
+    <path
+      d="M8.24493 13.3711L7.49015 14.8806C7.40148 15.058 7.58961 15.2461 7.76695 15.1574L9.27651 14.4027L14.6147 9.09934L13.5832 8.06775L8.24493 13.3711Z"
+      fill="currentColor"
+    />
+  </svg>
+)

packages/client/ui-primitives/src/index.ts

@@ -9,7 +9,8 @@ export type { ButtonVariant } from './Button.tsx'
 export { Pill } from './Pill.tsx'
 export { Input } from './Input.tsx'
 export { Menu } from './Menu.tsx'
-export type { MenuEntry, MenuItem, MenuSeparator } from './Menu.tsx'
+export type { MenuEntry, MenuItem, MenuSeparator, MenuLabel } from './Menu.tsx'
+export { HoverCard } from './HoverCard.tsx'
 export { Modal } from './Modal.tsx'
 export { ConnectionBanner } from './ConnectionBanner.tsx'
 export { FishLogo } from './FishLogo.tsx'

packages/client/ui-primitives/tests/atoms.spec.tsx

@@ -136,6 +136,51 @@ describe('Menu', () => {
     expect(screen.getByRole('separator')).toBeDefined()
   })
 
+  it('renders a non-interactive heading label and a danger row', () => {
+    const onSelect = vi.fn()
+    render(
+      <Menu
+        open
+        anchor={<span>trigger</span>}
+        items={[
+          { type: 'label', id: 'h', text: 'Group by' },
+          { id: 'del', label: 'Delete', danger: true },
+        ]}
+        onSelect={onSelect}
+        onClose={() => {}}
+      />)
+    const heading = screen.getByText('Group by')
+    expect(heading.getAttribute('role')).toBe('presentation')
+    // The heading is not a menu item — only the danger row is interactive.
+    expect(screen.getAllByRole('menuitem')).toHaveLength(1)
+    const danger = screen.getByRole('menuitem', { name: 'Delete' })
+    expect(danger.className).toMatch(/danger/)
+    fireEvent.click(danger)
+    expect(onSelect).toHaveBeenCalledWith('del')
+  })
+
+  it('closeOnPointerLeave closes when the pointer leaves the list; default stays open', () => {
+    const onClose = vi.fn()
+    const { rerender } = render(
+      <Menu open closeOnPointerLeave anchor={<span>trigger</span>} items={items} onSelect={() => {}} onClose={onClose} />)
+    fireEvent.pointerLeave(screen.getByRole('menu'))
+    expect(onClose).toHaveBeenCalledTimes(1)
+    rerender(
+      <Menu open anchor={<span>trigger</span>} items={items} onSelect={() => {}} onClose={onClose} />)
+    fireEvent.pointerLeave(screen.getByRole('menu'))
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('a list click does not bubble to the anchor row (portal synthetic-event path)', () => {
+    const rowClick = vi.fn()
+    render(
+      <div onClick={rowClick}>
+        <Menu open anchor={<span>trigger</span>} items={items} onSelect={() => {}} onClose={() => {}} />
+      </div>)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Alpha' }))
+    expect(rowClick).not.toHaveBeenCalled()
+  })
+
   it('opens a submenu on hover and selects a nested item', () => {
     const onSelect = vi.fn()
     render(

packages/client/ui-primitives/tests/hover-card.spec.tsx

@@ -0,0 +1,148 @@
+// @vitest-environment jsdom
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { HoverCard } from '@deepseek-ai/dsh-client-ui-primitives'
+
+afterEach(cleanup)
+beforeEach(() => { vi.useFakeTimers() })
+afterEach(() => { vi.useRealTimers() })
+
+/** Anchor wrapper rect: the card positions from this (jsdom rects are all-zero by default). */
+function stubAnchorRect(anchor: HTMLElement, rect: { top: number; right: number }): void {
+  const wrapper = anchor.parentElement as HTMLElement
+  wrapper.getBoundingClientRect = () => ({
+    top: rect.top, right: rect.right, left: rect.right - 100, bottom: rect.top + 34,
+    width: 100, height: 34, x: rect.right - 100, y: rect.top, toJSON: () => ({}),
+  } as DOMRect)
+}
+
+function mount(props: { openDelayMs?: number; disabled?: boolean } = {}) {
+  const view = render(
+    <HoverCard anchor={<span>row</span>} content={<div>card body</div>} {...props} />,
+  )
+  const anchor = screen.getByText('row')
+  stubAnchorRect(anchor, { top: 40, right: 200 })
+  return { view, anchor, wrapper: anchor.parentElement as HTMLElement }
+}
+
+describe('HoverCard', () => {
+  it('opens after the dwell delay, positioned right of the anchor', () => {
+    const { wrapper } = mount()
+    fireEvent.pointerEnter(wrapper)
+    expect(screen.queryByText('card body')).toBeNull()
+    act(() => { vi.advanceTimersByTime(499) })
+    expect(screen.queryByText('card body')).toBeNull()
+    act(() => { vi.advanceTimersByTime(1) })
+    const card = screen.getByText('card body').parentElement as HTMLElement
+    expect(card.parentElement).toBe(document.body)
+    expect(card.style.left).toBe('208px')
+    expect(card.style.top).toBe('40px')
+  })
+
+  it('honors a custom openDelayMs', () => {
+    const { wrapper } = mount({ openDelayMs: 50 })
+    fireEvent.pointerEnter(wrapper)
+    act(() => { vi.advanceTimersByTime(50) })
+    expect(screen.getByText('card body')).toBeTruthy()
+  })
+
+  it('pointerleave before the delay cancels the pending open', () => {
+    const { wrapper } = mount()
+    fireEvent.pointerEnter(wrapper)
+    fireEvent.pointerLeave(wrapper)
+    act(() => { vi.advanceTimersByTime(1000) })
+    expect(screen.queryByText('card body')).toBeNull()
+  })
+
+  it('pointerleave closes an open card immediately; re-enter restarts the dwell', () => {
+    const { wrapper } = mount()
+    fireEvent.pointerEnter(wrapper)
+    act(() => { vi.advanceTimersByTime(500) })
+    expect(screen.getByText('card body')).toBeTruthy()
+    fireEvent.pointerLeave(wrapper)
+    expect(screen.queryByText('card body')).toBeNull()
+    fireEvent.pointerEnter(wrapper)
+    act(() => { vi.advanceTimersByTime(500) })
+    expect(screen.getByText('card body')).toBeTruthy()
+  })
+
+  it('a press inside the anchor dismisses the card without waiting for disabled', () => {
+    const { wrapper } = mount()
+    fireEvent.pointerEnter(wrapper)
+    act(() => { vi.advanceTimersByTime(500) })
+    expect(screen.getByText('card body')).toBeTruthy()
+    fireEvent.pointerDown(screen.getByText('row'))
+    expect(screen.queryByText('card body')).toBeNull()
+    // The pending timer is also cleared: no reopen after the dwell.
+    act(() => { vi.advanceTimersByTime(1000) })
+    expect(screen.queryByText('card body')).toBeNull()
+  })
+
+  it('disabled suppresses opening entirely', () => {
+    const { wrapper } = mount({ disabled: true })
+    fireEvent.pointerEnter(wrapper)
+    act(() => { vi.advanceTimersByTime(1000) })
+    expect(screen.queryByText('card body')).toBeNull()
+  })
+
+  it('flipping disabled true closes an open card', () => {
+    const { view, wrapper } = mount()
+    fireEvent.pointerEnter(wrapper)
+    act(() => { vi.advanceTimersByTime(500) })
+    expect(screen.getByText('card body')).toBeTruthy()
+    view.rerender(<HoverCard anchor={<span>row</span>} content={<div>card body</div>} disabled />)
+    expect(screen.queryByText('card body')).toBeNull()
+  })
+
+  it('corrects the bottom-edge clamp once the mounted card height is measurable', () => {
+    // First placement reads height 0 (card not yet mounted) and keeps the
+    // anchor top; the post-mount correction re-clamps with the real height.
+    window.innerHeight = 300
+    const offsetHeight = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'offsetHeight')!
+    Object.defineProperty(HTMLElement.prototype, 'offsetHeight', { configurable: true, get: () => 120 })
+    try {
+      const { wrapper } = mount()
+      stubAnchorRect(screen.getByText('row'), { top: 280, right: 200 })
+      fireEvent.pointerEnter(wrapper)
+      act(() => { vi.advanceTimersByTime(500) })
+      const card = screen.getByText('card body').parentElement as HTMLElement
+      // 300 - 120 - 8 = 172, instead of the anchor top 280.
+      expect(card.style.top).toBe('172px')
+    } finally {
+      Object.defineProperty(HTMLElement.prototype, 'offsetHeight', offsetHeight)
+    }
+  })
+
+  it('clamps inside placement itself when the card is already measured (resize path)', () => {
+    window.innerHeight = 300
+    const { wrapper } = mount()
+    stubAnchorRect(screen.getByText('row'), { top: 280, right: 200 })
+    fireEvent.pointerEnter(wrapper)
+    act(() => { vi.advanceTimersByTime(500) })
+    const card = screen.getByText('card body').parentElement as HTMLElement
+    Object.defineProperty(card, 'offsetHeight', { value: 120 })
+    act(() => { fireEvent.resize(window) })
+    expect(card.style.top).toBe('172px')
+  })
+
+  it('repositions on capture-phase scroll while open and stops listening after close', () => {
+    const { wrapper } = mount()
+    fireEvent.pointerEnter(wrapper)
+    act(() => { vi.advanceTimersByTime(500) })
+    stubAnchorRect(screen.getByText('row'), { top: 90, right: 300 })
+    act(() => { fireEvent.scroll(document) })
+    const card = screen.getByText('card body').parentElement as HTMLElement
+    expect(card.style.left).toBe('308px')
+    expect(card.style.top).toBe('90px')
+    fireEvent.pointerLeave(wrapper)
+    expect(screen.queryByText('card body')).toBeNull()
+  })
+
+  it('unmount clears a pending open timer', () => {
+    const { view, wrapper } = mount()
+    fireEvent.pointerEnter(wrapper)
+    view.unmount()
+    act(() => { vi.advanceTimersByTime(1000) })
+    expect(screen.queryByText('card body')).toBeNull()
+  })
+})

packages/client/ui-primitives/tests/icons.spec.tsx

@@ -14,8 +14,8 @@ const icons = Object.fromEntries(
 const iconNames = Object.keys(icons)
 
 describe('ic_ds_ icon set', () => {
-  it('exports the full P-I set (43 deepsuite + 7 figma extracts)', () => {
-    expect(iconNames.length).toBe(50)
+  it('exports the full P-I set (43 deepsuite + 12 figma extracts)', () => {
+    expect(iconNames.length).toBe(55)
   })
 
   it.each(iconNames)('%s renders an svg with currentColor fills and no hardcoded palette', name => {

packages/client/ui-settings-general/README.md

@@ -0,0 +1,15 @@
+# @deepseek-ai/dsh-client-ui-settings-general
+
+Settings ownerless-copy plugin: registers everything on the Settings surface that belongs to no single feature — the shell's trigger/header/close chrome content, the General section (Permission/Tool Call skeleton rows + the `settings.general.item` slot declaration), and the `settings` dictionaries. Feature-owned rows (Language, Appearance) and sections (Models) stay with their feature packages.
+
+## Model Experience
+
+None, as the plugin renders browser settings UI; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Permission and Tool Call are display skeletons** — the backing host services and RPC methods do not exist yet; the controls are disabled and write nothing. When they gain real backing, each moves to its owning feature plugin per the self-registration doctrine.

packages/client/ui-settings-general/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-settings-general",
+  "description": "Settings ownerless-copy plugin: the General section (skeleton rows + item slot), the shell trigger/header chrome content, and the settings dictionaries",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-ui-settings",
+      "@deepseek-ai/dsh-client-locale"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-locale": "^0.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}

packages/client/ui-settings-general/src/client/GeneralSection.module.css

@@ -0,0 +1,111 @@
+/* General section rows (figma 501:29983 'Options'): stacked groups, 16px
+ * vertical padding each, hairline separator under all but the last child
+ * (feature-contributed rows carry their own row chrome and separators; the
+ * :last-child rule strips the trailing one wherever the column ends). */
+
+.section {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+.section > :last-child {
+  border-bottom: none;
+}
+
+/* Title + trailing control row (figma 'Setting-Cell': gap 8, pad 16/0). */
+.row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 16px 0;
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+}
+
+/* Title + full-width body group (figma 'Frame 2117131229': column, gap 8). */
+.group {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 16px 0;
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+}
+
+/* Leading text column (figma 'Frame 2036083120': gap 4, pad-right 48). */
+.rowText {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding-right: 48px;
+}
+
+.title {
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.desc {
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* Selector pill (figma 'Selector': h36 r18, fill #F5F6F7, pad 0/14, gap 12). */
+.selector {
+  display: inline-flex;
+  align-items: center;
+  gap: 12px;
+  height: 36px;
+  padding: 0 14px;
+  border: none;
+  border-radius: 18px;
+  background: var(--dsw-alias-bg-module-platform);
+  font: inherit;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+  cursor: pointer;
+}
+
+.selector:disabled {
+  cursor: default;
+}
+
+.chevron {
+  flex: none;
+}
+
+/* Tool Call mode cubes share an 8px gap. */
+.cubeRow {
+  display: flex;
+  align-items: stretch;
+  gap: 8px;
+}
+
+/* Tool Call mode cube (figma '.Selector Cube' 418w r16; horizontal inset =
+ * outer pad 4 + inner .Menu_cell pad 10, vertical = inner pad 8). */
+.modeCube {
+  box-sizing: border-box;
+  width: 418px;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: 2px;
+  padding: 8px 14px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 16px;
+  background: transparent;
+  text-align: left;
+}
+
+/* Selected cube: #F5F6F7 fill + #ADB2B8 border (static token — the bluish-400
+ * step has no alias-layer name). */
+.selected {
+  background: var(--dsw-alias-bg-module-platform);
+  border-color: var(--dsw-static-neutral-bluish-400);
+}

packages/client/ui-settings-general/src/client/GeneralSection.tsx

@@ -0,0 +1,61 @@
+/**
+ * The General section (figma 501:29983 'Options'): Permission and Tool Call
+ * skeleton rows, then the feature-contributed preference rows from the
+ * `settings.general.item` slot (locale → Language, ui-theme → Appearance).
+ * The section column stacks rows; each row draws its own internals and
+ * separator.
+ */
+import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import css from './GeneralSection.module.css'
+
+/** Injected face of the General section: the settings-namespace translate. */
+export interface GeneralSectionInjected {
+  /** Translate a `settings` dictionary key to the active-locale text. */
+  t: (key: string) => string
+}
+
+/** Full component props: section owner share + item render share + inject face. */
+export type GeneralSectionComponentProps =
+  PropsRuntime<'settings.section'> & PropsRenderSlots<'settings.general.item'> & GeneralSectionInjected
+
+/**
+ * Render the General section content column.
+ * @param props - composed slot props (contract/slots.ts).
+ * @returns the section element tree.
+ */
+export function GeneralSection({ t, renderSlot }: GeneralSectionComponentProps) {
+  return (
+    <div className={css.section}>
+      {/* Permission (skeleton): disabled selector pill. */}
+      <div className={css.row}>
+        <div className={css.rowText}>
+          <div className={css.title}>{t('permission.title')}</div>
+          <div className={css.desc}>{t('permission.desc')}</div>
+        </div>
+        <button type="button" className={css.selector} disabled>
+          {t('permission.value')}
+          <IconChevronDownOutline14 className={css.chevron} />
+        </button>
+      </div>
+
+      {/* Tool Call (skeleton): schema cube pinned selected, code cube unselected. */}
+      <div className={css.group}>
+        <div className={css.title}>{t('toolcall.title')}</div>
+        <div className={css.cubeRow}>
+          <div className={`${css.modeCube} ${css.selected}`}>
+            <div className={css.title}>{t('toolcall.schema.title')}</div>
+            <div className={css.desc}>{t('toolcall.schema.desc')}</div>
+          </div>
+          <div className={css.modeCube}>
+            <div className={css.title}>{t('toolcall.code.title')}</div>
+            <div className={css.desc}>{t('toolcall.code.desc')}</div>
+          </div>
+        </div>
+      </div>
+
+      {/* Feature-owned preference rows (Language, Appearance, …). */}
+      {renderSlot('settings.general.item', {})}
+    </div>
+  )
+}

packages/client/ui-settings-general/src/client/chrome.module.css

@@ -0,0 +1,7 @@
+/* Trigger row label (the shell's button provides layout/colors; the label
+ * only guards against overflow during the sidebar collapse crossfade). */
+
+.triggerLabel {
+  overflow: hidden;
+  white-space: nowrap;
+}

packages/client/ui-settings-general/src/client/chrome.tsx

@@ -0,0 +1,56 @@
+/**
+ * Shell chrome content registered into the shell's trigger/header seats: the
+ * trigger row icon + label (figma sidebar foot) and the panel title text.
+ * The shell renders the surrounding chrome (button, nav heading row) and
+ * reads each entry's `label` option for aria text.
+ */
+import { IconSettingsOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import css from './chrome.module.css'
+
+/** Injected face of both chrome seats: the settings-namespace translate. */
+export interface ChromeInjected {
+  /** Translate a `settings` dictionary key to the active-locale text. */
+  t: (key: string) => string
+}
+
+/** Trigger content props: the sidebar column state + translate. */
+export type TriggerContentProps = PropsRuntime<'settings.trigger'> & ChromeInjected
+
+/** Header content props: translate only. */
+export type HeaderContentProps = PropsRuntime<'settings.header'> & ChromeInjected
+
+/**
+ * Render the trigger row content (icon; label only in the wide column).
+ * @param props - composed slot props.
+ * @returns the trigger content fragment.
+ */
+export function TriggerContent({ wide, t }: TriggerContentProps) {
+  return (
+    <>
+      <IconSettingsOutline14 size={wide ? 14 : 18} />
+      {wide && <span className={css.triggerLabel}>{t('trigger')}</span>}
+    </>
+  )
+}
+
+/**
+ * Render the panel title text.
+ * @param props - composed slot props.
+ * @returns the title text node.
+ */
+export function HeaderContent({ t }: HeaderContentProps) {
+  return <>{t('title')}</>
+}
+
+/** Close-button label text props: translate only. */
+export type CloseLabelProps = PropsRuntime<'settings.close'> & ChromeInjected
+
+/**
+ * Render the close button's visually-hidden label text.
+ * @param props - composed slot props.
+ * @returns the label text node.
+ */
+export function CloseLabel({ t }: CloseLabelProps) {
+  return <>{t('close')}</>
+}

packages/client/ui-settings-general/src/client/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Settings ownerless-copy plugin, browser half: registers everything on the
+ * Settings surface that belongs to no single feature — the trigger/header
+ * chrome content, the General section (skeleton rows + the
+ * `settings.general.item` slot declaration), and the `settings`
+ * dictionaries. Feature-owned rows and sections stay with their features.
+ * Export discipline: packages/client/AGENTS.md.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only: pulls the shell's SlotMap merges (trigger/header/section/item).
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { ChromeInjected } from './chrome.tsx'
+import { CloseLabel, HeaderContent, TriggerContent } from './chrome.tsx'
+import type { GeneralSectionInjected } from './GeneralSection.tsx'
+import { GeneralSection } from './GeneralSection.tsx'
+import { en, zh } from './locales.ts'
+
+export type {
+  ChromeInjected, CloseLabelProps, HeaderContentProps, TriggerContentProps,
+} from './chrome.tsx'
+export type {
+  GeneralSectionComponentProps, GeneralSectionInjected,
+} from './GeneralSection.tsx'
+
+/** Dictionary namespace owned by this plugin (shell chrome + General copy). */
+const NS = 'settings'
+
+/**
+ * Required services (cordis fiber inject). The target slots are declared by
+ * ui-settings' apply, whose activation order relative to this one is NOT
+ * constrained; registration goes through declaration-aware deferral.
+ */
+export const inject = ['slots', 'locale']
+
+/**
+ * Register the `settings` dictionaries, the chrome content, and the General
+ * section, each once its slot declaration is on the ledger.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => {
+    const disposers = [
+      ctx.locale.register(NS, 'zh', zh),
+      ctx.locale.register(NS, 'en', en),
+    ]
+    return () => { for (const dispose of disposers) dispose() }
+  }, 'ui-settings-general: dictionaries')
+
+  const t = ctx.locale.bind(NS)
+  const chromeInjected = (): ChromeInjected => ({ t })
+  const generalInjected = (): GeneralSectionInjected => ({ t })
+
+  // All four seats refresh on locale change: re-registration bumps each
+  // slot's ledger version, which re-renders the outlets through their own
+  // subscriptions (outlet memoization would swallow a parent-only render).
+  ctx.effect(() => {
+    const trigger = deferRegistration(ctx.slots, 'settings.trigger', TriggerContent, () =>
+      ctx.slots.register({ name: 'settings.trigger', inject: chromeInjected }, TriggerContent))
+    const header = deferRegistration(ctx.slots, 'settings.header', HeaderContent, () =>
+      ctx.slots.register({ name: 'settings.header', inject: chromeInjected }, HeaderContent))
+    const close = deferRegistration(ctx.slots, 'settings.close', CloseLabel, () =>
+      ctx.slots.register({ name: 'settings.close', inject: chromeInjected }, CloseLabel))
+    const general = deferRegistration(ctx.slots, 'settings.section', GeneralSection, () =>
+      ctx.slots.register({
+        name: 'settings.section',
+        id: 'general',
+        order: 0,
+        label: t('general.nav'),
+        children: { 'settings.general.item': { kind: 'list', scope: 'root' } },
+        inject: generalInjected,
+      }, GeneralSection))
+    const offLocale = ctx.on('locale/change', () => {
+      trigger.refresh()
+      header.refresh()
+      close.refresh()
+      general.refresh()
+    })
+    return () => {
+      offLocale()
+      trigger.dispose()
+      header.dispose()
+      close.dispose()
+      general.dispose()
+    }
+  }, 'ui-settings-general: chrome and section registrations')
+}

packages/client/ui-settings-general/src/client/locales.ts

@@ -0,0 +1,40 @@
+/**
+ * `settings` namespace dictionaries: shell chrome plus the shell-owned
+ * General section (nav label, skeleton rows). Skeleton-row technical copy
+ * (Read only / Schema mode / Code mode and their descriptions) is shared
+ * verbatim across locales per the Figma design. Feature-owned rows
+ * (Language, Appearance) ship their copy in their own packages.
+ */
+import type { LocaleDict } from '@deepseek-ai/dsh-client-locale/client'
+
+const SHARED = {
+  'permission.value': 'Read only',
+  'toolcall.schema.title': 'Schema mode',
+  'toolcall.schema.desc': 'Traditional function calling — invoke tools one at a time',
+  'toolcall.code.title': 'Code mode',
+  'toolcall.code.desc': 'Chain multiple tools with code — multi-step orchestration',
+} satisfies LocaleDict
+
+/** Simplified Chinese dictionary. */
+export const zh: LocaleDict = {
+  ...SHARED,
+  'trigger': '设置',
+  'title': '设置',
+  'close': '关闭',
+  'general.nav': '通用设置',
+  'permission.title': '权限',
+  'permission.desc': '选择默认权限模式',
+  'toolcall.title': '工具调用',
+}
+
+/** English dictionary. */
+export const en: LocaleDict = {
+  ...SHARED,
+  'trigger': 'Settings',
+  'title': 'Settings',
+  'close': 'Close',
+  'general.nav': 'General',
+  'permission.title': 'Permission',
+  'permission.desc': 'Choose default permission mode',
+  'toolcall.title': 'Tool Call',
+}

packages/client/ui-settings-general/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

packages/client/ui-settings-general/src/index.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser implementation exported from `./client`. */
+
+/** Host plugin body — no host-side behavior for the general settings plugin. */
+export function apply(): void {}

packages/client/ui-settings-general/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-settings-general`.
+ * @module @deepseek-ai/dsh-client-ui-settings-general/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-settings-general'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-settings-general-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a copy-owning registrant contributing chrome content
+ * and the General section into shell-declared slots — it emits no cordis
+ * events and owns no cross-plugin mutable relation; slot conflicts already
+ * fail loud in the slot core at load time.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/client/ui-settings-general/tests/apply.spec.ts

@@ -0,0 +1,150 @@
+/** Ownerless-copy registrations: the four seats, the dictionaries, locale refresh, and HMR recovery. */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import { apply, inject } from '@deepseek-ai/dsh-client-ui-settings-general/client'
+import type { GeneralSectionInjected } from '@deepseek-ai/dsh-client-ui-settings-general/client'
+import { CloseLabel, HeaderContent, TriggerContent } from '../src/client/chrome.tsx'
+import { GeneralSection } from '../src/client/GeneralSection.tsx'
+
+/** The four seats this plugin fills (slot name → expected component). */
+const SEATS = [
+  ['settings.trigger', TriggerContent],
+  ['settings.header', HeaderContent],
+  ['settings.close', CloseLabel],
+  ['settings.section', GeneralSection],
+] as const
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  const locale = new LocaleService(ctx)
+  ctx.provide('locale', locale)
+  return { ctx, slots: ctx.get('slots') as SlotsService, locale }
+}
+
+/** Declare the shell's four child slots the way ui-settings' entry does. */
+function declare(slots: SlotsService): () => void {
+  return slots.register(
+    {
+      name: 'root',
+      children: {
+        'settings.trigger': { kind: 'single', scope: 'root' },
+        'settings.header': { kind: 'single', scope: 'root' },
+        'settings.close': { kind: 'single', scope: 'root' },
+        'settings.section': { kind: 'list', scope: 'root' },
+      },
+    } as never,
+    () => null,
+  )
+}
+
+function generalEntry(slots: SlotsService) {
+  return slots.entries('settings.section').find(e => e.component === GeneralSection)
+}
+
+describe('ui-settings-general apply', () => {
+  it('declares the services it uses', () => {
+    expect(inject).toEqual(['slots', 'locale'])
+  })
+
+  it('fills all four seats for declarations before or after apply', async () => {
+    const before = await bench()
+    declare(before.slots)
+    await before.ctx.plugin({ inject: [...inject], apply }).await()
+    for (const [name, component] of SEATS) {
+      expect(before.slots.entries(name)[0]!.component).toBe(component)
+    }
+    const entry = generalEntry(before.slots)!
+    expect(entry.options).toEqual({ id: 'general', order: 0, label: '通用设置' })
+    expect(before.slots.spec('settings.general.item')).toEqual({ kind: 'list', scope: 'root' })
+    const injected = (entry.inject as unknown as () => GeneralSectionInjected)()
+    expect(injected.t('permission.title')).toBe('权限')
+    // The chrome seats share one inject face: the settings-ns translate.
+    const chrome = (before.slots.entries('settings.trigger')[0]!.inject as unknown as () => GeneralSectionInjected)()
+    expect(chrome.t('trigger')).toBe('设置')
+
+    const after = await bench()
+    await after.ctx.plugin({ inject: [...inject], apply }).await()
+    for (const [name] of SEATS) expect(after.slots.entries(name)).toHaveLength(0)
+    declare(after.slots)
+    await Promise.resolve()
+    for (const [name, component] of SEATS) {
+      expect(after.slots.entries(name)[0]!.component).toBe(component)
+      // The self-inflicted ledger notifications hit the duplicate guard.
+      expect(after.slots.entries(name)).toHaveLength(1)
+    }
+  })
+
+  it('registers the zh/en settings dictionaries and frees the seats on teardown', async () => {
+    const b = await bench()
+    declare(b.slots)
+    const fiber = b.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(b.locale.bind('settings')('title')).toBe('设置')
+    b.locale.setLocale('en')
+    expect(b.locale.bind('settings')('close')).toBe('Close')
+    b.locale.setLocale('zh')
+    await fiber.dispose()
+    // The (ns, locale) seats are free again — the dictionary disposers ran.
+    expect(() => b.locale.register('settings', 'zh', {})).not.toThrow()
+    expect(() => b.locale.register('settings', 'en', {})).not.toThrow()
+  })
+
+  it('refreshes all four seats on locale change with fresh General label text', async () => {
+    const b = await bench()
+    declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const zhVersions = SEATS.map(([name]) => b.slots.getVersion(name))
+    b.locale.setLocale('en')
+    // Every seat re-registered (version moved) and the label re-resolved.
+    SEATS.forEach(([name], i) => {
+      expect(b.slots.getVersion(name)).toBeGreaterThan(zhVersions[i]!)
+      expect(b.slots.entries(name)).toHaveLength(1)
+    })
+    expect(generalEntry(b.slots)!.options.label).toBe('General')
+    b.locale.setLocale('zh')
+    expect(generalEntry(b.slots)!.options.label).toBe('通用设置')
+  })
+
+  it('locale change while the slots are undeclared stays a no-op', async () => {
+    const b = await bench()
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    b.locale.setLocale('en')
+    for (const [name] of SEATS) expect(b.slots.entries(name)).toHaveLength(0)
+    b.locale.setLocale('zh')
+  })
+
+  it('re-registers after an HMR collapse of the declaring chain (stale disposers must not block)', async () => {
+    const b = await bench()
+    const redeclare = declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    // Declarer unload: the cascade removes every seat entry and the item
+    // declaration while our local disposers go stale.
+    redeclare()
+    for (const [name] of SEATS) expect(b.slots.entries(name)).toHaveLength(0)
+    expect(b.slots.spec('settings.general.item')).toBeUndefined()
+    declare(b.slots)
+    await Promise.resolve()
+    for (const [name, component] of SEATS) {
+      expect(b.slots.entries(name)[0]!.component).toBe(component)
+    }
+    expect(b.slots.spec('settings.general.item')).toEqual({ kind: 'list', scope: 'root' })
+    // The recovered registrations still ride the locale path.
+    b.locale.setLocale('en')
+    expect(generalEntry(b.slots)!.options.label).toBe('General')
+    b.locale.setLocale('zh')
+  })
+
+  it('removes every seat and the item declaration on teardown', async () => {
+    const b = await bench()
+    declare(b.slots)
+    const fiber = b.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(b.slots.spec('settings.general.item')).toBeDefined()
+    await fiber.dispose()
+    for (const [name] of SEATS) expect(b.slots.entries(name)).toHaveLength(0)
+    expect(b.slots.spec('settings.general.item')).toBeUndefined()
+  })
+})

packages/client/ui-settings-general/tests/components.spec.tsx

@@ -0,0 +1,72 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import type { GeneralSectionComponentProps } from '../src/client/GeneralSection.tsx'
+import { GeneralSection } from '../src/client/GeneralSection.tsx'
+import { CloseLabel, HeaderContent, TriggerContent } from '../src/client/chrome.tsx'
+import { en } from '../src/client/locales.ts'
+
+afterEach(cleanup)
+
+const t = (key: string) => en[key] ?? key
+
+// Global standard kit stubs: none of these components consume the hooks.
+const unusedHook = (() => { throw new Error('unused by settings-general components') }) as never
+const kit = { useSessions: unusedHook, useWorkspaces: unusedHook }
+
+describe('chrome content', () => {
+  it('TriggerContent renders the icon with the label in the wide column', () => {
+    const { container } = render(<TriggerContent {...kit} wide t={t} />)
+    expect(container.querySelector('svg')).toBeTruthy()
+    expect(screen.getByText('Settings')).toBeTruthy()
+  })
+
+  it('TriggerContent drops the label in the rail state', () => {
+    const { container } = render(<TriggerContent {...kit} wide={false} t={t} />)
+    expect(container.querySelector('svg')).toBeTruthy()
+    expect(screen.queryByText('Settings')).toBeNull()
+  })
+
+  it('HeaderContent and CloseLabel render their translated text', () => {
+    render(<HeaderContent {...kit} t={t} />)
+    render(<CloseLabel {...kit} t={t} />)
+    expect(screen.getByText('Settings')).toBeTruthy()
+    expect(screen.getByText('Close')).toBeTruthy()
+  })
+})
+
+describe('GeneralSection', () => {
+  function mount() {
+    const renderSlot = vi.fn(
+      ((key: string) => <div data-testid={`slot-${key}`} />) as GeneralSectionComponentProps['renderSlot'],
+    )
+    const props: GeneralSectionComponentProps = { ...kit, t, renderSlot }
+    const view = render(<GeneralSection {...props} />)
+    return { view, renderSlot }
+  }
+
+  it('renders the Permission skeleton row with the disabled selector', () => {
+    mount()
+    expect(screen.getByText('Permission')).toBeTruthy()
+    expect(screen.getByText('Choose default permission mode')).toBeTruthy()
+    const selector = screen.getByRole('button', { name: /Read only/ }) as HTMLButtonElement
+    expect(selector.disabled).toBe(true)
+  })
+
+  it('renders the Tool Call skeleton cubes with schema pinned selected', () => {
+    mount()
+    expect(screen.getByText('Tool Call')).toBeTruthy()
+    const schema = screen.getByText('Schema mode')
+    const code = screen.getByText('Code mode')
+    expect(schema.parentElement!.className).toContain('selected')
+    expect(code.parentElement!.className).not.toContain('selected')
+    expect(screen.getByText('Traditional function calling — invoke tools one at a time')).toBeTruthy()
+    expect(screen.getByText('Chain multiple tools with code — multi-step orchestration')).toBeTruthy()
+  })
+
+  it('renders the feature-contributed item slot after the skeleton rows', () => {
+    const { renderSlot } = mount()
+    expect(renderSlot).toHaveBeenCalledWith('settings.general.item', {})
+    expect(screen.getByTestId('slot-settings.general.item')).toBeTruthy()
+  })
+})

packages/client/ui-settings-general/tests/invariant.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as GeneralInvariant from '@deepseek-ai/dsh-client-ui-settings-general/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(GeneralInvariant).await()).resolves.toBeDefined()
+  })
+
+  it('node-half apply is a no-op host placeholder', async () => {
+    const { apply } = await import('@deepseek-ai/dsh-client-ui-settings-general')
+    apply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+})

packages/client/ui-settings-general/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-settings"
+    },
+    {
+      "path": "../locale"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/client/ui-settings-general/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-settings-general', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/client/ui-settings/README.md

@@ -0,0 +1,15 @@
+# @deepseek-ai/dsh-client-ui-settings
+
+Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and the modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content) and `settings.section` (one page per feature). The shell ships no copy and reads no locale state — all text arrives from registrants (ui-settings-general owns chrome and General; features own their sections and rows), so the section ledger bump is its only re-render trigger.
+
+## Model Experience
+
+None, as the settings shell serves browser UI composition; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Panel is browser-preference scope only** — host-side settings surfaces (permission mode, tool-call mode) have no RPC backing yet; their skeletons live in ui-settings-general.

packages/client/ui-settings/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-settings",
+  "description": "Settings shell plugin: sidebar trigger + modal panel occupying sidebar.settings; declares the settings.section list slot",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-ui-sidebar"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "clsx": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}

packages/client/ui-settings/src/client/SettingsRoot.module.css

@@ -0,0 +1,202 @@
+/* Settings shell (figma 501:29904 mask context / 501:29947 panel): sidebar
+   foot trigger row + centered 1080x700 modal panel. The trigger reproduces
+   the former sidebar foot geometry (49px wide row / 36px rail circle); the
+   panel is a two-column layout — 188px nav rail + content column with a
+   54px header and the 24px-padded options area. */
+
+/* Trigger row (former sidebar foot, figma 133:7668): 49px hover pill. */
+.trigger {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  height: 49px;
+  margin: 8px 0 0;
+  padding: 0 2px 0 6px;
+  border: none;
+  border-radius: 12px;
+  background: transparent;
+  cursor: pointer;
+  overflow: hidden;
+  color: var(--dsw-alias-label-primary);
+  font-family: inherit;
+  font-size: 14px;
+}
+
+.trigger:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* Rail trigger: the same 36x36 circle box as the other rail controls. */
+.trigger.rail {
+  width: 36px;
+  height: 36px;
+  margin: 18px 0 10px;
+  justify-content: center;
+  gap: 0;
+  padding: 0;
+  border-radius: 50%;
+}
+
+.triggerLabel {
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+/* Full-viewport layer (figma Mask 501:29946 #000@24%, no blur). */
+.overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.mask {
+  position: absolute;
+  inset: 0;
+  background: var(--dsw-alias-bg-mask-1);
+}
+
+/* Panel (figma Settings 501:29947): 1080x700, r24, white, lv3 shadow
+   (figma effects match --dsw-shadow-lv3 exactly). */
+.panel {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  width: 1080px;
+  height: 700px;
+  max-width: calc(100vw - 48px);
+  max-height: calc(100vh - 48px);
+  border-radius: 24px;
+  overflow: hidden;
+  background: var(--dsw-alias-bg-layer-1);
+  box-shadow: var(--dsw-shadow-lv3);
+}
+
+/* Nav rail (figma .Setting-nav 501:29958): 188 wide, pad (12,22,12,0),
+   gap 18, no own fill — the panel white shows through. */
+.nav {
+  flex: none;
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  width: 188px;
+  padding: 22px 12px 0;
+  box-sizing: border-box;
+}
+
+/* Title row (figma 501:29959): 16/500 lh24, 12px side padding. */
+.navTitle {
+  padding: 0 12px;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Cell stack (figma 501:29961): gap 4. */
+.navList {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+/* Nav cell (figma .Setting-nav-cell 501:29962): 164x40, r12, pad
+   (12,9,16,9), gap 8; label 14/400 lh22; selected fill #EBEEF2. */
+.navCell {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 40px;
+  padding: 9px 16px 9px 12px;
+  box-sizing: border-box;
+  border: none;
+  border-radius: 12px;
+  background: transparent;
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 14px;
+  line-height: 22px;
+  font-weight: 400;
+  color: var(--dsw-alias-label-primary);
+  text-align: left;
+}
+
+.navCell:hover {
+  background: var(--dsw-specific-sidebar-nav-item-hover);
+}
+
+.navCell.active {
+  background: var(--dsw-specific-sidebar-nav-item-active);
+}
+
+.navIcon {
+  flex: none;
+}
+
+.navLabel {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/* Content column (figma Content 501:29980): header + options. */
+.content {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Header (figma .Header 501:29981): h54, pad (10,20,14,8), close right. */
+.header {
+  flex: none;
+  display: flex;
+  align-items: flex-start;
+  justify-content: flex-end;
+  height: 54px;
+  padding: 20px 14px 8px 10px;
+  box-sizing: border-box;
+}
+
+/* Close button (figma .Icon_container 501:29982): 28x28, r28, 14px glyph. */
+.close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: none;
+  border-radius: 28px;
+  background: transparent;
+  cursor: pointer;
+  color: var(--dsw-alias-label-primary);
+}
+
+.close:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* Options area (figma Options 501:29983): pad (24,0,24,8), scrolls. */
+.options {
+  flex: 1;
+  min-height: 0;
+  padding: 0 24px 8px;
+  overflow-y: auto;
+}
+
+/* Visually-hidden text seat (close button accessible name from slot content). */
+.hiddenLabel {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}

packages/client/ui-settings/src/client/SettingsRoot.tsx

@@ -0,0 +1,124 @@
+/**
+ * Settings shell root: the sidebar-foot trigger row plus the centered modal
+ * panel (figma 501:29947, 1080x700) with the section nav rail. The shell is
+ * a pure composition face — every piece of text (trigger label, panel title,
+ * close label, sections) arrives from registrants through slots; accessible
+ * names resolve to that content (trigger: its own text; dialog:
+ * aria-labelledby the title node; close: visually-hidden slot text). Modal
+ * open state and the active section id are component-local viewing state.
+ */
+import { useCallback, useEffect, useId, useRef, useState } from 'react'
+import clsx from 'clsx'
+import { IconCloseOutline16, IconDataOutline16, IconSettingsOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { SettingsRootComponentProps } from './contract/slots.ts'
+import css from './SettingsRoot.module.css'
+
+/** Nav glyph by section id; unknown ids fall back to the settings gear. */
+function navIcon(id: string) {
+  if (id === 'models') return <IconDataOutline16 className={css.navIcon} size={16} />
+  return <IconSettingsOutline16 className={css.navIcon} size={16} />
+}
+
+type PanelProps = {
+  rows: ReturnType<SettingsRootComponentProps['sections']>
+  renderSlot: SettingsRootComponentProps['renderSlot']
+  onClose: () => void
+}
+
+/**
+ * The modal layer: full-viewport mask + centered panel. Close paths: the
+ * header button, a mask click, and document-level Escape (mounted only while
+ * open, so the listener lifetime is the panel's).
+ */
+function SettingsPanel({ rows, renderSlot, onClose }: PanelProps) {
+  // Local selection; entries can unmount underneath it, so the render-time
+  // projection falls back to the first row when the id is gone.
+  const [activeId, setActiveId] = useState<string | undefined>(undefined)
+  const active = rows.find((r) => r.id === activeId)?.id ?? rows[0]?.id
+  const titleId = useId()
+
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', onKeyDown)
+    return () => { document.removeEventListener('keydown', onKeyDown) }
+  }, [onClose])
+
+  // Baseline focus management: entering the dialog lands on the close button.
+  const closeButton = useRef<HTMLButtonElement | null>(null)
+  useEffect(() => { closeButton.current?.focus() }, [])
+
+  return (
+    <div className={css.overlay} role="presentation">
+      <div className={css.mask} aria-hidden="true" onClick={onClose} />
+      <div className={css.panel} role="dialog" aria-modal="true" aria-labelledby={titleId}>
+        <nav className={css.nav}>
+          <div className={css.navTitle} id={titleId}>{renderSlot('settings.header', {})}</div>
+          <div className={css.navList}>
+            {rows.map((row) => (
+              <button
+                key={row.id}
+                type="button"
+                className={clsx(css.navCell, row.id === active && css.active)}
+                aria-current={row.id === active ? 'true' : undefined}
+                onClick={() => { setActiveId(row.id) }}
+              >
+                {navIcon(row.id)}
+                <span className={css.navLabel}>{row.label}</span>
+              </button>
+            ))}
+          </div>
+        </nav>
+        <div className={css.content}>
+          <div className={css.header}>
+            <button ref={closeButton} type="button" className={css.close} onClick={onClose}>
+              <IconCloseOutline16 size={14} />
+              <span className={css.hiddenLabel}>{renderSlot('settings.close', {})}</span>
+            </button>
+          </div>
+          <div className={css.options}>
+            {active !== undefined && renderSlot('settings.section', {}, { only: active })}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Render the settings trigger and panel.
+ * @param props - composed slot props (contract/slots.ts).
+ * @returns the settings shell element tree.
+ */
+export function SettingsRoot(props: SettingsRootComponentProps) {
+  const { wide, subscribeSections, sectionsVersion, sections, renderSlot } = props
+  const [open, setOpen] = useState(false)
+  const close = useCallback(() => { setOpen(false) }, [])
+
+  // The ledger tick keeps the nav rows fresh: registrants re-register with
+  // freshly localized text on locale change, and the trigger/header/close
+  // seats re-render through their own outlets' subscriptions.
+  // State = ledger version: same-version notifications dedupe to no render.
+  const [, setSectionsRev] = useState(() => sectionsVersion())
+  useEffect(
+    () => subscribeSections(() => { setSectionsRev(sectionsVersion()) }),
+    [subscribeSections, sectionsVersion],
+  )
+  const rows = sections()
+
+  return (
+    <>
+      <button
+        type="button"
+        className={clsx(css.trigger, !wide && css.rail)}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        onClick={() => { setOpen(true) }}
+      >
+        {renderSlot('settings.trigger', { wide })}
+      </button>
+      {open && <SettingsPanel rows={rows} renderSlot={renderSlot} onClose={close} />}
+    </>
+  )
+}

packages/client/ui-settings/src/client/contract/slots.ts

@@ -0,0 +1,97 @@
+/**
+ * Settings shell slot contract — the canonical home of every settings slot
+ * type. The shell is a pure composition face with zero copy of its own: it
+ * occupies the sidebar-owned `sidebar.settings` hole and declares the slots
+ * below; ALL text (trigger label, panel title, close aria, section content)
+ * arrives from registrants. A feature owns its settings surface — adding a
+ * setting never means editing the shell; copy that belongs to no single
+ * feature (chrome, the General section) is owned by ui-settings-general.
+ */
+import type { PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only: pulls ui-sidebar's SlotMap merge (the 'sidebar.settings' entry)
+// into every program that sees this contract.
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar/client'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /**
+     * The sidebar-foot trigger row content: icon + label, supplied as slot
+     * content (the accessible name comes from the content — rail state
+     * renders the label visually hidden). The shell renders the button
+     * chrome and owns open state. Absent contribution degrades to an
+     * icon-only button without an accessible name (broken-composition state;
+     * the shipped composition always registers the seat).
+     */
+    'settings.trigger': { kind: 'single'; scope: 'root'; owner: SettingsTriggerOwnerProps }
+    /**
+     * The panel title text seat. Content renders inside the nav heading row;
+     * the dialog's accessible name points at that node via aria-labelledby.
+     * Absent contribution leaves the heading empty.
+     */
+    'settings.header': { kind: 'single'; scope: 'root'; owner: SettingsHeaderOwnerProps }
+    /**
+     * The close button's visually-hidden label text (the button itself —
+     * icon, geometry, focus — is shell chrome). Absent contribution leaves
+     * the button without an accessible name (broken-composition state).
+     */
+    'settings.close': { kind: 'single'; scope: 'root'; owner: SettingsHeaderOwnerProps }
+    /**
+     * One settings page per list entry. Registrant options carry the nav
+     * identity: `id` (section key, drives `only` filtering), `order` (nav
+     * position), `label` (registrant-localized display text — the registrant
+     * re-registers with fresh text on locale change, so the shell never
+     * subscribes locale state; the ledger bump doubles as the shell's
+     * re-render trigger). Sections render inside the panel content column.
+     * (`settings.general.item`, declared by ui-settings-general's General
+     * entry, is typed in the locale package — the common dependency of every
+     * item registrant; the shell neither declares nor renders it.)
+     */
+    'settings.section': { kind: 'list'; scope: 'root'; owner: SettingsSectionOwnerProps }
+  }
+}
+
+/** Owner share of the trigger content seat: the sidebar column state. */
+export interface SettingsTriggerOwnerProps {
+  /** Whether the sidebar renders wide content (false = 56px rail, icon only). */
+  wide: boolean
+}
+
+/** Owner share of the header title seat (the shell supplies nothing). */
+export interface SettingsHeaderOwnerProps {
+  /** Marker field: header owner props are intentionally empty. */
+  children?: never
+}
+
+/**
+ * Owner share of a settings section entry. The shell owns modal visibility
+ * and navigation; sections receive nothing but the render site (their data
+ * arrives through their own inject faces and stores).
+ */
+export interface SettingsSectionOwnerProps {
+  /** Marker field: section owner props are intentionally empty for now. */
+  children?: never
+}
+
+/**
+ * Registrant-private injected share of the settings shell (assembled in
+ * apply): ledger projections only — the shell reads no locale state.
+ */
+export type SettingsRootInjected = {
+  /** Read the settings.section ledger version (nav invalidation). */
+  sectionsVersion: () => number
+  /** Subscribe to settings.section ledger changes. */
+  subscribeSections: (listener: () => void) => () => void
+  /** Project the settings.section ledger into nav rows (id/order/label). */
+  sections: () => readonly { id: string; order: number; label: string }[]
+}
+
+/**
+ * Full component props of the settings shell root: the sidebar owner share
+ * (wide/rail state) plus the declared render shares and the injected face.
+ * No store is registered — modal open state and active section id are
+ * component-local viewing state.
+ */
+export type SettingsRootComponentProps =
+  PropsRuntime<'sidebar.settings'>
+  & PropsRenderSlots<'settings.trigger' | 'settings.header' | 'settings.close' | 'settings.section'>
+  & SettingsRootInjected

packages/client/ui-settings/src/client/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Settings shell plugin, browser half. A pure composition face: occupies the
+ * sidebar-owned `sidebar.settings` hole with the trigger chrome + modal
+ * panel, declares the `settings.trigger` / `settings.header` /
+ * `settings.section` slots, and projects the section ledger into the panel
+ * navigation. The shell ships no copy and reads no locale state — all text
+ * arrives from registrants (ui-settings-general owns the chrome and General
+ * content; features own their rows and sections). Export discipline:
+ * packages/client/AGENTS.md.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SettingsRootInjected } from './contract/slots.ts'
+import { SettingsRoot } from './SettingsRoot.tsx'
+
+export type {
+  SettingsHeaderOwnerProps, SettingsRootComponentProps, SettingsRootInjected,
+  SettingsSectionOwnerProps, SettingsTriggerOwnerProps,
+} from './contract/slots.ts'
+
+/**
+ * Required services (cordis fiber inject). The target slot is declared by
+ * ui-sidebar's apply, whose activation order relative to this one is NOT
+ * constrained (dshClient.inject edges are informational); registration goes
+ * through declaration-aware deferral.
+ */
+export const inject = ['slots']
+
+/**
+ * Register the settings shell into `sidebar.settings` once the declaration is
+ * on the ledger.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  const injected = (): SettingsRootInjected => ({
+    sectionsVersion: () => ctx.slots.getVersion('settings.section'),
+    subscribeSections: listener => ctx.slots.subscribe('settings.section', listener),
+    sections: () => ctx.slots.entries('settings.section')
+      .map(e => ({
+        /* v8 ignore next -- list-slot registration requires id (SlotCore rejects an entry without one) */
+        id: e.options.id ?? '',
+        order: e.options.order ?? 0,
+        label: e.options.label ?? '',
+      }))
+      .sort((a, b) => a.order - b.order),
+  })
+  ctx.effect(() => {
+    const deferred = deferRegistration(ctx.slots, 'sidebar.settings', SettingsRoot, () =>
+      ctx.slots.register({
+        name: 'sidebar.settings',
+        children: {
+          'settings.trigger': { kind: 'single', scope: 'root' },
+          'settings.header': { kind: 'single', scope: 'root' },
+          'settings.close': { kind: 'single', scope: 'root' },
+          'settings.section': { kind: 'list', scope: 'root' },
+        },
+        inject: injected,
+      }, SettingsRoot))
+    return () => { deferred.dispose() }
+  }, 'ui-settings: shell registration')
+}

packages/client/ui-settings/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

packages/client/ui-settings/src/index.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser implementation exported from `./client`. */
+
+/** Host plugin body — no host-side behavior for the settings shell plugin. */
+export function apply(): void {}

packages/client/ui-settings/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-settings`.
+ * @module @deepseek-ai/dsh-client-ui-settings/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-settings'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-settings-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a presentation shell projecting the settings.section
+ * ledger into navigation — it emits no cordis events and owns no cross-plugin
+ * mutable relation; slot declaration/registration conflicts already fail loud
+ * in the slot core at load time.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/client/ui-settings/tests/apply.spec.ts

@@ -0,0 +1,111 @@
+/** Settings shell registration: declaration-aware deferral, the ledger projections, and HMR recovery. */
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { apply, inject } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { SettingsRootInjected } from '@deepseek-ai/dsh-client-ui-settings/client'
+import { SettingsRoot } from '../src/client/SettingsRoot.tsx'
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  return { ctx, slots: ctx.get('slots') as SlotsService }
+}
+
+function declare(slots: SlotsService): () => void {
+  return slots.register(
+    { name: 'root', children: { 'sidebar.settings': { kind: 'single', scope: 'root' } } } as never,
+    () => null,
+  )
+}
+
+function injectedOf(slots: SlotsService): SettingsRootInjected {
+  const entry = slots.entries('sidebar.settings')[0]!
+  return (entry.inject as () => SettingsRootInjected)()
+}
+
+/** The shell's four child declarations (chrome seats + the section list). */
+const CHILD_SPECS = {
+  'settings.trigger': { kind: 'single', scope: 'root' },
+  'settings.header': { kind: 'single', scope: 'root' },
+  'settings.close': { kind: 'single', scope: 'root' },
+  'settings.section': { kind: 'list', scope: 'root' },
+} as const
+
+describe('ui-settings apply', () => {
+  it('declares only the slot registry (a pure composition face, no locale)', () => {
+    expect(inject).toEqual(['slots'])
+  })
+
+  it('registers the shell and declares the four child slots, before or after the declaration', async () => {
+    const before = await bench()
+    declare(before.slots)
+    await before.ctx.plugin({ inject: [...inject], apply }).await()
+    expect(before.slots.entries('sidebar.settings')[0]!.component).toBe(SettingsRoot)
+    for (const [name, spec] of Object.entries(CHILD_SPECS)) {
+      expect(before.slots.spec(name as never)).toEqual(spec)
+    }
+
+    const after = await bench()
+    await after.ctx.plugin({ inject: [...inject], apply }).await()
+    expect(after.slots.entries('sidebar.settings')).toHaveLength(0)
+    declare(after.slots)
+    await Promise.resolve()
+    expect(after.slots.entries('sidebar.settings')[0]!.component).toBe(SettingsRoot)
+    // The self-inflicted ledger notifications hit the duplicate guard.
+    expect(after.slots.entries('sidebar.settings')).toHaveLength(1)
+  })
+
+  it('projects the section ledger into ordered nav rows with option defaults', async () => {
+    const b = await bench()
+    declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const injected = injectedOf(b.slots)
+    // The shell ships no sections of its own — registrants fill the ledger.
+    expect(injected.sections()).toEqual([])
+    b.slots.register({ name: 'settings.section', id: 'z', order: 20, label: 'Z' } as never, () => null)
+    // No order and no label: both projection defaults apply.
+    b.slots.register({ name: 'settings.section', id: 'a' } as never, () => null)
+    expect(injected.sections()).toEqual([
+      { id: 'a', order: 0, label: '' },
+      { id: 'z', order: 20, label: 'Z' },
+    ])
+    expect(injected.sectionsVersion()).toBe(b.slots.getVersion('settings.section'))
+    const listener = vi.fn()
+    const off = injected.subscribeSections(listener)
+    b.slots.register({ name: 'settings.section', id: 'b', order: 1, label: 'B' } as never, () => null)
+    await Promise.resolve()
+    expect(listener).toHaveBeenCalled()
+    off()
+  })
+
+  it('re-registers after an HMR collapse re-declares the slot (stale disposer must not block)', async () => {
+    const b = await bench()
+    const redeclare = declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    expect(b.slots.entries('sidebar.settings')).toHaveLength(1)
+    // Declarer unload: the cascade removes our entry and every child
+    // declaration while our local disposer variable goes stale.
+    redeclare()
+    expect(b.slots.entries('sidebar.settings')).toHaveLength(0)
+    expect(b.slots.spec('settings.trigger')).toBeUndefined()
+    declare(b.slots)
+    await Promise.resolve()
+    expect(b.slots.entries('sidebar.settings')[0]!.component).toBe(SettingsRoot)
+    for (const [name, spec] of Object.entries(CHILD_SPECS)) {
+      expect(b.slots.spec(name as never)).toEqual(spec)
+    }
+  })
+
+  it('unregisters the shell and collapses all four child slots on teardown', async () => {
+    const b = await bench()
+    declare(b.slots)
+    const fiber = b.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    await fiber.dispose()
+    expect(b.slots.entries('sidebar.settings')).toHaveLength(0)
+    for (const name of Object.keys(CHILD_SPECS)) {
+      expect(b.slots.spec(name as never)).toBeUndefined()
+    }
+  })
+})

packages/client/ui-settings/tests/invariant.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as SettingsInvariant from '@deepseek-ai/dsh-client-ui-settings/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(SettingsInvariant).await()).resolves.toBeDefined()
+  })
+
+  it('node-half apply is a no-op host placeholder', async () => {
+    const { apply } = await import('@deepseek-ai/dsh-client-ui-settings')
+    apply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+})

packages/client/ui-settings/tests/settings-root.spec.tsx

@@ -0,0 +1,180 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import type { SettingsRootComponentProps } from '../src/client/contract/slots.ts'
+import { SettingsRoot } from '../src/client/SettingsRoot.tsx'
+
+afterEach(cleanup)
+
+type Row = { id: string; order: number; label: string }
+
+/** Slot-content stand-ins: the shell renders whatever the seats contribute. */
+const SEAT_CONTENT: Record<string, string> = {
+  'settings.trigger': 'Settings',
+  'settings.header': 'Settings Title',
+  'settings.close': 'Close',
+}
+
+function mount({
+  wide = true,
+  rows = [
+    { id: 'general', order: 0, label: 'General' },
+    { id: 'models', order: 10, label: 'Models' },
+  ],
+}: { wide?: boolean; rows?: Row[] } = {}) {
+  // Mutable row store standing in for the ledger; bump() plays a change.
+  let current = rows
+  let version = 0
+  const listeners = new Set<() => void>()
+  const renderSlot = vi.fn(
+    ((key: string, _owner: unknown, opts?: { only?: string }) => {
+      if (key === 'settings.section') return <div data-testid={`section-${opts?.only ?? 'all'}`} />
+      return SEAT_CONTENT[key]
+    }) as SettingsRootComponentProps['renderSlot'],
+  )
+  // Global standard kit stubs: the shell consumes neither hook.
+  const unusedHook = (() => { throw new Error('unused by SettingsRoot') }) as never
+  const props: SettingsRootComponentProps = {
+    useSessions: unusedHook,
+    useWorkspaces: unusedHook,
+    wide,
+    sectionsVersion: () => version,
+    subscribeSections: (listener) => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    sections: () => current,
+    renderSlot,
+  }
+  const view = render(<SettingsRoot {...props} />)
+  const bump = (next: Row[]) => {
+    act(() => {
+      current = next
+      version += 1
+      for (const fn of [...listeners]) fn()
+    })
+  }
+  return { view, renderSlot, bump, listeners }
+}
+
+function openPanel() {
+  fireEvent.click(screen.getByRole('button', { name: 'Settings' }))
+}
+
+describe('SettingsRoot trigger', () => {
+  it('renders the trigger seat content as the accessible name (no aria-label of its own)', () => {
+    const { renderSlot } = mount()
+    const trigger = screen.getByRole('button', { name: 'Settings' })
+    expect(trigger.hasAttribute('aria-label')).toBe(false)
+    expect(renderSlot).toHaveBeenCalledWith('settings.trigger', { wide: true })
+    expect(trigger.getAttribute('aria-expanded')).toBe('false')
+    fireEvent.click(trigger)
+    expect(screen.getByRole('dialog')).toBeTruthy()
+    expect(screen.getByRole('button', { name: 'Settings', expanded: true })).toBeTruthy()
+  })
+
+  it('hands the rail state to the trigger seat', () => {
+    const { renderSlot } = mount({ wide: false })
+    expect(renderSlot).toHaveBeenCalledWith('settings.trigger', { wide: false })
+  })
+})
+
+describe('SettingsPanel chrome seats', () => {
+  it('names the dialog via aria-labelledby pointing at the header seat node', () => {
+    mount()
+    openPanel()
+    const dialog = screen.getByRole('dialog')
+    const titleId = dialog.getAttribute('aria-labelledby')!
+    expect(titleId).toBeTruthy()
+    const title = document.getElementById(titleId)!
+    expect(title.textContent).toBe('Settings Title')
+    expect(screen.getByRole('dialog', { name: 'Settings Title' })).toBeTruthy()
+  })
+
+  it('names the close button through the visually-hidden close seat text', () => {
+    mount()
+    openPanel()
+    const close = screen.getByRole('button', { name: 'Close' })
+    expect(close.hasAttribute('aria-label')).toBe(false)
+    expect(close.textContent).toContain('Close')
+  })
+})
+
+describe('SettingsPanel close paths', () => {
+  it('closes via the header button', () => {
+    mount()
+    openPanel()
+    fireEvent.click(screen.getByRole('button', { name: 'Close' }))
+    expect(screen.queryByRole('dialog')).toBeNull()
+  })
+
+  it('closes via a mask click', () => {
+    mount()
+    openPanel()
+    const dialog = screen.getByRole('dialog')
+    fireEvent.click(dialog.parentElement!.firstElementChild!)
+    expect(screen.queryByRole('dialog')).toBeNull()
+  })
+
+  it('closes via document-level Escape and unhooks the listener with the panel', () => {
+    mount()
+    openPanel()
+    fireEvent.keyDown(document, { key: 'Escape' })
+    expect(screen.queryByRole('dialog')).toBeNull()
+    // Ignored while closed (listener removed with the panel) and non-Escape
+    // keys are ignored while open.
+    fireEvent.keyDown(document, { key: 'Escape' })
+    openPanel()
+    fireEvent.keyDown(document, { key: 'Enter' })
+    expect(screen.getByRole('dialog')).toBeTruthy()
+  })
+
+  it('lands focus on the close button when the dialog opens', () => {
+    mount()
+    openPanel()
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Close' }))
+  })
+})
+
+describe('SettingsPanel navigation', () => {
+  it('projects rows, marks the first active, and renders only that section', () => {
+    mount()
+    openPanel()
+    expect(screen.getByRole('button', { name: 'General' }).getAttribute('aria-current')).toBe('true')
+    expect(screen.getByRole('button', { name: 'Models' }).getAttribute('aria-current')).toBeNull()
+    expect(screen.getByTestId('section-general')).toBeTruthy()
+  })
+
+  it('switches the rendered section on nav click', () => {
+    mount()
+    openPanel()
+    fireEvent.click(screen.getByRole('button', { name: 'Models' }))
+    expect(screen.getByRole('button', { name: 'Models' }).getAttribute('aria-current')).toBe('true')
+    expect(screen.getByTestId('section-models')).toBeTruthy()
+    expect(screen.queryByTestId('section-general')).toBeNull()
+  })
+
+  it('falls back to the first row when the active entry unregisters', () => {
+    const { bump } = mount()
+    openPanel()
+    fireEvent.click(screen.getByRole('button', { name: 'Models' }))
+    bump([{ id: 'general', order: 0, label: 'General' }])
+    expect(screen.queryByRole('button', { name: 'Models' })).toBeNull()
+    expect(screen.getByTestId('section-general')).toBeTruthy()
+  })
+
+  it('renders an empty content column when the ledger is empty', () => {
+    const { renderSlot } = mount({ rows: [] })
+    openPanel()
+    expect(screen.getByRole('dialog')).toBeTruthy()
+    const sectionCalls = renderSlot.mock.calls.filter(c => c[0] === 'settings.section')
+    expect(sectionCalls).toHaveLength(0)
+  })
+
+  it('drops the ledger subscription on unmount', () => {
+    const { view, listeners } = mount()
+    expect(listeners.size).toBe(1)
+    view.unmount()
+    expect(listeners.size).toBe(0)
+  })
+})

packages/client/ui-settings/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-sidebar"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/client/ui-settings/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-settings', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/client/ui-sidebar/README.md

@@ -4,7 +4,9 @@ Sidebar plugin: real Host Workspaces in stable Host order, each containing its `
 
 New Session starts the runtime's page-local frontend Session Intent; a real Workspace's "+" starts one targeted to that Workspace. The Workspace header "+" opens ui-workspace's shared picker, whose selection also targets a frontend Session. A Workspace Intent does not appear in the sidebar.
 
-`SidebarRootComponentProps` composes the layout owner share, the global `useSessions` and `useWorkspaces` hooks, the declared `sidebar.workspace` child slot, and injected `startSession`, `open`, and sidebar-toggle callbacks. There is no plugin store: `deriveGroups` consumes object-layer snapshots and component-local expansion/search state.
+`SidebarRootComponentProps` composes the layout owner share, the global `useSessions` and `useWorkspaces` hooks, the declared `sidebar.workspace` and `sidebar.settings` child slots, and injected `startSession`, `open`, and sidebar-toggle callbacks. There is no plugin store: `deriveGroups` consumes object-layer snapshots and component-local expansion/search state.
+
+The foot is the `sidebar.settings` seat: the sidebar renders only the bottom-pinned layout slot and shares its column state (`wide`); ui-settings registers the trigger row and settings panel there.
 
 The `/client` export surface is the plugin body (`apply`/`inject`) plus the contract types only — SidebarRoot, the row components, and the tree derivation are internal (the slot registration closes over them; tests import src paths directly).
 

packages/client/ui-sidebar/src/client/Rows.tsx

@@ -1,143 +0,0 @@
-/**
- * Sidebar tree row components (figma Cell set 14:3080): pure presentational —
- * all data and callbacks arrive via props. Hover swaps (folder->chevron,
- * time->ellipsis, action buttons) are CSS-only.
- */
-import clsx from 'clsx'
-import {
-  IconFolderClose16, IconFolderOpen16, IconPlusOutline16,
-  IconTriangleRightFill14, StateDot,
-} from '@deepseek-ai/dsh-client-ui-primitives'
-import type { GroupNode, SessionNode } from './tree.ts'
-import { formatRelativeTime } from './tree.ts'
-import css from './Rows.module.css'
-
-/** Indent step per tree level: one 16px slot (figma session cell). */
-const INDENT_STEP = 16
-
-/**
- * Project (workspace) header row: 54px, folder + title + session count;
- * hover reveals the chevron and create button. `containsCurrent` arrives on
- * the node (derivation fact, no renderer scan).
- * @param props.group - derived group node.
- * @param props.onToggle - expand/collapse the group.
- * @param props.onCreate - start a frontend Session inside this Workspace.
- * @returns the row element.
- */
-export function ProjectRowItem({ group, onToggle, onCreate }: {
-  group: GroupNode
-  onToggle: () => void
-  onCreate: () => void
-}) {
-  const row = group
-  const active = group.expanded && group.containsCurrent
-  const count = `${row.sessionCount} ${row.sessionCount === 1 ? 'session' : 'sessions'}`
-  return (
-    <div className={css.projectRow} role="treeitem" aria-expanded={row.expanded} onClick={onToggle}>
-      <span className={clsx(css.slot, css.folder, active && css.folderActive)}>
-        {row.expanded ? <IconFolderOpen16 /> : <IconFolderClose16 />}
-      </span>
-      <span className={clsx(css.slot, css.chevron)}>
-        <IconTriangleRightFill14 className={clsx(css.arrow, row.expanded && css.arrowOpen)} />
-      </span>
-      <span className={css.projectText}>
-        <span className={css.title}>{row.label}</span>
-        <span className={css.meta}>{count}</span>
-      </span>
-      <span className={css.rowActions}>
-        <button
-          type="button"
-          className={css.iconButton}
-          aria-label={`New session in ${row.label}`}
-          onClick={(e) => { e.stopPropagation(); onCreate() }}
-        >
-          <IconPlusOutline16 />
-        </button>
-      </span>
-    </div>
-  )
-}
-
-/**
- * The selected "New session" row for a frontend Session Intent targeted to a
- * real Workspace. The row disappears when the Intent is replaced or connects.
- * @returns the placeholder row element.
- */
-export function IntentRowItem() {
-  return (
-    <div className={clsx(css.sessionRow, css.selected)} role="treeitem" aria-selected style={{ paddingLeft: 8 }}>
-      <span className={css.slot} />
-      <span className={css.slot} />
-      <span className={css.title}>New session</span>
-    </div>
-  )
-}
-
-/**
- * One session subtree: the node's own 34px row (indent by depth, expand
- * twist when it has children, running dot, relative time) plus its visible
- * children, recursively — the component tree mirrors the derived tree.
- * @param props.node - derived session node.
- * @param props.depth - 0 = directly under the group header.
- * @param props.currentId - selected session id (row highlight).
- * @param props.now - epoch ms for relative-time formatting.
- * @param props.onOpen - open a session by id.
- * @param props.onToggle - unfold/fold a subtree by id.
- * @returns the node's row followed by its children.
- */
-export function SessionNodeItem({ node, depth, currentId, now, onOpen, onToggle }: {
-  node: SessionNode
-  depth: number
-  currentId: string | undefined
-  now: number
-  onOpen: (id: SessionNode['id']) => void
-  onToggle: (id: SessionNode['id']) => void
-}) {
-  const row = node
-  const selected = node.id === currentId
-  // Rail (figma session cell: pad 8, twist slot 16, status slot 16, gap 4 to
-  // the title): both slots are always reserved so titles align whether or not
-  // the twist/dot is lit. Extra depth rides the left padding.
-  const ownRow = (
-    <div
-      className={clsx(css.sessionRow, selected && css.selected)}
-      role="treeitem"
-      aria-selected={selected}
-      {...(row.hasChildren ? { 'aria-expanded': row.expanded } : {})}
-      style={{ paddingLeft: 8 + depth * INDENT_STEP }}
-      onClick={() => { onOpen(node.id) }}
-    >
-      {row.hasChildren
-        ? (
-            <button
-              type="button"
-              className={css.twist}
-              aria-label={row.expanded ? 'Collapse' : 'Expand'}
-              onClick={(e) => { e.stopPropagation(); onToggle(node.id) }}
-            >
-              <IconTriangleRightFill14 className={clsx(css.arrow, row.expanded && css.arrowOpen)} />
-            </button>
-          )
-        : <span className={css.slot} />}
-      <span className={css.slot}>{row.running && <StateDot state="ongoing" />}</span>
-      <span className={css.title}>{row.title}</span>
-      <span className={css.time}>{formatRelativeTime(row.updatedAt, now)}</span>
-    </div>
-  )
-  return (
-    <>
-      {ownRow}
-      {node.children.map(child => (
-        <SessionNodeItem
-          key={child.id}
-          node={child}
-          depth={depth + 1}
-          currentId={currentId}
-          now={now}
-          onOpen={onOpen}
-          onToggle={onToggle}
-        />
-      ))}
-    </>
-  )
-}

packages/client/ui-sidebar/src/client/SidebarRoot.module.css

@@ -48,8 +48,7 @@
    refresh straight into the collapsed state renders statically. */
 .railIn .iconButton,
 .railIn .newSession,
-.railIn .searchButton,
-.railIn .foot {
+.railIn .footArea {
   animation: rail-in 150ms var(--ds-ease-in-out) 100ms backwards;
 }
 
@@ -184,133 +183,9 @@
   max-width: 0;
 }
 
-/* Section header: 36px, "WorkSpace" label + group-by / new-workspace buttons;
-   the right-anchored new-workspace button is the row's rail survivor. */
-.sectionHeader {
-  flex: none;
-  display: flex;
-  align-items: center;
-  justify-content: flex-end;
-  gap: 4px;
-  height: 36px;
-  padding-left: 12px;
-  margin-bottom: 4px;
-  box-sizing: border-box;
-  border-radius: 12px;
-  overflow: hidden;
-  color: var(--dsw-alias-label-tertiary);
-}
-
-.collapsed .sectionHeader {
-  height: 36px;
-  padding-left: 0;
-  margin-bottom: 12px;
-}
-
-.sectionLabel {
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  white-space: nowrap;
-  line-height: 20px;
-}
-
-/* Search input: 38px capsule (figma 133:7649); collapsed it renders as the
-   rail's search control. Upstream binds a dedicated design-system variable (light
-   #F1F3F5 / dark #1B1B1C) matching no shipped alias — a component token
-   pinned to the static scale mirrors it (ruled compliant: indirect via
-   custom property, upstream-variable equivalent). */
-.search {
-  --dsh-search-input-fill: var(--dsw-static-neutral-bluish-75);
-  flex: none;
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  height: 38px;
-  margin: 0 2px 12px; /* bottom: former listArea gap 4 + own 8 (spec padB12 to the first cell) */
-  padding: 0 14px;
-  box-sizing: border-box;
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 24px;
-  background: var(--dsh-search-input-fill);
-  color: var(--dsw-alias-label-caption);
-  overflow: hidden;
-}
-
-:global(body[data-ds-dark-theme]) .search {
-  --dsh-search-input-fill: var(--dsw-static-neutral-bluish-900);
-}
-
-.collapsed .search {
-  height: 36px;
-  padding: 0;
-  margin: 0 0 12px;
-  gap: 0;
-  border-color: transparent;
-  background: transparent;
-}
-
-/* The capsule's leading icon, upgraded to the rail's search control. While
-   expanded it is decorative: pointer-events off so clicks reach the label
-   (native input focus); collapsed it becomes the hit target. */
-.searchButton {
-  flex: none;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  border: none;
-  border-radius: 50%;
-  padding: 0;
-  background: transparent;
-  pointer-events: none;
-  color: inherit;
-}
-
-.collapsed .searchButton {
-  width: 36px;
-  height: 36px;
-  pointer-events: auto;
-  cursor: pointer;
-  color: var(--dsw-alias-label-primary);
-}
-
-.collapsed .searchButton:hover {
-  background: var(--dsw-alias-interactive-bg-hover);
-}
-
-.searchInput {
-  flex: 1;
-  min-width: 0;
-  border: none;
-  outline: none;
-  background: transparent;
-  font-size: 14px;
-  line-height: 20px;
-  color: var(--dsw-alias-label-primary);
-}
-
-.searchInput::placeholder {
-  color: var(--dsw-alias-label-tertiary);
-}
-
-.clearButton {
-  flex: none;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 28px;
-  height: 28px;
-  border: none;
-  border-radius: 50%;
-  padding: 0;
-  background: transparent;
-  cursor: pointer;
-  color: var(--dsw-alias-label-secondary);
-}
-
-/* Tree seat: always mounted so the foot never moves; the tree content inside
-   is wide-only and clips while the column squeezes. */
-.listArea {
+/* Region seat: always mounted so the foot never moves; the browser inside
+   handles its own wide/rail content. */
+.regionArea {
   flex: 1;
   min-height: 0;
   display: flex;
@@ -318,99 +193,11 @@
   overflow: hidden;
 }
 
-/* Relative for the bottom fade overlay. */
-.treeBody {
-  flex: 1;
-  min-height: 0;
-  display: flex;
-  flex-direction: column;
-  position: relative;
-}
-
-/* Bottom fade (figma 133:7666): 72px overlay pinned to the visible bottom,
-   transparent -> sidebar fill so it tracks the theme. */
-.fade {
-  position: absolute;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  height: 72px;
-  background: linear-gradient(to bottom, transparent, var(--dsw-specific-sidebar-fill));
-  pointer-events: none;
-}
-
-/* Tree list: the only scrolling region. Block, not a flex column: as flex
-   items the 54/34 rows would shrink under content overflow (scrollHeight
-   collapses onto clientHeight and wheel scrolling dies); block children keep
-   their design heights and the 4px rhythm rides margins instead of gap. */
-.list {
-  flex: 1;
-  min-height: 0;
-  overflow-y: auto;
-  padding-bottom: 12px;
-}
-
-/* One workspace section: header row + expanded session run. Rows inside
-   keep the former flat-list 4px gap as sibling margins; the inter-group
-   breathing room (figma 133:7661 batch separator, 20px after an expanded
-   run) rides the NEXT section's top margin so the last group adds none. */
-.groupSection > * + * {
-  margin-top: 4px;
-}
-
-.groupSection + .groupSection {
-  margin-top: 4px;
-}
-
-.groupSection:has([aria-expanded='true']) + .groupSection {
-  margin-top: 20px;
-}
-
-.empty {
-  padding: 16px 12px;
-  color: var(--dsw-alias-label-tertiary);
-  font-size: 13px;
-}
-
-/* Foot: settings entry (figma 133:7668, 49 hug): the former 18/10 vertical
-   margins fold into the row so the hover pill spans the full 49px. */
-.foot {
+/* Foot seat: a pure layout socket pinned under the region; the ui-settings
+   trigger row inside owns its own geometry (49px wide row / 36px rail
+   circle) and hover chrome. */
+.footArea {
   flex: none;
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  height: 49px;
-  margin: 8px 0 0; /* + 49px row + root padBottom 6 keeps the old 57px band */
-  padding: 0 2px 0 6px;
-  border-radius: 12px;
-  cursor: pointer;
-  overflow: hidden;
-  color: var(--dsw-alias-label-primary);
-}
-
-.foot:hover {
-  background: var(--dsw-alias-interactive-bg-hover);
-}
-
-/* Rail settings: the same 36x36 circle box as the other rail controls. */
-.collapsed .foot {
-  width: 36px;
-  height: 36px;
-  margin: 18px 0 10px;
-  justify-content: center;
-  gap: 0;
-  padding: 0;
-  border-radius: 50%;
-}
-
-.footLabel {
-  max-width: 120px;
-  overflow: hidden;
-  white-space: nowrap;
-}
-
-.collapsed .footLabel {
-  max-width: 0;
 }
 
 @media (prefers-reduced-motion: reduce) {
@@ -418,8 +205,7 @@
   .fading > *,
   .railIn .iconButton,
   .railIn .newSession,
-  .railIn .searchButton,
-  .railIn .foot {
+  .railIn .footArea {
     transition: none;
     animation: none;
   }

packages/client/ui-sidebar/src/client/SidebarRoot.tsx

@@ -1,170 +1,39 @@
 /**
- * Collapse is a slide plus crossfade: content freezes at its expanded
- * width (inline style) and fades out in place while the sliding column
- * (AppFrame grid tracks) clips it — nothing reflows mid-slide. At settle
- * the wide-only content (brand, labels, input, tree) unmounts, dropping
- * the sessions subscription, and the control rows snap to the 56px rail
- * (one icon each, same top-down order) fading in as the slide ends. Rail
- * search expands and focuses the search box.
+ * Sidebar shell: column geometry only. Collapse is a slide plus crossfade:
+ * content freezes at its expanded width (inline style) and fades out in place
+ * while the sliding column (AppFrame grid tracks) clips it — nothing reflows
+ * mid-slide. At settle the wide-only content unmounts and the control rows
+ * snap to the 56px rail (one icon each, same top-down order) fading in as the
+ * slide ends. The workspace/session browsing region between the New Session
+ * button and the foot is the `sidebar.workspaces` registrant's, and the foot
+ * is the `sidebar.settings` registrant's; the shell hands them the wide flag
+ * (plus an expand request callback for the browser).
  */
-import { useEffect, useMemo, useRef, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import clsx from 'clsx'
 import {
   BrandWordmark, FishLogo,
-  IconCloseFill14, IconNewChatOutline16, IconPanelLeftOutline16, IconPersonalizationOutline16,
-  IconProjectAddOutline16, IconSearchOutline16, IconSettingsOutline14,
-  Menu, Tooltip,
+  IconNewChatOutline16, IconPanelLeftOutline16,
+  Tooltip,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { WorkspaceView } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SidebarRootComponentProps } from './contract/slots.ts'
-import { deriveGroups, UNGROUPED_KEY } from './tree.ts'
-import { IntentRowItem, ProjectRowItem, SessionNodeItem } from './Rows.tsx'
 import css from './SidebarRoot.module.css'
 
 /** Wide-content unmount delay; matches the 150ms wide-content fade-out. */
 const COLLAPSE_SETTLE_MS = 150
 
-/** Column slide length (--ds-transition-duration-slow): rail-search focus waits it out — focus() forces a synchronous layout and would jank the slide. */
-const EXPAND_SLIDE_MS = 300
-
-const GROUP_BY_ITEMS = [
-  { id: 'workspace', label: 'Workspace' },
-  // Only workspace grouping is implemented.
-  { id: 'update', label: 'Update', disabled: true },
-  { id: 'status', label: 'Status', disabled: true },
-]
-
-/** Immutable membership toggle for the local expansion arrays. */
-function toggled(list: readonly string[], key: string): string[] {
-  return list.includes(key) ? list.filter((k) => k !== key) : [...list, key]
-}
-
-/** Group-by strategy menu; own open state so it resets with the wide chrome. */
-function GroupByMenu() {
-  const [open, setOpen] = useState(false)
-  return (
-    <Menu
-      open={open}
-      onClose={() => { setOpen(false) }}
-      items={GROUP_BY_ITEMS}
-      selectedId="workspace"
-      onSelect={() => { setOpen(false) }}
-      align="end"
-      anchor={(
-        <button
-          type="button"
-          className={clsx(css.iconButton, css.wide)}
-          aria-label="Group by"
-          onClick={() => { setOpen((v) => !v) }}
-        >
-          <IconPersonalizationOutline16 />
-        </button>
-      )}
-    />
-  )
-}
-
-type SessionTreeProps = Pick<
-  SidebarRootComponentProps,
-  'useSessions' | 'startSession' | 'open'
-> & {
-  workspaces: readonly WorkspaceView[]
-  /** Live search filter owned by the root (the query outlives the tree). */
-  query: string
-}
-
-/** The scrolling session tree; unmounting at collapse settle drops the sessions subscription and expansion state. */
-function SessionTree({ useSessions, startSession, open, workspaces, query }: SessionTreeProps) {
-  const list = useSessions((s) => s)
-  const current = list.current
-  const [expandedProjects, setExpandedProjects] = useState<string[]>([])
-  const [expandedSessions, setExpandedSessions] = useState<string[]>([])
-  // Re-expand when publication moves the selected intent into a real Workspace.
-  const intent = list.intent
-  const intentWorkspaceId = intent?.target.kind === 'workspace'
-    ? intent.target.workspaceId
-    : undefined
-  const currentGroup = current === undefined
-    ? undefined
-    : intent?.sessionId === current
-      ? intentWorkspaceId
-      : (workspaces.find(w => w.sessionIds.includes(current))?.workspaceId as string | undefined)
-        ?? UNGROUPED_KEY
-  useEffect(() => {
-    if (current === undefined || currentGroup === undefined) return
-    setExpandedProjects((l) => (l.includes(currentGroup) ? l : [...l, currentGroup]))
-  }, [current, currentGroup])
-  const groups = useMemo(
-    () => deriveGroups(list, workspaces, { expandedProjects, expandedSessions, query }),
-    [list, workspaces, expandedProjects, expandedSessions, query],
-  )
-  const now = Date.now()
-
-  return (
-    <div className={clsx(css.treeBody, css.wide)}>
-      <div className={css.list} role="tree" aria-label="Sessions">
-        {groups.length === 0 && (
-          <div className={css.empty}>{query === '' ? 'No sessions yet' : 'No matches'}</div>
-        )}
-        {groups.map(group => (
-          // Group section: header row + expanded session subtree. The
-          // inter-group breathing room (former flat-list batch separator)
-          // is the section's own margin (SidebarRoot.module.css).
-          <div key={group.key} className={css.groupSection}>
-            <ProjectRowItem
-              group={group}
-              onToggle={() => { setExpandedProjects((l) => toggled(l, group.key)) }}
-              onCreate={() => {
-                if (group.workspaceId !== undefined) startSession(group.workspaceId)
-              }}
-            />
-            {group.intentHere && <IntentRowItem />}
-            {group.sessions.map(node => (
-              <SessionNodeItem
-                key={node.id}
-                node={node}
-                depth={0}
-                currentId={current}
-                now={now}
-                onOpen={open}
-                onToggle={(id) => { setExpandedSessions((l) => toggled(l, id)) }}
-              />
-            ))}
-          </div>
-        ))}
-      </div>
-      <span className={css.fade} />
-    </div>
-  )
-}
-
 /**
- * Render the sidebar column.
+ * Render the sidebar column shell.
  * @param props - composed slot props (runtime share + injected callbacks, contract/slots.ts).
  * @returns the sidebar element tree.
  */
 export function SidebarRoot({
   collapsed,
   width,
-  useSessions,
-  useWorkspaces,
   startSession,
-  open,
   toggleSidebar,
   renderSlot,
 }: SidebarRootComponentProps) {
-  const workspaces = useWorkspaces(state => state.items)
-  // The query outlives the tree and the input (both wide-only) so collapsing
-  // does not silently drop an in-progress filter.
-  const [query, setQuery] = useState('')
-  const searchInput = useRef<HTMLInputElement | null>(null)
-  // Section-header ＋ opens the workspace picker (same popover in wide and
-  // rail states; the hole sits beside the button and opens rightward).
-  const [wsPickerOpen, setWsPickerOpen] = useState(false)
-  // Placement anchor for the picker popover: the slot span renders elsewhere
-  // in the DOM, so the picker positions off this button's rect.
-  const wsPlusRef = useRef<HTMLButtonElement>(null)
-
   // Wide content stays mounted while the collapse animates (fading via
   // .collapsed .wide), unmounts at settle, and remounts right away on expand.
   const [settled, setSettled] = useState(collapsed)
@@ -186,19 +55,6 @@ export function SidebarRoot({
   const everWide = useRef(!collapsed)
   if (!collapsed) everWide.current = true
 
-  // Rail search = expand + land in the search box: the flag arms before the
-  // expand toggle; once expanded the input is mounted and takes focus.
-  const [searchOnExpand, setSearchOnExpand] = useState(false)
-  useEffect(() => {
-    if (!collapsed && searchOnExpand) {
-      const timer = window.setTimeout(() => {
-        searchInput.current?.focus({ preventScroll: true })
-        setSearchOnExpand(false)
-      }, EXPAND_SLIDE_MS)
-      return () => { window.clearTimeout(timer) }
-    }
-  }, [collapsed, searchOnExpand])
-
   return (
     <div
       className={clsx(css.root, !wide && css.collapsed, !wide && everWide.current && css.railIn, collapsed && wide && css.fading)}
@@ -238,85 +94,18 @@ export function SidebarRoot({
         </button>
       </Tooltip>
 
-      <div className={css.sectionHeader}>
-        {wide && <span className={clsx(css.sectionLabel, css.wide)}>Workspaces</span>}
-        {wide && <GroupByMenu />}
-        <Tooltip label="New Workspace" disabled={wide}>
-          <button
-            ref={wsPlusRef}
-            type="button"
-            className={css.iconButton}
-            aria-label="Create workspace"
-            onClick={() => { setWsPickerOpen(v => !v) }}
-          >
-            <IconProjectAddOutline16 size={wide ? 16 : 18} />
-          </button>
-        </Tooltip>
-        {/* Picker hole beside the ＋ (same site in wide and rail states). */}
-        {renderSlot('sidebar.workspace', {
-          open: wsPickerOpen,
-          anchorRef: wsPlusRef,
-          onPick: (workspaceId) => {
-            setWsPickerOpen(false)
-            startSession(workspaceId)
-          },
-          onClose: () => { setWsPickerOpen(false) },
+      {/* The browsing region fills the column between the controls and the
+          foot in both states; its rail icon column rides the same slot. */}
+      <div className={css.regionArea}>
+        {renderSlot('sidebar.workspaces', {
+          wide,
+          expandSidebar: () => { if (collapsed) toggleSidebar() },
         })}
       </div>
 
-      {/* Expanded: the row is a click-to-focus field (the leading icon is
-          decorative). Collapsed: the icon is the rail's search control. */}
-      <div className={css.search} onClick={() => { if (!collapsed) searchInput.current?.focus() }}>
-        <Tooltip label="Search" disabled={wide}>
-          <button
-            type="button"
-            className={css.searchButton}
-            aria-label="Search sessions"
-            tabIndex={collapsed ? 0 : -1}
-            onClick={() => { if (collapsed) { setSearchOnExpand(true); toggleSidebar() } }}
-          >
-            <IconSearchOutline16 size={wide ? 14 : 18} />
-          </button>
-        </Tooltip>
-        {wide && (
-          <input
-            ref={searchInput}
-            className={clsx(css.searchInput, css.wide)}
-            type="text"
-            placeholder="Search name, keywords..."
-            value={query}
-            onChange={(e) => { setQuery(e.target.value) }}
-          />
-        )}
-        {wide && query !== '' && (
-          <button
-            type="button"
-            className={clsx(css.clearButton, css.wide)}
-            aria-label="Clear search"
-            onClick={() => { setQuery('') }}
-          >
-            <IconCloseFill14 />
-          </button>
-        )}
-      </div>
-
-      {/* Always-mounted seat: its flex slot pins the foot to the bottom in
-          both states while the tree itself is wide-only. */}
-      <div className={css.listArea}>
-        {wide && (
-          <SessionTree
-            useSessions={useSessions}
-            workspaces={workspaces}
-            startSession={startSession}
-            open={open}
-            query={query}
-          />
-        )}
-      </div>
-
-      <div className={css.foot} role="button" tabIndex={0} aria-label="Settings">
-        <IconSettingsOutline14 size={wide ? 14 : 18} />
-        {wide && <span className={clsx(css.footLabel, css.wide)}>Settings</span>}
+      {/* Foot seat: ui-settings registers the trigger row + panel here. */}
+      <div className={css.footArea}>
+        {renderSlot('sidebar.settings', { wide })}
       </div>
     </div>
   )

packages/client/ui-sidebar/src/client/contract/slots.ts

@@ -1,69 +1,70 @@
 /**
  * Sidebar slot contract: the registrant-side props composition for the
- * layout-owned `sidebar` slot and the Workspace picker hole declared here.
- * The runtime share combines layout-owned page state and actions with the
- * global useSessions and useWorkspaces hooks; the injected share adds the
- * runtime navigation actions and sidebar toggle.
+ * layout-owned `sidebar` slot, plus the holes this shell declares. The shell
+ * owns column geometry (fold state machine, brand row, New Session);
+ * everything between the section header and the list bottom is the
+ * `sidebar.workspaces` registrant's (ui-workspace), and the foot is the
+ * `sidebar.settings` registrant's (ui-settings).
  */
-import type { RefObject } from 'react'
 import type { PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 // Type-only: pulls ui-layout's SlotMap merge (the 'sidebar' entry) into every
 // program that sees this contract, so PropsRuntime<'sidebar'> resolves.
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
-import type { SessionId, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface SlotMap {
     /**
-     * The workspace picker hole in the sidebar section header (anchored at
-     * the ＋ button). Declared by this package's 'sidebar' entry (declaring
-     * is claiming); ui-workspace registers the picker.
+     * The workspace/session browsing region: section header, search, the
+     * grouped/flat session list, and every workspace dialog. Declared by this
+     * package's 'sidebar' entry (declaring is claiming); ui-workspace
+     * registers the browser.
      */
-    'sidebar.workspace': { kind: 'single'; scope: 'root'; owner: SidebarWorkspaceOwnerProps }
+    'sidebar.workspaces': { kind: 'single'; scope: 'root'; owner: SidebarSectionOwnerProps }
+    /**
+     * The settings seat at the sidebar foot. Declared by this package's
+     * 'sidebar' entry; ui-settings registers its trigger row + modal panel.
+     * The sidebar passes only its column state — it holds no settings state.
+     */
+    'sidebar.settings': { kind: 'single'; scope: 'root'; owner: SidebarSettingsOwnerProps }
   }
 }
 
 /**
- * Owner share of the sidebar workspace hole: popover geometry plus the
- * sidebar's pick semantics. The picked Host Workspace is already real; the
- * callback starts a frontend Session Intent targeted to it.
+ * Owner share of the browser hole — the only facts crossing the shell/region
+ * seam. Business data and actions arrive through the region's own inject.
  */
-export interface SidebarWorkspaceOwnerProps {
-  /** Popover visibility (＋ button toggle state, host-local). */
-  open: boolean
-  /**
-   * The ＋ button element — the popover's placement anchor. The picker's
-   * slot span renders elsewhere in the DOM, so without this the menu
-   * positions off the zero-size placement span (order-dependent). Optional
-   * only until the host passes it; absent falls back to in-place placement.
-   */
-  anchorRef?: RefObject<HTMLElement>
-  /** Start a frontend Session in a selected or newly created real Workspace. */
-  onPick: (workspaceId: WorkspaceId) => void
-  /** Close the popover (outside click / Escape / post-pick). */
-  onClose: () => void
+export interface SidebarSectionOwnerProps {
+  /** Shell fold-state output: wide renders the full browser, rail the icon column. */
+  wide: boolean
+  /** Rail icons request expansion; the browser rides the wide flip for focus. */
+  expandSidebar: () => void
+}
+
+/**
+ * Owner share of the sidebar settings seat: the column display state the
+ * occupant's trigger row must render against (wide row vs rail icon).
+ */
+export interface SidebarSettingsOwnerProps {
+  /** Whether the sidebar renders wide content (false = 56px rail). */
+  wide: boolean
 }
 
 /**
  * Registrant-private injected share (arrives via the register inject
- * factory). Host Workspace and Session data use the global framework hooks;
- * navigation and panel actions are plain callbacks, and viewing state remains
- * component-local. A type alias supplies the implicit index signature required
- * by the registry.
+ * factory). The shell keeps only its own controls: starting a Session from
+ * the New Session button and toggling the column.
  */
 export type SidebarRootInjected = {
   /** Start or replace the current frontend Session Intent. */
   startSession: (workspaceId?: WorkspaceId, prompt?: string) => void
-  /** Open a real Session. */
-  open: (sessionId: SessionId) => void
   /** Toggle the sidebar column through the layout service. */
   toggleSidebar: () => void
 }
 
 /**
- * Full component props: layout owner state/actions plus global useSessions
- * and useWorkspaces, the declared Workspace picker render share, and this
- * package's injected callback. No store is registered.
+ * Full component props: layout owner state/actions plus the declared holes'
+ * render shares and this package's injected callbacks. No store is registered.
  */
 export type SidebarRootComponentProps =
-  PropsRuntime<'sidebar'> & PropsRenderSlots<'sidebar.workspace'> & SidebarRootInjected
+  PropsRuntime<'sidebar'> & PropsRenderSlots<'sidebar.workspaces' | 'sidebar.settings'> & SidebarRootInjected

packages/client/ui-sidebar/src/client/index.ts

@@ -1,28 +1,31 @@
-/** Registers the sidebar UI into the layout-owned slot. */
+/** Registers the sidebar shell into the layout-owned slot. */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SidebarRootInjected } from './contract/slots.ts'
 import { SidebarRoot } from './SidebarRoot.tsx'
 
-export type { SidebarRootComponentProps, SidebarRootInjected, SidebarWorkspaceOwnerProps } from './contract/slots.ts'
+export type { SidebarRootComponentProps, SidebarRootInjected, SidebarSectionOwnerProps, SidebarSettingsOwnerProps } from './contract/slots.ts'
 
 /** Services required by the sidebar plugin. */
-export const inject = ['slots', 'layout', 'sessions', 'workspaces']
+export const inject = ['slots', 'layout', 'workspaces']
 
-/** Registers the sidebar component and its service callbacks.
+/** Registers the sidebar shell and its service callbacks.
  * @param ctx - Client root context.
  */
 export function apply(ctx: ClientContext): void {
   const injectProps = (): SidebarRootInjected => ({
     startSession: (workspaceId, prompt) => { ctx.workspaces.startSession(workspaceId, prompt) },
-    open: (sessionId) => { ctx.sessions.open(sessionId) },
     toggleSidebar: () => { ctx.layout.toggleSidebar() },
   })
   ctx.effect(
     () => ctx.slots.register({
       name: 'sidebar',
-      // SidebarRoot owns this picker site; ui-workspace registers the shared
-      // picker that selects a Host Workspace for a frontend Session Intent.
-      children: { 'sidebar.workspace': { kind: 'single', scope: 'root' } },
+      // The shell owns geometry; ui-workspace registers the whole browsing
+      // region (header, search, session list, workspace dialogs), ui-settings
+      // registers the foot trigger + settings panel.
+      children: {
+        'sidebar.workspaces': { kind: 'single', scope: 'root' },
+        'sidebar.settings': { kind: 'single', scope: 'root' },
+      },
       inject: injectProps,
     }, SidebarRoot),
     'ui-sidebar: slot registration',

packages/client/ui-sidebar/tests/apply.spec.tsx

@@ -1,4 +1,4 @@
-/** Sidebar slot registration and its plain runtime/layout callbacks. */
+/** Sidebar shell slot registration and its plain runtime/layout callbacks. */
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
@@ -9,10 +9,8 @@ async function bench(declare = true) {
   const ctx = new Context()
   await ctx.plugin(SlotsService).await()
   const layout = { toggleSidebar: vi.fn() }
-  const sessions = { open: vi.fn() }
   const workspaces = { startSession: vi.fn() }
   ctx.provide('layout', layout)
-  ctx.provide('sessions', sessions as never)
   ctx.provide('workspaces', workspaces as never)
   const slots = ctx.get('slots') as SlotsService
   if (declare) {
@@ -21,25 +19,23 @@ async function bench(declare = true) {
       () => null,
     )
   }
-  return { ctx, slots, layout, sessions, workspaces }
+  return { ctx, slots, layout, workspaces }
 }
 
 describe('ui-sidebar apply', () => {
   it('declares only the services it uses', () => {
-    expect(inject).toEqual(['slots', 'layout', 'sessions', 'workspaces'])
+    expect(inject).toEqual(['slots', 'layout', 'workspaces'])
   })
 
-  it('registers the sidebar and declares its Workspace picker hole', async () => {
+  it('registers the shell and declares the browsing-region hole', async () => {
     const b = await bench()
     await b.ctx.plugin({ inject: [...inject], apply }).await()
     expect(b.slots.entries('sidebar')).toHaveLength(1)
-    expect(b.slots.spec('sidebar.workspace')).toEqual({ kind: 'single', scope: 'root' })
+    expect(b.slots.spec('sidebar.workspaces')).toEqual({ kind: 'single', scope: 'root' })
     const injected = (b.slots.entries('sidebar')[0]!.inject as () => SidebarRootInjected)()
-    expect(Object.keys(injected)).toEqual(['startSession', 'open', 'toggleSidebar'])
+    expect(Object.keys(injected)).toEqual(['startSession', 'toggleSidebar'])
     injected.startSession('workspace' as never, 'prompt')
     expect(b.workspaces.startSession).toHaveBeenCalledWith('workspace', 'prompt')
-    injected.open('session' as never)
-    expect(b.sessions.open).toHaveBeenCalledWith('session')
     injected.toggleSidebar()
     expect(b.layout.toggleSidebar).toHaveBeenCalledOnce()
   })
@@ -55,6 +51,6 @@ describe('ui-sidebar apply', () => {
     await fiber.await()
     await fiber.dispose()
     expect(b.slots.entries('sidebar')).toHaveLength(0)
-    expect(b.slots.spec('sidebar.workspace')).toBeUndefined()
+    expect(b.slots.spec('sidebar.workspaces')).toBeUndefined()
   })
 })