wip

fix: docs

packages/client/ui-plan/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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 packages/client/ui-plan/README.md
-README.md: 1d22c057b439ff337bf9daadcdba96dd4cca4540
-README.zh.md: 183b8ef7776b60c1f0afa630e04627a474d40391
+README.md: 568539c19331cc268217ee2c28b928c38a68323c
+README.zh.md: 68e3092ad77267a779d21ba627ce2f19469ae05b

packages/client/ui-plan/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Plan-mode status chip, a pure browser surface plugin. The browser half occupies the conversation-declared `conversation.input.plan` single seat (to the right of the access-mode control); the node half is an empty apply (the roster row). Plan behavior itself — the `/plan` command, the boundary-or-idle-committed `plan/mode` state, the `plan` projection unit, and the policy section — is owned by [`@deepseek-ai/dsh-plan-mode`](../../plan/plan-mode/README.md), composed independently on the host roster.
 
-Plan mode is entered through the `/plan` command only; there is no UI control that turns it on. While the host-computed `plan` projection's effective target is plan mode (`pending ? !active : active` — a folded host value, not client optimism, so an arriving frame corrects the chip either way), the seat renders a read-only "Plan" chip whose hover × executes `/plan off` through `command.execute`; otherwise the seat stays empty — a host without plan-mode (or a Draft with no session) shows nothing. While plan mode is the effective target, the composer textarea's placeholder switches to the plan-task hint — "describe your task to generate plan", localized through ui-conversation's `command.hint` locale namespace and shared verbatim with the claimed `/plan` command hint (rendered by the composer from the same projection; owner-supplied placeholders win).
+Plan mode is entered through the `/plan` command only; there is no UI control that turns it on. While the host-computed `plan` projection's effective target is plan mode (`pending ? !active : active` — a folded host value, not client optimism, so an arriving frame corrects the chip either way), the seat renders a read-only "Plan" chip whose hover × executes `/plan off` through `command.execute`; otherwise the seat stays empty — a host without plan-mode (or a Draft with no session) shows nothing. While plan mode is the effective target, the composer textarea's placeholder switches to the plan-task hint — "describe your task to generate plan", localized through ui-conversation's `conversation` locale namespace (the `placeholder.plan` / `hint.plan` keys) and shared verbatim with the claimed `/plan` command hint (rendered by the composer from the same projection; owner-supplied placeholders win).
 
 The chip carries the accessible description "Plan mode on, press to turn off". Admission failures (`matched: false`, business errors, transport faults) surface as an inline error and the chip stays until the projection confirms the exit.
 

packages/client/ui-plan/README.zh.md

@@ -4,7 +4,7 @@
 
 Plan mode 状态徽章，纯浏览器 surface 插件。浏览器侧占据会话声明的 `conversation.input.plan` 单座（位于 access 模式控件右侧）；node 侧是空 apply（roster 行）。plan 行为本身——`/plan` 命令、边界或空闲即时提交的 `plan/mode` 状态、`plan` 投影单元与 policy 段——归 [`@deepseek-ai/dsh-plan-mode`](../../plan/plan-mode/README.md) 所有，由 host roster 独立组合。
 
-plan mode 只经 `/plan` 命令进入；UI 上没有打开它的控件。当 host 计算的 `plan` 投影有效目标为 plan mode 时（`pending ? !active : active`——折叠的 host 值而非客户端乐观态，帧到达即自动纠正），座位渲染一个只读 "Plan" chip，hover 出现的 × 经 `command.execute` 执行 `/plan off`；否则座位保持为空——未组合 plan-mode 的 host（或尚无会话的 Draft）不显示任何内容。plan mode 为有效目标期间，composer 文本框的 placeholder 切换为 plan 任务提示——"describe your task to generate plan"（中文「描述你的任务以生成计划」），经 ui-conversation 的 `command.hint` locale 命名空间本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（由 composer 从同一投影渲染；owner 提供的 placeholder 优先）。
+plan mode 只经 `/plan` 命令进入；UI 上没有打开它的控件。当 host 计算的 `plan` 投影有效目标为 plan mode 时（`pending ? !active : active`——折叠的 host 值而非客户端乐观态，帧到达即自动纠正），座位渲染一个只读 "Plan" chip，hover 出现的 × 经 `command.execute` 执行 `/plan off`；否则座位保持为空——未组合 plan-mode 的 host（或尚无会话的 Draft）不显示任何内容。plan mode 为有效目标期间，composer 文本框的 placeholder 切换为 plan 任务提示——"describe your task to generate plan"（中文「描述你的任务以生成计划」），经 ui-conversation 的 `conversation` locale 命名空间（`placeholder.plan` / `hint.plan` 键）本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（由 composer 从同一投影渲染；owner 提供的 placeholder 优先）。
 
 chip 携带无障碍描述 "Plan mode on, press to turn off"。准入失败（`matched: false`、业务错误、传输故障）以内联错误呈现，chip 保持显示直至投影确认退出。
 

