Merge branch 'code-mode-ui/shiki' into code-mode-ui/trajectory-spans

2026-07-26 21:52:41 +08:00
parent 0f3f8b3def 426da32217
commit 430f6441c8
965 changed files with 23842 additions and 4514 deletions
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 80228a180faba0c556ff720e999b29b5bb1635b6
+README.zh.md: f4b857886bfafa891ceb1bd6b79b27e1fb725819
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-client-connection

+English | [中文](README.zh.md)
+
 Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. Contract: api-contracts v3 §3.

 ## Keyless fixture
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-connection
+
+[English](README.md) | 中文
+
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。契约：api-contracts v3 §3。
+
+## 无密钥 fixture
+
+任何 `fixture` 查询参数都会选择内存载体。`fixture=empty` 启动时不含 Workspace 或 Session；`fixturePrompt=reject` 在接受前拒绝提示词；`fixtureAttach=fail` 发布 Session 但拒绝将其附加到 Workspace；`fixtureSessionCreate=drop-response` 在丢弃创建响应前发布 Session 并为其发出帧；`fixtureFrames=workspace-first` 则反转默认的 Session 优先创建帧顺序。按名称／路径创建 Workspace 以及由调用方预先分配 SessionId，均具有足够的确定性，组装后的 Web 测试可以据此协调列表与帧的到达。
+
+## 模型体验
+
+无。协议消费层只在浏览器与主机之间搬运已经组合好的消息；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **history 的隐式恢复存在争议**：在未附加的会话上打开 history，会在主机侧拉起 agent；纯持久化读取的替代方案记录在 rt-core 协调账本中，P-I 不作改变。该包的消费方会在首次打开时感受到这段延迟。
+- **计划移除 `ToolEventView`／`ToolCallView`／`ToolResultView` 的重新导出**：当 toolview 迁移删除主机 `viewFor` 行时，它们会一并移除（呈现属于客户端）；在此之前，fixture 保留一份局部 `viewFor` 镜像。
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -684,6 +684,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) {
@@ -800,6 +853,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)
    }
  }

