fix(web-todo): dock-owned selection, keyboard-openable row, documented tail todos field

Three ds-review-bot round-8 findings on the todo display surfaces. TodoPanel took the whole `useSession` hook and cast the snapshot to reach `todos`, which put slot plumbing and an unchecked cast inside the presentation component. The panel now takes `todos: readonly TodoItem[]`; TodoDock does the selecting, matching the QueueDock posture the dock slot already establishes. The todo row carried `onClick` with no keyboard route, so its details panel was mouse-only. It now takes ToolRow's route verbatim: `role="button"`, `tabIndex={0}`, and an Enter/Space handler that claims the event. The row stays a `<div>` because a `<button>` flattens its inline spans. `session.history`'s tail-only `todos` field was documented at the TS signature but not in the apiproxy README pair, and the Agent Note claimed the feature added no new wire vocabulary. Both README sides now state the tail/omission semantics (an omitted field on a tail response is the empty plan, not unchanged state), and the note records the one added field instead of denying it. Tests: TodoPanel specs render the plain list; new TodoDock specs cover selection, live follow, rollback-to-empty, and the registration shape; a new row spec pins Enter/Space activation and non-activating keys.
2026-07-27 12:08:46 +08:00
parent 8ebdad5076
commit d2bb2a809b
9 changed files with 92 additions and 40 deletions
@@ -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 .agents/notes/implemented/feature/2026-07-23-web-todo-display.md
-2026-07-23-web-todo-display.md: a8ee5a5d2799b6e2f9ff442e0bd6230b46e9374b
-2026-07-23-web-todo-display.zh.md: 0bf7157789a0be8f2c68d462bc815db8cf07d96e
+2026-07-23-web-todo-display.md: 830f55c86c893c4942a1a9d3b8529395d5f5e38b
+2026-07-23-web-todo-display.zh.md: e68928d7eddaaa92ac831722a738ee2002342b38
@@ -33,4 +33,4 @@ The dedicated `todo_write` chat row is a plain registrant plugin (`todoToolview`

 ## Consequences

-Replay correctness is owned by one code path: any future change to window rebuild keeps todos consistent for free, and the fixture (fx-alpha turn 65) plus the assembled keyless snapshot (`apps/web/tests/todo-display.snapshot.ts`) pin the full chain (row summary and state, dock panel content, collapse round-trip) over the built client graph. `todos` is a required `ConversationSnapshot` field, so scripted fakes in specs must carry it. The TUI panel is untouched (the automation-only ACP bridge deliberately omits todo presentation); the web surfaces render the same event with no new wire vocabulary. Cold-load reconstruction is host-backed: the tail history page carries `todos` — the full-log latest `todo/write`, computed independently of the page window (the same backscan posture the view pairing uses) — so a reopened session restores the plan even when the last write precedes the window; that value survives an older-page prepend, is overwritten by any later write, and resets to empty when a tail response carries no projection.
+Replay correctness is owned by one code path: any future change to window rebuild keeps todos consistent for free, and the fixture (fx-alpha turn 65) plus the assembled keyless snapshot (`apps/web/tests/todo-display.snapshot.ts`) pin the full chain (row summary and state, dock panel content, collapse round-trip) over the built client graph. `todos` is a required `ConversationSnapshot` field, so scripted fakes in specs must carry it. The TUI panel is untouched (the automation-only ACP bridge deliberately omits todo presentation); the web surfaces render the same event, adding one wire field and no new event type. That field is how cold-load reconstruction stays host-backed: the tail history page carries `todos` — the full-log latest `todo/write`, computed independently of the page window (the same backscan posture the view pairing uses) — so a reopened session restores the plan even when the last write precedes the window; that value survives an older-page prepend, is overwritten by any later write, and resets to empty when a tail response carries no projection.
@@ -33,4 +33,4 @@ Status: implemented

 ## Consequences

-回放正确性由一条代码路径掌管：未来对窗口重建的任何改动都免费保持 todos 一致；fx-alpha 第 65 轮的 fixture（测试前置数据）加 assembled keyless snapshot（`apps/web/tests/todo-display.snapshot.ts`）在构建产物客户端全图上钉住整条链（行摘要与状态、dock 面板内容、折叠往返）。`todos` 是 `ConversationSnapshot` 的必填字段，所以 spec 里脚本化的 fake 必须带上它。TUI 面板未受改动（自动化专用的 ACP 桥接刻意不做 todo 呈现）；Web 各面渲染同一个事件，不引入任何新的协议词汇。冷加载重建由 host 兜底：history 尾页附带 `todos`——全量 log 上最新一次 `todo/write` 的投影，独立于分页窗口计算（与 view 配对同一种 backscan 姿势）——因此重开会话时即使最后一次写入落在窗口之前，计划也照常恢复；该值跨往前翻页保留，之后的任何写入照常覆盖，而尾页响应不带投影时复位为空。
+回放正确性由一条代码路径掌管：未来对窗口重建的任何改动都免费保持 todos 一致；fx-alpha 第 65 轮的 fixture（测试前置数据）加 assembled keyless snapshot（`apps/web/tests/todo-display.snapshot.ts`）在构建产物客户端全图上钉住整条链（行摘要与状态、dock 面板内容、折叠往返）。`todos` 是 `ConversationSnapshot` 的必填字段，所以 spec 里脚本化的 fake 必须带上它。TUI 面板未受改动（自动化专用的 ACP 桥接刻意不做 todo 呈现）；Web 各面渲染同一个事件，只新增一个协议字段，不新增事件类型。冷加载重建正是靠这个字段由 host 兜底：history 尾页附带 `todos`——全量 log 上最新一次 `todo/write` 的投影，独立于分页窗口计算（与 view 配对同一种 backscan 姿势）——因此重开会话时即使最后一次写入落在窗口之前，计划也照常恢复；该值跨往前翻页保留，之后的任何写入照常覆盖，而尾页响应不带投影时复位为空。
@@ -1,20 +1,19 @@
 // TodoPanel: persistent plan strip above the composer (the web counterpart
-// of the TUI plan panel). Renders
-// the latest todo/write whole-list snapshot off the session snapshot — no
-// data of its own, hidden while the list is empty. Mounted through the
-// 'conversation.input.dock' slot (QueueDock posture): the standard session
-// kit supplies useSession, so the inner component stays framework-free.
+// of the TUI plan panel). Renders the latest todo/write whole-list snapshot —
+// no data of its own, hidden while the list is empty. Mounted through the
+// 'conversation.input.dock' slot (QueueDock posture): the dock adapter does
+// the selecting, so the panel takes the plain list and stays framework-free.

 import { useState } from 'react'
 import type { Context } from 'cordis'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import type { TodoItem } from '@deepseek-ai/dsh-client-runtime/client'
-import type { UseSession } from '@deepseek-ai/dsh-client-ui-slots'
 import { IconChevronDownOutline14, IconChevronUpOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import css from './TodoPanel.module.css'

 export interface TodoPanelProps {
-  useSession: UseSession
+  /** The session's current plan (empty renders nothing) — selected by the dock adapter. */
+  todos: readonly TodoItem[]
 }

 /** Status glyphs mirror the TUI plan panel (✓ done / ● active / ○ pending). */
@@ -22,8 +21,7 @@ const STATUS_GLYPHS: Record<TodoItem['status'], string> = {
  completed: '✓', in_progress: '●', pending: '○',
 }

-export function TodoPanel({ useSession }: TodoPanelProps) {
-  const todos = useSession(s => (s as { todos: readonly TodoItem[] }).todos)
+export function TodoPanel({ todos }: TodoPanelProps) {
  const [collapsed, setCollapsed] = useState(false)
  if (todos.length === 0) return null

@@ -64,9 +62,10 @@ export function TodoPanel({ useSession }: TodoPanelProps) {
 /** Full props of a dock entry: InputZone owner share + session standard kit + global seat. */
 export type TodoDockProps = PropsRuntime<'conversation.input.dock'>

-/** Dock adapter: the standard kit's useSession feeds the strip. */
+/** Dock adapter: selects the plan off the session snapshot and hands the strip a plain list. */
 export function TodoDock({ useSession }: TodoDockProps) {
-  return <TodoPanel useSession={useSession} />
+  const todos = useSession(s => s.todos)
+  return <TodoPanel todos={todos} />
 }

 /**
@@ -5,6 +5,7 @@
 // durable list itself renders in the TodoPanel above the composer, so the
 // row stays one line.

+import type { KeyboardEvent } from 'react'
 import type { Context } from 'cordis'
 import { StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ToolRowProps } from '../contract/slots.ts'
@@ -46,8 +47,23 @@ export function TodoRow({ toolName, block, openDetails }: ToolRowProps) {
  const model = toolRowModel(toolName, block)
  const argsRaw = ('kind' in block ? block.call?.argsRaw : block.argsRaw) ?? ''
  const summary = summarize(argsRaw) ?? model.summary
+  // Button semantics, not a <button>: the row carries inline spans a button
+  // would flatten, and ToolRow takes the same role/tabIndex/Enter-Space route.
+  const openFromKeyboard = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key !== 'Enter' && event.key !== ' ') return
+    event.preventDefault()
+    openDetails()
+  }
  return (
-    <div className={css.row} data-sample="todo-row" data-state={model.state} onClick={openDetails}>
+    <div
+      className={css.row}
+      data-sample="todo-row"
+      data-state={model.state}
+      role="button"
+      tabIndex={0}
+      onClick={openDetails}
+      onKeyDown={openFromKeyboard}
+    >
      {model.state === 'ok'
        ? <span className={css.badge} aria-hidden>☰</span>
        : <StateDot state={model.state === 'running' ? 'ongoing' : model.state === 'stopped' ? 'warning' : 'error'} />}
@@ -1,27 +1,24 @@
 // @vitest-environment jsdom
 /**
 * Todo display acceptance: the TodoPanel plan strip (empty-hidden, status
- * rows, collapse with active hint) and the todo_write toolview row (progress
- * summary from args, generic fallback on malformed JSON, error badge).
+ * rows, collapse with active hint), its TodoDock adapter (selects the plan off
+ * the session snapshot and follows changes), and the todo_write toolview row
+ * (progress summary from args, generic fallback on malformed JSON, error badge,
+ * keyboard activation).
 */
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type { TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
-import type { UseSession } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 // Export discipline: packages/client/AGENTS.md.
 import { TodoRow, todoToolview } from '../src/client/toolviews/todo-row.tsx'
-import { TodoPanel } from '../src/client/skeleton/TodoPanel.tsx'
+import type { TodoDockProps } from '../src/client/skeleton/TodoPanel.tsx'
+import { TodoDock, TodoPanel, todoDockEntry } from '../src/client/skeleton/TodoPanel.tsx'

 afterEach(cleanup)

-function sessionWith(todos: readonly TodoItem[]) {
-  const store = createSnapshotStore<{ todos: readonly TodoItem[] }>({ todos })
-  return { store, useSession: bindSnapshotSelector(store) as unknown as UseSession }
-}
-
 const LIST: TodoItem[] = [
  { content: '搭骨架', status: 'completed' },
  { content: '写组件', status: 'in_progress' },
@@ -29,17 +26,14 @@ const LIST: TodoItem[] = [
 ]

 describe('TodoPanel', () => {
-  it('renders nothing while the list is empty, appears when todos land', () => {
-    const { store, useSession } = sessionWith([])
-    render(<TodoPanel useSession={useSession} />)
-    expect(screen.queryByTestId('todo-panel')).toBeNull()
-    act(() => { store.set({ todos: LIST }) })
-    expect(screen.getByTestId('todo-panel')).toBeTruthy()
+  it('renders nothing while the list is empty', () => {
+    const { container } = render(<TodoPanel todos={[]} />)
+    expect(container.innerHTML).toBe('')
  })

  it('shows progress, one row per item with its status, and strikes done items', () => {
-    const { useSession } = sessionWith(LIST)
-    render(<TodoPanel useSession={useSession} />)
+    render(<TodoPanel todos={LIST} />)
+    expect(screen.getByTestId('todo-panel')).toBeTruthy()
    expect(screen.getByText('1/3')).toBeTruthy()
    const items = screen.getAllByRole('listitem')
    expect(items.map(li => li.getAttribute('data-status'))).toEqual(['completed', 'in_progress', 'pending'])
@@ -48,8 +42,7 @@ describe('TodoPanel', () => {
  })

  it('collapse hides the list and surfaces the active item in the header; expand restores', () => {
-    const { useSession } = sessionWith(LIST)
-    render(<TodoPanel useSession={useSession} />)
+    render(<TodoPanel todos={LIST} />)
    const header = screen.getByRole('button', { expanded: true })
    fireEvent.click(header)
    expect(screen.queryByRole('list')).toBeNull()
@@ -60,14 +53,39 @@ describe('TodoPanel', () => {
  })

  it('collapsed header omits the hint when nothing is in progress', () => {
-    const { useSession } = sessionWith([{ content: '都完了', status: 'completed' }])
-    render(<TodoPanel useSession={useSession} />)
+    render(<TodoPanel todos={[{ content: '都完了', status: 'completed' }]} />)
    fireEvent.click(screen.getByRole('button', { expanded: true }))
    expect(screen.queryByText('都完了')).toBeNull()
    expect(screen.getByText('1/1')).toBeTruthy()
  })
 })

+/** Dock props stub: the adapter reads useSession only; the rest of the owner share is unused. */
+function dockProps(store: ReturnType<typeof createSnapshotStore<{ todos: readonly TodoItem[] }>>): TodoDockProps {
+  return { useSession: bindSnapshotSelector(store) } as unknown as TodoDockProps
+}
+
+describe('TodoDock', () => {
+  it('selects the plan off the session snapshot and follows later writes', () => {
+    const store = createSnapshotStore<{ todos: readonly TodoItem[] }>({ todos: [] })
+    render(<TodoDock {...dockProps(store)} />)
+    expect(screen.queryByTestId('todo-panel')).toBeNull()
+    act(() => { store.set({ todos: LIST }) })
+    expect(screen.getByText('1/3')).toBeTruthy()
+    // A rollback to the empty list retires the strip (the panel owns no data).
+    act(() => { store.set({ todos: [] }) })
+    expect(screen.queryByTestId('todo-panel')).toBeNull()
+  })
+
+  it('ships the registrant plugin shape (list entry above the queue rows)', () => {
+    expect(todoDockEntry.name).toBe('conversation-todo-dock')
+    expect(todoDockEntry.inject).toEqual(['slots', 'conversation'])
+    const register = vi.fn()
+    todoDockEntry.apply({ slots: { register } } as never)
+    expect(register).toHaveBeenCalledWith({ name: 'conversation.input.dock', id: 'todo', order: -1 }, TodoDock)
+  })
+})
+
 const resultNode = (argsRaw: string, over?: Partial<ToolResultNode>): ToolResultNode => ({
  kind: 'tool-result', seq: 10, time: 2_000, callTime: 1_000, callId: 'c1',
  call: { name: 'todo_write', argsRaw },
@@ -126,6 +144,21 @@ describe('TodoRow', () => {
    expect(openDetails).toHaveBeenCalledTimes(1)
  })

+  it('opens details from the keyboard on Enter and Space, ignoring other keys', () => {
+    const openDetails = vi.fn()
+    render(<TodoRow {...rowProps(resultNode(ARGS), openDetails)} />)
+    const row = screen.getByRole('button')
+    expect(row.getAttribute('tabindex')).toBe('0')
+    fireEvent.keyDown(row, { key: 'Enter' })
+    fireEvent.keyDown(row, { key: ' ' })
+    expect(openDetails).toHaveBeenCalledTimes(2)
+    // Space must not also scroll the flow: the handler claims the event.
+    expect(fireEvent.keyDown(row, { key: ' ' })).toBe(false)
+    fireEvent.keyDown(row, { key: 'a' })
+    fireEvent.keyDown(row, { key: 'ArrowDown' })
+    expect(openDetails).toHaveBeenCalledTimes(3)
+  })
+
  it.each([
    { label: 'null root', argsRaw: 'null' },
    { label: 'non-object root', argsRaw: '42' },
@@ -1,6 +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: 43ad70fa8b865b0b80496bbb67013f24e9e3a33f
-README.zh.md: cc95a7512fb872add816bf0456a93dfcf7b84c10
+#   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
+README.md: 775ceec5b2171b81977650b739b5b94662902dd5
+README.zh.md: d28d6cdad43b7c944f6bdf17e80e99494b39308f
@@ -14,6 +14,8 @@ The mux stream projects the latest log-backed title as a validated `session/titl

 Workspace and Session lists are separate reconnect baselines. `workspace.create` creates a unique name or adopts an existing directory, `session.create` accepts an optional preallocated Session id, and `host/workspace-changed` plus `host/session-added` carry committed increments in either arrival order. `SessionSummary.blank` and the `host/session-added` frame carry the derived zero-events bit: clients hide blank sessions and reuse them per workspace, flip blank on the first `host/session-status(running:true)`, and treat `session.list` as the reconnect authority; cold summaries are never blank because lazy persistence keeps never-appended sessions out of `list()`.

+`session.history` pages on message boundaries, and its tail page (no `beforeSeq`) carries two session-level extras the page window cannot supply: the in-flight partial's chunk events, and `todos` — the latest `todo/write` whole-list projection over the full log. Older pages omit `todos` because the projection is session-level, not per-page; a tail response that omits it means the whole log holds no `todo/write`, so clients read the absent field as the empty plan rather than as unchanged state.
+
 The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `command.execute` runs a slash-command line host-side and returns a detached result; the carrier's request signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.

 ## Carrier layer (`/client` + root)
@@ -14,6 +14,8 @@ mux 流会在每个已附加会话的订阅基线之后，以及对应的实时

 Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.create` 会创建唯一名称或接纳现有目录，`session.create` 接受可选的预分配 Session id，`host/workspace-changed` 与 `host/session-added` 则以任意到达顺序携带已提交的增量。`SessionSummary.blank` 与 `host/session-added` 帧携带派生的零事件位：客户端隐藏空白会话并按 workspace 复用它们，在首个 `host/session-status(running:true)` 时翻转 blank，并以 `session.list` 作为重连权威；冷会话摘要永远不是空白——惰性持久化让从未追加过事件的会话根本不出现在 `list()` 中。

+`session.history` 按消息边界分页，其尾页（不带 `beforeSeq`）额外携带两项页窗口本身无法提供的会话级数据：进行中局部消息的 chunk 事件，以及 `todos`——整份日志上最后一次 `todo/write` 的整表投影。较早的页面不带 `todos`，因为该投影是会话级而非分页级的；尾页响应缺少该字段意味着整份日志中没有任何 `todo/write`，因此客户端要把缺失字段读作空计划，而不是读作「状态未变」。
+
 `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`command.execute` 在宿主侧运行一条斜杠命令行并返回脱耦结果；载体的请求信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。

 ## 载体层（`/client` + 根路径）