packages/client/ui-plan/package.json

@@ -25,6 +25,7 @@
   "dshClient": {
     "inject": [
       "@deepseek-ai/dsh-client-connection",
+      "@deepseek-ai/dsh-client-locale",
       "@deepseek-ai/dsh-client-ui-conversation"
     ],
     "platform": "web"
@@ -36,6 +37,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-client-connection": "^0.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
@@ -46,7 +48,9 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-client-web-react": "workspace:^",

packages/client/ui-plan/src/client/PlanModeControl.tsx

@@ -1,14 +1,14 @@
 import { useEffect, useRef, useState } from 'react'
-import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 // Type-only: pulls the ui-conversation SlotMap merge (the input.plan seat and
 // its {locked} owner share).
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { PlanChipInjected } from './index.ts'
 import css from './PlanModeControl.module.css'
 
-/** Full plan-seat component props: runtime share (standard kit + locked owner prop) & injected share. */
+/** Full plan-seat component props: runtime share (standard kit + locked owner prop) & injected share & the locale seat. */
 export type PlanChipProps =
-  PropsRuntime<'conversation.input.plan'> & InjectFace<PlanChipInjected>
+  PropsRuntime<'conversation.input.plan'> & InjectFace<PlanChipInjected> & PropsLocale<'plan'>
 
 /**
  * Plan-mode toggle over the host-computed `plan` projection. The chip renders
@@ -17,7 +17,7 @@ export type PlanChipProps =
  * client optimism, so an arriving frame corrects it). Clicking executes
  * /plan or /plan off toward the opposite target.
  */
-export function PlanChip({ useProjection, locked, setPlanMode }: PlanChipProps) {
+export function PlanChip({ useProjection, locked, setPlanMode, t }: PlanChipProps) {
   const plan = useProjection('plan')
   const [busy, setBusy] = useState(false)
   const [error, setError] = useState<{ text: string; detail: string } | null>(null)
@@ -37,8 +37,9 @@ export function PlanChip({ useProjection, locked, setPlanMode }: PlanChipProps)
 
   const toggle = (): void => {
     // No busy/locked guard: both disable the button, so no click arrives.
+    // Failure copy stays English (error-surface policy: not localized).
     const on = !target
-    const failText = on ? '进入 plan mode 失败' : '退出 plan mode 失败'
+    const failText = on ? 'failed to enter plan mode' : 'failed to exit plan mode'
     setBusy(true)
     setError(null)
     void setPlanMode(on).then((failure) => {
@@ -58,13 +59,12 @@ export function PlanChip({ useProjection, locked, setPlanMode }: PlanChipProps)
         type="button"
         className={css.chip}
         aria-pressed={target}
-        aria-label={target ? 'Plan mode on, press to turn off' : 'Plan mode off, press to turn on'}
-        title={target
-          ? 'Plan mode on — click to turn off (/plan off)'
-          : 'Plan mode off — click to turn on (/plan)'}
+        aria-label={target ? t('chip.on.aria') : t('chip.off.aria')}
+        title={target ? t('chip.on.title') : t('chip.off.title')}
         disabled={locked || busy}
         onClick={toggle}
       >
+        {/* Design literal, not copy: the chip wordmark stays 'Plan on/off' in every locale. */}
         Plan { target ? 'on' : 'off' }
       </button>
       {error !== null && <span className={css.error} role="status" title={error.detail}>{error.text}</span>}

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

@@ -11,9 +11,24 @@ import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client
 import type { ClientContext, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 // Type-only: pulls the ui-conversation SlotMap merge (the input.plan seat).
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+// Type-only: pulls the locale plugin's Context merge (ctx.locale).
+import type {} from '@deepseek-ai/dsh-client-locale/client'
 // Type-only: pulls the `plan` SessionProjectionMap merge for useProjection.
 import type {} from '@deepseek-ai/dsh-plan-mode/client'
 import { PlanChip } from './PlanModeControl.tsx'
+import { en, zh, type PlanKey } from './locales.ts'
+
+export type { PlanKey } from './locales.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** The composer plan chip's copy. */
+    plan: PlanKey
+  }
+}
+
+/** Dictionary namespace owned by this plugin. */
+const NS = 'plan'
 
 /** Injected business face of the composer plan seat. */
 export interface PlanChipInjected {
@@ -26,25 +41,30 @@ export interface PlanChipInjected {
 }
 
 /**
- * Required services: the seat's slot registry, the transport, and the
- * conversation service whose presence guarantees the seat is declared.
+ * Required services: the seat's slot registry, the transport, the copy's
+ * locale registry, and the conversation service whose presence guarantees
+ * the seat is declared.
  */
-export const inject = ['slots', 'connection', 'conversation']
+export const inject = ['slots', 'connection', 'conversation', 'locale']
 
 /**
  * Client plugin body: register the plan chip over the command channel.
  * @param ctx - client root context.
  */
 export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-plan: dictionaries')
+
   ctx.effect(() => ctx.slots.register({
     name: 'conversation.input.plan',
+    locale: NS,
     inject: (sessionId: SessionId): PlanChipInjected => ({
+      // Failure strings stay English (error-surface policy: not localized).
       setPlanMode: async (on) => {
         const line = on ? '/plan' : '/plan off'
         const connection = ctx.get('connection') as ConnectionHandle
         const { result } = await connection.api.commands.execute({ sessionId, line })
-        if (!result.ok) return `${result.error.message}（${result.error.code}）`
-        if (!result.value.matched) return `未知命令：${line}`
+        if (!result.ok) return `${result.error.message} (${result.error.code})`
+        if (!result.value.matched) return `unknown command: ${line}`
         return null
       },
     }),

packages/client/ui-plan/src/client/locales.ts

@@ -0,0 +1,20 @@
+/** `plan` namespace dictionaries (the composer plan chip's copy). */
+
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export const zh = {
+  'chip.on.aria': 'plan mode 已开启，按下关闭',
+  'chip.on.title': 'plan mode 已开启 — 点击关闭（/plan off）',
+  'chip.off.aria': 'plan mode 已关闭，按下开启',
+  'chip.off.title': 'plan mode 已关闭 — 点击开启（/plan）',
+} satisfies Record<string, string>
+
+/** The plan namespace key union. */
+export type PlanKey = keyof typeof zh
+
+/** English dictionary, checked complete against the zh key set. */
+export const en = {
+  'chip.on.aria': 'Plan mode on, press to turn off',
+  'chip.on.title': 'Plan mode on — click to turn off (/plan off)',
+  'chip.off.aria': 'Plan mode off, press to turn on',
+  'chip.off.title': 'Plan mode off — click to turn on (/plan)',
+} satisfies Record<PlanKey, string>

packages/client/ui-plan/tests/browser-plugin.spec.ts

@@ -9,6 +9,7 @@ import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { PlanChip } from '../src/client/PlanModeControl.tsx'
 import type { PlanChipInjected } from '../src/client/index.ts'
 import { apply, inject } from '../src/client/index.ts'
@@ -28,12 +29,13 @@ async function bench() {
     Promise.resolve({ result: { ok: true as const, value: { matched: true as const, commandId: 'c1' } } }))
   ctx.provide('connection', { api: { commands: { execute } } })
   ctx.provide('conversation', {})
+  ctx.provide('locale', new LocaleService(ctx))
   return { ctx, slots, execute }
 }
 
 describe('ui-plan browser apply', () => {
   it('declares every service it binds', () => {
-    expect(inject).toEqual(['slots', 'connection', 'conversation'])
+    expect(inject).toEqual(['slots', 'connection', 'conversation', 'locale'])
   })
 
   it('node-half apply is an intentional no-op', () => {
@@ -45,6 +47,7 @@ describe('ui-plan browser apply', () => {
     await ctx.plugin(SlotsService).await()
     ctx.provide('connection', {})
     ctx.provide('conversation', {})
+    ctx.provide('locale', new LocaleService(ctx))
     await expect(ctx.plugin({ inject: [...inject], apply }))
       .rejects.toThrow(/slot "conversation.input.plan" is not declared/)
   })
@@ -66,13 +69,13 @@ describe('ui-plan browser apply', () => {
     b.execute.mockResolvedValueOnce({
       result: { ok: false as const, error: { code: 'session-not-found', message: 'gone', details: {} } },
     } as never)
-    await expect(injected.setPlanMode(false)).resolves.toBe('gone（session-not-found）')
+    await expect(injected.setPlanMode(false)).resolves.toBe('gone (session-not-found)')
 
     // Unmatched admission (plan-mode not composed host-side) is also a failure line.
     b.execute.mockResolvedValueOnce({
       result: { ok: true as const, value: { matched: false as const } },
     } as never)
-    await expect(injected.setPlanMode(true)).resolves.toBe('未知命令：/plan')
+    await expect(injected.setPlanMode(true)).resolves.toBe('unknown command: /plan')
 
     await fiber.dispose()
     expect(b.slots.entries('conversation.input.plan')).toHaveLength(0)

packages/client/ui-plan/tests/plan-mode-control.spec.tsx

@@ -13,9 +13,15 @@ import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import type { PlanProjection } from '@deepseek-ai/dsh-plan-mode/client'
 import { PlanChip, type PlanChipProps } from '../src/client/PlanModeControl.tsx'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import { zh } from '../src/client/locales.ts'
 
 afterEach(cleanup)
 
+// The framework-injected t seat, stubbed over the zh dictionaries (the default locale).
+const t: PlanChipProps['t'] = makeTranslate(zh, commonZh)
+
 function setup(
   plan: PlanProjection | undefined,
   setPlanMode = vi.fn((_on: boolean) => Promise.resolve<string | null>(null)),
@@ -24,13 +30,13 @@ function setup(
   const store = createSnapshotStore<{ value: PlanProjection | undefined }>({ value: plan })
   const useProjection = (_key: string, selector?: (v: unknown) => unknown) =>
     bindSnapshotSelector(store)(s => (selector ?? (v => v))(s.value))
-  const props = { useProjection, locked, setPlanMode } as unknown as PlanChipProps
+  const props = { useProjection, locked, setPlanMode, t } as unknown as PlanChipProps
   const view = render(<PlanChip {...props} />)
   return { store, setPlanMode, view }
 }
 
-const onChip = () => screen.getByRole('button', { name: 'Plan mode on, press to turn off' })
-const offChip = () => screen.getByRole('button', { name: 'Plan mode off, press to turn on' })
+const onChip = () => screen.getByRole('button', { name: 'plan mode 已开启，按下关闭' })
+const offChip = () => screen.getByRole('button', { name: 'plan mode 已关闭，按下开启' })
 
 describe('PlanChip', () => {
   it('renders nothing while the capability is absent', () => {
@@ -95,7 +101,7 @@ describe('PlanChip', () => {
       .mockRejectedValueOnce('socket closed')
     setup({ active: true, pending: false }, exitFailing)
     fireEvent.click(onChip())
-    expect((await screen.findByText('退出 plan mode 失败')).getAttribute('title')).toBe('host said no')
+    expect((await screen.findByText('failed to exit plan mode')).getAttribute('title')).toBe('host said no')
     expect(onChip()).toBeTruthy()
 
     fireEvent.click(onChip())
@@ -108,7 +114,7 @@ describe('PlanChip', () => {
     const enterFailing = vi.fn().mockResolvedValueOnce('agent busy')
     setup({ active: false, pending: false }, enterFailing)
     fireEvent.click(offChip())
-    expect((await screen.findByText('进入 plan mode 失败')).getAttribute('title')).toBe('agent busy')
+    expect((await screen.findByText('failed to enter plan mode')).getAttribute('title')).toBe('agent busy')
     expect(offChip()).toBeTruthy()
   })
 

packages/client/ui-plan/tsconfig.json

@@ -17,6 +17,9 @@
     {
       "path": "../connection"
     },
+    {
+      "path": "../locale"
+    },
     {
       "path": "../ui-conversation"
     },