--- a/packages/client/connection/tests/fake-api.ts
+++ b/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). */
--- a/packages/client/connection/tests/fixture.spec.ts
+++ b/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 () => {
--- a/packages/client/hmr/README.i18n.yaml
+++ b/packages/client/hmr/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 2b2f63c25cbf3a46babef78a4dfb52f859156887
+README.zh.md: 6d94ca4a5e91f390e58575aa4ddf64fc18a509de
--- a/packages/client/hmr/README.md
+++ b/packages/client/hmr/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-client-hmr

+English | [中文](README.zh.md)
+
 Hot reload for fetch-arrival client plugins. A static-arrival entry composed only into `--dev` graphs (`dsh web --dev`); production graphs omit the row, so the shell-bundled code stays inert.

 The browser half subscribes to the system SSE channel (`GET /plugins/events`) and reloads one plugin per `rebuilt` frame, serialized through a queue (the bundle handoff slot is single). The sequence per frame — `prefetch` (fetch the new bundle before touching anything), `invalidate`, `registry.delete` (before the fiber: a bare fiber dispose trips the vendored Loader's self-dispose branch, which would mark the entry disabled), drain the old fiber, delete `entry.fiber`, remove owned `<style data-plugin>` tags, `entry.refresh()` re-imports and remounts, `fiber.await()` rethrows startup failures loud. Dependents reload through cordis itself: a fiber's activation epoch strings its service providers' uids, so replacing a provider's fiber cascades every dependent with zero client-side graph analysis. The node half detects rebuilds with one interval that stat-polls each graph bundle from a synchronous baseline, immediately re-hashes after adding a row, retains missing rows as dirty, and broadcasts only real rev changes; any tsdown watch process producing the bundle therefore triggers HMR with no builder→host channel.
--- a/packages/client/hmr/README.zh.md
+++ b/packages/client/hmr/README.zh.md
@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-client-hmr
+
+[English](README.md) | 中文
+
+为通过 fetch 到达的客户端插件提供热重载。该静态到达配置项只组合进 `--dev` 图（`dsh web --dev`）；生产图省略此行，因此外壳打包的代码保持不活动。
+
+浏览器侧订阅系统 SSE 通道（`GET /plugins/events`），每个 `rebuilt` 帧重载一个插件，并通过队列串行执行（组合包交接 slot 只能容纳一个）。每帧的顺序是：`prefetch`（在触碰任何内容前抓取新组合包）、`invalidate`、`registry.delete`（在 fiber 之前执行：只释放 fiber 会触发 vendored Loader 的 self-dispose 分支，把配置项标为禁用）、排空旧 fiber、删除 `entry.fiber`、移除自身拥有的 `<style data-plugin>` 标签、通过 `entry.refresh()` 重新导入并挂载、以 `fiber.await()` 将启动失败高声重新抛出。依赖方由 cordis 自身重载：fiber 的激活 epoch 会串联其服务提供方的 uid，因此替换提供方 fiber 会级联所有依赖方，无需客户端图分析。node 侧使用一个 interval 检测重建：从同步基线开始 stat-poll 每个图组合包；新增一行后立即重新计算 hash；缺失行保持 dirty；只广播真实 rev 变更。因此，任何生成组合包的 tsdown watch 进程都能触发 HMR，无需 builder→host 通道。
+
+## 模型体验
+
+无。重载驱动器属于浏览器侧机制；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **重载有意保持粗粒度**：会创建全新的 fiber 和组件；重载插件中的 React 状态会丢失，数据层（connection/runtime fiber、Session 对象）不受影响。react-refresh 级状态保留与「重新执行组合包会重新运行 factory」冲突，因此有意排除。
+- **失败时不回滚**：失败的重载会使配置项处于 FAILED 状态，并在 loader 状态投影中高声报告；自动恢复先前组合包会等到实际需要出现后再实现。
+- **重建帧不会刷新图 rev**：陈旧 rev 无害（组合包端点以 no-cache 提供内容）；rev 刷新会随重新连接握手机制落地。
--- a/packages/client/i18n/README.md
+++ b/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.
--- a/packages/client/i18n/src/client/index.ts
+++ b/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)
-}
--- a/packages/client/i18n/tests/i18n.spec.ts
+++ b/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)
-  })
-})
--- a/packages/client/i18n/tests/invariant.spec.ts
+++ b/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')
-  })
-})
--- a/packages/client/i18n/tsdown.config.ts
+++ b/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'])
--- a/packages/client/locale/README.i18n.yaml
+++ b/packages/client/locale/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 9015af2b44a33771b06863ace139fe97695df616
+README.zh.md: 6b129bcabbef5b5a00c5073ebc9142a0e406ddba
--- a/packages/client/locale/README.md
+++ b/packages/client/locale/README.md
@@ -0,0 +1,18 @@
+# @deepseek-ai/dsh-client-locale
+
+English | [中文](README.zh.md)
+
+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.
--- a/packages/client/locale/README.zh.md
+++ b/packages/client/locale/README.zh.md
@@ -0,0 +1,18 @@
+# @deepseek-ai/dsh-client-locale
+
+[English](README.md) | 中文
+
+locale 插件：LocaleService 包含浏览器 locale 偏好（`zh`／`en`，以 `dsh.locale` 为键持久化；提供 getter／setter，并生成 `locale/change` 快照），以及 ns×locale 字典注册表（`bind(ns)`→t 的函数标识稳定；查找链为 active → zh → key）。
+
+## 模型体验
+
+无。locale 注册表为浏览器 UI 文案提供服务；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **只有设置界面完成翻译**：其他页面仍保留内联文案；将全仓文案提取到字典的工作暂缓。
+- **切换 locale 只重新渲染已订阅的消费方**：未接入 `locale/change` 的分区会保留已渲染文本，直到重新挂载。
--- a/packages/client/locale/package.json
+++ b/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"
+  }
 }
--- a/packages/client/locale/src/client/LanguageRow.module.css
+++ b/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;
+}
--- a/packages/client/locale/src/client/LanguageRow.tsx
+++ b/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>
+  )
+}
--- a/packages/client/locale/src/client/index.ts
+++ b/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')
+}
--- a/packages/client/locale/src/client/settings-contract.ts
+++ b/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
+}
--- a/packages/client/locale/src/client/settings-store.ts
+++ b/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
+      },
+    },
+  })
+}
--- a/packages/client/locale/src/css-modules.d.ts
+++ b/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'
--- a/packages/client/locale/src/index.ts
+++ b/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 {}
--- a/packages/client/locale/src/invariant.ts
+++ b/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']

--- a/packages/client/locale/src/locales/en.ts
+++ b/packages/client/locale/src/locales/en.ts
--- a/packages/client/locale/src/locales/zh.ts
+++ b/packages/client/locale/src/locales/zh.ts
--- a/packages/client/locale/tests/apply.spec.ts
+++ b/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)
+  })
+})
--- a/packages/client/locale/tests/invariant.spec.ts
+++ b/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')
+  })
+})
--- a/packages/client/locale/tests/language-row.spec.tsx
+++ b/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()
+  })
+})
--- a/packages/client/locale/tests/locale.spec.ts
+++ b/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' },
+    ])
+  })
+})
--- a/packages/client/locale/tests/settings-store.spec.ts
+++ b/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)
+  })
+})
--- a/packages/client/locale/tsconfig.json
+++ b/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"
--- a/packages/client/locale/tsdown.config.ts
+++ b/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'])
--- a/packages/client/modules/README.i18n.yaml
+++ b/packages/client/modules/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: efba9e2eb0b148677fc7ac18bfad6333fb6f80da
+README.zh.md: 7d1aa8af08256c47c1ae65343e46c30e910128d0
--- a/packages/client/modules/README.md
+++ b/packages/client/modules/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-client-modules

+English | [中文](README.zh.md)
+
 Client module system: the browser peer of Node's internal ESM loader, built as a lazy CJS table. The web shell mounts the vendored cordis Loader for entry governance (fiber lifecycle, inject waiting, update/refresh) and injects this package's `ClientModuleLoader` as its `internal` seam — the vendored side's only consumption point is `EntryTree.import`, so replacing `internal` replaces exactly "how plugin code arrives" and nothing else.

 Lazy CJS model (web2): executing a plugin bundle only REGISTERS its factory (`window.__ModuleLoader__.load({id, factory})`); every module body side effect — CSS injection included — lives in the factory closure and runs at materialization (`factory(require)` → export surface, memoized in `loadCache`), not at script execution. A factory that requires another registered-but-unmaterialized module materializes it recursively, so load order needs no external sequencing; require cycles throw (factory-form CJS cannot deliver partial exports). `<id>/client` and the bare id name the same surface (a plugin bundle IS its package's client half).
--- a/packages/client/modules/README.zh.md
+++ b/packages/client/modules/README.zh.md
@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-modules
+
+[English](README.md) | 中文
+
+客户端模块系统：Node 内部 ESM loader 的浏览器端对等实现，以惰性 CJS 表构建。web 外壳挂载 vendored cordis Loader 来治理配置项（fiber 生命周期、inject 等待、update/refresh），并把该包的 `ClientModuleLoader` 作为其 `internal` seam 注入；vendored 一侧唯一的消费点是 `EntryTree.import`，因此替换 `internal` 恰好只会替换「插件代码如何到达」，不会改变其他内容。
+
+惰性 CJS 模型（web2）：执行插件组合包只会注册其 factory（`window.__ModuleLoader__.load({id, factory})`）；每个模块主体的副作用（包括 CSS 注入）都位于 factory 闭包中，在物化时运行（`factory(require)` → 导出表层，并在 `loadCache` 中记忆化），不会在脚本执行时运行。如果 factory 请求另一个已注册但尚未物化的模块，系统会递归物化它，因此加载顺序无需外部编排；require 循环会抛出异常（factory 形式的 CJS 无法交付部分导出）。`<id>/client` 与裸 id 指向同一表层（一个插件组合包就是其包的客户端侧）。
+
+解析分支顺序（`import(specifier)`）：平台种子词 → 外壳实例；记忆化记录 → 表层；外壳自身的静态注册表（`registerStatic`，app-shell）→ 模块；已注册 factory → 物化；图行（`window.__DSH_BOOT__`）→ 抓取 + 执行 + 物化；其他情况一律抛出异常。这是构建时组合包纯度门禁的运行时镜像。交给 factory 的同步 `require` 采用相同顺序，但不含抓取分支，并把观察到的边记录到模块记录中。`prefetch` 是第一阶段到达 hook（抓取 + 执行，只注册；并发调用共享一个进行中的 task）；`invalidate` 会丢弃 factory 与物化记录，使下一次 prefetch/import 重新抓取（HMR hook）。
+
+## 模型体验
+
+无。模块 loader 属于浏览器侧内核机制；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **有意采用扁平模块图**：每个组合包是一个模块节点，其边只指向表叶；接口（loadCache/edges/invalidate）按通用模块图塑形，因此可以改变 externalization 粒度而不更改接口。
+- **自身不记录卸载账目**：样式移除与 fiber 拆卸顺序属于 HMR 驱动器（`@deepseek-ai/dsh-client-hmr`）；loader 只逐记录清点自身拥有的样式标签 id。
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 7776a5c2cf1d0990c9c339c6e5fc66401f935810
+README.zh.md: 8a0b7394c07878b8de958eae43d11203c92b5827
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-client-runtime

+English | [中文](README.zh.md)
+
 Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects, list/scope/history state, and page-local Session Intent state; WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, page-local Workspace Intent state, default-target derivation, and the cross-object New Session flow. The runtime fans the shared Host stream into both managers. Contract: api-contracts v3 §4.

 ## Workspace and Session lists
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -0,0 +1,37 @@
+# @deepseek-ai/dsh-client-runtime
+
+[English](README.md) | 中文
+
+客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象、列表／scope／history 状态和页面局部 Session Intent 状态；WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、页面局部 Workspace Intent 状态、默认目标派生，以及跨对象 New Session 流程。运行时把共享 Host 流分发给两个 manager。契约：api-contracts v3 §4。
+
+## Workspace 与 Session 列表
+
+Workspace 和 Session 列表各自具有单调的 `pending` → `ready` 基线阶段，也有各自的刷新活动／错误状态。列表请求期间到达的增量帧会在其响应之上回放。第一次成功的基线建立 Host 顺序；后续刷新更新行和成员关系，但不改变已经显示的标识之间的相对顺序。Workspace 新近程度只在两条基线都 ready 后派生，且绝不改变 Workspace 列表顺序。
+
+SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 observable；web-react 创建 hook。Workspace 业务状态不会进入 `SessionListState` 或配置项 store。
+
+## Session 创建失败
+
+`SessionsService.create` 接受可选的、由调用方预先分配的 SessionId。失败时抛出 `SessionCreateError`：传输状态不确定后仍可取得 `requestedSessionId`；如果 Host 在附加失败前已经发布真实 Session，则会设置 `publishedSessionId`，此时 `workspace-attach-failed` 提供了证明。在 New Session 流程中，前端 Session 对象拥有其保留的提示词，并推动提示词完成附加与发送；部分发布的 Session 会保留同一对象和提示词，同时显示为 Ungrouped。
+
+## Code Mode 子调用索引
+
+`ConversationSnapshot.codeDispatches` 按父调用的 callId 和启动顺序，用原生调用块形状组织一个 `run_code` 调用的子调用：`tool/code-dispatch-start` 事件落成 `RunningToolCall` 形状（行组件从该形状推导运行中的转圈状态），其 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode` 形状，`callTime` 携带成对 start 事件的时间。start 落在回放窗口之外的完结事件则直接追加，`callTime: null`（耗时未知——绝不伪造零耗时）。live mux 帧与历史回放构建相同的索引；子调用永不进入 surface `nodes` 流；无关快照交换不会改变每个父调用对应的数组引用和映射引用，两者均保持 memo 稳定。
+
+## Session 标题投影
+
+`SessionManager` 独立于列表和 Session 实例到达情况，保留最近一次通过验证的 `session/title` 控制快照。seq 更新的事件会替换旧快照，标题时间戳计入列表新近程度；订阅基线会先丢弃 seq 超过其 `lastSeq` 的任何已保留标题，再接收可选的折叠标题。显式移除 Session 也会清除已保留标题。因此，面向客户端的 `SessionSummary.title` 只包含真实的持久标题；`displayTitle` 始终存在，并依次回退到 cwd basename 和 Session id。冷启动的持久会话会保持该回退值，直到打开或恢复会话，促使主机折叠并投影日志支持的标题。
+
+## 模型体验
+
+无。客户端运行时承载浏览器侧服务与 Session 对象层；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **`loader.unload` 是 stub（抛出 not-implemented）**：完整链路（fiber 释放 → 注册级联 → 样式移除）随 HMR 项目落地。
+- **scope 拆卸由阶段驱动，目前只能有一个占用者**：已 staged 的 Session 精确跟随 `list.current`（staging 就是打开信号：事件窗口打开 ⟺ Session 位于 stage）；在 staged 状态下被移除的 Session，其 scope 会冻结保留，直到 stage 转向其他 Session，而非直到真实观察者数量降为零。解析（`cell()`／`binding()`／`scope()`）只是纯寻址，可安全用于渲染。并发 pane 落地时，staged 状态可以扩展为多 pane 列表。
+- **插件组合包从该包执行值导入时必须使用 `/client` 子路径**：裸包名不在 loader external 表中，会内联第二个模块实例；其私有 scope-tag Symbol 永远无法匹配（空状态 P0 事故复盘）。
--- a/packages/client/runtime/src/client/sessions/manager.ts
+++ b/packages/client/runtime/src/client/sessions/manager.ts
@@ -162,7 +162,14 @@ export class SessionManager {
   * @param text - exact controlled-input value for the active frontend Session.
   */
  updateIntent(text: string): void {
-    this.getIntent()?.updatePendingPrompt(text)
+    const session = this.getIntent()
+    if (session === undefined) return
+    session.updatePendingPrompt(text)
+    // The intent watch defers via markDirty, but the hero composer reads this
+    // prompt from the LIST snapshot as a controlled value: it must flush in
+    // the same tick as onChange (see Notifier.notifyNow) or React rolls the
+    // textarea back and IME composition breaks.
+    this.notifier.notifyNow()
  }

  private discardIntent(): void {
--- a/packages/client/runtime/src/client/workspaces/manager.ts
+++ b/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]
--- a/packages/client/runtime/src/client/workspaces/service.ts
+++ b/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.
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/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). */
--- a/packages/client/runtime/tests/session-intents.spec.ts
+++ b/packages/client/runtime/tests/session-intents.spec.ts
@@ -60,6 +60,34 @@ describe('frontend Session and Workspace intents', () => {
    expect(workspaces.list.getSnapshot().intent).toBeUndefined()
  })

+  it('echoes updateIntent into the list snapshot in the same tick (controlled-input contract)', async () => {
+    const api = new FakeApiClient()
+    const { sessions, workspaces } = services(api)
+    await ready(api, workspaces, sessions, [workspace('target')])
+    let notified = 0
+    sessions.list.subscribe(() => { notified += 1 })
+    // IME composition drives change events that a controlled textarea must see
+    // reflected before the handler returns; a microtask-deferred echo makes
+    // React roll the DOM back and the composition commits partial keystrokes.
+    sessions.updateIntent('你')
+    expect(sessions.list.getSnapshot().intent?.prompt).toBe('你')
+    expect(notified).toBeGreaterThan(0)
+  })
+
+  it('ignores updateIntent with no active Intent', async () => {
+    const api = new FakeApiClient()
+    const { sessions, workspaces } = services(api)
+    await ready(api, workspaces, sessions, [workspace('only', [sid('s-real')])], [
+      { sessionId: sid('s-real'), updatedAt: 1, running: false },
+    ])
+    sessions.open(sid('s-real'))
+    expect(sessions.list.getSnapshot().intent).toBeUndefined()
+    let notified = 0
+    sessions.list.subscribe(() => { notified += 1 })
+    sessions.updateIntent('dropped')
+    expect(notified).toBe(0)
+  })
+
  it('materializes zero-state Workspace and Session intents and retains a rejected first prompt', async () => {
    const api = new FakeApiClient()
    const { sessions, workspaces } = services(api)
--- a/packages/client/tsdown.client.ts
+++ b/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
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: b9ec555f158722ea1f41e01c4b3f7131d3fe3467
+README.zh.md: b1e3c1f4331148ebf1c58b4bcd4869270bb44311
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-client-ui-conversation

+English | [中文](README.zh.md)
+
 Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, stats line, per-tool row slot with a bash sample registrant), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares).

 The no-session hero renders the frontend Session Intent from the Session list projection, including its frontend Workspace Intent when no real Workspace exists. It declares `conversation.empty.workspace`, where ui-workspace registers the same picker used by the sidebar. WorkspacesService starts the cross-object flow; each Workspace or Session object owns its own materialization. The Session keeps its identity across publication and retains any prompt that still needs connection or delivery; ConversationRoot reads that `pendingPrompt` from `useSession` and edits or retries it through the scoped ConversationService.
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -0,0 +1,33 @@
+# @deepseek-ai/dsh-client-ui-conversation
+
+[English](README.md) | 中文
+
+会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、统计行、逐工具行 slot 及一个 bash 示例注册方）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。
+
+无会话主视觉区会渲染来自 Session 列表投影的前端 Session Intent；没有真实 Workspace 时，还会包含其前端 Workspace Intent。它声明 `conversation.empty.workspace`，ui-workspace 会在此注册侧边栏所用的同一选择器。WorkspacesService 启动跨对象流程；每个 Workspace 或 Session 对象拥有自身的物化。Session 在发布期间保持身份，并保留任何仍需连接或交付的提示词；ConversationRoot 读取该 `pendingPrompt`，其来源是 `useSession`，再通过 scope 内的 ConversationService 编辑或重试。
+
+视图环本身就是 slot：会话注册声明 `'conversation.view'` 列表 slot（Session scope），并将其列在 `children` 表中；ConversationRoot 通过 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页从环账本的注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的环配置项；其他插件（ui-trajectory）通过普通的 `ctx.slots.register` 贡献标签页。先前包内的视图注册表（`registerView`／`ViewEntry`／`ConversationViewMap` 及 chrome 附加表）已退役，逐视图 chrome 则被拆入视图组件自身。
+
+通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和 `Write · <path>` 或 `Edit · <path>` 摘要，同时保留共享的行到详情交互。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行），details 面板则会根据选中的子调用 id 解析出其完整记录的参数与完整输出。
+
+工具行同样是 slot：独立工具环（`ToolViewRegistry`／`ctx.toolviews`／outlet）已经退役。聊天配置项声明键控的 `'conversation.chat.toolview'` 空位（Session scope；key 空间在运行时开放）；其渲染点逐行通过 `entryKey: toolName` 分发，并以 `GenericToolCard` 作为调用点 `fallback`。owner 载荷是统一的 `ToolRowOwnerProps`（`callId`／`toolName`／`block`／`openDetails`），`ToolRowProps` 则预先将其与 Session 标准工具包组合。注册方只是普通插件：`ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)`，以 `inject: ['slots', 'conversation']` 作为加载顺序 seam（apply 在聊天注册后挂载 ConversationService，因此服务存在即可保证 slot 已声明）；Session 区分在组件内部完成（`useSessions` 读取 `parentId`，bash 示例是第三方姿态的范例）。Trajectory/waterfall 工具视图 slot 共享此形状，并随各自的渲染点落地（RendersCheck 会拒绝没有任何渲染方的声明）。
+
+逐 Session UI 状态（选择、普通编辑器草稿、活跃视图）位于已声明的聊天 store（`stores.ts` `createChatStore`）中：apply 构造一个 handle，并将其传给会话、聊天视图和详情注册，因此 Session slot 每个 Session 共享一个实例（选择由聊天视图写入、详情读取），框架拥有实例生命周期与草稿持久化。前端 Session Intent 来自 Session 列表投影；发布后，任何保留的提示词都来自该 Session 的会话快照。组件保持纯粹：框架标准工具包（Session scope 下的 `useSession`／`sessionId`，以及全局 `useSessions`／`useWorkspaces`）和 store 表层（`useStore`／`actions`）会从注册声明自动到达；inject factory 为运行时 Session 操作、发送／停止、标签页、详情和分页贡献普通数据与回调。
+
+`src/client/` 按未来的包拆分组织：`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明 + 组合后的 slot props，包括工具行契约、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/`（示例注册方）领域目录只导入 contract 文件，彼此绝不导入；`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件（骨架、聊天行）与 store factory 保持内部状态，只能通过 apply 的 slot 注册到达页面（测试通过 `./src/*` 子路径获取它们）。
+
+## 模型体验
+
+无。会话 UI 在浏览器中渲染会话历史与流；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **统计行没有耗时区段**：assistant `usage` 只携带 token 计数；耗时需要主机数据源。
+- **详情面板是最小形态**：以原始形式显示已选择调用的参数／结果；Input/Output/Metadata 切换、Prev/Next 步进与 See-in-trajectory 深链接暂缓实现。
+- **assistant footer 扩展（IconActions 行、逐消息分页）是预留 slot**：设计中已有图稿，尚未实现。
+- **others 工具行的闪光图标是手绘近似版本**：无法在本地导出设计字形的矢量几何；等到存在精确导出后再将其提升到 ui-primitives。
+- **审批卡片只是只读占位符**：问题请求通过编辑器链回答（ui-question），Web 侧审批回答属于 P-II 审批项目。
--- a/packages/client/ui-conversation/package.json
+++ b/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"
    ],
--- a/packages/client/ui-conversation/tests/apply-inject.spec.tsx
+++ b/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
--- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx
+++ b/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
--- a/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
+++ b/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: {
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -27,7 +27,7 @@
      "path": "../ui-layout"
    },
    {
-      "path": "../i18n"
+      "path": "../locale"
    },
    {
      "path": "../../support/invariants"
--- a/packages/client/ui-layout/README.i18n.yaml
+++ b/packages/client/ui-layout/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 6aeda0e04bf690f5cc8a6d52eea95b1b2782a143
+README.zh.md: 9fbc2ed8392ae3ceba453517d9af5ef41f039d2d
--- a/packages/client/ui-layout/README.md
+++ b/packages/client/ui-layout/README.md
@@ -1,6 +1,8 @@
 # @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.
+English | [中文](README.zh.md)
+
+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.

--- a/packages/client/ui-layout/README.zh.md
+++ b/packages/client/ui-layout/README.zh.md
@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-client-ui-layout
+
+[English](README.md) | 中文
+
+外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏宽度固定（只会收缩详情栏，然后将其自动关闭）；关闭的侧边栏仍保留 56px 控制轨道，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 `document.body`（依据当前配色方案设置 `data-ds-dark-theme`，并将主题的别名 token 设为内联变量）。
+
+AppFrame 读取运行时 Session 投影：`baselinesReady` 选择加载状态，页面局部的 `SessionListState.intent` 选择空白编辑器，已连接 Session 则通过 `SessionProvider` 渲染。会话及空状态的 owner share 为空；每个注册方通过标准 hook 获取业务数据，并从自身的 inject 表层获取操作。侧边栏 owner share 只包含 `collapsed` 和 `width`；导航操作属于侧边栏自身注入的服务表层。
+
+`/client` 导出表层包含插件主体（`apply`／`inject`）、`LayoutService` 和四个 owner-share 接口。AppFrame、面板 store 与让步求解器仍属于包内部；测试通过 `/src` 导入内部实现。
+
+## 模型体验
+
+无。布局外壳管理浏览器查看状态；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **详情栏打开／宽度状态是全局状态**：它不会随会话变化（P-I 已裁定）；为逐会话键控升级预留了 slot。
+- **让步链自动关闭通过推导零宽度实现，不会改动持久化的打开标志**：窗口变宽时面板会自行恢复；消费方禁止把 `details.open` 当作实际渲染状态。
+- **挤压重排期间尚未实现滚动锚定**：与虚拟化列表项目一并暂缓。
--- a/packages/client/ui-layout/package.json
+++ b/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",
--- a/packages/client/ui-layout/src/client/index.ts
+++ b/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')
 }
--- a/packages/client/ui-layout/src/client/theme-presenter.ts
+++ b/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 = []
+  }
+}
--- a/packages/client/ui-layout/tests/apply.spec.ts
+++ b/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 })
--- a/packages/client/ui-layout/tests/theme-presenter.spec.ts
+++ b/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')
+  })
+})
--- a/packages/client/ui-layout/tsconfig.json
+++ b/packages/client/ui-layout/tsconfig.json
@@ -11,9 +11,15 @@
    {
      "path": "../../../vendor/cordis"
    },
+    {
+      "path": "../locale"
+    },
    {
      "path": "../ui-slots"
    },
+    {
+      "path": "../ui-theme"
+    },
    {
      "path": "../ui-primitives"
    },
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 13f51d5338affd65d0705cec6a3b4ef78a534f0f
+README.zh.md: 466505beb27c729246afe04e6378235b91d072cf
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -0,0 +1,17 @@
+# @deepseek-ai/dsh-client-ui-models
+
+English | [中文](README.zh.md)
+
+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.
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -0,0 +1,17 @@
+# @deepseek-ai/dsh-client-ui-models
+
+[English](README.md) | 中文
+
+模型设置分区插件：注册 `models` 导航项，使其进入 `settings.section`；内容栏有意留空，模型管理将在后续阶段实现。
+
+## 模型体验
+
+无。该分区渲染空白的浏览器 UI 内容栏；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **内容栏按设计留空**：提供方列表、编辑表单和激活流程均暂缓，待模型管理服务就绪后实现。
--- a/packages/client/ui-models/package.json
+++ b/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"
+  ]
+}
--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/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
+}
--- a/packages/client/ui-models/src/client/index.ts
+++ b/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')
+}
--- a/packages/client/ui-models/src/css-modules.d.ts
+++ b/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'
--- a/packages/client/ui-models/src/index.ts
+++ b/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 {}
--- a/packages/client/ui-models/src/invariant.ts
+++ b/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 */
--- a/packages/client/ui-models/tests/apply.spec.ts
+++ b/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()
+  })
+})
--- a/packages/client/ui-models/tests/invariant.spec.ts
+++ b/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()
+  })
+})
--- a/packages/client/ui-models/tsconfig.json
+++ b/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"
+    }
+  ]
+}
--- a/packages/client/ui-models/tsdown.config.ts
+++ b/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'])
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 4e2a22e77dc1611728477ea0a9d8c50dfc9f7f5d
+README.zh.md: 36253971281fd346f9b0ec4648c4b8824ed918a7
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-client-ui-primitives

+English | [中文](README.zh.md)
+
 Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, markdown family (MessageText/MarkdownText/JsonBlock). Contract: api-contracts v3 §8.

 ## Markdown rendering
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-client-ui-primitives
+
+[English](README.md) | 中文
+
+纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input，以及 markdown 家族（MessageText/MarkdownText/JsonBlock）。契约：api-contracts v3 §8。
+
+## Markdown 渲染
+
+`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并只渲染图片 alt 文本而不加载远程资源；`MessageText` 仍是用户创作内容使用的字面文本原语。
+
+## 模型体验
+
+无。该包在浏览器中渲染纯 React 原子组件；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **字形级图标是重新绘制的近似版本**：鱼形标志（以及 ui-conversation 持有的闪光图标）来自字体字形，而本地设计数据无法导出其矢量几何；在获得精确导出路径前，使用手工重建版本代替。
+- **Pill 与 Input 没有设计来源**：两个原子组件均自行定义；与其相似的侧边栏搜索字段和视图标签条由消费方组合，不是这些原子组件。
+- **StateDot 的 `Active` 变体是设计中的隐藏占位符**：尚未实现；已交付的四种状态（done/warning/ongoing/error）构成完整的 P-I 表层。
--- a/packages/client/ui-primitives/src/HoverCard.module.css
+++ b/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;
+}
--- a/packages/client/ui-primitives/src/HoverCard.tsx
+++ b/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>
+  )
+}
--- a/packages/client/ui-primitives/src/Menu.module.css
+++ b/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;
--- a/packages/client/ui-primitives/src/Menu.tsx
+++ b/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}
--- a/packages/client/ui-primitives/src/icons/index.tsx
+++ b/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>
+)
--- a/packages/client/ui-primitives/src/index.ts
+++ b/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'
--- a/packages/client/ui-primitives/tests/atoms.spec.tsx
+++ b/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(
--- a/packages/client/ui-primitives/tests/hover-card.spec.tsx
+++ b/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()
+  })
+})
--- a/packages/client/ui-primitives/tests/icons.spec.tsx
+++ b/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 => {
--- a/packages/client/ui-question/README.i18n.yaml
+++ b/packages/client/ui-question/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 28132d1d0643f5e8f658ab77de9017467da2d172
+README.zh.md: c70e77fc90eb5b226ceabd8a1e7cc7ca6c011c40
--- a/packages/client/ui-question/README.md
+++ b/packages/client/ui-question/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-client-ui-question

+English | [中文](README.zh.md)
+
 Web `ask_user_question` feature plugin. Its host half mounts `dsh-tool-ask-user` only when the Web feature is selected; its browser half registers the `question` entry in the conversation-owned `conversation.composer` keyed slot.

 The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. Single-select choices advance immediately, and Enter submits once every question is answered or skipped; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`.
--- a/packages/client/ui-question/README.zh.md
+++ b/packages/client/ui-question/README.zh.md
@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-ui-question
+
+[English](README.md) | 中文
+
+Web `ask_user_question` 功能插件。只有选择 Web 功能时，其主机侧才会挂载 `dsh-tool-ask-user`；浏览器侧会把 `question` 配置项注册到会话拥有的 `conversation.composer` 键控 slot 中。
+
+组件每次渲染一个问题，提供进度导航、单选和多选选项、由标签后缀派生的推荐徽标，以及自定义答案。单选选项会立即前进；所有问题均已回答或跳过后，Enter 会提交；IME 输入法组合期间按 Enter 只会确认输入候选，不会前进。组件为整个请求提交一批结构化答案：「跳过此问题」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 形状；关闭则以 `ASK_CANCELLED` 拒绝整个等待。
+
+选择状态只存在于以请求 rpcId 为 key 的组件本地。使用相同 id 回放时，只要组件仍挂载，就会保留草稿；主机发出的 `question/resolved` 则会移除编辑器。主机仍具有最终决定权：HTTP 交付成功不会在本地移除待处理状态。
+
+## 模型体验
+
+通过 `dsh-tool-ask-user` 间接影响；该包拥有模型可见的工具 schema 和结构化结果。
+
+#### KV Cache 影响
+
+不会直接失效；模型可见的工具调用与结果由 `dsh-tool-ask-user` 拥有。
+
+## 已知限制与暂缓事项
+
+- **未提交的草稿不持久**：重新连接再同步或完整刷新页面时，会恢复主机拥有且 rpcId 相同的待处理请求，但编辑器卸载会重置本地选项和自定义文本草稿。
+- **每次只有一个请求拥有编辑器**：后续待处理请求仍留在会话快照中，并在较早请求解决后显示。
--- a/packages/client/ui-settings-general/README.i18n.yaml
+++ b/packages/client/ui-settings-general/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: c392d745021c0fc6a752cf71dd0506a435106c50
+README.zh.md: 83ab81e01eae435a74b50fa363a4de203c483002
--- a/packages/client/ui-settings-general/README.md
+++ b/packages/client/ui-settings-general/README.md
@@ -0,0 +1,17 @@
+# @deepseek-ai/dsh-client-ui-settings-general
+
+English | [中文](README.zh.md)
+
+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.
--- a/packages/client/ui-settings-general/README.zh.md
+++ b/packages/client/ui-settings-general/README.zh.md
@@ -0,0 +1,17 @@
+# @deepseek-ai/dsh-client-ui-settings-general
+
+[English](README.md) | 中文
+
+设置界面文案插件：在设置界面注册所有不属于单一功能的内容，包括外壳的触发器、标题栏与关闭控件内容，「通用」分区（「权限」／「工具调用」骨架行和 `settings.general.item` slot 声明），以及 `settings` 字典。归具体功能所有的行（「语言」、「外观」）和分区（「模型」）仍由各自的功能包提供。
+
+## 模型体验
+
+无。该插件渲染浏览器设置 UI；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **「权限」与「工具调用」只是展示骨架**：对应的宿主服务和 RPC 方法尚不存在；这些控件已禁用，不会写入任何内容。一旦获得实际支撑，按照自注册原则，每一项都会移至拥有它的功能插件。
--- a/packages/client/ui-settings-general/package.json
+++ b/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"
+  ]
+}
--- a/packages/client/ui-settings-general/src/client/GeneralSection.module.css
+++ b/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);
+}
--- a/packages/client/ui-settings-general/src/client/GeneralSection.tsx
+++ b/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>
+  )
+}
--- a/packages/client/ui-settings-general/src/client/chrome.module.css
+++ b/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;
+}
--- a/packages/client/ui-settings-general/src/client/chrome.tsx
+++ b/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')}</>
+}
--- a/Show More
+++ b/Show More