Merge latest master into manual compaction

# Conflicts:
#	apps/cli/README.i18n.yaml
#	docs/architecture.i18n.yaml
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	packages/compact/compact-basic/README.i18n.yaml
#	packages/pty/pty-local/tests/index.spec.ts

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

@@ -15,6 +15,7 @@ import type {
   AssistantMessage,
   ContentBlock,
   MessageSource,
+  TokenUsage,
   ToolResultMessage,
   UserMessage,
 } from '@deepseek-ai/dsh-llm'
@@ -138,7 +139,107 @@ const TERMINAL_EXIT_STATUS: Record<string, { exitCode: number } | { signal: stri
 }
 
 /**
- * The structured `web_search` result view for fixture turn 66, authored inline
+ * Structured grep result for the search sample (turn 66): matches grouped by
+ * file, authored inline because the client-side fixture cannot import the tool
+ * that produces the canonical value. `truncated` with a larger `total` than the
+ * retained match count exercises the search card's capped indicator; the file
+ * with more than CHAT_SEARCH_MAX_LINES rows exercises its head/tail height cap.
+ */
+const SEARCH_MATCHES_FIXTURE: { path: string; matches: { lineNumber: number; line: string }[] }[] = [
+  {
+    path: 'packages/client/ui-primitives/src/SearchBlock.tsx',
+    matches: [
+      { lineNumber: 16, line: 'export const DEFAULT_SEARCH_MAX_LINES = 16' },
+      { lineNumber: 138, line: 'export function SearchBlock(props: SearchBlockProps) {' },
+      { lineNumber: 141, line: '  const [collapsed, setCollapsed] = useState<ReadonlySet<number>>(() => new Set())' },
+    ],
+  },
+  {
+    path: 'packages/client/ui-conversation/src/client/contract/search-card-model.ts',
+    matches: [
+      { lineNumber: 24, line: 'export const CHAT_SEARCH_MAX_LINES = 8' },
+      { lineNumber: 60, line: 'export function searchCardModel(block: ToolCallBlock): SearchCardModel | null {' },
+    ],
+  },
+  {
+    path: 'packages/client/ui-conversation/src/client/toolviews/search-row.tsx',
+    matches: [
+      { lineNumber: 71, line: 'export function SearchRow({ toolName, block }: ToolRowProps) {' },
+      { lineNumber: 73, line: '  const search = searchCardModel(block)' },
+      { lineNumber: 90, line: '        <SearchBlock {...search.card} maxLines={CHAT_SEARCH_MAX_LINES} className={css.search} />' },
+      { lineNumber: 113, line: "    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep' }, SearchRow)" },
+    ],
+  },
+]
+
+/**
+ * The model-facing grep render text for the sample — what a UI without a search
+ * card shows, attached as the view's `content`. Mirrors the real grep
+ * presenter's shape (see formatGrepOutput in dsh-tool-fs-search): a
+ * `Found X of Y matches` header, the matches grouped under file headers with
+ * `Line N:` rows, then a spill-recovery footer.
+ */
+const SEARCH_MATCHES_TEXT = [
+  'Found 9 of 42 matches',
+  '',
+  ...SEARCH_MATCHES_FIXTURE.map(file =>
+    [file.path, ...file.matches.map(m => `Line ${m.lineNumber}: ${m.line}`)].join('\n')),
+  '',
+  '(Full grep result stored at: fixture://spill/grep-66. Read it to see every match.)',
+].join('\n')
+
+/**
+ * Structured glob result for the search sample (turn 67): a flat path list,
+ * truncated with a larger `total` so the path card shows its capped indicator.
+ */
+const SEARCH_PATHS_FIXTURE = [
+  'packages/client/ui-primitives/src/SearchBlock.tsx',
+  'packages/client/ui-primitives/src/SearchBlock.module.css',
+  'packages/client/ui-conversation/src/client/contract/search-card-model.ts',
+  'packages/client/ui-conversation/src/client/toolviews/search-row.tsx',
+  'packages/client/ui-conversation/src/client/toolviews/search-row.module.css',
+]
+
+/**
+ * The model-facing glob render text — the newline-joined path list plus a
+ * spill-recovery footer, mirroring the real glob presenter's shape (see
+ * formatGlobOutput in dsh-tool-fs-search).
+ */
+const SEARCH_PATHS_TEXT = [
+  ...SEARCH_PATHS_FIXTURE,
+  '',
+  '(Showing 5 of 23 paths. Full sorted result stored at: fixture://spill/glob-67. Read it to see every path.)',
+].join('\n')
+
+/**
+ * Read-card sample for the read turn: a WINDOW past an offset, so the line
+ * numbers start above 1 (the card's gutter keeps the file's own numbering) and
+ * `totalLines` exceeds the window (the card shows a "showing N of M" note). The
+ * fixture is client-side and cannot import the read tool, so the structured
+ * window is authored inline exactly as the tool would project it through
+ * `presentationMeta`. `lang` is a `ts` hint so the shiki path highlights it.
+ */
+const READ_SAMPLE_FIRST_LINE = 41
+const READ_SAMPLE_SOURCE = [
+  'export interface ReadBlockProps {',
+  '  label?: string | undefined',
+  '  lines: readonly ReadBlockLine[]',
+  '  totalLines: number',
+  '  lang?: string | undefined',
+  '  maxLines?: number | undefined',
+  '  className?: string | undefined',
+  '}',
+  '',
+  '// A windowed read keeps the file line numbers in the gutter.',
+  'const marker = "fixture read sample"',
+]
+const READ_SAMPLE_LINES = READ_SAMPLE_SOURCE.map((text, index) => ({ number: READ_SAMPLE_FIRST_LINE + index, text }))
+const READ_SAMPLE_PATH = 'packages/client/ui-primitives/src/ReadBlock.tsx'
+const READ_SAMPLE_TOTAL = 180
+const READ_SAMPLE_TEXT = READ_SAMPLE_SOURCE.map((text, index) => `${READ_SAMPLE_FIRST_LINE + index}: ${text}`).join('\n')
+
+/**
+ * The structured `web_search` result view for the web-search turn, authored inline
  * because this client-side fixture cannot import the web tool that projects it.
  * The sources exercise the citation list's features: a titled source with a
  * snippet and a date, a source with no title (its hostname labels the link) and
@@ -168,7 +269,7 @@ const WEB_SEARCH_RESULT: Omit<Extract<ToolResultView, { card: 'web'; kind: 'sear
   truncated: true,
 }
 
-/** The `web_fetch` result view for fixture turn 67, authored inline for the same reason. */
+/** The `web_fetch` result view for the web-fetch turn, authored inline for the same reason. */
 const WEB_FETCH_RESULT: Omit<Extract<ToolResultView, { card: 'web'; kind: 'fetch' }>, 'card' | 'kind'> = {
   url: 'https://www.deepseek.com/blog/harness-architecture',
   statusCode: 200,
@@ -227,6 +328,16 @@ function sid(id: string): SessionId {
   return id as SessionId
 }
 
+/** Deterministic provider billing attached to fixture assistant messages. */
+function fixtureUsage(turn: number, step: number): TokenUsage {
+  return {
+    inputTokens: 20 + turn % 5,
+    outputTokens: 8 + step,
+    cacheReadTokens: turn === 0 ? 0 : 80,
+    cacheWriteTokens: turn % 10 === 0 ? 4 : 0,
+  }
+}
+
 /** fx-alpha history script: 60 turns (~130+ messages -> 3 pages at PAGE_MESSAGES=50),
  *  mixing reasoning blocks / tool call+result / steering / context. */
 function buildAlphaLog(): SessionEvent[] {
@@ -234,7 +345,17 @@ function buildAlphaLog(): SessionEvent[] {
   let time = Date.now() - 3_600_000
   const push = (e: Record<string, unknown>): number => {
     const seq = events.length
-    events.push({ seq, time: (time += 800), ...e })
+    const data = e['data'] as Record<string, unknown> | undefined
+    const authored = e['type'] === 'assistant/message' && data !== undefined
+      ? {
+        ...e,
+        data: {
+          ...data,
+          usage: fixtureUsage(data['turn'] as number, data['step'] as number),
+        },
+      }
+      : e
+    events.push({ seq, time: (time += 800), ...authored })
     return seq
   }
   for (let turn = 0; turn < 60; turn++) {
@@ -315,8 +436,8 @@ function buildAlphaLog(): SessionEvent[] {
     const turn = 64
     const callId = `fx-call-${turn}`
     const program = 'const listing = await tools.bash({ command: "ls notes", description: "List notes" })\n'
-      + 'const demo = await tools.read({ path: "notes/demo.txt" })\n'
-      + 'await tools.read({ path: "notes/missing.txt" }).catch(() => "tolerated")\n'
+      + 'const demo = await tools.read({ file_path: "notes/demo.txt" })\n'
+      + 'await tools.read({ file_path: "notes/missing.txt" }).catch(() => "tolerated")\n'
       + 'return { listing, demo }'
     const args = JSON.stringify({ code: program, description: 'Read the notes files and summarize' })
     push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
@@ -341,8 +462,8 @@ function buildAlphaLog(): SessionEvent[] {
       })
     }
     dispatchPair(1, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt\nnew-demo.txt')
-    dispatchPair(2, 'read', { path: 'notes/demo.txt' }, 'hello fixture\n')
-    dispatchPair(3, 'read', { path: 'notes/missing.txt' }, 'Error: ENOENT: notes/missing.txt not found', true)
+    dispatchPair(2, 'read', { file_path: 'notes/demo.txt' }, 'hello fixture\n')
+    dispatchPair(3, 'read', { file_path: 'notes/missing.txt' }, 'Error: ENOENT: notes/missing.txt not found', true)
     push({
       type: 'tool/result', surfaceOp: 'append',
       data: { turn, step: 0, message: toolResultMessage(callId, text('{"listing":"demo.txt\\nnew-demo.txt","demo":"hello fixture\\n"}'), false) },
@@ -350,7 +471,7 @@ function buildAlphaLog(): SessionEvent[] {
     push({ type: 'step/end', data: { turn, step: 0 } })
     push({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
   }
-  // Turn 65: todo_write sample — the TodoRow toolview in the flow plus the
+  // Turn 67: todo_write sample — the TodoRow toolview in the flow plus the
   // todo/write snapshot event feeding the TodoPanel plan strip.
   const fixtureTodos = [
     { content: '梳理需求', status: 'completed' },
@@ -371,7 +492,30 @@ function buildAlphaLog(): SessionEvent[] {
   // strip empty and take the todo surfaces' own coverage with it.
   toolTurn(65, 'bash', '{"command":"pnpm run check","cwd":"/tmp/fixture/deep/nested"}', TERMINAL_OUTPUT_FIXTURE)
 
-  // Turns 66-67: the web render intent — a web_search whose result view carries
+  // Turns 66-67: the search card's two shapes. `grep` emits a `card: 'search'`
+  // `shape: 'matches'` result view (grouped-by-file matches, truncated with a
+  // larger `total`), `glob` emits `shape: 'paths'` (a flat path list, likewise
+  // truncated). Both ride the keyed SearchRow registration under their own
+  // names; the render-site fallback row is covered by the model derivation
+  // tests, since every fixture search tool has a keyed row. Ordered before the
+  // todo turn for the same standing-plan reason the bash turn is.
+  toolTurn(66, 'grep', '{"pattern":"SEARCH_MAX_LINES","path":"packages/client"}', SEARCH_MATCHES_TEXT)
+  toolTurn(67, 'glob', '{"pattern":"**/SearchBlock*","path":"packages/client"}', SEARCH_PATHS_TEXT)
+
+  // Turn 68: the read sample — a WINDOW past an offset so the card draws file
+  // line numbers starting above 1 and a "showing N of M" note (the window is
+  // shorter than READ_SAMPLE_TOTAL), with a `ts` language hint the shiki path
+  // highlights. Named `read`, so it exercises the keyed ReadRow registration.
+  // The render-site fallback ROW SHAPE (a read call on the generic flattened
+  // path) is covered by the turn 64 run_code read sub-dispatches, which
+  // session.ts folds with resultView: null; the fallback-row + read-CARD
+  // combination is pinned by the web_fetch case in read-card.spec.tsx, not by
+  // this fixture. The read render intent is result-side only, so its pending
+  // call stays a generic `kind: 'read'` card; presentResult carries the
+  // structured window.
+  toolTurn(68, 'read', `{"file_path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)
+
+  // Turns 69-70: the web render intent — a web_search whose result view carries
   // structured sources plus an answer (the citation list, one source lacking a
   // title so its hostname labels the link, the capped indicator on), and a
   // web_fetch whose result view carries the fetched URL and its HTTP status.
@@ -380,11 +524,11 @@ function buildAlphaLog(): SessionEvent[] {
   // the real tools so they hit the keyed WebRow registration. Ordered BEFORE
   // the todo turn for the same reason turn 65 is: the standing plan retires at
   // the next turn/start, so a turn after it would empty the dock's plan strip.
-  toolTurn(66, 'web_search', '{"query":"deepseek harness architecture"}', 'Search results for deepseek harness architecture.')
-  toolTurn(67, 'web_fetch', '{"url":"https://www.deepseek.com/blog/harness-architecture"}', '# Harness architecture\n\nEverything is a plugin.')
+  toolTurn(69, 'web_search', '{"query":"deepseek harness architecture"}', 'Search results for deepseek harness architecture.')
+  toolTurn(70, 'web_fetch', '{"url":"https://www.deepseek.com/blog/harness-architecture"}', '# Harness architecture\n\nEverything is a plugin.')
 
   const todoArgs = JSON.stringify({ todos: fixtureTodos })
-  toolTurn(68, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 1 in progress, 1 completed.')
+  toolTurn(71, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 1 in progress, 1 completed.')
   // The real tool appends the snapshot mid-execution — between tool/call and
   // tool/result — so the fixture reproduces that exact ordering (the last
   // toolTurn events run ... tool/call, tool/result, step/end, turn/end).
@@ -419,6 +563,12 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
         card: 'diff', title: `Write ${str(args.path)}`,
         diffs: [{ path: str(args.path), oldText: null, newText: str(args.content) }],
       }
+    // A read pending call is a GENERIC card (kind: 'read', a follow-along
+    // location): the read render intent is result-side only, because a call
+    // carries no file content until execute returns. The rich read card arrives
+    // in presentResult.
+    case 'read':
+      return { card: 'generic', title: `Read ${str(args.file_path)}`, kind: 'read', locations: [{ path: str(args.file_path) }] }
     case 'edit':
       // The multi-hunk sample (turn 67) is keyed on its file_path, so the two
       // scattered hunks share one path header and the card draws the `⋯` gap.
@@ -440,6 +590,13 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
         card: 'diff', title: `Write ${str(args.file_path)}`,
         diffs: [{ path: str(args.file_path), oldText: null, newText: str(args.content) }],
       }
+    // A search call stays a generic card (kind: 'search'): the structured
+    // matches/paths exist only after execute, so the search card is result-time
+    // only (presentResult builds it). This mirrors the real grep/glob presenters.
+    case 'grep':
+      return { card: 'generic', title: `Grep ${str(args.pattern)}`, kind: 'search', rawInput: args }
+    case 'glob':
+      return { card: 'generic', title: `Glob ${str(args.pattern)}`, kind: 'search', rawInput: args }
     // The web tools keep a GENERIC pending card and add the `web` result card
     // only at result time (the contract's result-only web shape); their pending
     // kind matches the result kind so a call and its result read as one category.
@@ -455,6 +612,28 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
 function presentResult(name: string, argsRaw: string, resultText: string): ToolResultView | undefined {
   const call = presentCall(name, argsRaw)
   if (call === undefined) return undefined
+  // Search is result-time only: the call stays a generic search card, and the
+  // result view carries the structured shape the card renders. The view holds no
+  // result text — a UI without a search card falls back to the raw tool/result
+  // content — so the truncation recovery footer rides that raw content (the
+  // `toolTurn` message text), not the view. `total` exceeds the retained count so
+  // the card shows its capped indicator.
+  if (name === 'grep') {
+    return { card: 'search', shape: 'matches', files: SEARCH_MATCHES_FIXTURE, truncated: true, total: 42 }
+  }
+  if (name === 'glob') {
+    return { card: 'search', shape: 'paths', paths: SEARCH_PATHS_FIXTURE, truncated: true, total: 23 }
+  }
+  // The read result is the structured window the tool projects through
+  // `presentationMeta`; the fixture authors it inline (it cannot import the
+  // tool). Keyed on the name because the read pending call is a generic card,
+  // so `call.card` alone does not distinguish it from edit/write.
+  if (name === 'read') {
+    return {
+      card: 'read', path: READ_SAMPLE_PATH, offset: READ_SAMPLE_FIRST_LINE, lines: READ_SAMPLE_LINES,
+      totalLines: READ_SAMPLE_TOTAL, lang: 'ts', content: text(resultText),
+    }
+  }
   // The web tools keep a generic pending card, so their result card is chosen
   // by tool name rather than by the pending card tag: the structured `web` card
   // the frontend consumes. The view carries no `content` copy (per the contract
@@ -569,6 +748,113 @@ function permissionSelectOf(
   }
 }
 
+interface FixtureTokenUsageProjection {
+  uncachedInputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheWriteTokens: number
+}
+
+interface FixtureUsageSample {
+  turn: number
+  step: number
+  usage: TokenUsage
+}
+
+/** Read one provider usage sample from either durable carrier. */
+function usageSampleOf(event: SessionEvent): FixtureUsageSample | undefined {
+  const item = event as unknown as {
+    type: string
+    data: {
+      turn?: number
+      step?: number
+      usage?: TokenUsage
+      chunk?: { type?: string; usage?: TokenUsage }
+    }
+  }
+  const usage = item.type === 'assistant/chunk' && item.data.chunk?.type === 'usage'
+    ? item.data.chunk.usage
+    : item.type === 'assistant/message'
+      ? item.data.usage
+      : undefined
+  return usage === undefined || item.data.turn === undefined || item.data.step === undefined
+    ? undefined
+    : { turn: item.data.turn, step: item.data.step, usage }
+}
+
+/** Fixture parallel of token-meter's last-sample-replacing usage projection. */
+function tokenUsageOf(log: readonly SessionEvent[]): FixtureTokenUsageProjection {
+  const totals: FixtureTokenUsageProjection = {
+    uncachedInputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+  }
+  let last: {
+    turn: number
+    step: number
+    buckets: FixtureTokenUsageProjection
+  } | null = null
+  for (const event of log) {
+    const sample = usageSampleOf(event)
+    if (sample === undefined) continue
+    const buckets: FixtureTokenUsageProjection = {
+      uncachedInputTokens: sample.usage.inputTokens,
+      outputTokens: sample.usage.outputTokens,
+      cacheReadTokens: sample.usage.cacheReadTokens ?? 0,
+      cacheWriteTokens: sample.usage.cacheWriteTokens ?? 0,
+    }
+    const previous = last?.turn === sample.turn && last.step === sample.step
+      ? last.buckets
+      : undefined
+    totals.uncachedInputTokens += buckets.uncachedInputTokens - (previous?.uncachedInputTokens ?? 0)
+    totals.outputTokens += buckets.outputTokens - (previous?.outputTokens ?? 0)
+    totals.cacheReadTokens += buckets.cacheReadTokens - (previous?.cacheReadTokens ?? 0)
+    totals.cacheWriteTokens += buckets.cacheWriteTokens - (previous?.cacheWriteTokens ?? 0)
+    last = { turn: sample.turn, step: sample.step, buckets }
+  }
+  return totals
+}
+
+interface FixtureRequestContext {
+  provider: string
+  model: string
+  contextWindow?: number
+}
+
+/** Latest log-only route context, or undefined before any request ran. */
+function lastRequestContext(
+  log: readonly SessionEvent[],
+): FixtureRequestContext | undefined {
+  const event = log.findLast(item => (item as { type: string }).type === 'request/context')
+  return event === undefined
+    ? undefined
+    : (event as unknown as { data: FixtureRequestContext }).data
+}
+
+/**
+ * Fixture parallel of token-meter's request-pressure projection: the last
+ * provider-reported prompt size paired with the last recorded capacity. The
+ * two need not come from one request — see the token-meter README.
+ */
+function contextPressureOf(
+  log: readonly SessionEvent[],
+): { pressureTokens?: number; contextWindow?: number } {
+  let pressureTokens: number | undefined
+  for (const event of log) {
+    const sample = usageSampleOf(event)
+    if (sample === undefined) continue
+    pressureTokens = sample.usage.inputTokens
+      + (sample.usage.cacheReadTokens ?? 0)
+      + (sample.usage.cacheWriteTokens ?? 0)
+  }
+  const contextWindow = lastRequestContext(log)?.contextWindow
+  return {
+    ...pressureTokens === undefined ? {} : { pressureTokens },
+    ...contextWindow === undefined ? {} : { contextWindow },
+  }
+}
+
 function projectionValuesOf(log: readonly SessionEvent[]): Record<string, unknown> {
   const values: Record<string, unknown> = {}
   const titleEvent = log.findLast(item => (item as { type: string }).type === 'session/title')
@@ -583,12 +869,32 @@ function projectionValuesOf(log: readonly SessionEvent[]): Record<string, unknow
   values['plan'] = planViewOf(log)
   // Always present (GoalService unit composed): null before create / after clear.
   values['goal'] = backscanGoal(log)
+  // Always present (token-meter composed): full-log provider billing.
+  values['tokenUsage'] = tokenUsageOf(log)
+  // Always present (token-meter composed): last request pressure and capacity.
+  values['contextPressure'] = contextPressureOf(log)
   return values
 }
 
 /** Host push-frame parallel: emit one session/projection frame per key the given event advanced. */
 function projectionFramesOf(id: SessionId, log: readonly SessionEvent[], event: SessionEvent): Extract<MuxFrame, { type: 'session/projection' }>[] {
   const type = (event as { type: string }).type
+  // One usage sample advances both token-meter units.
+  if (usageSampleOf(event) !== undefined) {
+    return [
+      { type: 'session/projection', sessionId: id, key: 'tokenUsage', value: tokenUsageOf(log), seq: event.seq },
+      { type: 'session/projection', sessionId: id, key: 'contextPressure', value: contextPressureOf(log), seq: event.seq },
+    ]
+  }
+  if (type === 'request/context') {
+    return [{
+      type: 'session/projection',
+      sessionId: id,
+      key: 'contextPressure',
+      value: contextPressureOf(log),
+      seq: event.seq,
+    }]
+  }
   if (type === 'session/title') {
     const values = projectionValuesOf(log)
     /* v8 ignore next -- the advancing title event is in the log, so the key is present. */
@@ -1285,7 +1591,16 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       replays.delete(id)
       const done = pieces.slice(0, i).join('')
       append(id, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'block-end', index: 0, block: { type: 'text', text: done } } } })
-      append(id, { type: 'assistant/message', surfaceOp: 'append', data: { turn, step, message: assistantMessage(text(aborted ? `${done}（已中断）` : done)) } })
+      append(id, {
+        type: 'assistant/message',
+        surfaceOp: 'append',
+        data: {
+          turn,
+          step,
+          message: assistantMessage(text(aborted ? `${done}（已中断）` : done)),
+          usage: fixtureUsage(turn, step),
+        },
+      })
       append(id, { type: 'step/end', data: { turn, step } })
       append(id, { type: 'turn/end', data: { turn, reason: { kind: aborted ? 'cancelled' : 'completed' } } })
       setRunning(id, false)
@@ -1554,6 +1869,16 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
           append(id, { type: 'plan/mode', data: { active: plan.wanted } })
         }
         append(id, { type: 'user/message', surfaceOp: 'append', data: userMessage(content) })
+        // Capacity parallel of the host token-meter's request/context record:
+        // log-only, appended inside the open turn, and deduplicated against the
+        // route already recorded (the fixture never varies contextWindow).
+        const target = modelTargets.get(id) ?? { provider: 'deepseek', model: 'deepseek-v4-flash' }
+        if (lastRequestContext(logOf(id))?.model !== target.model) {
+          append(id, {
+            type: 'request/context',
+            data: { provider: target.provider, model: target.model, contextWindow: 128_000 },
+          })
+        }
         startReply(
           id,
           turn,

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

@@ -141,6 +141,14 @@ describe('createFixtureApi', () => {
         },
         plan: { active: false, pending: false },
         goal: null,
+        tokenUsage: {
+          uncachedInputTokens: 0,
+          outputTokens: 0,
+          cacheReadTokens: 0,
+          cacheWriteTokens: 0,
+        },
+        // No request ran, so neither pressure nor capacity is known yet.
+        contextPressure: {},
       } },
     })
   })
@@ -275,6 +283,17 @@ describe('createFixtureApi', () => {
     expect(types).toContain('assistant/chunk')
     expect(types).toContain('assistant/message')
     expect(types.at(-1)).toBe('turn/end')
+    // Capacity is durable log state, not a transient frame: the prompt path
+    // records request/context and the projection carries it to the client.
+    expect(types).toContain('request/context')
+    expect(frames.some(frame =>
+      frame.type === 'session/projection'
+      && frame.key === 'tokenUsage'
+      && (frame.value as { outputTokens?: number }).outputTokens === 8)).toBe(true)
+    expect(frames.some(frame =>
+      frame.type === 'session/projection'
+      && frame.key === 'contextPressure'
+      && (frame.value as { contextWindow?: number }).contextWindow === 128_000)).toBe(true)
     const finalize = frames.find((f): f is Extract<MuxFrame, { type: 'session/event' }> => f.type === 'session/event' && f.event.type === 'assistant/message')
     expect(JSON.stringify(finalize?.event.data)).toContain('（已中断）')
     // Idle cancel: no replay in flight, must not explode; running flips false.
@@ -306,7 +325,7 @@ describe('createFixtureApi', () => {
       const envelopes: RpcRequest<MuxFrame>[] = []
       for await (const envelope of api.events.mux(req({}), abort.signal)) {
         envelopes.push(envelope)
-        if (envelopes.length >= 8) abort.abort()
+        if (envelopes.length >= 10) abort.abort()
       }
       return envelopes
     }
@@ -314,16 +333,18 @@ describe('createFixtureApi', () => {
     const second = await openOnce()
     expect(first[0]?.payload).toMatchObject({ type: 'session/subscribed', sessionId: 'fx-alpha' })
     expect((first[0]?.payload as { lastSeq: number }).lastSeq).toBeGreaterThan(0)
-    // Projection baseline frames follow the subscribed frame (title + todos + permissions + plan + goal units).
+    // Projection baseline frames follow subscribed (domain units + token usage).
     expect(first[1]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'title', value: 'Fixture 历史会话' })
     expect(first[2]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'todos' })
     expect(first[3]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'permissions' })
     expect(first[4]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'plan', value: { active: false, pending: false } })
     expect(first[5]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'goal', value: null })
-    expect(first[6]?.payload).toMatchObject({ type: 'approval/requested', toolName: 'dangerous_tool' })
-    expect(second[6]?.rpcId).toBe(first[6]?.rpcId) // stable rpcId across replays (host replay semantics)
-    expect(first[7]?.payload).toMatchObject({ type: 'question/requested', sessionId: 'fx-alpha' })
-    expect(second[7]?.rpcId).toBe(first[7]?.rpcId)
+    expect(first[6]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'tokenUsage' })
+    expect(first[7]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'contextPressure' })
+    expect(first[8]?.payload).toMatchObject({ type: 'approval/requested', toolName: 'dangerous_tool' })
+    expect(second[8]?.rpcId).toBe(first[8]?.rpcId) // stable rpcId across replays (host replay semantics)
+    expect(first[9]?.payload).toMatchObject({ type: 'question/requested', sessionId: 'fx-alpha' })
+    expect(second[9]?.rpcId).toBe(first[9]?.rpcId)
   })
 
   it('steer with no replay in flight falls through to a fresh queued turn; non-text blocks stringify empty', async () => {

packages/client/locale/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/locale/README.md
-README.md: c2adbcabc77def740094288da4643032873aa5b8
-README.zh.md: c6ecb31e21d7513a4e7d579b17588107ccd7ea59
+README.md: 7f780092af9bc7079cc5080c06e986bef2dfdbce
+README.zh.md: 62c037977115d33b834fe60b042431e44d208524

packages/client/locale/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Locale plugin: LocaleService — the browser locale preference (`zh`/`en`, persisted under `dsh.locale`; `locale/change` fires on switches only) plus the ns×locale dictionary registry (typed `register(ns, {zh, en})` checked against `LocaleNamespaceMap`, `bind(ns)`→`TranslateNS<ns>`; lookup chain ns → common → zh → key). The service implements the slot system's `LocaleFace` and installs itself through `ctx.slots.installLocale`, backing the framework-injected `t` standard seat (`Translate`/`TranslateNS` are ui-slots types; import them from there — this package only re-exports for dictionary owners' convenience).
+Locale plugin: LocaleService — the browser locale preference (`zh`/`en`, persisted under `dsh.locale`; with nothing persisted a fresh browser opens in the language `navigator` asks for — matched on the primary subtag, `zh` when it asks for none this app ships; `locale/change` fires on switches only) plus the ns×locale dictionary registry (typed `register(ns, {zh, en})` checked against `LocaleNamespaceMap`, `bind(ns)`→`TranslateNS<ns>`; lookup chain ns → common → zh → key). The service implements the slot system's `LocaleFace` and installs itself through `ctx.slots.installLocale`, backing the framework-injected `t` standard seat (`Translate`/`TranslateNS` are ui-slots types; import them from there — this package only re-exports for dictionary owners' convenience).
 
 ## Model Experience
 

packages/client/locale/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-locale 插件：LocaleService——浏览器 locale 偏好（`zh`／`en`，以 `dsh.locale` 持久化；`locale/change` 仅在切换语言时触发），加上 ns×locale 字典注册表（类型化 `register(ns, {zh, en})` 按 `LocaleNamespaceMap` 校验，`bind(ns)`→`TranslateNS<ns>`；查找链 ns → common → zh → key）。该服务实现 slot 系统的 `LocaleFace` 并经 `ctx.slots.installLocale` 自行安装，支撑框架注入的 `t` 标准席位（`Translate`／`TranslateNS` 是 ui-slots 的类型；请从那里导入——本包的再导出仅为字典所有者提供便利）。
+locale 插件：LocaleService——浏览器 locale 偏好（`zh`／`en`，以 `dsh.locale` 持久化；未持久化偏好时，全新浏览器以 `navigator` 请求的语言开场——按主子标签匹配，若其请求的语言本应用都不提供则为 `zh`；`locale/change` 仅在切换语言时触发），加上 ns×locale 字典注册表（类型化 `register(ns, {zh, en})` 按 `LocaleNamespaceMap` 校验，`bind(ns)`→`TranslateNS<ns>`；查找链 ns → common → zh → key）。该服务实现 slot 系统的 `LocaleFace` 并经 `ctx.slots.installLocale` 自行安装，支撑框架注入的 `t` 标准席位（`Translate`／`TranslateNS` 是 ui-slots 的类型；请从那里导入——本包的再导出仅为字典所有者提供便利）。
 
 ## 模型体验
 

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

@@ -83,7 +83,7 @@ declare module 'cordis' {
   }
 }
 
-/** Fallback locale consulted after the active locale misses (also the default). */
+/** Fallback locale consulted after the active locale misses (also the last-resort initial locale). */
 export const FALLBACK_LOCALE: LocaleId = 'zh'
 
 /** Shared namespace for shell-level texts. */
@@ -123,7 +123,7 @@ export class LocaleService {
    */
   constructor(ctx: Context) {
     this.ctx = ctx
-    this.snapshot = Object.freeze({ active: restorePreference(), locales: LOCALES, revision: 0 })
+    this.snapshot = Object.freeze({ active: resolveInitialLocale(), locales: LOCALES, revision: 0 })
   }
 
   /**
@@ -288,17 +288,52 @@ export class LocaleService {
   }
 }
 
-/** Read the persisted locale id; unknown or unreadable values fall back to zh. */
-function restorePreference(): LocaleId {
+/**
+ * The locale a fresh service opens with: an explicit preference the user
+ * already chose wins over the browser's own language, which in turn wins over
+ * {@link FALLBACK_LOCALE} (non-browser boots and browsers set to a language
+ * this app does not ship).
+ */
+function resolveInitialLocale(): LocaleId {
+  return restorePreference() ?? detectBrowserLocale() ?? FALLBACK_LOCALE
+}
+
+/** Read the persisted locale id; unknown or unreadable values read as no preference. */
+function restorePreference(): LocaleId | undefined {
   // Non-browser runs (node e2e booting the client tree) have no localStorage.
-  if (typeof localStorage === 'undefined') return FALLBACK_LOCALE
+  if (typeof localStorage === 'undefined') return undefined
   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.
+    // Storage access can throw (privacy mode); an unreadable store simply
+    // records no preference, and the browser language decides instead.
   }
-  return FALLBACK_LOCALE
+  return undefined
+}
+
+/**
+ * The first shipped locale the browser asks for, matched on the primary
+ * subtag so every regional variant lands on its language (`zh-Hans-CN` -> zh,
+ * `en-GB` -> en). `window` is the browser test, not `navigator`: Node exposes
+ * a global `navigator` reporting the machine's own language, which would
+ * otherwise decide the locale for non-browser runs (node e2e booting the
+ * client tree). `navigator.language` trails the ordered `languages` list and
+ * covers its absence on hosts that expose only the single tag.
+ */
+function detectBrowserLocale(): LocaleId | undefined {
+  if (typeof window === 'undefined') return undefined
+  /* oxlint-disable-next-line typescript/no-unnecessary-condition --
+   * The DOM lib types `languages` as always present; embedders and older
+   * WebViews ship a Navigator without it, and spreading undefined would
+   * throw at boot. Same environment-boundary distrust as the localStorage
+   * guards below. */
+  for (const tag of [...(navigator.languages ?? []), navigator.language]) {
+    const primary = tag.toLowerCase().split('-')[0]
+    const match = LOCALES.find(locale => locale.id === primary)
+    if (match) return match.id
+  }
+  return undefined
 }
 
 /** Persist the locale id; storage failures are non-fatal (preference resets next boot). */

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

@@ -2,7 +2,7 @@
  * 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 { afterEach, beforeEach, describe, expect, it, vi } 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'
@@ -36,6 +36,16 @@ function faceOf(slots: SlotsService) {
 }
 
 describe('locale apply', () => {
+  // A fresh service opens in the browser's language, so these wiring specs
+  // pin one to keep their zh baseline independent of the test environment.
+  beforeEach(() => {
+    vi.stubGlobal('navigator', { languages: ['zh-CN'], language: 'zh-CN' })
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
   it('declares the slot service', () => {
     expect(inject).toEqual(['slots'])
   })

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

@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, 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'
@@ -11,9 +11,26 @@ const make = (): { ctx: Context; svc: LocaleService; events: LocaleSnapshot[] }
   return { ctx, svc: new LocaleService(ctx), events }
 }
 
+/**
+ * Pin the browser environment a fresh service reads its initial locale from.
+ * This package's own specs stub the globals directly instead of using
+ * `usePinnedBrowserLanguages` (dsh-client-test-runtime): they need the shapes
+ * that helper deliberately cannot express — a missing `languages` list, a
+ * list decoupled from `language`, and a non-browser run with no `window`.
+ */
+const stubLanguages = (...tags: string[]): void => {
+  vi.stubGlobal('navigator', { languages: tags, language: tags[0] ?? '' })
+}
+
 describe('LocaleService', () => {
   beforeEach(() => {
     localStorage.clear()
+    // A Chinese browser is the baseline these specs assert their zh state on.
+    stubLanguages('zh-CN')
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
   })
 
   it('translates through the active-locale -> zh -> key chain', () => {
@@ -132,23 +149,51 @@ describe('LocaleService', () => {
     expect(() => { svc.setLocale('fr') }).toThrow('not registered')
   })
 
-  it('restores a persisted locale and falls back to zh on garbage', () => {
+  it('restores a persisted locale over the browser language, and garbage reads as no preference', () => {
     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', () => {
+  it('opens in the browser language when nothing is persisted, matching regional variants on their primary subtag', () => {
+    stubLanguages('en-GB', 'zh-CN')
+    expect(make().svc.getLocale().active).toBe('en')
+    stubLanguages('zh-Hant-TW')
+    expect(make().svc.getLocale().active).toBe('zh')
+    // An unshipped language walks the list to the first one this app ships.
+    stubLanguages('fr-FR', 'en-US')
+    expect(make().svc.getLocale().active).toBe('en')
+    // Only `language` populated: an empty ordered list, and a host that
+    // exposes no `languages` property at all.
+    vi.stubGlobal('navigator', { languages: [], language: 'en-US' })
+    expect(make().svc.getLocale().active).toBe('en')
+    vi.stubGlobal('navigator', { language: 'en-US' })
+    expect(make().svc.getLocale().active).toBe('en')
+    // No shipped language anywhere in the browser's preferences: zh remains
+    // the product default rather than an arbitrary near-match.
+    stubLanguages('fr-FR', 'de')
+    expect(make().svc.getLocale().active).toBe('zh')
+  })
+
+  it('runs outside a browser (node boots): the fallback decides, the machine language does not, writes no-op', () => {
     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()
-    }
+    vi.stubGlobal('window', undefined)
+    // Node exposes its own global navigator; without a window it must not
+    // reach the resolution at all.
+    stubLanguages('en-US')
+    const { svc } = make()
+    expect(svc.getLocale().active).toBe('zh')
+    svc.setLocale('en')
+    expect(svc.getLocale().active).toBe('en')
+  })
+
+  it('keeps the browser language out of the way once a preference exists', () => {
+    stubLanguages('en-US')
+    const { svc } = make()
+    svc.setLocale('zh')
+    expect(localStorage.getItem(STORAGE_KEY)).toBe('zh')
+    expect(make().svc.getLocale().active).toBe('zh')
   })
 
   it('exposes the two shipped locales with self-described labels', () => {

packages/client/test-runtime/src/index.ts

@@ -38,6 +38,7 @@ export { TestWorkspaces } from './workspaces.ts'
 export { conversationSnapshot, workspaceListState } from './fixtures.ts'
 export type { SessionBehaviorOverrides, SessionFixture, Stabilizer } from './fixtures.ts'
 export { makeTranslate } from './translate.ts'
+export { usePinnedBrowserLanguages } from './locale-env.ts'
 
 /** Erased register face for the internal root call (the public declare seam holds the typing). */
 type ErasedRegister = (options: object, component: unknown) => () => void

packages/client/test-runtime/src/locale-env.ts

@@ -0,0 +1,29 @@
+/**
+ * Browser-language pin for specs that assert localized copy. A fresh
+ * LocaleService with no stored preference opens in the language `navigator`
+ * asks for, and jsdom reports the runner's own (`en-US`) — so a spec asserting
+ * the product's Chinese copy states the browser it assumes instead of
+ * inheriting the machine's.
+ */
+import { afterEach, beforeEach } from 'vitest'
+
+/**
+ * Pin `navigator.languages`/`navigator.language` for every test in the
+ * calling file (or describe block), restoring the environment's own values
+ * afterwards. Call at suite level, like the other vitest hooks.
+ * @param primary - most preferred BCP 47 tag; also becomes `navigator.language`.
+ * @param rest - further tags in preference order.
+ */
+export function usePinnedBrowserLanguages(primary: string, ...rest: string[]): void {
+  beforeEach(() => {
+    Object.defineProperty(navigator, 'languages', { value: [primary, ...rest], configurable: true })
+    Object.defineProperty(navigator, 'language', { value: primary, configurable: true })
+  })
+  afterEach(() => {
+    // Deleting the own properties uncovers the environment's own accessors
+    // again (Navigator declares both readonly, hence the erased receiver).
+    const own = navigator as unknown as Record<string, unknown>
+    delete own.languages
+    delete own.language
+  })
+}

packages/client/ui-conversation/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-conversation/README.md
-README.md: 7552e198190a2736092299953dfff61be9a07147
-README.zh.md: 7af337c03305d1da7019869befdd9cbf65584eac
+README.md: 66120f222de4b4d4707430a1ec310c6fe801c0c5
+README.zh.md: f5e953f363733341400a292a1946b4e298858b77

packages/client/ui-conversation/README.md

@@ -24,6 +24,8 @@ A tool call declaring the `diff` render intent (the `write`/`edit` tools) render
 
 The chat flow projects consecutive model-retry nodes across retry turns into one stable, muted status row updated to the latest attempt; every retry event remains in the runtime snapshot and session log. Its frontend countdown anchors the scheduled delay to client receipt, avoiding host/browser clock skew, rounds remaining time up to seconds, and has a one-second floor. The latest unresolved retry uses a left-to-right text shimmer. Subsequent turn facts distinguish an attempt that started from one cancelled during backoff, while the Host running bit only controls the live animation; the row then shows a static completed or cancelled label. Normal policy rows show the finite retry maximum; always policy rows show `∞`. Activating the row reveals the latest exact retry delay and failure message. The client runtime removes each failed step's streaming tail before its retry node arrives, while the status remains visible after a later attempt succeeds.
 
+A `grep`/`glob` call declaring the `search` render intent renders its result inline, at the same render sites, through ui-primitives' `SearchBlock` — grep's matches grouped by file (each a collapsible header of `lineNumber: line` rows), glob's flat path list. `contract/search-card-model.ts` is the single derivation from the snapshot's `resultView`; unlike the terminal card it reads no `callView`, since a search has no matches or paths before `execute`, so a running search shows its summary alone. It yields null — the generic path — for any non-search result view, a `card` or `kind` this client version does not compile, and (because those ride the untrusted wire frame) a known kind whose `files`/`paths` is malformed. The keyed `SearchRow`, registered under both `grep` and `glob` since the derived `kind` decides the shape, carries the card resident below its summary; the render-site fallback keeps it behind the expand control. Both cap at `CHAT_SEARCH_MAX_LINES` (8) against the panel's 16. A capped search drops rows from the card, but the locator to the rest — grep/glob's `Full … stored at …` footer — lives only in the result text, so the derivation surfaces that as a recovery footer below the card when (and only when) the result was truncated; a settled call with no card at all (an errored search, a nested `run_code` sub-dispatch, a legacy generic result) falls back to its flattened result text so nothing is lost behind a bare summary ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md)).
+
 Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.toolviews`/outlet) is retired. The chat entry declares the keyed `'conversation.chat.toolview'` hole (session scope; the key space is runtime-open); its render site dispatches per row via `entryKey: toolName` with `GenericToolCard` as the call-site `fallback`. The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openFile`) and `ToolRowProps` pre-composes it with the session standard kit. A registrant is a plain plugin: `ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)` with `inject: ['slots', 'conversation']` as the load-order seam (apply mounts ConversationService after the chat registration, so the service being present guarantees the slot is declared); session differentiation happens inside the component (`useSessions` reading `parentId` — the bash sample is the third-party-posture exemplar). Trajectory/waterfall toolview slots share this shape and land with their own render sites (RendersCheck rejects a declaration nobody renders).
 
 The todo surfaces are two registrations over that shape, both plain registrant plugins with `inject: ['slots', 'conversation']`. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> 已完成 · <active item>` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: -1` — above the queue rows — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus `"<done>/<total> tasks · <n> in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
@@ -34,6 +36,8 @@ Per-session UI state for selection and the active view lives in the declared cha
 
 The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop button), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The leading plus button is a Command launcher, not an attachment surface: it asks the session's `SlashController` to open only the `/` trigger's `command` source over the current textarea selection, while ui-slash's existing `MenuView` remains the sole floating menu and pick path. No file row, file input, upload protocol, or second menu component is introduced. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `conversation` locale namespace this package registers (the `placeholder.plan` / `hint.plan` keys) and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar renders inert (machine faces absent, `disabled` owner prop) instead of swapping in a parallel disabled tree, so the textarea DOM survives the workspace pick; the strict-session control seats simply stay empty until a session exists.
 
+The chat stats line takes its token accounting from two generic token-meter projections read through the standard-kit `useProjection`: `tokenUsage` for full-log billing (billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total) and `contextPressure` for context occupancy. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. A deployment without token-meter drops the token groups, and occupancy stays hidden until both provider pressure and route capacity are known. Occupancy is deliberately an approximation — its numerator and capacity are independent last-wins projection fields, not one atomic request observation ([rationale](../../llm/token-meter/README.md)). The inline stats row remains the sole context UI; the model selector has no circle or accessory.
+
 `src/client/` is organized for the future package split: `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations + composed slot props including the tool-row contract, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` (sample registrants) domain directories import contract files and never each other; `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components (skeleton, chat rows) and the store factory stay internal and reach the page exclusively through apply's slot registrations (tests take them via the `./src/*` subpath).
 
 ## Model Experience
@@ -50,6 +54,7 @@ None; this package neither assembles nor sends a provider request.
 - **Stats-line durations cover the in-window flow only** — LLM and tool wall times fold the snapshot's assistant `timing` and tool call/result pairs, so nodes outside the loaded event window (older history) are not counted.
 - **Details panel is the minimal form and currently has no entry point** — selected call args/result raw display; the Input/Output/Metadata switch, Prev/Next stepping, and See-in-trajectory deep link are deferred. Tool rows stopped being details-panel click targets and nothing replaced that gesture, so `ChatViewInjected.openDetails` is implemented but uncalled and the panel (including its terminal card) is unreachable in the assembled application; its rendering stays covered by mounting it with a selection directly.
 - **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / branch / clock) ships under the last content-text assistant of each turn only; mid-turn narration and Think-only nodes stay chrome-free. Branch forks through the turn containing that message, increments the inherited title on the client, and then opens the child, while a fork or rename failure leaves the source selected.
+- **Sent user messages cannot be edited** — the user bubble's IconActions row carries clock / copy / branch only, and branching from the message is the nearest gesture. The control returns with the capability behind it: a client mutation over a settled user message, plus the host behavior for the turn that already consumed it ([decision](../../../.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.md)).
 - **The sparkle icon for the others tool row is a hand-drawn approximation** — the design glyph's vector geometry is not exportable locally; promotion into ui-primitives waits on an exact export.
 - **The approval panel's "Always allow this type" is deferred** — durable grants need a grant-storage design; only allow-once/reject answer today.
 - **TodoPanel truncates long item text to one ellipsized line** — the figma strip has no wrap or expand affordance; full text is not readable inline.

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

@@ -22,6 +22,8 @@
 
 聊天流会将跨重试轮次连续出现的模型重试节点投影为一个稳定的弱化状态行，并用最新一次尝试更新该行；每个重试事件仍保留在运行时快照与会话日志中。前端倒计时以客户端收到事件的时刻为计划延迟的起点，避免 Host 与浏览器的时钟偏差；剩余时间向上取整到秒，且下限为 1 秒。最近一次尚未完成的重试会显示从左到右的文字渐变动画。后续轮次事实用于区分已开始的尝试与在退避期间取消的尝试，Host 的 running 位只控制实时动画；随后该行会显示静态的已完成或已取消标签。normal 策略行显示有限重试上限；always 策略行显示 `∞`。激活该行会显示最近一次重试的精确延迟和失败消息。客户端运行时会在相应重试节点到达前移除每个失败步骤的流式输出尾部；后续某次尝试成功后，该状态仍保持可见。
 
+声明 `search` 渲染意图的 `grep`／`glob` 调用，会在同样的渲染点上通过 ui-primitives 的 `SearchBlock` 内联渲染其结果——grep 的匹配按文件分组（每个是一个可折叠的头，下辖 `lineNumber: line` 行），glob 是扁平路径列表。`contract/search-card-model.ts` 是从快照的 `resultView` 推导的唯一位置；与终端卡片不同，它不读 `callView`，因为搜索在 `execute` 前没有匹配或路径，所以运行中的搜索只显示摘要。对任何非搜索的结果视图、当前客户端版本无法编译的 `card` 或 `kind`、以及（因为这些都与不可信的 wire 帧同行）一个 `files`／`paths` 格式错误的已知 kind，它都返回 null，落回通用路径。键控的 `SearchRow` 因推导出的 `kind` 决定形态而同时注册在 `grep` 与 `glob` 下，把卡片常驻在摘要行下方；渲染点兜底行则把它保持在展开控件之后。两者上限都是 `CHAT_SEARCH_MAX_LINES`（8），面板为 16。被截断的搜索会从卡片里丢掉一些行，但通往其余部分的定位符——grep/glob 的 `Full … stored at …` 脚注——只存在于结果文本里，因此推导在（且仅在）结果被截断时把它作为恢复脚注画在卡片下方；一个完全没有卡片的已结算调用（出错的搜索、嵌套 `run_code` 子派发、旧日志的 generic 结果）则回退到其压平后的结果文本，从而不让任何内容丢失在一个光秃秃的摘要之后（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md)）。
+
 工具行同样是 slot：独立工具环（`ToolViewRegistry`／`ctx.toolviews`／outlet）已经退役。聊天配置项声明键控的 `'conversation.chat.toolview'` 空位（Session scope；key 空间在运行时开放）；其渲染点逐行通过 `entryKey: toolName` 分发，并以 `GenericToolCard` 作为调用点 `fallback`。owner 载荷是统一的 `ToolRowOwnerProps`（`callId`／`toolName`／`block`／`openFile`），`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 会拒绝没有任何渲染方的声明）。
 
 审批经由本包声明的链接管编辑器：`ApprovalPanel` 注册为按选择器路由的 `'conversation.composer'` 配置项（ui-question 模式），在审批等待未决期间取代 InputBar 占据编辑器（琥珀色条、理由标题、来自运行中调用参数的配对命令行、一次性的拒绝／允许）。`contract/slots.ts` 中的 `PendingApproval` 领域面在运行时 `PendingWait` 载体之上拥有 wire 编码——带审计关联的 `ApprovalResponsePayload` 值；广播的 `approval/resolved` 帧使等待落定并恢复编辑器。侧边栏通过 manager 跟踪的 `waitingApproval` 列表位（未实例化会话同样点亮）镜像该阻塞状态，其优先级高于运行中圆环，直至问题解决。未决等待完全离开消息流：问题（ui-question）与审批（ApprovalPanel）都经编辑器接管作答，不再保留只读占位卡。编辑器底行的 Access 席位挂载 `PermissionSelect`，由 host 计算的 `permissions` 投影经标准工具包 `useProjection` 供数（key 缺席即隐藏 chip）；chip 打开 Menu 原语下拉，其中 kebab-case 预设名渲染为 Title Case 标签；普通安全预设会立即经输入栏注入的 `command` 回调提交 `/permission <preset>`，而 `danger-full-access` 在界面中显示为 `Full access`，选择后先打开页面内的 Modal 风险确认。用户勾选确认项前启用按钮始终不可用；取消、Escape、关闭按钮与点击遮罩都不会提交命令。
@@ -34,6 +36,8 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插
 
 输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止按钮之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。前置加号按钮是 Command launcher，而非附件入口：它要求当前会话的 `SlashController` 基于 textarea 当前 selection，只打开 `/` trigger 的 `command` source，同时 ui-slash 既有的 `MenuView` 仍是唯一的浮层菜单与 pick 路径。不引入 File 行、file input、上传协议或第二套菜单组件。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `conversation` locale 命名空间（`placeholder.plan` / `hint.plan` 键）本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。
 
+聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的两个通用 token-meter 投影：`tokenUsage` 提供完整日志计费用量（计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量），`contextPressure` 提供上下文占用率。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。未组合 token-meter 的部署会整组省略 token 分组；只有提供方压力与路由容量都已知时才显示占用率。占用率是刻意为之的近似值：它的分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测（[原理](../../llm/token-meter/README.md)）。行内统计行仍是唯一的上下文 UI；模型选择器不增加圆环或附属控件。
+
 `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/*` 子路径获取它们）。
 
 ## 模型体验
@@ -47,9 +51,10 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插
 ## 已知限制与暂缓事项
 
 - **压缩标记不显示规模**：该行尚不报告检查点替换了多少条消息或哪段范围。
-- **统计行的耗时只覆盖窗口内消息流**：LLM（大语言模型）与工具墙钟时间由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。
+- **统计行的耗时只覆盖窗口内消息流**：LLM 与工具墙钟时间由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。
 - **详情面板是最小形态，且当前没有入口**：以原始形式显示已选择调用的参数／结果；Input/Output/Metadata 切换、Prev/Next 步进与 See-in-trajectory 深链接暂缓实现。工具行已不再是详情面板的点击目标，且没有任何手势接替它，因此 `ChatViewInjected.openDetails` 虽已实现却无人调用，该面板（含其终端卡片）在组装后的应用中不可达；其渲染仍由直接以选中态挂载它来覆盖。
 - **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／分支／时钟）只挂在每个轮次中最后一条带 text 内容的 assistant 下；轮次中间的叙述与纯 Think 节点不带 chrome。分支会 fork 到包含该消息的轮次末尾，在 client 端递增继承标题后打开子会话，而 fork 或改名失败时源会话保持选中。
+- **已发送的 user 消息无法编辑**：user 气泡的 IconActions 行只有时钟／复制／分支，从该消息分支是最接近的手势。该控件要与其背后的能力一起回归：既需要针对已定稿 user 消息的 client 变更，也需要 host 侧对已经消费过它的轮次给出行为（[决策](../../../.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.md)）。
 - **others 工具行的闪光图标是手绘近似版本**：无法在本地导出设计字形的矢量几何；等到存在精确导出后再将其提升到 ui-primitives。
 - **审批面板的「始终允许此类」暂缓**：持久授权需要授权存储设计；今天只能回答允许一次／拒绝。
 - **TodoPanel 将过长条目截成单行省略号**：figma 条没有换行或展开入口，完整文本无法在行内读完。

packages/client/ui-conversation/package.json

@@ -45,12 +45,14 @@
     "@deepseek-ai/dsh-client-ui-slash": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-token-meter": "^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-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-plan-mode": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
@@ -60,6 +62,7 @@
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-permission": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
     "@deepseek-ai/dsh-tool-todo": "workspace:^",
     "@types/react": "~18.3.1",
     "cordis": "^4.0.0-rc.7",

packages/client/ui-conversation/src/client/apply.ts

@@ -20,6 +20,8 @@ import { InputBar } from './skeleton/InputBar.tsx'
 import { ChatView } from './chat/ChatView.tsx'
 import { StatsLine } from './chat/StatsLine.tsx'
 import { bashToolviewSample } from './toolviews/bash-sample.tsx'
+import { searchToolview } from './toolviews/search-row.tsx'
+import { readToolview } from './toolviews/read-row.tsx'
 import { fileMutationToolview } from './toolviews/file-mutation-row.tsx'
 import { webToolview } from './toolviews/web-row.tsx'
 import { ApprovalPanel } from './skeleton/ApprovalPanel.tsx'
@@ -320,6 +322,14 @@ export function apply(ctx: Context): void {
   // (ToolRow-matching Bash · {description} chrome; scoped badge in child sessions).
   ctx.plugin(bashToolviewSample)
 
+  // The grep/glob search row rides the same seam: one component registered
+  // under both tool names, since both declare the same search render intent.
+  ctx.plugin(searchToolview)
+
+  // The read row rides the same seam (a product registration, not a sample):
+  // Read · {path} chrome with the file's read card resident below it.
+  ctx.plugin(readToolview)
+
   // The write/edit rows ride the same seam: a file-mutation call declares the
   // diff render intent, so these rows stack the applied diff card under their
   // path-link summary (the terminal card's posture, applied to diffs).

packages/client/ui-conversation/src/client/chat/GenericToolCard.module.css

@@ -1,7 +1,8 @@
-/* The generic card grows a resident web card under its summary row when the
-   tool declares the `web` render intent but has no keyed row of its own (the
-   web_search/web_fetch rows register their own WebRow). A column around the
-   ToolRow keeps the row's own 24px height. */
+/* GenericToolCard resident cards: a read-declaring or web-declaring tool
+   without its own keyed row (e.g. web_fetch) grows a resident card under its
+   summary row. A column around the ToolRow keeps the row's own 24px height, so
+   the read card renders identically to the keyed ReadRow and the web card to
+   the web_search/web_fetch WebRow. */
 
 .card {
   display: flex;
@@ -10,6 +11,7 @@
 
 /* Row indentation matches ToolRow's expanded bodies (16px leading + 6px gap),
    and replaces the primitive's standalone vertical margin with the flow's. */
+.read,
 .web {
   margin: 4px 0 4px 22px;
 }

packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx

@@ -7,9 +7,11 @@
 import type { ReactNode } from 'react'
 import {
   IconApiOutline14, IconBrowseOutline16, IconCodeOutline16, IconEditOutline16, IconSearchOutline16, IconSparkle16,
-  IconThinkOutline14, WebBlock,
+  IconThinkOutline14, ReadBlock, WebBlock,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps, ToolRowOwnerProps } from '../contract/slots.ts'
+import { searchCardModel } from '../contract/search-card-model.ts'
+import { CHAT_READ_MAX_LINES, readCardModel } from '../contract/read-card-model.ts'
 import { diffCardModel } from '../contract/diff-card-model.ts'
 import { terminalCardModel, terminalFailed } from '../contract/terminal-card-model.ts'
 import { CHAT_WEB_MAX_SOURCES, webCardModel } from '../contract/web-card-model.ts'
@@ -37,6 +39,8 @@ export interface GenericToolCardProps extends ToolRowOwnerProps {
 export function GenericToolCard({ toolName, block, cwd, openFile, inspect, t }: GenericToolCardProps) {
   const model = toolRowModel(toolName, block, cwd)
   const terminal = terminalCardModel(block, cwd)
+  const search = searchCardModel(block)
+  const read = readCardModel(block, cwd)
   const diff = diffCardModel(block)
   const web = webCardModel(block)
   // A failing exit status is the terminal card's own error signal (the call
@@ -53,8 +57,9 @@ export function GenericToolCard({ toolName, block, cwd, openFile, inspect, t }:
       icon={VARIANT_ICONS[model.variant]}
       title={model.title}
       // A terminal presenter's description is the contract's above-card text, so
-      // it outranks the args-derived summary here exactly as it does in BashRow.
-      summary={terminal?.description ?? model.summary}
+      // it outranks the args-derived summary here exactly as it does in BashRow;
+      // a search result view's replacement title outranks it the same way.
+      summary={terminal?.description ?? search?.title ?? model.summary}
       // Single-file tools never expose an args body — the path link is the only
       // args interaction. A diff card is not an args body: a write/edit row is
       // single-file AND carries a diff, so the card expands under the path link.
@@ -62,6 +67,7 @@ export function GenericToolCard({ toolName, block, cwd, openFile, inspect, t }:
       output={model.output}
       errorSummary={model.errorSummary}
       terminal={terminal}
+      search={search}
       diff={diff}
       state={state}
       filePath={model.filePath}
@@ -69,6 +75,18 @@ export function GenericToolCard({ toolName, block, cwd, openFile, inspect, t }:
       inspect={inspect}
     />
   )
+  // A read-declaring tool without its own keyed row lands here (e.g. web_fetch),
+  // so the file's read card is resident below the summary row exactly as the
+  // keyed ReadRow draws it. Only wrap when a card is present, so every other
+  // tool keeps the bare ToolRow.
+  if (read !== null) {
+    return (
+      <div className={css.card}>
+        {row}
+        <ReadBlock {...read} maxLines={CHAT_READ_MAX_LINES} className={css.read} />
+      </div>
+    )
+  }
   // A web-declaring tool without its own keyed row lands here; its card is
   // resident under the summary, mirroring WebRow (and BashRow's terminal card).
   if (web === null) return row

packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx

@@ -1,10 +1,9 @@
 // Shared IconActions chrome for user and assistant messages: copy live,
-// branch wired through onBranch, date-aware clock,
-// optional edit stub.
+// branch wired through onBranch, date-aware clock.
 
 import { useCallback } from 'react'
 import {
-  IconBranchOutline16, IconCopyOutline16, IconEditOutline16, Tooltip,
+  IconBranchOutline16, IconCopyOutline16, Tooltip,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
 import { formatMessageClock, writeClipboard } from './message-chrome.ts'
@@ -18,8 +17,6 @@ export interface MessageIconActionsProps {
   time: number
   /** Clock before icons (user) or after (assistant). */
   clock: 'start' | 'end'
-  /** When true, append the stub edit control (user bubble). */
-  edit?: boolean | undefined
   /** Fork the session at this message. */
   onBranch?: (() => void) | undefined
   /** Parent layout class composed onto the actions row. */
@@ -30,11 +27,11 @@ export interface MessageIconActionsProps {
 
 /**
  * Copy / branch (/ clock) IconActions row shared by user and assistant chrome.
- * @param props - Copy text, event time, clock side, optional edit, branch callback, className.
+ * @param props - Copy text, event time, clock side, branch callback, className.
  * @returns The actions row element.
  */
 export function MessageIconActions({
-  text, time, clock, edit, onBranch, className, t,
+  text, time, clock, onBranch, className, t,
 }: MessageIconActionsProps) {
   const day = useCalendarDay()
   const onCopy = useCallback(() => {
@@ -58,13 +55,6 @@ export function MessageIconActions({
           <IconBranchOutline16 />
         </button>
       </Tooltip>
-      {edit === true && (
-        <Tooltip label={t('edit')} side="bottom">
-          <button type="button" className={css.action} aria-label={t('edit')}>
-            <IconEditOutline16 />
-          </button>
-        </Tooltip>
-      )}
       {clock === 'end' ? clockEl : null}
     </div>
   )

packages/client/ui-conversation/src/client/chat/MessageItem.tsx

@@ -1,5 +1,5 @@
 // MessageItem: simple chat nodes — user bubble (right-aligned, with
-// clock + copy / branch / edit IconActions), steering (badged bubble), context
+// clock + copy / branch IconActions), steering (badged bubble), context
 // injection, compaction marker, retry disclosure, and unknown-surface JSON rows.
 
 import { memo, useEffect, useMemo, useState } from 'react'
@@ -158,7 +158,6 @@ export const MessageItem = memo(function MessageItem({
             text={text}
             time={node.time}
             clock="start"
-            edit
             onBranch={onFork === undefined ? undefined : () => { onFork(node.seq) }}
             className={css.actions}
             t={t}

packages/client/ui-conversation/src/client/chat/StatsLine.tsx

@@ -3,43 +3,35 @@
 // active conversation scrollport (see ConversationRoot data-conversation-scroll).
 
 import { Fragment, memo, useMemo } from 'react'
-import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConversationSnapshot, UseProjection } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
 import css from './StatsLine.module.css'
 
-interface UsageTotals {
+interface WindowStats {
   turns: number
   steps: number
   /** Summed request wall time (step/start → assistant/message); 0 when no node carries timing. */
   llmMs: number
   /** Summed tool wall time (tool/call → tool/result); 0 when no pair is in-window. */
   toolMs: number
-  /** Prompt-side tokens: inputTokens + cacheReadTokens. */
-  inputTokens: number
-  outputTokens: number
-  cacheHitPct: number | null
-}
-
-/** Token accounting slice of assistant `usage` (typed upstream as unknown). */
-interface UsageLike {
-  inputTokens?: number
-  outputTokens?: number
-  cacheReadTokens?: number
 }
 
 /**
- * Fold assistant and tool-result nodes into display totals.
+ * Fold assistant and tool-result nodes into the window-scoped display totals.
+ *
+ * Counts and wall times describe the loaded window on purpose — they answer
+ * "what is on screen". Token accounting deliberately does NOT come from here:
+ * the window is paged and compaction rewrites it, so billing rides the durable
+ * `tokenUsage` projection instead.
  * @param nodes - snapshot nodes.
- * @returns totals; cacheHitPct null until any cache accounting arrives.
+ * @returns visible counts and summed wall times.
  */
-export function deriveStats(nodes: ConversationSnapshot['nodes']): UsageTotals {
+export function deriveStats(nodes: ConversationSnapshot['nodes']): WindowStats {
   const turns = new Set<number>()
   let steps = 0
   let llmMs = 0
   let toolMs = 0
-  let input = 0
-  let output = 0
-  let cacheRead = 0
   for (const node of nodes) {
     if (node.kind === 'tool-result') {
       if (node.callTime !== null) toolMs += Math.max(0, node.time - node.callTime)
@@ -51,22 +43,8 @@ export function deriveStats(nodes: ConversationSnapshot['nodes']): UsageTotals {
     if (node.timing !== undefined && node.timing.stepStartTime !== null) {
       llmMs += Math.max(0, node.timing.completedTime - node.timing.stepStartTime)
     }
-    const usage = node.usage as UsageLike | undefined
-    if (usage === undefined) continue
-    input += usage.inputTokens ?? 0
-    output += usage.outputTokens ?? 0
-    cacheRead += usage.cacheReadTokens ?? 0
-  }
-  const denom = input + cacheRead
-  return {
-    turns: turns.size,
-    steps,
-    llmMs,
-    toolMs,
-    inputTokens: input + cacheRead,
-    outputTokens: output,
-    cacheHitPct: denom === 0 ? null : Math.round((cacheRead / denom) * 100),
   }
+  return { turns: turns.size, steps, llmMs, toolMs }
 }
 
 /**
@@ -94,21 +72,82 @@ export function formatDuration(ms: number): string {
   return `${Math.floor(whole / 60)}m${whole % 60}s`
 }
 
-/** Props: the conversation-snapshot selector (dock registration or unit mount). */
-export interface StatsLineProps { useSession: SnapshotSelectorHook<ConversationSnapshot> }
+/**
+ * Cache-hit share of prompt-side input over the whole durable log.
+ * @param usage - the session's token-usage projection value.
+ * @returns rounded integer percent, or null when no input was billed.
+ */
+export function cacheHitPercent(usage: TokenUsageProjection): number | null {
+  const denominator = billedInputTokens(usage)
+  return denominator === 0
+    ? null
+    : Math.round(usage.cacheReadTokens / denominator * 100)
+}
 
-export const StatsLine = memo(function StatsLine({ useSession }: StatsLineProps) {
+/** Sum the three disjoint prompt-side billing buckets. */
+function billedInputTokens(usage: TokenUsageProjection): number {
+  return usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
+}
+
+interface ContextOccupancy {
+  percent: number
+  contextWindow: number
+}
+
+/**
+ * Approximate context occupancy, using the TUI's integer rounding and upper
+ * clamp. The numerator and capacity are independent last-wins projection
+ * fields, so this is a reference figure rather than an exact measurement of one
+ * request (see the token-meter README).
+ * @param pressure - the session's context-pressure projection value.
+ * @returns occupancy and its denominator, or null until both values are known.
+ */
+export function contextOccupancy(
+  pressure: ContextPressureProjection | undefined,
+): ContextOccupancy | null {
+  if (pressure?.pressureTokens === undefined || pressure.contextWindow === undefined) return null
+  return {
+    percent: Math.min(100, Math.round(pressure.pressureTokens / pressure.contextWindow * 100)),
+    contextWindow: pressure.contextWindow,
+  }
+}
+
+/** Props: the conversation-snapshot selector plus the projection read seat. */
+export interface StatsLineProps {
+  useSession: SnapshotSelectorHook<ConversationSnapshot>
+  useProjection: UseProjection
+}
+
+export const StatsLine = memo(function StatsLine({ useSession, useProjection }: StatsLineProps) {
   const nodes = useSession(s => s.nodes)
+  const usage = useProjection('tokenUsage')
+  const pressure = useProjection('contextPressure')
   const stats = useMemo(() => deriveStats(nodes), [nodes])
-  if (stats.steps === 0) return null
   // Pipe-separated groups (figma stats strip); a group with no data drops out whole.
-  const groups: string[] = [`${stats.turns} turns · ${stats.steps} steps`]
-  const durations: string[] = []
-  if (stats.llmMs > 0) durations.push(`LLM ${formatDuration(stats.llmMs)}`)
-  if (stats.toolMs > 0) durations.push(`Tool call ${formatDuration(stats.toolMs)}`)
-  if (durations.length > 0) groups.push(durations.join(' · '))
-  if (stats.cacheHitPct !== null) groups.push(`Cache hit ${stats.cacheHitPct}%`)
-  groups.push(`Input ${formatTokens(stats.inputTokens)} tok · Output ${formatTokens(stats.outputTokens)} tok`)
+  const groups: string[] = []
+  if (stats.steps > 0) {
+    groups.push(`${stats.turns} turns · ${stats.steps} steps`)
+    const durations: string[] = []
+    if (stats.llmMs > 0) durations.push(`LLM ${formatDuration(stats.llmMs)}`)
+    if (stats.toolMs > 0) durations.push(`Tool call ${formatDuration(stats.toolMs)}`)
+    if (durations.length > 0) groups.push(durations.join(' · '))
+  }
+  const context = contextOccupancy(pressure)
+  if (context !== null) {
+    groups.push(`Context ${context.percent}% of ${formatTokens(context.contextWindow)}`)
+  }
+  // Billing rides the durable projection, so these survive paging and
+  // compaction. Suppress the empty projection on a brand-new session.
+  if (usage !== undefined
+    && (stats.steps > 0 || billedInputTokens(usage) > 0 || usage.outputTokens > 0)) {
+    const cacheHit = cacheHitPercent(usage)
+    if (cacheHit !== null) groups.push(`Cache hit ${cacheHit}%`)
+    groups.push(
+      `Input ${formatTokens(billedInputTokens(usage))} tok`
+      + ` · Output ${formatTokens(usage.outputTokens)} tok`,
+    )
+  }
+  if (groups.length === 0) return null
   return (
     <div className={css.root}>
       {groups.map((group, i) => (

packages/client/ui-conversation/src/client/chat/ToolRow.module.css

@@ -246,17 +246,29 @@
   color: var(--dsw-alias-state-error-primary);
 }
 
-/* The two block-shaped expanded bodies: the code variant's run_code program
-   through CodeBlock (shiki-highlighted TypeScript) and a terminal card's
-   command output through TerminalBlock. Both are drawn by the shared
-   primitive, so only the row's indentation is this file's concern — the margin
-   also replaces each primitive's own standalone vertical spacing with the
-   flow's row rhythm. */
+/* The block-shaped expanded bodies: the code variant's run_code program
+   through CodeBlock (shiki-highlighted TypeScript), a terminal card's command
+   output through TerminalBlock, and a search card's grouped matches or path
+   list through SearchBlock. All are drawn by the shared primitive, so only the
+   row's indentation is this file's concern — the margin also replaces each
+   primitive's own standalone vertical spacing with the flow's row rhythm. */
 .codeBody,
-.terminalBody {
+.terminalBody,
+.searchBody {
   margin: 4px 0 4px 4px;
 }
 
+/* The recovery footer for a capped search: the result text (its `Full … stored
+   at …` locator) below the card in the muted tone, since the card holds only the
+   retained rows. Same column indent as the card body. */
+.searchRecovery {
+  margin: 4px 0 4px 4px;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-tertiary);
+}
+
 /* A write/edit diff renders through DiffBlock; like the terminal card it draws
    its own surface, so only the row indentation is this file's concern. */
 .diffBody {

packages/client/ui-conversation/src/client/chat/ToolRow.tsx

@@ -3,23 +3,25 @@
 // separator dot + FILL-truncated summary, drawn through the shared
 // DisclosureRow chrome with the whole row as the expand toggle (click /
 // Enter / Space, icon→chevron hover preview). The collapsed row is always
-// one line; every row with body, output, or terminal material is expandable;
-// the summary stays inline while open, except Think, whose body opens with
-// the same first line and would repeat it.
+// one line; every row with body, output, terminal, or search material is
+// expandable; the summary stays inline while open, except Think, whose body
+// opens with the same first line and would repeat it.
 // The expanded body — an IN/OUT gutter-labeled card (figma 1249:35657) for
-// text input/output, the run_code program through CodeBlock, or a terminal
-// card's command output through TerminalBlock — lives in a max-height scroll
-// container so a long payload scrolls internally instead of taking over the
-// message flow; Think's prose is the exception and flows uncapped like
-// message text. Expand state is component-local view state. File-tool
-// summaries are path links that open through the host (stopPropagation keeps
-// the two gestures independent); an error row's collapsed summary is the
+// text input/output, the run_code program through CodeBlock, a terminal
+// card's command output through TerminalBlock, or a search card's grouped
+// matches / path list through SearchBlock (capped at CHAT_SEARCH_MAX_LINES) —
+// lives in a max-height scroll container so a long payload scrolls internally
+// instead of taking over the message flow; Think's prose is the exception and
+// flows uncapped like message text. Expand state is component-local view state.
+// File-tool summaries are path links that open through the host (stopPropagation
+// keeps the two gestures independent); an error row's collapsed summary is the
 // failure's first line in the error color.
 
 import { useState, type MouseEvent, type ReactNode } from 'react'
 import clsx from 'clsx'
-import { CodeBlock, DiffBlock, StateDot, TerminalBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import { CodeBlock, DiffBlock, SearchBlock, StateDot, TerminalBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../contract/search-card-model.ts'
 import { CHAT_DIFF_MAX_LINES, type DiffCardModel } from '../contract/diff-card-model.ts'
 import { terminalBlockLabels, type TerminalCardModel } from '../contract/terminal-card-model.ts'
 import type { ToolRowState, ToolRowVariant } from '../contract/tool-call-model.ts'
@@ -49,10 +51,17 @@ export interface ToolRowProps {
    * expandable.
    */
   terminal?: TerminalCardModel | null | undefined
+  /**
+   * Search-card material for a call whose render intent is a search card
+   * (derived by `searchCardModel`); it replaces the text body when present.
+   * Null or absent leaves the text body. A call carries at most one card kind,
+   * so `terminal`, `search`, and `diff` are never both present on the same row.
+   */
+  search?: SearchCardModel | null | undefined
   /**
    * Diff-card material for a call whose render intent is a diff card (derived by
    * `diffCardModel`); it replaces the text body when present, the same way
-   * `terminal` does. A call carries at most one card intent, so the two are
+   * `terminal` does. A call carries at most one card intent, so the cards are
    * never both set.
    */
   diff?: DiffCardModel | null | undefined
@@ -103,6 +112,7 @@ export function ToolRow({
   output,
   errorSummary,
   terminal,
+  search,
   diff,
   state,
   filePath,
@@ -111,9 +121,12 @@ export function ToolRow({
 }: ToolRowProps) {
   const [expanded, setExpanded] = useState(false)
   const terminalBody = terminal ?? null
+  const searchBody = search ?? null
   const diffBody = diff ?? null
   const outputText = output ?? null
-  const expandable = body !== null || outputText !== null || terminalBody !== null || diffBody !== null
+  // A search or diff card replaces the text body; a call carries at most one
+  // card kind, so terminal, search, and diff are never both present on a row.
+  const expandable = body !== null || outputText !== null || terminalBody !== null || searchBody !== null || diffBody !== null
   const open = expanded && expandable
   // An error row's collapsed summary IS the failure: the first error line in
   // the error color outranks both the args summary and a terminal description.
@@ -185,40 +198,51 @@ export function ToolRow({
                 className={css.terminalBody}
               />
             )
-            : diffBody !== null
-              ? <DiffBlock {...diffBody.card} maxLines={CHAT_DIFF_MAX_LINES} className={css.diffBody} />
-              : isThink
-                ? <div className={css.thinkBody}>{body}</div>
-                : (
-                  <>
-                    {variant === 'code' && body !== null && (
-                      <div className={css.bodyScroll}>
-                        <CodeBlock code={body} lang="typescript" copyLabel={t('copy')} copiedLabel={t('copied')} className={css.codeBody} />
-                      </div>
-                    )}
-                    {(cardBody !== null || outputText !== null) && (
-                      <div className={css.ioCard}>
-                        {cardBody !== null && (
-                          <div className={css.ioSection}>
-                            <span className={css.ioLabel}>IN</span>
-                            <span className={css.ioText}>{cardBody}</span>
-                          </div>
-                        )}
-                        {cardBody !== null && outputText !== null && (
-                          <span className={css.ioDivider} aria-hidden />
-                        )}
-                        {outputText !== null && (
-                          <div className={css.ioSection}>
-                            <span className={css.ioLabel}>OUT</span>
-                            <span className={css.ioText} data-error={state === 'error' || undefined}>
-                              {outputText}
-                            </span>
-                          </div>
-                        )}
-                      </div>
-                    )}
-                  </>
-                )}
+            : searchBody !== null
+              ? (
+                <>
+                  <SearchBlock {...searchBody.card} maxLines={CHAT_SEARCH_MAX_LINES} className={css.searchBody} />
+                  {/* A capped search's recovery locator lives only in the result
+                      text; show it below the card so the dropped rows survive. */}
+                  {searchBody.recovery !== undefined && (
+                    <div className={css.searchRecovery}>{searchBody.recovery}</div>
+                  )}
+                </>
+              )
+              : diffBody !== null
+                ? <DiffBlock {...diffBody.card} maxLines={CHAT_DIFF_MAX_LINES} className={css.diffBody} />
+                : isThink
+                  ? <div className={css.thinkBody}>{body}</div>
+                  : (
+                    <>
+                      {variant === 'code' && body !== null && (
+                        <div className={css.bodyScroll}>
+                          <CodeBlock code={body} lang="typescript" copyLabel={t('copy')} copiedLabel={t('copied')} className={css.codeBody} />
+                        </div>
+                      )}
+                      {(cardBody !== null || outputText !== null) && (
+                        <div className={css.ioCard}>
+                          {cardBody !== null && (
+                            <div className={css.ioSection}>
+                              <span className={css.ioLabel}>IN</span>
+                              <span className={css.ioText}>{cardBody}</span>
+                            </div>
+                          )}
+                          {cardBody !== null && outputText !== null && (
+                            <span className={css.ioDivider} aria-hidden />
+                          )}
+                          {outputText !== null && (
+                            <div className={css.ioSection}>
+                              <span className={css.ioLabel}>OUT</span>
+                              <span className={css.ioText} data-error={state === 'error' || undefined}>
+                                {outputText}
+                              </span>
+                            </div>
+                          )}
+                        </div>
+                      )}
+                    </>
+                  )}
           {inspect !== undefined && (
             <button
               type="button"

packages/client/ui-conversation/src/client/contract/read-card-model.ts

@@ -0,0 +1,76 @@
+/**
+ * Pure derivation of the read-card props from a frozen call slice: the
+ * `card:'read'` render intent the read tool declares arrives on the snapshot as
+ * the settled result node's `resultView`, and this is the one place that turns
+ * it into what {@link ReadBlock} draws. Both conversation render sites (the chat
+ * tool row's resident body and the details panel's Output section) call this, so
+ * the path, lines, total, and language they show are derived once.
+ *
+ * The read card is result-side only ([read card note](../../../../../../.agents/notes/implemented/feature/2026-07-30-web-read-card.md)):
+ * a call carries no file content until `execute` returns, so the pending call
+ * stays a generic card (`kind: 'read'`). A running read therefore has no read
+ * card, and this returns null for it — the row keeps its args-derived summary
+ * until the result arrives.
+ * @module
+ */
+import type { ReadBlockLine, ReadBlockProps } from '@deepseek-ai/dsh-client-ui-primitives'
+import { relativizeToCwd, type ToolCallBlock } from './tool-call-model.ts'
+
+/**
+ * Content lines the chat row's resident read body shows before collapsing the
+ * middle — half the primitive's own default, which the details panel keeps. A
+ * chat row is a summary surface inside the message flow: the flow must stay
+ * scannable across many calls, while the details panel is the single-call
+ * reading surface. A design constant of this UI's row geometry, not a
+ * deployment choice, so it is fixed here rather than a plugin Config field. The
+ * same split [`CHAT_TERMINAL_MAX_LINES`](./terminal-card-model.ts) draws for
+ * terminal output.
+ */
+export const CHAT_READ_MAX_LINES = 8
+
+/**
+ * The {@link ReadBlock} props this derivation owns. Picked off the primitive's
+ * props so the two stay in step; `maxLines`/`className` belong to each render
+ * site.
+ */
+export type ReadCardModel = Pick<ReadBlockProps, 'label' | 'lines' | 'totalLines' | 'lang'>
+
+/**
+ * Derive the read-card props for a tool call, or null when this call is not a
+ * read card and belongs on the generic path.
+ *
+ * The read card is result-side only, so only a settled call whose result view
+ * declares `card:'read'` produces one. Every other case is null — the
+ * documented generic-card default:
+ *
+ * - A running call: it has no result view yet, and a read carries no content at
+ *   call time.
+ * - A settled call whose result view is not a read card — including a `card`
+ *   value this UI version does not know, which arrives over the wire and cannot
+ *   be trusted to be one of the compiled variants, and the read tool's own
+ *   generic fallback for an error result or a non-envelope body.
+ *
+ * The label is the read view's `title` when the tool supplied one (the
+ * presentation contract's replacement-title rule), otherwise the file path
+ * relativized to the session workspace so a workspace-rooted absolute path
+ * displays the same short form the row summary shows.
+ * @param block - RunningToolCall or ToolResultNode off the snapshot caches.
+ * @param sessionCwd - the session workspace root; a workspace-rooted absolute
+ *   path label displays relative to it. Absent leaves the path as authored.
+ * @returns the read-card props, or null for the generic path.
+ */
+export function readCardModel(block: ToolCallBlock, sessionCwd?: string): ReadCardModel | null {
+  // Running has no result view; a read carries no content until execute returns.
+  if (!('kind' in block)) return null
+  const result = block.resultView?.card === 'read' ? block.resultView : null
+  if (result === null) return null
+  // Lines arrive frozen off the snapshot; copy into the primitive's own line
+  // shape so the card never holds a reference into the runtime's cache.
+  const lines: ReadBlockLine[] = result.lines.map(line => ({ number: line.number, text: line.text }))
+  return {
+    label: result.title ?? relativizeToCwd(result.path, sessionCwd),
+    lines,
+    totalLines: result.totalLines,
+    lang: result.lang,
+  }
+}

packages/client/ui-conversation/src/client/contract/search-card-model.ts

@@ -0,0 +1,159 @@
+/**
+ * Pure derivation of the search-card props from a frozen call slice: the
+ * `card:'search'` render intent the `grep` and `glob` tools declare arrives on
+ * the snapshot as `resultView`, and this is the one place that turns it into
+ * what {@link SearchBlock} draws. Both conversation render sites (the chat tool
+ * row's resident body and the details panel's Output section) call this, so the
+ * grouped matches or the path list they show are derived once.
+ *
+ * The search card is result-time only: a search call has no matches or paths
+ * before `execute`, so its pending state stays a `GenericCallView`
+ * ({@link module:@deepseek-ai/dsh-tools/src/presentation}). This derivation
+ * therefore reads only `resultView` and returns null for a still-running call,
+ * unlike the terminal card whose call view carries the command before
+ * execution.
+ *
+ * A capped result also carries a recovery locator (grep/glob's `Full … stored
+ * at …` footer) in the raw `tool/result` content, not in the structured
+ * matches/paths the view carries. Since both render sites replace that raw
+ * result with the card, this derivation surfaces the block's own result text as
+ * {@link SearchCardModel.recovery} so the one path to the dropped rows is not
+ * lost.
+ * @module
+ */
+import type { SearchBlockProps, SearchFileGroup } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolCallBlock } from './tool-call-model.ts'
+
+/**
+ * Distributive `Omit`: a plain `Omit<A | B, K>` keeps only the keys common to
+ * both members, which would drop the `files`/`paths` discriminated fields.
+ * Distributing over the naked type parameter `T` preserves each shape.
+ */
+type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never
+
+/** The {@link SearchBlockProps} union minus each render site's own fields. */
+type SearchBlockModelProps = DistributiveOmit<SearchBlockProps, 'maxLines' | 'className'>
+
+/**
+ * Result rows the chat row's resident search body shows before collapsing the
+ * middle — half the primitive's own default, which the details panel keeps. A
+ * chat row is a summary surface inside the message flow: the flow must stay
+ * scannable across many calls, while the details panel is the single-call
+ * reading surface. A design constant of this UI's row geometry, not a
+ * deployment choice, so it is fixed here rather than a plugin Config field.
+ */
+export const CHAT_SEARCH_MAX_LINES = 8
+
+/**
+ * The {@link SearchBlock} props this derivation owns. Held as a nested object
+ * (`card`) so a render site spreads exactly the primitive's own surface and can
+ * never leak a neighbouring field into it. `maxLines`/`className` belong to each
+ * render site.
+ */
+export interface SearchCardModel {
+  /**
+   * The props {@link SearchBlock} draws, minus each render site's own
+   * `maxLines`/`className`.
+   */
+  card: SearchBlockModelProps
+  /**
+   * The result view's replacement title, which the presentation contract lets a
+   * search tool set at settle time. Absent when the presenter supplied none; a
+   * row then keeps its args-derived summary.
+   */
+  title: string | undefined
+  /**
+   * The raw `tool/result` text, flattened, surfaced only when the search was
+   * capped. The card renders the retained matches or paths, but the recovery
+   * locator a capped result carries — grep/glob's `Full … stored at: <locator>`
+   * footer, the one way to reach the rows the cap dropped — lives only in the raw
+   * result text, which the card replaces. A UI that shows the card would
+   * otherwise lose it. Absent when the result was not capped (the card holds
+   * every result) or the block carries no text.
+   */
+  recovery: string | undefined
+}
+
+/**
+ * Whether every file group in a matches view is structurally valid: the wire
+ * frame carries `shape` and `card` as strings the host schema checks, but not the
+ * grouped shape, so a version mismatch or loose producer could deliver
+ * `shape: 'matches'` with a missing or malformed `files`. Rendering that would
+ * crash {@link SearchBlock} at `.reduce`/`.map`; an invalid shape falls to the
+ * generic path instead.
+ * @param files - the candidate `files` field off the untrusted result view.
+ * @returns whether `files` is a valid {@link SearchFileGroup} array.
+ */
+function isValidFiles(files: unknown): files is SearchFileGroup[] {
+  return Array.isArray(files) && files.every(file =>
+    typeof file === 'object' && file !== null
+    && typeof (file as { path?: unknown }).path === 'string'
+    && Array.isArray((file as { matches?: unknown }).matches)
+    && (file as { matches: unknown[] }).matches.every(match =>
+      typeof match === 'object' && match !== null
+      && typeof (match as { lineNumber?: unknown }).lineNumber === 'number'
+      && typeof (match as { line?: unknown }).line === 'string'))
+}
+
+/**
+ * Flatten a settled tool result's content blocks to their text, joined by
+ * newlines. The search view carries no result text — a UI without a card falls
+ * back to the raw `tool/result` content — so the truncation recovery footer is
+ * read from the block's own content here. Non-text blocks (a search result
+ * carries none) are skipped.
+ * @param content - the result node's content blocks.
+ * @returns the joined text, or undefined when empty.
+ */
+function flattenContent(content: readonly { type: string; text?: string }[]): string | undefined {
+  const text = content
+    .filter((block): block is { type: 'text'; text: string } => block.type === 'text' && typeof block.text === 'string')
+    .map(block => block.text)
+    .join('\n')
+  return text === '' ? undefined : text
+}
+
+/**
+ * Derive the search-card props for a tool call, or null when this call is not a
+ * search card and belongs on the generic path.
+ *
+ * Only the result side matters: the search card carries no call-time state, so
+ * a still-running call (no result view) is null, as is a settled call whose
+ * result view is not a search card — including a `card` value this UI version
+ * does not know, which arrives over the wire and cannot be trusted to be one of
+ * the compiled variants, a `card: 'search'` view whose `shape` is neither
+ * `matches` nor `paths` (equally untrusted wire data), and a generic result a
+ * `grep`/`glob` failure or nested `run_code` dispatch produces (its text keeps
+ * the generic path).
+ * @param block - RunningToolCall or ToolResultNode off the snapshot caches.
+ * @returns the search-card props, or null for the generic path.
+ */
+export function searchCardModel(block: ToolCallBlock): SearchCardModel | null {
+  // Running: no result view exists yet, and a search card is result-only.
+  if (!('kind' in block)) return null
+  const result = block.resultView?.card === 'search' ? block.resultView : null
+  if (result === null) return null
+  const common = { truncated: result.truncated, total: result.total }
+  // The recovery footer only matters when the tool capped the result: an
+  // uncapped card holds every match/path, so the raw text adds nothing the card
+  // does not already show. When capped, the raw result's `Full … stored at …`
+  // locator is the only path to the dropped rows, so surface it.
+  const recovery = result.truncated ? flattenContent(block.content) : undefined
+  if (result.shape === 'matches') {
+    // `files` rides the untrusted wire frame: the host schema checks `card`/`shape`
+    // strings but not the grouped shape, so validate it before SearchBlock, which
+    // would crash on a missing/malformed `files`. An invalid shape falls to generic.
+    if (!isValidFiles(result.files)) return null
+    return { title: result.title, recovery, card: { kind: 'matches', files: result.files, ...common } }
+  }
+  // `shape` rides the same untrusted wire frame as `card`, so a version mismatch
+  // or a loose protocol producer could deliver a `card: 'search'` subtype this
+  // client does not compile. Guard the paths shape explicitly: an unknown shape
+  // falls to the generic path rather than being rendered as a paths card, which
+  // would leave SearchBlock calling `.length`/`.map` on an absent `paths`.
+  // oxlint-disable-next-line typescript/no-unnecessary-condition -- shape is wire data; the compiled union cannot prove this exhaustive.
+  if (result.shape !== 'paths') return null
+  // `paths` is likewise unchecked by the wire schema; a known shape with a
+  // missing/malformed array would crash the paths card at `.map`.
+  if (!Array.isArray(result.paths) || !result.paths.every((path): path is string => typeof path === 'string')) return null
+  return { title: result.title, recovery, card: { kind: 'paths', paths: result.paths, ...common } }
+}

packages/client/ui-conversation/src/client/contract/tool-call-model.ts

@@ -133,8 +133,13 @@ const SUMMARY_KEYS: Record<ToolRowVariant, readonly string[]> = {
   others: [],
 }
 
-/** Strip the workspace root from workspace-rooted absolute paths (display only). */
-function relativizeToCwd(text: string, cwd: string | undefined): string {
+/**
+ * Strip the workspace root from a workspace-rooted absolute path (display only).
+ * @param text - the path to shorten.
+ * @param cwd - session workspace root; absent or empty leaves the path unchanged.
+ * @returns the path relative to the workspace root, or unchanged when it is not rooted there.
+ */
+export function relativizeToCwd(text: string, cwd: string | undefined): string {
   if (cwd === undefined || cwd === '') return text
   const root = cwd.replace(/[/\\]+$/, '')
   if (text.startsWith(`${root}/`) || text.startsWith(`${root}\\`)) return text.slice(root.length + 1)

packages/client/ui-conversation/src/client/contract/toolview-status.ts

@@ -0,0 +1,45 @@
+// Shared toolview-row helpers for the keyed rows whose card is resident below a
+// summary (SearchRow, FileMutationRow): the visually hidden run-state label and
+// the flattened settled-result text for the fallback arm a card cannot render.
+// Both are pure functions of a frozen call slice — no chat-domain imports — so a
+// row stays a thin ToolRowProps consumer.
+
+import type { ToolRowProps } from './slots.ts'
+import type { ToolRowState } from './tool-call-model.ts'
+
+/**
+ * Visually hidden run-state label for a row's leading `StateDot` (which is
+ * `aria-hidden`), so assistive technology still announces the state. Returns
+ * null for the settled-ok state, which needs no spoken label.
+ * @param state - the row's run state.
+ * @returns the label, or null when none is needed.
+ */
+export function rowStateStatus(state: ToolRowState): string | null {
+  switch (state) {
+    case 'running': return '运行中'
+    case 'error': return '失败'
+    case 'stopped': return '已停止'
+    default: return null
+  }
+}
+
+/**
+ * A settled result's text, flattened from its content blocks, for the fallback
+ * arm a keyed row shows when its card cannot render the result — an errored call
+ * (the tool emits no result view on error) or a settled call with no card view
+ * (a nested `run_code` sub-dispatch, a legacy generic result). The keyed row owns
+ * the render slot, so without this the model-facing text would have nowhere to
+ * go. Falls back to the error name/code when the result carries no text block.
+ * @param block - the frozen call slice.
+ * @returns the result text, or null for a running call or an empty result.
+ */
+export function rowResultText(block: ToolRowProps['block']): string | null {
+  if (!('kind' in block)) return null
+  const parts: string[] = []
+  for (const item of block.content) {
+    if (item.type === 'text') parts.push(item.text)
+  }
+  if (parts.length === 0 && block.error !== undefined) parts.push(`${block.error.name}: ${block.error.code}`)
+  const text = parts.join('\n')
+  return text === '' ? null : text
+}

packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css

@@ -101,15 +101,27 @@
   font: var(--dsw-font-xs-13);
 }
 
-/* A card body (terminal or diff) sits directly under its section label, so it
-   drops the primitive's standalone vertical margin; the section owns the
-   spacing. Card-neutral: no terminal- or diff-specific value. */
+/* A card body (terminal, search, or diff) sits directly under its section
+   label, so it drops the primitive's standalone vertical margin; the section
+   owns the spacing. Card-neutral: no card-specific value. */
 .cardBody {
   margin: 0;
 }
 
-/* Same rule for the web card: it sits under the section label, so the section
-   owns the spacing rather than the primitive's own vertical margin. */
+/* The recovery footer for a capped search: the result text (its `Full … stored
+   at …` locator) below the card in the muted tone, since the card holds only the
+   retained rows. */
+.searchRecovery {
+  margin: 6px 0 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  color: var(--dsw-alias-label-tertiary);
+  font: var(--dsw-font-xs-13);
+}
+
+/* The read and web cards sit directly under their section label, same as the
+   terminal card: drop the primitive's standalone vertical margin. */
+.read,
 .web {
   margin: 0;
 }

packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx

@@ -7,10 +7,12 @@
 // share the store seat exists for) and derives the call material from the
 // session snapshot — no data of its own.
 
-import { CodeBlock, DiffBlock, TerminalBlock, WebBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import { CodeBlock, DiffBlock, ReadBlock, SearchBlock, TerminalBlock, WebBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import { shallowEqual } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { DetailsSlotProps } from '../contract/slots.ts'
+import { searchCardModel } from '../contract/search-card-model.ts'
+import { readCardModel } from '../contract/read-card-model.ts'
 import { diffCardModel } from '../contract/diff-card-model.ts'
 import { terminalBlockLabels, terminalCardModel } from '../contract/terminal-card-model.ts'
 import { webCardModel } from '../contract/web-card-model.ts'
@@ -129,11 +131,15 @@ export function DetailsPanel({ useSession, useSessions, sessionId, useStore, clo
  * The Output section's body for the selected call. A terminal-card call — a
  * shell command's call/result views — renders through the shared TerminalBlock
  * at the primitive's own full height allowance, so column-aligned output keeps
- * its alignment and scrolls sideways instead of folding. A diff-card call — a
- * write/edit's applied change — renders through the shared DiffBlock at the same
- * full height. A web-card call — a `web_search`/`web_fetch` result — renders
- * through WebBlock at its own full source-list allowance. Every other call, and
- * a running call with no card yet, keeps the flattened text form.
+ * its alignment and scrolls sideways instead of folding. A search-card call —
+ * a `grep`/`glob` result view — renders through the shared SearchBlock at the
+ * same full height allowance, with a capped search's recovery footer below it.
+ * A read-card call renders through the shared ReadBlock at that same full height,
+ * so the whole returned window is line-numbered and highlighted. A diff-card
+ * call — a write/edit's applied change — renders through the shared DiffBlock at
+ * the same full height. A web-card call — a `web_search`/`web_fetch` result —
+ * renders through WebBlock at its own full source-list allowance. Every other
+ * call, and a running call with no card yet, keeps the flattened text form.
  * @param props.material - the selected call's material from {@link materialFor}.
  * @param props.cwd - the session workspace root, resolving the terminal view's cwd.
  * @param props.t - the panel's locale seat, passed down as a plain prop.
@@ -153,6 +159,23 @@ function OutputBody({ material, cwd, t }: { material: CallMaterial; cwd: string
       </>
     )
   }
+  const search = searchCardModel(material.block)
+  if (search !== null) {
+    return (
+      <>
+        <SearchBlock {...search.card} className={css.cardBody} />
+        {/* A capped search's recovery locator lives only in the result text;
+            show it below the card so the dropped rows stay reachable. */}
+        {search.recovery !== undefined && (
+          <div className={css.searchRecovery}>{search.recovery}</div>
+        )}
+      </>
+    )
+  }
+  const read = readCardModel(material.block, cwd)
+  // The panel takes the primitive's own default cap, not the row's tighter one:
+  // it is the single-call reading surface, so the whole window is available.
+  if (read !== null) return <ReadBlock {...read} className={css.read} />
   const diff = diffCardModel(material.block)
   if (diff !== null) return <DiffBlock {...diff.card} className={css.cardBody} />
   const web = webCardModel(material.block)

packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx

@@ -18,6 +18,7 @@ import { DiffBlock, IconEditOutline16, StateDot } from '@deepseek-ai/dsh-client-
 import type { ToolRowProps } from '../contract/slots.ts'
 import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../contract/diff-card-model.ts'
 import { toolRowModel, type ToolRowState } from '../contract/tool-call-model.ts'
+import { rowResultText, rowStateStatus } from '../contract/toolview-status.ts'
 import css from './file-mutation-row.module.css'
 
 function leadingFor(state: ToolRowState) {
@@ -29,37 +30,6 @@ function leadingFor(state: ToolRowState) {
   }
 }
 
-/** Visually hidden status — StateDot is aria-hidden; AT needs a text label. */
-function stateStatus(state: ToolRowState): string | null {
-  switch (state) {
-    case 'running': return '运行中'
-    case 'error': return '失败'
-    case 'stopped': return '已停止'
-    default: return null
-  }
-}
-
-/**
- * A settled result's text, flattened from its content blocks, for the arm that
- * shows a failure the diff card cannot: write/edit return `undefined` from
- * `presentResult` on `result.isError`, so an errored mutation has no diff card,
- * and the keyed row is not a details-panel target. Without this the failure —
- * an `old_string` that did not match, a permission denial — would read as a bare
- * red dot with the model-facing error text nowhere on screen.
- * @param block - the frozen call slice.
- * @returns the result text, or null for a running call or an empty result.
- */
-function errorText(block: ToolRowProps['block']): string | null {
-  if (!('kind' in block)) return null
-  const parts: string[] = []
-  for (const item of block.content) {
-    if (item.type === 'text') parts.push(item.text)
-  }
-  if (parts.length === 0 && block.error !== undefined) parts.push(`${block.error.name}: ${block.error.code}`)
-  const text = parts.join('\n')
-  return text === '' ? null : text
-}
-
 /**
  * File-mutation row: icon + {Edit,Write} · {path} in the shared ToolRow chrome,
  * with the applied diff resident below it. The summary is a path link (a file
@@ -70,11 +40,11 @@ function errorText(block: ToolRowProps['block']): string | null {
 export function FileMutationRow({ toolName, block, cwd, openFile }: ToolRowProps) {
   const model = toolRowModel(toolName, block, cwd)
   const diff = diffCardModel(block)
-  const status = stateStatus(model.state)
+  const status = rowStateStatus(model.state)
   const filePath = model.filePath
   // An errored mutation has no diff card (presentResult returns undefined on
   // isError); surface its result text so the failure is more than a red dot.
-  const failure = diff === null && model.state === 'error' ? errorText(block) : null
+  const failure = diff === null && model.state === 'error' ? rowResultText(block) : null
   return (
     <div className={css.card}>
       <div className={css.root} data-variant={model.variant} data-state={model.state}>

packages/client/ui-conversation/src/client/toolviews/read-row.module.css

@@ -0,0 +1,119 @@
+/* Read toolview: same geometry/tokens as ToolRow (figma Read · {path}), plus
+   the read card the row stacks under its summary line. */
+
+/* Summary line over the read card; the summary row keeps its own 24px height,
+   so the card is a column around it rather than a change to it. */
+.card {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Row indentation matches ToolRow's expanded bodies (16px leading + 6px gap),
+   and replaces the primitive's standalone vertical margin with the flow's. */
+.read {
+  margin: 4px 0 4px 22px;
+}
+
+.root {
+  position: relative; /* sweep-glare overlay anchor */
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  height: 24px;
+  min-width: 0;
+}
+
+/* Running sweep glare — same pattern as BashRow/ToolRow, so a running read row
+   gives the same executing feedback a running command row does. The leading
+   read icon stays static (a read has no per-step state to animate); the sweep
+   is the row-level running signal. */
+.root[data-state='running']::after {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 300px;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    color-mix(in srgb, var(--dsw-alias-bg-base) 60%, transparent) 55%,
+    transparent 100%
+  );
+  animation: dsh-read-row-sweep 2.6s ease-out infinite;
+  pointer-events: none;
+}
+
+@keyframes dsh-read-row-sweep {
+  0% { left: -300px; }
+  90%, 100% { left: 100%; }
+}
+
+.leading {
+  flex: none;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-right: 6px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.title {
+  flex: none;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.sep {
+  flex: none;
+  width: 2px;
+  height: 2px;
+  border-radius: 1px;
+  margin: 0 8px;
+  background: var(--dsw-alias-label-caption);
+}
+
+.summary {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* File path: same geometry as .summary; hover underline + pointer. */
+.fileLink {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  text-align: left;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+}
+
+.fileLink:hover {
+  text-decoration: underline;
+}
+
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}

packages/client/ui-conversation/src/client/toolviews/read-row.tsx

@@ -0,0 +1,105 @@
+// Read toolview registrant: the keyed toolview hole for the read tool
+// (ctx.slots.register + ToolRowProps only — never imports the chat domain).
+// Product chrome matches ToolRow (figma: Read · {path}); the summary is the
+// file path as an openable link, exactly as the generic read row draws it.
+//
+// A read RESULT declares the read render intent, so this row renders the file's
+// own line-numbered, syntax-highlighted content through ReadBlock resident
+// below its summary line — the same posture BashRow gives a terminal card. The
+// card is capped at CHAT_READ_MAX_LINES (the chat flow's tighter cap over the
+// block's own default of 16) with the block's internal expander keeping a long
+// read from taking over the message flow. A running read (no result yet) and a
+// non-read result both render the summary row alone. The read intent is
+// result-side only, so there is no running-state read card to draw.
+
+import type { Context } from 'cordis'
+import { IconBrowseOutline16, ReadBlock, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolRowProps } from '../contract/slots.ts'
+import { CHAT_READ_MAX_LINES, readCardModel } from '../contract/read-card-model.ts'
+import { toolRowModel, type ToolRowState } from '../contract/tool-call-model.ts'
+import css from './read-row.module.css'
+
+/** Leading-slot state substitution: the tool icon yields to the state dot
+ *  (error = red, interrupted = amber). Running keeps the icon. */
+function leadingFor(state: ToolRowState) {
+  switch (state) {
+    case 'error': return <StateDot state="error" />
+    case 'stopped': return <StateDot state="warning" />
+    default: return <IconBrowseOutline16 size={14} />
+  }
+}
+
+/** Visually hidden status — StateDot is aria-hidden; AT needs a text label. */
+function stateStatus(state: ToolRowState): string | null {
+  switch (state) {
+    case 'running': return '运行中'
+    case 'error': return '失败'
+    case 'stopped': return '已停止'
+    default: return null
+  }
+}
+
+/**
+ * Read row: icon + Read · {path} in the shared ToolRow chrome, with the file's
+ * read card resident below it. The summary path is an openable host link when
+ * the row names a single file; the card's copy and expand controls plus that
+ * link are the row's only interactions (tool rows are not details-panel
+ * targets).
+ */
+export function ReadRow({ toolName, block, sessionId, useSessions, openFile }: ToolRowProps) {
+  // Session workspace root: the read view's path relativizes against it (a
+  // workspace-rooted absolute path shows its short form), which the pure
+  // presenter cannot do.
+  const cwd = useSessions(list => list.byId[sessionId]?.cwd)
+  const model = toolRowModel(toolName, block, cwd)
+  const read = readCardModel(block, cwd)
+  const status = stateStatus(model.state)
+  const filePath = model.filePath
+  return (
+    <div className={css.card}>
+      {/* jscpd:ignore-start — the summary-line chrome (leading, status, title,
+          sep, path-link/summary) is the shared ToolRow row shape every keyed
+          toolview draws; extracting it into one component is a separate change
+          tracked for all rows at once, not this read-card PR. */}
+      <div className={css.root} data-variant="read" data-state={model.state}>
+        <span className={css.leading}>{leadingFor(model.state)}</span>
+        {status !== null && <span className={css.visuallyHidden}>{status}</span>}
+        <span className={css.title}>{model.title}</span>
+        <span className={css.sep} aria-hidden />
+        {filePath !== undefined ? (
+          <button
+            type="button"
+            className={css.fileLink}
+            onClick={() => { openFile(filePath) }}
+          >
+            {model.summary}
+          </button>
+        ) : (
+          <span className={css.summary}>{model.summary}</span>
+        )}
+      </div>
+      {/* jscpd:ignore-end */}
+      {read !== null && (
+        <ReadBlock {...read} maxLines={CHAT_READ_MAX_LINES} className={css.read} />
+      )}
+    </div>
+  )
+}
+
+/**
+ * The read row as a plain registrant plugin. `inject` carries the load-order
+ * seam: requiring the conversation service guarantees the chat entry (and with
+ * it the 'conversation.chat.toolview' declaration) is registered —
+ * ui-conversation's apply mounts the service after the chat entry.
+ */
+export const readToolview = {
+  name: 'read-toolview',
+  inject: ['slots', 'conversation'],
+  /**
+   * Register the read row into the chat view's keyed toolview hole.
+   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
+   */
+  apply(ctx: Context): void {
+    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'read' }, ReadRow)
+  },
+}

packages/client/ui-conversation/src/client/toolviews/search-row.module.css

@@ -0,0 +1,117 @@
+/* Search toolview: same geometry/tokens as ToolRow and BashRow (figma
+   Search · summary), plus the search card the row stacks resident under its
+   summary line. */
+
+/* Summary line over the search card; the summary row keeps its own 24px
+   height, so the card is a column around it rather than a change to it. */
+.card {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Row indentation matches ToolRow's expanded bodies (16px leading + 6px gap),
+   and replaces the primitive's standalone vertical margin with the flow's. */
+.search {
+  margin: 4px 0 4px 22px;
+}
+
+.root {
+  position: relative; /* sweep-glare overlay anchor */
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  height: 24px;
+  min-width: 0;
+}
+
+/* Running sweep glare — same deepsuite ShimmerText pattern as ToolRow / BashRow. */
+.root[data-state='running']::after {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 300px;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    color-mix(in srgb, var(--dsw-alias-bg-base) 60%, transparent) 55%,
+    transparent 100%
+  );
+  animation: dsh-search-row-sweep 2.6s ease-out infinite;
+  pointer-events: none;
+}
+
+@keyframes dsh-search-row-sweep {
+  0% { left: -300px; }
+  90%, 100% { left: 100%; }
+}
+
+.leading {
+  flex: none;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-right: 6px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.title {
+  flex: none;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.sep {
+  flex: none;
+  width: 2px;
+  height: 2px;
+  border-radius: 1px;
+  margin: 0 8px;
+  background: var(--dsw-alias-label-caption);
+}
+
+.summary {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}
+
+/* The result text for an errored search, indented to the card's own column and
+   in the error tone, standing in for the search card the failure path does not
+   produce. */
+.failure {
+  margin: 4px 0 4px 22px;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-state-error-primary);
+}
+
+/* The recovery footer for a capped search: the model-facing result text (its
+   `Full … stored at …` locator) shown below the card in the muted tone, since
+   the card holds only the retained rows. Same column indent as the card body. */
+.recovery {
+  margin: 4px 0 4px 22px;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-tertiary);
+}

packages/client/ui-conversation/src/client/toolviews/search-row.tsx

@@ -0,0 +1,96 @@
+// Search toolview registrant: the keyed toolview hole (ctx.slots.register +
+// ToolRowProps only — never imports the chat domain). One SearchRow component
+// registered under both `grep` and `glob`, since both tools declare the same
+// `card: 'search'` render intent and render as one visual object; the row reads
+// the `kind` discriminant off the derived model to draw grouped matches or a
+// path list. Product chrome matches ToolRow / BashRow (Search · {summary}).
+//
+// A search call declares its render intent result-time only, so this row's
+// search card is resident below the summary rather than expand-gated: the row
+// itself has no expand control, and the card's own copy, per-file collapse, and
+// head/tail expand are the row's only interactions. CHAT_SEARCH_MAX_LINES is
+// passed as `maxLines` — the chat flow's tighter cap over the block's own
+// default of 16 — so a large result stays bounded in the message flow.
+
+import type { Context } from 'cordis'
+import { IconSearchOutline16, SearchBlock, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolRowProps } from '../contract/slots.ts'
+import { CHAT_SEARCH_MAX_LINES, searchCardModel } from '../contract/search-card-model.ts'
+import { toolRowModel, type ToolRowState } from '../contract/tool-call-model.ts'
+import { rowResultText, rowStateStatus } from '../contract/toolview-status.ts'
+import css from './search-row.module.css'
+
+/** Leading-slot glyph substitution: the search icon yields to the terminal
+ *  state semantic (error = red, interrupted = amber). Running keeps the icon —
+ *  the row sweep carries the in-flight signal. */
+function leadingFor(state: ToolRowState) {
+  switch (state) {
+    case 'error': return <StateDot state="error" />
+    case 'stopped': return <StateDot state="warning" />
+    default: return <IconSearchOutline16 size={14} />
+  }
+}
+
+/**
+ * Search row: icon + Search · {summary} in the shared ToolRow chrome, with the
+ * completed search's card resident below it, and — when the result was capped —
+ * the recovery footer below the card. The summary row is not a details-panel
+ * control, so the card's copy, per-file collapse, and expand controls are the
+ * row's only interactions. Registered under both `grep` and `glob`; the derived
+ * model's `kind` decides the card shape.
+ */
+export function SearchRow({ toolName, block }: ToolRowProps) {
+  const model = toolRowModel(toolName, block)
+  const search = searchCardModel(block)
+  const status = rowStateStatus(model.state)
+  // A settled call with no search card — an errored search (grep/glob emit no
+  // result view on error), a successful nested run_code sub-dispatch, or a
+  // legacy generic result — has its model-facing text nowhere else to go, since
+  // the keyed SearchRow owns this render slot. Surface it as the fallback body.
+  // A running call ('kind' absent) has no result to flatten; rowResultText
+  // returns null for it, so the arm stays closed until settle.
+  const settled = 'kind' in block
+  const fallback = search === null && settled ? rowResultText(block) : null
+  return (
+    <div className={css.card}>
+      <div className={css.root} data-variant="search" data-tool={toolName} data-state={model.state}>
+        <span className={css.leading}>{leadingFor(model.state)}</span>
+        {status !== null && <span className={css.visuallyHidden}>{status}</span>}
+        <span className={css.title}>{model.title}</span>
+        <span className={css.sep} aria-hidden />
+        {/* The result view's replacement title outranks the args-derived
+            summary, matching the terminal card's description precedence. */}
+        <span className={css.summary}>{search?.title ?? model.summary}</span>
+      </div>
+      {search !== null && (
+        <SearchBlock {...search.card} maxLines={CHAT_SEARCH_MAX_LINES} className={css.search} />
+      )}
+      {/* A capped search drops rows from the card; its recovery locator (the
+          `Full … stored at …` footer) lives only in the result text, so show it
+          below the card so the one path to the dropped rows survives. */}
+      {search?.recovery !== undefined && <div className={css.recovery}>{search.recovery}</div>}
+      {fallback !== null && <div className={css.failure}>{fallback}</div>}
+    </div>
+  )
+}
+
+/**
+ * The search toolview as a plain registrant plugin. `inject` carries the
+ * load-order seam: requiring the conversation service guarantees the chat entry
+ * (and with it the 'conversation.chat.toolview' declaration) is registered.
+ * The one component registers under both keys, since `grep` and `glob` are the
+ * same visual object discriminated only by the result view's `kind`.
+ */
+export const searchToolview = {
+  name: 'search-toolview',
+  inject: ['slots', 'conversation'],
+  /**
+   * Register the search row into the chat view's keyed toolview hole under both
+   * the `grep` and `glob` tool names.
+   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
+   */
+  apply(ctx: Context): void {
+    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep' }, SearchRow)
+    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'glob' }, SearchRow)
+  },
+}

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

@@ -15,7 +15,7 @@
 // chat-toolview-slot.spec.tsx.
 
 import { describe, expect, it, vi } from 'vitest'
-import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import type { SessionBehaviorOverrides } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { ISession, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
@@ -25,6 +25,10 @@ import type {
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { createChatStore } from '../src/client/stores.ts'
 
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
 const ROOT = 'root-1' as SessionId
 
 type ChatInstance = ReturnType<ReturnType<typeof createChatStore>['create']>

packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx

@@ -24,9 +24,13 @@ import { cleanup, fireEvent, waitFor, within } from '@testing-library/react'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { ISession, SessionId, TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
-import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
 const SID = 's1' as SessionId
 
 /** jsdom has no ResizeObserver; the composer seat publishes its height through one. */

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

@@ -9,12 +9,16 @@
 // stops at the assembly surface.
 
 import { describe, expect, it, vi } from 'vitest'
-import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
 const ROOT = 'root-1' as SessionId
 const CHILD = 'child-1' as SessionId
 
@@ -84,14 +88,15 @@ describe('apply wiring', () => {
     await b.runtime.dispose()
   })
 
-  it('mounts the bash sample, the file-mutation rows, the web rows, and the product rows as keyed entries through the load-order seam', async () => {
+  it('mounts the bash sample, the search rows, the read row, the file-mutation rows, the web rows, and the product rows as keyed entries through the load-order seam', async () => {
     const b = await bench()
     // Every registrant plugin's inject: ['slots', 'conversation'] resolved — the
     // service being present implies the chat entry declared the hole first. The
-    // file-mutation registrant claims both write and edit for the diff card; the
-    // web rows register one component under both web tool names.
+    // one search row registers under both grep and glob; the file-mutation
+    // registrant claims both write and edit for the diff card; the web rows
+    // register one component under both web tool names.
     const entries = b.slots.entries('conversation.chat.toolview')
-    expect(entries.map(e => e.options.key)).toEqual(['bash', 'edit', 'write', 'web_search', 'web_fetch', 'todo_write', 'ask_user_question'])
+    expect(entries.map(e => e.options.key)).toEqual(['bash', 'grep', 'glob', 'read', 'edit', 'write', 'web_search', 'web_fetch', 'todo_write', 'ask_user_question'])
     // Stats stick with the composer (not inside ChatView).
     expect(b.slots.entries('conversation.composer.dock').map(e => e.options.id)).toEqual(['stats'])
     await b.runtime.dispose()

packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx

@@ -27,7 +27,7 @@ afterEach(() => {
 const t: MessageItemProps['t'] = makeTranslate(zh, commonZh)
 
 describe('MessageItem arms', () => {
-  it('user bubbles expose clock / copy / branch / edit; copy writes the text', () => {
+  it('user bubbles expose clock / copy / branch and no edit; copy writes the text', () => {
     const writeText = vi.fn().mockResolvedValue(undefined)
     Object.defineProperty(navigator, 'clipboard', {
       configurable: true,
@@ -47,7 +47,7 @@ describe('MessageItem arms', () => {
     expect(screen.getByText('14:24')).toBeTruthy()
     expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
     expect(screen.getByRole('button', { name: '在新对话中分支' })).toBeTruthy()
-    expect(screen.getByRole('button', { name: '编辑' })).toBeTruthy()
+    expect(screen.queryByRole('button', { name: '编辑' })).toBeNull()
     fireEvent.click(screen.getByRole('button', { name: '复制' }))
     expect(writeText).toHaveBeenCalledWith('hello bubble')
   })
@@ -445,14 +445,19 @@ describe('small branch tails', () => {
   })
 
   it('StatsLine omits the cache-hit segment when no input accounting exists at all', () => {
-    // cacheHitPct is null only when input+cacheRead are both zero (pure
-    // output accounting) — any input makes it a real 0%.
+    // Cache hit is null only when all three prompt buckets are zero (pure
+    // output accounting) — any billed input makes it a real 0%.
     const snap = {
       nodes: [{ kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [], usage: { outputTokens: 10 } }],
     }
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
-      <StatsLine useSession={bindSnapshotSelector(source) as unknown as StatsLineProps['useSession']} />,
+      <StatsLine
+        useSession={bindSnapshotSelector(source) as unknown as StatsLineProps['useSession']}
+        useProjection={(key: string) => key === 'tokenUsage'
+          ? { uncachedInputTokens: 0, outputTokens: 10, cacheReadTokens: 0, cacheWriteTokens: 0 }
+          : undefined}
+      />,
     )
     expect(view.container.textContent).toBe('1 turns · 1 steps|Input 0 tok · Output 10 tok')
   })

packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx

@@ -58,7 +58,7 @@ function makeSource(init?: Partial<ConversationSnapshot>) {
 }
 
 describe('deriveStats', () => {
-  it('folds turns/steps/token split and cache hit percentage', () => {
+  it('counts turns and steps and never folds node usage into accounting', () => {
     const stats = deriveStats([
       assistant(1, 1, { inputTokens: 100, outputTokens: 50, cacheReadTokens: 900 }),
       assistant(2, 1, { inputTokens: 100, outputTokens: 50 }),
@@ -66,12 +66,12 @@ describe('deriveStats', () => {
     ])
     expect(stats.turns).toBe(2)
     expect(stats.steps).toBe(3)
-    expect(stats.inputTokens).toBe(1100)
-    expect(stats.outputTokens).toBe(100)
-    expect(stats.cacheHitPct).toBe(82)
+    // Window-scoped by design: the paged window is not an accounting source, so
+    // the fold exposes no token fields at all (billing rides the projection).
+    expect(Object.keys(stats).sort()).toEqual(['llmMs', 'steps', 'toolMs', 'turns'])
   })
 
-  it('cache hit stays null with no cache accounting; out-of-window tool results ignored', () => {
+  it('ignores tool results with no call time', () => {
     const tool: ToolResultNode = {
       kind: 'tool-result', seq: 5, time: 5_000, callId: 'c', call: null, callTime: null, content: [],
       isError: false, callView: null, resultView: null,
@@ -79,7 +79,6 @@ describe('deriveStats', () => {
     const stats = deriveStats([tool, assistant(1, 1)])
     expect(stats.steps).toBe(1)
     expect(stats.toolMs).toBe(0)
-    expect(stats.cacheHitPct).toBeNull()
   })
 
   it('sums LLM wall time from assistant timing and tool wall time from call/result pairs', () => {
@@ -116,22 +115,105 @@ describe('formatters', () => {
 })
 
 describe('StatsLine', () => {
-  function props(source: { getSnapshot(): ConversationSnapshot; subscribe(fn: () => void): () => void }): StatsLineProps {
-    return { useSession: bindSnapshotSelector(source) }
+  const USAGE = { uncachedInputTokens: 10, outputTokens: 5, cacheReadTokens: 90, cacheWriteTokens: 0 }
+
+  /** Stub the projection seat: a key-addressed table of whole values. */
+  function projections(values: Record<string, unknown>): StatsLineProps['useProjection'] {
+    return (key: string) => values[key]
   }
 
-  it('renders the grouped stats row and hides with zero steps', () => {
-    const { source } = makeSource({
-      nodes: [assistant(1, 1, { inputTokens: 10, outputTokens: 5, cacheReadTokens: 90 })],
-    })
+  function props(
+    source: { getSnapshot(): ConversationSnapshot; subscribe(fn: () => void): () => void },
+    values: Record<string, unknown> = { tokenUsage: USAGE },
+  ): StatsLineProps {
+    return { useSession: bindSnapshotSelector(source), useProjection: projections(values) }
+  }
+
+  it('renders the grouped stats row and hides a brand-new empty session', () => {
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
     const view = render(<StatsLine {...props(source)} />)
-    // No timing on the fixture: the duration group drops out whole.
+    // No timing on the fixture: the duration group drops out whole. Tokens come
+    // from the projection, so paging the window cannot change them.
     expect(view.container.textContent).toBe('1 turns · 1 steps|Cache hit 90%|Input 100 tok · Output 5 tok')
     const empty = makeSource()
-    const emptyView = render(<StatsLine {...props(empty.source)} />)
+    const emptyView = render(<StatsLine {...props(empty.source, {
+      tokenUsage: { uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
+      contextPressure: {},
+    })} />)
     expect(emptyView.container.textContent).toBe('')
   })
 
+  it('keeps durable token and context groups after the visible step window is empty', () => {
+    const { source } = makeSource()
+    const view = render(<StatsLine {...props(source, {
+      tokenUsage: USAGE,
+      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
+    })} />)
+    expect(view.container.textContent)
+      .toBe('Context 25% of 128K|Cache hit 90%|Input 100 tok · Output 5 tok')
+  })
+
+  it('renders context occupancy only when the projection knows a capacity', () => {
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const withCapacity = render(<StatsLine {...props(source, {
+      tokenUsage: USAGE,
+      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
+    })} />)
+    expect(withCapacity.container.textContent).toContain('Context 25% of 128K')
+    // Pressure without capacity has no denominator: the group drops out.
+    const noCapacity = render(<StatsLine {...props(source, {
+      tokenUsage: USAGE,
+      contextPressure: { pressureTokens: 32_000 },
+    })} />)
+    expect(noCapacity.container.textContent).not.toContain('Context')
+    // Capacity arrives before usage in the log; no provider sample means there
+    // is no numerator yet, rather than a synthetic 0%.
+    const noPressure = render(<StatsLine {...props(source, {
+      tokenUsage: USAGE,
+      contextPressure: { contextWindow: 128_000 },
+    })} />)
+    expect(noPressure.container.textContent).not.toContain('Context')
+  })
+
+  it('clamps occupancy at 100% when pressure exceeds the recorded capacity', () => {
+    // Capacity and pressure are independent last-wins fields, so a model switch
+    // can pair a smaller new window with the previous route's larger prompt.
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const view = render(<StatsLine {...props(source, {
+      tokenUsage: USAGE,
+      contextPressure: { pressureTokens: 300_000, contextWindow: 128_000 },
+    })} />)
+    expect(view.container.textContent).toContain('Context 100% of 128K')
+  })
+
+  it('drops every token group when no projection is composed', () => {
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const view = render(<StatsLine {...props(source, {})} />)
+    expect(view.container.textContent).toBe('1 turns · 1 steps')
+  })
+
+  it('omits cache hit when nothing was billed on the input side', () => {
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const view = render(<StatsLine {...props(source, {
+      tokenUsage: { uncachedInputTokens: 0, outputTokens: 7, cacheReadTokens: 0, cacheWriteTokens: 0 },
+    })} />)
+    expect(view.container.textContent).toBe('1 turns · 1 steps|Input 0 tok · Output 7 tok')
+  })
+
+  it('includes cache writes in billed input and the cache-hit denominator', () => {
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const view = render(<StatsLine {...props(source, {
+      tokenUsage: {
+        uncachedInputTokens: 10,
+        outputTokens: 7,
+        cacheReadTokens: 90,
+        cacheWriteTokens: 100,
+      },
+    })} />)
+    expect(view.container.textContent)
+      .toBe('1 turns · 1 steps|Cache hit 45%|Input 200 tok · Output 7 tok')
+  })
+
   it('renders ZERO times during streaming chunk frames (RFC hard acceptance)', () => {
     const { set, source } = makeSource({ nodes: [assistant(1, 1)] })
     let renders = 0

packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx

@@ -43,20 +43,24 @@ describe('render branch tails', () => {
     expect(view.container.querySelector('[data-state="ok"]')).not.toBeNull()
   })
 
-  it('StatsLine skips usage-less nodes and defaults each absent counter to zero', () => {
+  it('StatsLine counts window nodes but drops every token group without a projection', () => {
+    // Node `usage` is deliberately ignored: billing rides the durable
+    // tokenUsage projection, so an absent projection leaves counts only.
     const snap = {
       nodes: [
         { kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [] },
         { kind: 'assistant', seq: 2, turn: 1, step: 2, blocks: [], usage: { inputTokens: 4, outputTokens: 6 } },
-        // outputTokens absent: the tokens sum's ?? 0 arm for output.
         { kind: 'assistant', seq: 3, turn: 2, step: 1, blocks: [], usage: { inputTokens: 5 } },
       ],
     }
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
-      <StatsLine useSession={bindSnapshotSelector(source) as unknown as UseSession<ConversationSnapshot>} />,
+      <StatsLine
+        useSession={bindSnapshotSelector(source) as unknown as UseSession<ConversationSnapshot>}
+        useProjection={() => undefined}
+      />,
     )
-    expect(view.container.textContent).toBe('2 turns · 3 steps|Cache hit 0%|Input 9 tok · Output 6 tok')
+    expect(view.container.textContent).toBe('2 turns · 3 steps')
   })
 
   it('AssistantMarkdown reasoning as the streaming tail renders the running ring', () => {

packages/client/ui-conversation/tests/read-card.spec.tsx

@@ -0,0 +1,293 @@
+// @vitest-environment jsdom
+// The read render intent on the web side: the pure readCardModel derivation
+// over the settled result view, and both conversation render sites that consume
+// it — the chat tool row (the keyed ReadRow and the GenericToolCard fallback,
+// each with the read card resident under the summary) and the details panel's
+// Output section. Also pins the keyed 'read' toolview registration.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { Context } from 'cordis'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import type {
+  ConversationSnapshot, RunningToolCall, SessionId, SessionListState, ToolResultNode, WorkspaceListState,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { SelectionTarget, ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { CHAT_READ_MAX_LINES, readCardModel } from '../src/client/contract/read-card-model.ts'
+import { createChatStore } from '../src/client/stores.ts'
+import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx'
+import { zh } from '../src/client/locales.ts'
+import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
+import { ReadRow, readToolview } from '../src/client/toolviews/read-row.tsx'
+
+afterEach(cleanup)
+
+const SID = 's1' as SessionId
+
+/** The chat-view locale seat: this package's namespace over the common fallback. */
+const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
+
+// The read tool's real schema key is `file_path`; the top-level read samples
+// use it so the row exercises a production-shaped call. `web_fetch` (below) has
+// its own schema whose key is not `file_path`, so it keeps a `url`-less `path`.
+const ARGS = '{"file_path":"src/a.ts","offset":41}'
+const WEB_FETCH_ARGS = '{"path":"src/a.ts","offset":41}'
+
+/** The read block's rendered content cells, one string per row (highlighting
+ *  breaks a line across token spans, so match on the row's textContent). */
+function contentTexts(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[data-read] [class^="_content_"]')].map(cell => cell.textContent ?? '')
+}
+
+/** Three windowed lines starting at file line 41 (a read past an offset). */
+const sampleLines = [
+  { number: 41, text: 'export const a = 1' },
+  { number: 42, text: 'export const b = 2' },
+  { number: 43, text: 'export const c = 3' },
+]
+
+/** The read tool's own result view for a settled file read. */
+const resultRead = (over?: Partial<Extract<ToolResultView, { card: 'read' }>>): ToolResultView => ({
+  card: 'read', path: 'src/a.ts', offset: 41, lines: sampleLines, totalLines: 180, lang: 'ts', ...over,
+})
+
+const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
+  callId: 'c1', name: 'read', argsRaw: ARGS,
+  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, ...over,
+})
+
+const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
+  kind: 'tool-result', seq: 10, time: 2_000, callId: 'c1',
+  call: { name: 'read', argsRaw: ARGS },
+  callTime: 1_000,
+  content: [{ type: 'text', text: '41: export const a = 1' }], isError: false,
+  callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, resultView: resultRead(), ...over,
+})
+
+describe('readCardModel', () => {
+  it('derives the card from a settled read result view', () => {
+    expect(readCardModel(settled())).toEqual({
+      label: 'src/a.ts', lines: sampleLines, totalLines: 180, lang: 'ts',
+    })
+  })
+
+  it('copies the lines into the primitive shape rather than aliasing the frozen slice', () => {
+    const model = readCardModel(settled())
+    expect(model?.lines).toEqual(sampleLines)
+    expect(model?.lines).not.toBe(sampleLines)
+    expect(model?.lines[0]).not.toBe(sampleLines[0])
+  })
+
+  it('takes the result view\'s replacement title over the relativized path', () => {
+    // The presentation contract defines a result title as REPLACING the pending
+    // one, so a tool that supplies a label wins over the path here.
+    expect(readCardModel(settled({ resultView: resultRead({ title: 'Read (head) src/a.ts' }) }))?.label)
+      .toBe('Read (head) src/a.ts')
+  })
+
+  it('relativizes a workspace-rooted path label, and leaves others as authored', () => {
+    // A workspace-rooted absolute path shows its short form.
+    expect(readCardModel(settled({ resultView: resultRead({ path: '/w/app/src/a.ts' }) }), '/w/app')?.label)
+      .toBe('src/a.ts')
+    // A path outside the workspace stays as authored.
+    expect(readCardModel(settled({ resultView: resultRead({ path: '/srv/other.ts' }) }), '/w/app')?.label)
+      .toBe('/srv/other.ts')
+    // With no session cwd there is nothing to relativize against.
+    expect(readCardModel(settled({ resultView: resultRead({ path: '/w/app/src/a.ts' }) }))?.label)
+      .toBe('/w/app/src/a.ts')
+  })
+
+  it('carries an omitted language through as undefined', () => {
+    const noLang = resultRead()
+    delete (noLang as { lang?: string }).lang
+    expect(readCardModel(settled({ resultView: noLang }))?.lang).toBeUndefined()
+  })
+
+  it('returns null for a running read: the read intent is result-side only', () => {
+    // A read carries no content until execute returns, so the pending call is a
+    // generic card and there is no read card to draw yet.
+    expect(readCardModel(running())).toBeNull()
+  })
+
+  it('returns null for every non-read settled call: no view, generic view, unknown card', () => {
+    expect(readCardModel(settled({ resultView: null }))).toBeNull()
+    expect(readCardModel(settled({ resultView: { card: 'generic' } }))).toBeNull()
+    // A card tag this UI version does not know arrives over the wire; the
+    // documented generic-card default takes it, not a crash.
+    const future = { card: 'chart' } as unknown as ToolResultView
+    expect(readCardModel(settled({ resultView: future }))).toBeNull()
+  })
+})
+
+describe('GenericToolCard read body', () => {
+  const ownerProps = (block: RunningToolCall | ToolResultNode): GenericToolCardProps => ({
+    callId: 'c1', toolName: 'web_fetch', block, openFile: vi.fn(), t,
+  })
+
+  it('renders the read card resident under the summary, capped tighter than the panel', () => {
+    expect(CHAT_READ_MAX_LINES).toBeLessThan(16)
+    // web_fetch lands on the read variant without its own keyed row, so the
+    // fallback card owns the resident read block.
+    const view = render(<GenericToolCard {...ownerProps(settled({ call: { name: 'web_fetch', argsRaw: WEB_FETCH_ARGS } }))} />)
+    expect(view.container.querySelector('[data-read]')).not.toBeNull()
+    expect(contentTexts(view.container)).toContain('export const a = 1')
+    // The gutter keeps the file's own line numbers.
+    expect(view.getByText('41')).toBeTruthy()
+  })
+
+  it('a non-read tool renders the bare row with no read card', () => {
+    const view = render(<GenericToolCard {...({
+      callId: 'c1', toolName: 'echo', block: settled({
+        call: { name: 'echo', argsRaw: '{"text":"x"}' }, callView: null, resultView: null,
+      }), openFile: vi.fn(), t,
+    })} />)
+    expect(view.container.querySelector('[data-read]')).toBeNull()
+  })
+
+  it('a running read renders the summary row alone (no result view yet)', () => {
+    const view = render(<GenericToolCard {...ownerProps(running({ name: 'web_fetch' }))} />)
+    expect(view.container.querySelector('[data-read]')).toBeNull()
+  })
+})
+
+describe('ReadRow keyed toolview', () => {
+  const list = () => createSnapshotStore<SessionListState>({
+    ids: [SID],
+    byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, waitingApproval: false, updatedAt: 0, cwd: '/w/app' } },
+    current: SID,
+    phase: 'ready',
+  })
+
+  const rowProps = (block: RunningToolCall | ToolResultNode): ToolRowProps => ({
+    callId: 'c1', toolName: 'read', block, openFile: vi.fn(),
+    sessionId: SID, useSessions: bindSnapshotSelector(list()),
+  } as unknown as ToolRowProps)
+
+  it('renders the file path summary and the resident read card', () => {
+    const view = render(<ReadRow {...rowProps(settled())} />)
+    expect(view.getByText('Read')).toBeTruthy()
+    // The path appears twice: the row summary link and the card's banner label.
+    expect(view.getAllByText('src/a.ts').length).toBe(2)
+    expect(view.container.querySelector('[data-read]')).not.toBeNull()
+    expect(contentTexts(view.container)).toContain('export const a = 1')
+    expect(view.getByText('显示 3 / 180 行')).toBeTruthy()
+  })
+
+  it('the path summary opens the file through the host', () => {
+    const openFile = vi.fn()
+    const view = render(<ReadRow {...{ ...rowProps(settled()), openFile }} />)
+    fireEvent.click(view.getByRole('button', { name: 'src/a.ts' }))
+    // The row derives the file path from args; the chat view resolves it against
+    // the cwd before this callback opens it, so the arg path is what arrives.
+    expect(openFile).toHaveBeenCalledWith('src/a.ts')
+  })
+
+  it('a running read renders the summary row alone, and its state', () => {
+    const view = render(<ReadRow {...rowProps(running())} />)
+    expect(view.container.querySelector('[data-variant="read"]')?.getAttribute('data-state')).toBe('running')
+    expect(view.container.querySelector('[data-read]')).toBeNull()
+  })
+
+  it('an error read result shows the error state and no read card', () => {
+    const view = render(<ReadRow {...rowProps(settled({
+      resultView: { card: 'generic' }, isError: true,
+      content: [{ type: 'text', text: 'ENOENT' }],
+    }))} />)
+    expect(view.container.querySelector('[data-variant="read"]')?.getAttribute('data-state')).toBe('error')
+    expect(view.container.querySelector('[data-read]')).toBeNull()
+  })
+
+  it('an interrupted read shows the stopped state', () => {
+    const view = render(<ReadRow {...rowProps(settled({
+      resultView: null, isError: true, error: { name: 'ToolError', code: 'interrupted' },
+    }))} />)
+    expect(view.container.querySelector('[data-variant="read"]')?.getAttribute('data-state')).toBe('stopped')
+  })
+
+  it('registers under the read key of the keyed toolview slot', () => {
+    const registered: { name: unknown; key?: unknown }[] = []
+    const ctx = { slots: { register: (options: { name: unknown; key?: unknown }) => { registered.push(options) } } } as unknown as Context
+    readToolview.apply(ctx)
+    expect(registered).toEqual([{ name: 'conversation.chat.toolview', key: 'read' }])
+    expect(readToolview.inject).toContain('conversation')
+  })
+})
+
+describe('DetailsPanel Output section (read)', () => {
+  function mount(snapshot: ConversationSnapshot, selection: SelectionTarget | null, cwd?: string) {
+    localStorage.clear()
+    const chat = createChatStore().create()
+    if (selection !== null) chat.actions.select(selection)
+    const sessions = createSnapshotStore<SessionListState>(cwd === undefined
+      ? { ids: [], byId: {}, current: undefined, phase: 'ready' }
+      : {
+        ids: [SID],
+        byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, waitingApproval: false, updatedAt: 0, cwd } },
+        current: SID,
+        phase: 'ready',
+      })
+    const workspaces = createSnapshotStore<WorkspaceListState>({
+      items: [], archivedSessionIds: [], state: 'idle', phase: 'ready', error: null,
+      baselinesReady: true, recentWorkspaceId: undefined,
+    })
+    return render(
+      <DetailsPanel
+        sessionId={SID}
+        t={t}
+        useSession={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
+        useSessions={bindSnapshotSelector(sessions)}
+        useWorkspaces={bindSnapshotSelector(workspaces)}
+        useInput={(() => { throw new Error('unused') })}
+        inputActions={{ setDraft: () => {}, submit: () => {} }}
+        useProjection={(() => undefined)}
+        useStore={bindSnapshotSelector(chat)}
+        actions={chat.actions}
+        closeDetails={vi.fn()}
+      />,
+    )
+  }
+
+  function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    return {
+      sessionId: SID, nodes: [], partial: null, runningCalls: [], codeDispatches: new Map(),
+      pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
+      openState: 'open', openError: null, hasMore: false, loadingOlder: false,
+      promptError: null, blank: false, lastAgentError: null, ...over,
+    }
+  }
+
+  const target: SelectionTarget = { turnSeq: 10, callId: 'c1', toolName: 'read' }
+
+  it('renders the read card at full height, keeping the JSON Input section', () => {
+    const long = Array.from({ length: 20 }, (_, i) => ({ number: i + 1, text: `row-${i}` }))
+    const view = mount(snapshot({
+      nodes: [settled({ resultView: resultRead({ lines: long, totalLines: 20 }) })],
+    }), target)
+    expect(view.getByText(/"file_path"/)).toBeTruthy()
+    expect(view.container.querySelector('[data-read]')).not.toBeNull()
+    // The panel takes the primitive's own default cap (16), not the row's.
+    expect(view.getByText(`… 其余 ${20 - 16} 行`)).toBeTruthy()
+    expect(contentTexts(view.container)).toContain('row-0')
+  })
+
+  it('a non-read result keeps the flattened pre form', () => {
+    const view = mount(snapshot({
+      nodes: [settled({
+        callView: null, resultView: null,
+        content: [{ type: 'text', text: 'plain result' }],
+      })],
+    }), target)
+    expect(view.container.querySelector('[data-read]')).toBeNull()
+    expect(view.getByText('输出').closest('section')?.querySelector('pre')?.textContent).toBe('plain result')
+  })
+
+  it('a running read keeps the 运行中… placeholder (no result view)', () => {
+    const view = mount(snapshot({ runningCalls: [running()] }), target)
+    expect(view.getByText('运行中…')).toBeTruthy()
+    expect(view.container.querySelector('[data-read]')).toBeNull()
+  })
+})

packages/client/ui-conversation/tests/search-card.spec.tsx

@@ -0,0 +1,409 @@
+// @vitest-environment jsdom
+// The search render intent on the web side: the pure searchCardModel derivation
+// over resultView, and the conversation render sites that consume it — the chat
+// tool row (GenericToolCard's expand-gated body and SearchRow's resident card)
+// and the details panel's Output section. The keyed registration under both grep
+// and glob is pinned here too.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ConversationSnapshot, RunningToolCall, SessionId, SessionListState, ToolResultNode, WorkspaceListState,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { SelectionTarget, ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import { CHAT_SEARCH_MAX_LINES, searchCardModel } from '../src/client/contract/search-card-model.ts'
+import { zh } from '../src/client/locales.ts'
+import { createChatStore } from '../src/client/stores.ts'
+import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx'
+import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
+import { SearchRow, searchToolview } from '../src/client/toolviews/search-row.tsx'
+
+afterEach(cleanup)
+
+/** Conversation-locale translate stub for the render sites' `t` seat. */
+const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
+
+/** The rendered search card's kind attribute, so a render site cannot silently drop it. */
+function searchKindOf(container: HTMLElement): string | null {
+  return container.querySelector('[data-search]')?.getAttribute('data-search') ?? null
+}
+
+/** The rendered result rows of the search card, one string per visible row. */
+function searchRows(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[data-search] [class^="_line_"]')].map(row => row.textContent ?? '')
+}
+
+const SID = 's1' as SessionId
+
+const GREP_ARGS = '{"pattern":"foo","path":"src"}'
+const GLOB_ARGS = '{"pattern":"**/*.ts","path":"src"}'
+
+/** A grep result view: matches grouped by file. */
+const resultMatches = (over?: Partial<Extract<ToolResultView, { card: 'search'; shape: 'matches' }>>): ToolResultView => ({
+  card: 'search', shape: 'matches',
+  files: [
+    { path: 'a.ts', matches: [{ lineNumber: 12, line: 'const foo = 1' }, { lineNumber: 40, line: 'return foo' }] },
+    { path: 'b.ts', matches: [{ lineNumber: 7, line: 'foo()' }] },
+  ],
+  truncated: false, total: 3, ...over,
+})
+
+/** A glob result view: a flat path list. */
+const resultPaths = (over?: Partial<Extract<ToolResultView, { card: 'search'; shape: 'paths' }>>): ToolResultView => ({
+  card: 'search', shape: 'paths', paths: ['src/a.ts', 'src/b.ts'], truncated: false, total: 2, ...over,
+})
+
+const runningGrep = (over?: Partial<RunningToolCall>): RunningToolCall => ({
+  callId: 'c1', name: 'grep', argsRaw: GREP_ARGS,
+  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, ...over,
+})
+
+const settledGrep = (over?: Partial<ToolResultNode>): ToolResultNode => ({
+  kind: 'tool-result', seq: 10, time: 2_000, callId: 'c1',
+  call: { name: 'grep', argsRaw: GREP_ARGS },
+  callTime: 1_000,
+  content: [{ type: 'text', text: 'a.ts\n  Line 12: const foo = 1' }], isError: false,
+  callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, resultView: resultMatches(), ...over,
+})
+
+const settledGlob = (over?: Partial<ToolResultNode>): ToolResultNode => ({
+  kind: 'tool-result', seq: 11, time: 2_000, callId: 'c2',
+  call: { name: 'glob', argsRaw: GLOB_ARGS },
+  callTime: 1_000,
+  content: [{ type: 'text', text: 'src/a.ts\nsrc/b.ts' }], isError: false,
+  callView: { card: 'generic', title: 'Glob **/*.ts', kind: 'search' }, resultView: resultPaths(), ...over,
+})
+
+describe('searchCardModel', () => {
+  it('derives a matches card from the grep result view', () => {
+    expect(searchCardModel(settledGrep())).toEqual({
+      title: undefined,
+      recovery: undefined,
+      card: {
+        kind: 'matches',
+        files: [
+          { path: 'a.ts', matches: [{ lineNumber: 12, line: 'const foo = 1' }, { lineNumber: 40, line: 'return foo' }] },
+          { path: 'b.ts', matches: [{ lineNumber: 7, line: 'foo()' }] },
+        ],
+        truncated: false, total: 3,
+      },
+    })
+  })
+
+  it('derives a paths card from the glob result view, carrying the truncation signal', () => {
+    // Empty block content isolates the truncation signal from the recovery arm.
+    expect(searchCardModel(settledGlob({ content: [], resultView: resultPaths({ truncated: true, total: 20 }) }))).toEqual({
+      title: undefined,
+      recovery: undefined,
+      card: { kind: 'paths', paths: ['src/a.ts', 'src/b.ts'], truncated: true, total: 20 },
+    })
+  })
+
+  it('carries the result view\'s replacement title when the presenter sets one', () => {
+    expect(searchCardModel(settledGrep({ resultView: resultMatches({ title: '3 matches' }) }))?.title).toBe('3 matches')
+    // Without one it is absent, so the row keeps its args-derived summary.
+    expect(searchCardModel(settledGrep())?.title).toBeUndefined()
+  })
+
+  it('returns null for every non-search call: running, no views, generic, terminal, unknown cards', () => {
+    // A search card is result-time only: a running call has no result view yet.
+    expect(searchCardModel(runningGrep())).toBeNull()
+    expect(searchCardModel(settledGrep({ callView: null, resultView: null }))).toBeNull()
+    // A generic result settles a search call as a generic card (grep/glob failure
+    // or a nested run_code dispatch), which keeps the generic path.
+    expect(searchCardModel(settledGrep({ resultView: { card: 'generic' } }))).toBeNull()
+    // A terminal result view is a different card entirely.
+    expect(searchCardModel(settledGrep({ resultView: { card: 'terminal', output: 'x' } }))).toBeNull()
+    // A card tag this UI version does not know arrives over the wire; the
+    // documented generic-card default takes it, not a crash.
+    const future = { card: 'chart' } as unknown as ToolResultView
+    expect(searchCardModel(settledGrep({ resultView: future }))).toBeNull()
+  })
+
+  it('returns null for a card:search view whose shape this version does not compile', () => {
+    // `shape` rides the same untrusted wire frame as `card`; a subtype this client
+    // does not know must fall to the generic path, never render as a paths card
+    // that would crash SearchBlock on an absent `paths`.
+    const futureShape = {
+      card: 'search', shape: 'future', truncated: false, total: 0,
+    } as unknown as ToolResultView
+    expect(searchCardModel(settledGrep({ resultView: futureShape }))).toBeNull()
+  })
+
+  it('returns null for a known shape whose structured shape is missing or malformed', () => {
+    // The host wire schema checks the `card`/`shape` strings but not the grouped
+    // shape, so a version mismatch could deliver shape:'matches' with no `files`
+    // (or shape:'paths' with no `paths`). Rendering that crashes SearchBlock at
+    // `.reduce`/`.map`; the derivation drops to the generic path instead.
+    const noFiles = { card: 'search', shape: 'matches', truncated: false, total: 0 } as unknown as ToolResultView
+    expect(searchCardModel(settledGrep({ resultView: noFiles }))).toBeNull()
+    const badFile = {
+      card: 'search', shape: 'matches', truncated: false, total: 1,
+      files: [{ path: 'a.ts', matches: [{ lineNumber: 'x', line: 1 }] }],
+    } as unknown as ToolResultView
+    expect(searchCardModel(settledGrep({ resultView: badFile }))).toBeNull()
+    const noPaths = { card: 'search', shape: 'paths', truncated: false, total: 0 } as unknown as ToolResultView
+    expect(searchCardModel(settledGlob({ resultView: noPaths }))).toBeNull()
+    const badPaths = {
+      card: 'search', shape: 'paths', truncated: false, total: 1, paths: [42],
+    } as unknown as ToolResultView
+    expect(searchCardModel(settledGlob({ resultView: badPaths }))).toBeNull()
+  })
+
+  it('surfaces the recovery text only when the result was capped', () => {
+    const recovery = 'a.ts\n  12: const foo = 1\n\n(Full grep result stored at: spill://grep-1. Read it to see every match.)'
+    // The recovery locator lives in the raw tool/result content (the view carries
+    // no text), surfaced only when the card capped the result.
+    const capped = searchCardModel(settledGrep({
+      content: [{ type: 'text', text: recovery }],
+      resultView: resultMatches({ truncated: true, total: 42 }),
+    }))
+    expect(capped?.recovery).toBe(recovery)
+    // Not capped: the card holds every match, so the raw content adds nothing and
+    // is dropped.
+    const whole = searchCardModel(settledGrep({
+      content: [{ type: 'text', text: recovery }],
+      resultView: resultMatches({ truncated: false }),
+    }))
+    expect(whole?.recovery).toBeUndefined()
+    // Capped but the block carries no text: nothing to surface.
+    const noText = searchCardModel(settledGrep({ content: [], resultView: resultMatches({ truncated: true, total: 42 }) }))
+    expect(noText?.recovery).toBeUndefined()
+  })
+})
+
+describe('chat row search body (GenericToolCard fallback)', () => {
+  const ownerProps = (block: RunningToolCall | ToolResultNode, toolName: string): GenericToolCardProps => ({
+    callId: 'c1', toolName, block, openFile: vi.fn(), t,
+  })
+  /** The whole summary row is the expand toggle (ToolRow's unified interaction). */
+  const toggleRow = (view: { container: HTMLElement }) => {
+    fireEvent.click(view.container.querySelector('[data-expandable]')!)
+  }
+
+  it('the expanded body is the grouped matches, capped tighter than the panel', () => {
+    expect(CHAT_SEARCH_MAX_LINES).toBeLessThan(16)
+    const view = render(<GenericToolCard {...ownerProps(settledGrep(), 'grep')} />)
+    // Collapsed: the one-line summary row only, no card.
+    expect(view.queryByText(/const foo = 1/)).toBeNull()
+    toggleRow(view)
+    expect(searchRows(view.container)).toContain('12: const foo = 1')
+    expect(view.getByText('a.ts')).toBeTruthy()
+    expect(searchKindOf(view.container)).toBe('matches')
+    // The args JSON body the generic path would have shown is gone.
+    expect(view.queryByText(/"pattern"/)).toBeNull()
+  })
+
+  it('the glob fallback expands to the flat path card', () => {
+    const view = render(<GenericToolCard {...ownerProps(settledGlob(), 'glob')} />)
+    toggleRow(view)
+    expect(view.getByText('src/a.ts')).toBeTruthy()
+    expect(searchKindOf(view.container)).toBe('paths')
+  })
+
+  it('a non-search result keeps the args-JSON text body', () => {
+    const view = render(<GenericToolCard {...ownerProps(settledGrep({
+      resultView: { card: 'generic' },
+    }), 'grep')} />)
+    toggleRow(view)
+    expect(view.getByText(/"pattern"/)).toBeTruthy()
+    expect(searchKindOf(view.container)).toBeNull()
+  })
+
+  it('the expanded body shows the recovery footer below a capped card', () => {
+    const recovery = 'a.ts\n  12: const foo = 1\n\n(Full grep result stored at: spill://grep-1. Read it to see every match.)'
+    const view = render(<GenericToolCard {...ownerProps(settledGrep({
+      content: [{ type: 'text', text: recovery }],
+      resultView: resultMatches({ truncated: true, total: 42 }),
+    }), 'grep')} />)
+    toggleRow(view)
+    expect(searchKindOf(view.container)).toBe('matches')
+    expect(view.getByText(/Full grep result stored at: spill:\/\/grep-1/)).toBeTruthy()
+  })
+})
+
+describe('SearchRow keyed card', () => {
+  const rowProps = (block: RunningToolCall | ToolResultNode, toolName: string): ToolRowProps => ({
+    callId: 'c1', toolName, block, openFile: vi.fn(), sessionId: SID,
+  } as unknown as ToolRowProps)
+
+  it('renders the grep card resident under the summary row, without an expand gesture', () => {
+    const view = render(<SearchRow {...rowProps(settledGrep(), 'grep')} />)
+    expect(view.getByText('Search')).toBeTruthy()
+    expect(searchRows(view.container)).toContain('12: const foo = 1')
+    expect(searchKindOf(view.container)).toBe('matches')
+    // The card's controls are the row's only interactions.
+    expect(view.getByText('复制')).toBeTruthy()
+  })
+
+  it('renders the glob path card resident', () => {
+    const view = render(<SearchRow {...rowProps(settledGlob(), 'glob')} />)
+    expect(view.getByText('src/a.ts')).toBeTruthy()
+    expect(searchKindOf(view.container)).toBe('paths')
+  })
+
+  it('agrees with the summary row about the run state', () => {
+    const runningView = render(<SearchRow {...rowProps(runningGrep(), 'grep')} />)
+    expect(runningView.container.querySelector('[data-variant="search"]')?.getAttribute('data-state')).toBe('running')
+    // No result view yet, so no resident card.
+    expect(searchKindOf(runningView.container)).toBeNull()
+    cleanup()
+    const errorView = render(<SearchRow {...rowProps(settledGrep({
+      isError: true, resultView: { card: 'generic' },
+    }), 'grep')} />)
+    expect(errorView.container.querySelector('[data-variant="search"]')?.getAttribute('data-state')).toBe('error')
+  })
+
+  it('surfaces the result text when an errored search has no card', () => {
+    // grep/glob return no presentResult on error → no card; the row shows the
+    // model-facing error text instead of a bare red dot.
+    const view = render(<SearchRow {...rowProps(settledGrep({
+      isError: true, resultView: null,
+      content: [{ type: 'text', text: 'grep: invalid regular expression' }],
+    }), 'grep')} />)
+    expect(searchKindOf(view.container)).toBeNull()
+    expect(view.getByText('grep: invalid regular expression')).toBeTruthy()
+  })
+
+  it('surfaces the result text for a settled non-error call with no card', () => {
+    // A successful nested run_code sub-dispatch (backend computes no
+    // presentationMeta, so resultView is null) or a legacy generic result settles
+    // with search === null and state ok. The keyed SearchRow owns the slot, so
+    // without the widened arm the content would be lost behind a bare summary.
+    const view = render(<SearchRow {...rowProps(settledGrep({
+      isError: false, resultView: null,
+      content: [{ type: 'text', text: 'nested run_code output line' }],
+    }), 'grep')} />)
+    expect(view.container.querySelector('[data-variant="search"]')?.getAttribute('data-state')).toBe('ok')
+    expect(searchKindOf(view.container)).toBeNull()
+    expect(view.getByText('nested run_code output line')).toBeTruthy()
+  })
+
+  it('renders the recovery footer below the card when the search was capped', () => {
+    const recovery = 'a.ts\n  12: const foo = 1\n\n(Full grep result stored at: spill://grep-1. Read it to see every match.)'
+    const view = render(<SearchRow {...rowProps(settledGrep({
+      content: [{ type: 'text', text: recovery }],
+      resultView: resultMatches({ truncated: true, total: 42 }),
+    }), 'grep')} />)
+    expect(searchKindOf(view.container)).toBe('matches')
+    expect(view.getByText(/Full grep result stored at: spill:\/\/grep-1/)).toBeTruthy()
+  })
+
+  it('shows no recovery footer for an uncapped search', () => {
+    const view = render(<SearchRow {...rowProps(settledGrep(), 'grep')} />)
+    expect(view.container.textContent).not.toMatch(/stored at/)
+  })
+
+  it('falls back to the error name/code when an errored result has no text block', () => {
+    const view = render(<SearchRow {...rowProps(settledGrep({
+      isError: true, resultView: null, content: [],
+      error: { name: 'ToolError', code: 'timeout' },
+    }), 'grep')} />)
+    expect(view.getByText('ToolError: timeout')).toBeTruthy()
+  })
+
+  it('shows the result view\'s replacement title instead of the args summary', () => {
+    const view = render(<SearchRow {...rowProps(settledGrep({
+      resultView: resultMatches({ title: '3 matches in 2 files' }),
+    }), 'grep')} />)
+    expect(view.getByText('3 matches in 2 files')).toBeTruthy()
+  })
+
+  it('keeps the args-derived summary when the result view has no title', () => {
+    const view = render(<SearchRow {...rowProps(settledGrep(), 'grep')} />)
+    expect(view.getByText('foo')).toBeTruthy()
+  })
+
+  it('registers the one row component under both grep and glob keys', () => {
+    const registered: { key: unknown; component: unknown }[] = []
+    const ctx = {
+      slots: {
+        register: (options: { name: string; key: string }, component: unknown) => {
+          registered.push({ key: options.key, component })
+        },
+      },
+    } as never
+    searchToolview.apply(ctx)
+    expect(registered.map(r => r.key)).toEqual(['grep', 'glob'])
+    // One component, two keys.
+    expect(registered[0]!.component).toBe(SearchRow)
+    expect(registered[1]!.component).toBe(SearchRow)
+    expect(searchToolview.inject).toEqual(['slots', 'conversation'])
+  })
+})
+
+describe('DetailsPanel Output section (search)', () => {
+  function mount(snapshot: ConversationSnapshot, selection: SelectionTarget | null) {
+    localStorage.clear()
+    const chat = createChatStore().create()
+    if (selection !== null) chat.actions.select(selection)
+    const sessions = createSnapshotStore<SessionListState>({ ids: [], byId: {}, current: undefined, phase: 'ready' })
+    const workspaces = createSnapshotStore<WorkspaceListState>({
+      items: [], archivedSessionIds: [], state: 'idle', phase: 'ready', error: null,
+      baselinesReady: true, recentWorkspaceId: undefined,
+    })
+    return render(
+      <DetailsPanel
+        sessionId={SID}
+        useSession={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
+        useSessions={bindSnapshotSelector(sessions)}
+        useWorkspaces={bindSnapshotSelector(workspaces)}
+        useInput={(() => { throw new Error('unused') })}
+        inputActions={{ setDraft: () => {}, submit: () => {} }}
+        useProjection={(() => undefined)}
+        useStore={bindSnapshotSelector(chat)}
+        actions={chat.actions}
+        closeDetails={vi.fn()}
+        t={t}
+      />,
+    )
+  }
+
+  function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    return {
+      sessionId: SID, nodes: [], partial: null, runningCalls: [], codeDispatches: new Map(),
+      pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
+      openState: 'open', openError: null, hasMore: false, loadingOlder: false,
+      promptError: null, blank: false, lastAgentError: null, ...over,
+    }
+  }
+
+  const grepTarget: SelectionTarget = { turnSeq: 10, callId: 'c1', toolName: 'grep' }
+  const globTarget: SelectionTarget = { turnSeq: 11, callId: 'c2', toolName: 'glob' }
+
+  it('renders the grep matches card at full height, keeping the JSON Input section', () => {
+    const view = mount(snapshot({ nodes: [settledGrep()] }), grepTarget)
+    expect(view.getByText(/"pattern"/)).toBeTruthy()
+    expect(searchRows(view.container)).toContain('12: const foo = 1')
+    expect(searchKindOf(view.container)).toBe('matches')
+  })
+
+  it('renders the glob path card', () => {
+    const view = mount(snapshot({ nodes: [settledGlob()] }), globTarget)
+    expect(view.getByText('src/a.ts')).toBeTruthy()
+    expect(searchKindOf(view.container)).toBe('paths')
+  })
+
+  it('renders the recovery footer below the card for a capped search', () => {
+    const recovery = 'src/a.ts\nsrc/b.ts\n\n(Showing 2 of 23 paths. Full sorted result stored at: spill://glob-7.)'
+    const view = mount(snapshot({
+      nodes: [settledGlob({ content: [{ type: 'text', text: recovery }], resultView: resultPaths({ truncated: true, total: 23 }) })],
+    }), globTarget)
+    expect(searchKindOf(view.container)).toBe('paths')
+    expect(view.getByText(/Full sorted result stored at: spill:\/\/glob-7/)).toBeTruthy()
+  })
+
+  it('a non-search result keeps the flattened pre form', () => {
+    const view = mount(snapshot({
+      nodes: [settledGrep({ callView: null, resultView: null })],
+    }), grepTarget)
+    expect(searchKindOf(view.container)).toBeNull()
+    const output = view.getByText('输出').closest('section')
+    expect(output?.querySelector('pre')?.textContent).toContain('const foo = 1')
+  })
+})

packages/client/ui-conversation/tsconfig.json

@@ -26,6 +26,9 @@
     {
       "path": "../../session-projection/session-projection"
     },
+    {
+      "path": "../../llm/token-meter"
+    },
     {
       "path": "../../plan/plan-mode"
     },

packages/client/ui-models/package.json

@@ -51,6 +51,7 @@
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-schema-form": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",

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

@@ -4,10 +4,15 @@ import { describe, expect, it, vi } from 'vitest'
 import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject, refreshIfLoaded } from '@deepseek-ai/dsh-client-ui-models/client'
 import { ModelsSection } from '../src/client/ModelsSection.tsx'
 import { DeepSeekOnboardingDialog } from '../src/client/DeepSeekOnboardingDialog.tsx'
 
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
 async function bench() {
   const ctx = new Context()
   await ctx.plugin(SlotsService).await()

packages/client/ui-primitives/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-primitives/README.md
-README.md: 58be01d56a85c66a144df3f8054840961e987403
-README.zh.md: 2efbec77e64d664553e93b5a8f8dcd2ec7fce49e
+README.md: 6430a789c15634538a38d6581df50a489522db55
+README.zh.md: 78249612cce3148fcececded40c529682450460a

packages/client/ui-primitives/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, and WebBlock. Contract: api-contracts v3 §8.
+Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, SearchBlock, DiffBlock, and WebBlock. Contract: api-contracts v3 §8.
 
 ## Markdown rendering
 
@@ -12,6 +12,10 @@ Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/
 
 `TerminalBlock` renders a shell command as a terminal surface: one prompt row per line of the command (the shortened `cwd` label on the first row only, since the view knows one working directory and a `cd` moves later lines elsewhere, then that line), the command's output, a status pill for a non-zero exit code or a terminating signal, and a copy control that writes the raw `output` prop. A run-state `StateDot` marks the call once, on the first row, out of flow in a gutter the card reserves as its own left padding, so the dot sits inside the card box yet left of the prompt text. It reaches three of `StateDot`'s states — the chase while `running`, red for the same exit status that renders the pill, green otherwise — so a card states whether its command is still running rather than leaving that to be inferred from the presence of output; it carries one visually hidden text label because `StateDot` is `aria-hidden`. One dot regardless of line count is deliberate: the exit status is the whole call's, so a dot per line would claim a per-line outcome the view does not carry. Command text is `white-space: pre`, so repeated spaces, tabs, and an indented continuation render verbatim while the row stays single-line and ellipsizes. ANSI escape sequences are parsed with the `anser` runtime dependency into React spans; cursor movements replay into a per-line column buffer before inert controls are stripped, since carriage return and backspace only MOVE the cursor: `100%` + CR + `OK` alone shows `OK0%`, while the `\x1b[K` a spinner writes with its redraw erases the tail so `100%\r\x1b[KOK` shows `OK`. Erase-in-line is honored in all three parameter forms, the cursor advances by terminal columns (8-column tab stops, two for emoji and CJK, none for a combining mark), and SGR state is normalized per cell as a terminal stores it, threading across lines and closing at the state the line ended in; basic-16 foreground colors map onto `--dsw-*` tokens, while 256-palette and truecolor values pass through as literal rgb. Output keeps `white-space: pre` with horizontal scrolling, so column-aligned output holds its alignment instead of soft-wrapping, and collapses to a head slice plus a tail slice past `maxLines` (default 16, the TUI transcript's split arithmetic) behind an expand button. Rationale: [the web terminal card note](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md).
 
+## Search results
+
+`SearchBlock` renders a completed search, one component for both kinds (discriminated by `kind`). A `matches` (grep) shows each file as a bold path header with its `lineNumber: line` rows, the per-file group collapsible; a `paths` (glob) shows a flat path list. Both flatten to one row list the height cap slices head/tail over (default 16, the TerminalBlock split arithmetic), and neither soft-wraps — a long match line or path scrolls horizontally instead of folding. The banner summary folds the pre-cap total in when the tool capped the result (`显示 X / 共 N 处匹配 · K 个文件` for grep, `显示 X / 共 N 个路径` for glob), so the card never presents a capped result as complete; a copy control writes the whole structured result regardless of the cap or which groups are collapsed. Geometry mirrors CodeBlock/TerminalBlock. Rationale: [the web search card note](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md).
+
 ## Diff rendering
 
 `DiffBlock` renders a file mutation as an inline diff surface: one bold path header per file, the removed lines (`- `, error token) above the added lines (`+ `, success token), a `⋯` gap before a same-file second hunk, and a dim `└ +A -R · N file(s)` footer. Lines are `white-space: pre` with horizontal scrolling, so a source line holds its indentation instead of soft-wrapping, and the body collapses to a head slice plus a tail slice past `maxLines` (default 16, `TerminalBlock`'s split arithmetic) behind an expand button. A create (`oldText: null`) has no removed side. The copy control writes the prefixed diff text (path headers, `- `/`+ ` lines, the gap) so a multi-file copy stays attributable, and floats in the top-right corner rather than on a banner row of its own. Geometry mirrors `CodeBlock`/`TerminalBlock`. The `+`/`-` block form mirrors the TUI transcript's diff card so a diff reads the same across front ends. Rationale: [the web diff card note](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md).

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

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock，以及 WebBlock。契约：api-contracts v3 §8。
+纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、SearchBlock、DiffBlock，以及 WebBlock。契约：api-contracts v3 §8。
 
 ## Markdown 渲染
 
@@ -11,6 +11,10 @@
 
 `TerminalBlock` 将一条 shell 命令渲染为终端表层：命令的每一行各占一个提示行（缩短后的 `cwd` 标签只出现在第一行，因为视图只知道一个工作目录，而一个 `cd` 就会让后面的行去到别处，标签之后是该行）、命令输出、非零退出码或终止信号对应的状态胶囊，以及写入原始 `output` prop 的复制控件。一枚运行状态 `StateDot` 为整次调用标记一次，位于第一行，以脱离文档流的方式落在卡片以自身左内边距预留的落区中，因此它位于卡片盒之内、提示文字之左。它用到 `StateDot` 的三种状态——`running` 期间为追逐动画，与渲染状态胶囊相同的退出状态为红色，其余为绿色——因此卡片直接陈述其命令是否仍在运行，而不是让人从有无输出中推断；由于 `StateDot` 是 `aria-hidden`，它携带一处视觉隐藏的文本标签。无论多少行都只有一枚状态点是有意为之：退出状态属于整次调用，因此每行一枚就会声称一个视图并不携带的逐行结果。命令文本使用 `white-space: pre`，因此重复空格、制表符与缩进续行都原样呈现，同时该行仍保持单行并以省略号截断。ANSI 转义序列通过运行时依赖 `anser` 解析为 React span；光标移动在剥除无显示意义控制符之前先重放进逐行的列缓冲，因为回车与退格**只移动**光标：单是 `100%` 加回车再加 `OK` 显示为 `OK0%`，而 spinner 随重绘写出的 `\x1b[K` 会擦掉尾巴，因此 `100%\r\x1b[KOK` 显示为 `OK`。行内擦除的三种参数形式都被遵循，光标按终端列推进（8 列制表位；emoji 与 CJK 占两列；组合标记不占列），SGR 状态按单元格归一化存储，与终端一致，并跨行延续、在行结束时的状态处收束；基础 16 色前景色映射到 `--dsw-*` token，而 256 色板与真彩色值按字面 rgb 透传。输出保持 `white-space: pre` 并支持横向滚动，因此按列对齐的输出保留其对齐而不会软换行；超过 `maxLines`（默认 16，与 TUI 转录相同的切分算法）时折叠为头部切片加尾部切片，由展开按钮控制。原理：[Web 终端卡片笔记](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)。
 
+## 搜索结果
+
+`SearchBlock` 渲染一次已完成的搜索,一个组件绘制两种 kind(由 `kind` 判别)。`matches`(grep)把每个文件渲染为粗体路径头加其 `lineNumber: line` 行,每个文件组可折叠;`paths`(glob)渲染扁平路径列表。两者都摊平成一个行列表,由高度上限做头/尾切片(默认 16,与 TerminalBlock 相同的切分算法),且都不软换行——长匹配行或路径横向滚动而非折行。当工具截断结果时,banner 摘要把截断前总数折入(grep 为 `显示 X / 共 N 处匹配 · K 个文件`,glob 为 `显示 X / 共 N 个路径`),使卡片绝不把截断结果呈现为完整;复制控件写入完整结构化结果,无论是否触及上限或哪些组被折叠。几何镜像 CodeBlock/TerminalBlock。原理:[Web 搜索卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md)。
+
 ## Diff 渲染
 
 `DiffBlock` 将一次文件改动渲染为内联 diff 表层：每个文件一个粗体路径头、删除行（`- `，error token）在新增行（`+ `，success token）之上、同文件第二个 hunk 前一个 `⋯` gap，以及暗色 `└ +A -R · N file(s)` 页脚。各行使用 `white-space: pre` 并横向滚动，因此源码行保留其缩进而不软换行；超过 `maxLines`（默认 16，与 `TerminalBlock` 相同的切分算法）时折叠为头部切片加尾部切片，由展开按钮控制。新建（`oldText: null`）没有删除侧。复制控件写入带前缀的 diff 文本（路径头、`- `/`+ ` 行、gap），使多文件复制保持可归属，并浮在右上角而非占据自己的 banner 行。几何镜像 `CodeBlock`/`TerminalBlock`。`+`/`-` 块形式镜像 TUI 转录的 diff 卡片，使 diff 在两个前端读起来一致。原理：[Web diff 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)。

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

@@ -0,0 +1,117 @@
+/* Geometry mirrors CodeBlock (12px radius, code-block surface + banner row,
+   markdown code-block font) so a read card and a fenced code block read as one
+   family. Content keeps `white-space: pre` and scrolls horizontally rather than
+   folding, because a source line's indentation is part of what a reader is
+   reading. */
+
+.block {
+  --dsl-read-radius: 12px;
+  --dsl-read-line-height: 22px;
+  /* Fixed-width gutter column for the line numbers, so the content edge stays
+     put down the whole window regardless of how wide the numbers grow. */
+  --dsl-read-gutter: 48px;
+
+  position: relative;
+  margin: 16px 0;
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-markdown-code-block);
+  border-radius: var(--dsl-read-radius);
+}
+
+.banner {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 12px;
+  padding: 9px 14px;
+  background: var(--dsw-alias-markdown-code-block-banner);
+  border-top-left-radius: var(--dsl-read-radius);
+  border-top-right-radius: var(--dsl-read-radius);
+}
+
+.label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--dsw-alias-label-primary);
+  font-family: var(--ds-font-family-code);
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.action {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  gap: 12px;
+}
+
+.count {
+  color: var(--dsw-alias-label-tertiary);
+  font: var(--dsw-font-xs-13);
+}
+
+.lang {
+  color: var(--dsw-alias-label-tertiary);
+  font-family: var(--ds-font-family-code);
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.copyButton {
+  background-color: transparent;
+  border: none;
+  padding: 0;
+  margin: 0;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+  font: var(--dsw-font-xs-13);
+}
+
+.body {
+  padding: 12px 0;
+  font: var(--dsw-font-markdown-code-block);
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+/* One row per file line: a fixed gutter column, then the content. No wrapping —
+   a source line's leading whitespace is meaningful and scrolls sideways. */
+.line {
+  display: flex;
+  min-height: var(--dsl-read-line-height);
+  line-height: var(--dsl-read-line-height);
+  white-space: pre;
+}
+
+.gutter {
+  flex: none;
+  width: var(--dsl-read-gutter);
+  padding-right: 14px;
+  text-align: right;
+  color: var(--dsw-alias-label-tertiary);
+  /* The gutter is chrome, not content: keep it out of a text selection so a
+     copy of the visible rows carries the source, not the line numbers. */
+  user-select: none;
+}
+
+.content {
+  color: var(--dsw-alias-label-primary);
+}
+
+.expand {
+  display: block;
+  width: 100%;
+  padding: 0 0 0 var(--dsl-read-gutter);
+  border: none;
+  background-color: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+  font: inherit;
+  text-align: left;
+}
+
+.expand:hover {
+  color: var(--dsw-alias-label-secondary);
+}

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

@@ -0,0 +1,172 @@
+// ReadBlock: the file surface for a read tool result — a banner (label +
+// language + a "showing N of M" note when the read is a window + a copy
+// control) over line-numbered, syntax-highlighted source. Each row carries the
+// file's OWN line number in a gutter, so a windowed read past an offset keeps
+// its file numbering rather than re-counting from 1. Highlighting reuses the
+// CodeBlock shiki path (highlight.ts) at the per-line granularity a gutter
+// needs; an unknown or absent language renders plain monospace. Long content is
+// height-capped with the same head/tail arithmetic TerminalBlock uses, so the
+// two cards collapse a long body at the same place. Colors resolve through
+// --shiki-*/--dsw-* tokens.
+
+import { useCallback, useMemo, useState, useSyncExternalStore } from 'react'
+import clsx from 'clsx'
+import { writeClipboard } from './clipboard.ts'
+import {
+  grammarLoadCount,
+  highlightLines,
+  subscribeGrammarLoaded,
+  type HighlightSpan,
+} from './markdown/highlight.ts'
+import css from './ReadBlock.module.css'
+
+/**
+ * Content lines shown before the height cap collapses the middle. Matches
+ * TerminalBlock's default so a long read and a long command output cut at the
+ * same place in the same flow.
+ */
+export const DEFAULT_READ_MAX_LINES = 16
+
+/** One line of the read window: its file line number and its text (no trailing newline). */
+export interface ReadBlockLine {
+  /** 1-based line number in the file (a window past an offset keeps the file's own numbering). */
+  number: number
+  /** The line's text, already truncated to the read tool's per-line cap. */
+  text: string
+}
+
+export interface ReadBlockProps {
+  /** Banner label (the file path, or a tool-supplied replacement title); omitted draws no label. */
+  label?: string | undefined
+  /** The returned window's lines, in file order, each keeping its file line number. */
+  lines: readonly ReadBlockLine[]
+  /** Exact total line count in the file, for the "showing N of M" note when the read is a window. */
+  totalLines: number
+  /** Grammar hint (a file-extension-derived language id); unknown or absent = plain monospace. */
+  lang?: string | undefined
+  /** Height cap in content lines before the middle collapses (default {@link DEFAULT_READ_MAX_LINES}). */
+  maxLines?: number | undefined
+  /** Extra class merged onto the wrapper (callers position; this component draws). */
+  className?: string | undefined
+}
+
+/**
+ * Render one line's highlighted runs. The css-variables theme colors every run,
+ * so each run is a styled span; a line with no highlighting at all takes the
+ * bare-text path in the caller instead (an unknown or absent language).
+ * @param spans - the line's styled runs.
+ * @returns the line's children.
+ */
+function renderSpans(spans: readonly HighlightSpan[]) {
+  return spans.map((span, index) => <span key={index} style={span.style}>{span.text}</span>)
+}
+
+/**
+ * Render a read tool result as a line-numbered, optionally syntax-highlighted
+ * file view.
+ * @param props - see {@link ReadBlockProps}.
+ * @returns the read block element.
+ */
+export function ReadBlock({
+  label,
+  lines,
+  totalLines,
+  lang,
+  maxLines = DEFAULT_READ_MAX_LINES,
+  className,
+}: ReadBlockProps) {
+  // The raw text the copy control writes and the highlighter tokenizes: the
+  // window's lines joined by newlines, without the file numbers or any chrome.
+  // Highlighting the whole window in one call (not line by line) keeps grammar
+  // context across lines — a multi-line string or comment stays one construct.
+  const raw = useMemo(() => lines.map(line => line.text).join('\n'), [lines])
+  // Re-render when a lazy grammar finishes loading, so a read card that showed
+  // plain text while its language's grammar imported picks up highlighting. The
+  // snapshot value is opaque; only its change across renders drives the memo.
+  const loaded = useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount, grammarLoadCount)
+  // Per-line highlighted runs aligned 1:1 with `lines`; undefined for an
+  // unknown/absent (or not-yet-loaded) language, when every line renders as
+  // bare text.
+  const highlighted = useMemo(() => highlightLines(raw, lang), [raw, lang, loaded])
+  const [expanded, setExpanded] = useState(false)
+  const [copied, setCopied] = useState(false)
+
+  const onCopy = useCallback(() => {
+    if (copied) return
+    // The window's raw text, never the rendered tree: the gutter numbers and the
+    // banner are chrome the file does not contain.
+    void writeClipboard(raw).then((ok) => {
+      if (!ok) return
+      setCopied(true)
+      window.setTimeout(() => { setCopied(false) }, 1000)
+    })
+  }, [copied, raw])
+
+  const onToggle = useCallback(() => { setExpanded(value => !value) }, [])
+
+  const hidden = lines.length - maxLines
+  const capped = hidden > 0 && !expanded
+  // Same split arithmetic as TerminalBlock's height cap, so a long read and a
+  // long command output slice their head and tail at the same place.
+  const headLines = Math.ceil(maxLines / 2)
+  const tailLines = maxLines - headLines
+  // A read is a window when its returned lines are fewer than the file's total;
+  // the note states that so a reader is not misled that the file ends here.
+  const windowed = lines.length < totalLines
+
+  /**
+   * Render a slice of the line array as gutter-numbered rows.
+   * @param slice - the lines to draw, each with its aligned run array.
+   * @returns the row elements.
+   */
+  const rows = (slice: readonly (readonly [ReadBlockLine, readonly HighlightSpan[] | undefined])[]) =>
+    slice.map(([line, spans]) => (
+      <div key={line.number} className={css.line}>
+        <span className={css.gutter} aria-hidden>{line.number}</span>
+        <span className={css.content}>{spans === undefined ? line.text : renderSpans(spans)}</span>
+      </div>
+    ))
+
+  // Pair each line with its aligned run array up front, so head/tail slicing
+  // keeps the two in step without re-indexing.
+  const paired = lines.map((line, index): readonly [ReadBlockLine, readonly HighlightSpan[] | undefined] =>
+    [line, highlighted?.[index]])
+
+  return (
+    <div className={clsx(css.block, className)} data-read="">
+      <div className={css.banner}>
+        <div className={css.label}>{label ?? ''}</div>
+        <div className={css.action}>
+          {windowed && (
+            <span className={css.count}>{`显示 ${lines.length} / ${totalLines} 行`}</span>
+          )}
+          <span className={css.lang}>{lang ?? ''}</span>
+          {/* Hide copy on an empty window, matching TerminalBlock's empty-output
+              guard: a successful read of an empty file returns lines: [] with
+              card:'read', so this branch is reachable, and copying then would
+              wipe the clipboard with an empty string. */}
+          {lines.length > 0 && (
+            <button type="button" className={css.copyButton} onClick={onCopy}>
+              {copied ? '复制成功' : '复制'}
+            </button>
+          )}
+        </div>
+      </div>
+      <div className={css.body}>
+        {rows(capped ? paired.slice(0, headLines) : paired)}
+        {hidden > 0 && (
+          <button
+            type="button"
+            className={css.expand}
+            aria-expanded={expanded}
+            aria-label={expanded ? '收起内容' : `展开其余 ${hidden} 行`}
+            onClick={onToggle}
+          >
+            {expanded ? '收起' : `… 其余 ${hidden} 行`}
+          </button>
+        )}
+        {capped && rows(paired.slice(paired.length - tailLines))}
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,120 @@
+/* Geometry mirrors CodeBlock and TerminalBlock (12px radius, code-block
+   surface + banner row, markdown code-block font) so a search card reads as one
+   family with them. The deliberate divergence they share: the result rows keep
+   `white-space: pre` and scroll horizontally, because folding a long match line
+   or path destroys the alignment a reader scans by. */
+
+.block {
+  --dsl-search-radius: 12px;
+  --dsl-search-line-height: 22px;
+
+  position: relative;
+  margin: 16px 0;
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-markdown-code-block);
+  border-radius: var(--dsl-search-radius);
+}
+
+/* The banner: result summary on the left, the copy control holding its
+   intrinsic width on the right. */
+.header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 9px 14px;
+  background: var(--dsw-alias-markdown-code-block-banner);
+  border-top-left-radius: var(--dsl-search-radius);
+  border-top-right-radius: var(--dsl-search-radius);
+}
+
+.summary {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-secondary);
+}
+
+.copyButton {
+  flex: none;
+  background-color: transparent;
+  border: none;
+  padding: 0;
+  margin: 0;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+  font: var(--dsw-font-xs-13);
+}
+
+.body {
+  padding: 8px 14px 12px 0;
+  font: var(--dsw-font-markdown-code-block);
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+/* No wrapping: a match line or a path keeps its content on one row and scrolls
+   sideways instead of folding. */
+.line {
+  min-height: var(--dsl-search-line-height);
+  padding-left: 14px;
+  white-space: pre;
+}
+
+/* The 1-based line number ahead of a grep match line, dimmed so the match text
+   stays the salient content. */
+.lineNumber {
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* A file group's header: a bold path label plus its match count, the whole row
+   the collapse control. */
+.fileHeader {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  width: 100%;
+  min-height: var(--dsl-search-line-height);
+  padding: 0 14px;
+  border: none;
+  background-color: transparent;
+  cursor: pointer;
+  font: inherit;
+  text-align: left;
+}
+
+.filePath {
+  min-width: 0;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary);
+  white-space: pre;
+}
+
+.fileCount {
+  flex: none;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.expand {
+  display: block;
+  width: 100%;
+  padding: 0 14px;
+  border: none;
+  background-color: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+  font: inherit;
+  text-align: left;
+}
+
+.expand:hover {
+  color: var(--dsw-alias-label-secondary);
+}
+
+.empty {
+  padding: 12px 14px;
+  font: var(--dsw-font-markdown-code-block);
+  color: var(--dsw-alias-label-tertiary);
+}

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

@@ -0,0 +1,277 @@
+// SearchBlock: the search surface for a completed content or path search — a
+// banner (result summary that folds the pre-cap total in when the tool capped
+// the result, plus a copy control), then either grep matches grouped by file
+// (each file a bold
+// path header with its `lineNumber: line` rows, the group collapsible) or a
+// flat glob path list. Both shapes flatten to one list of rows the height cap
+// slices head/tail over, and neither soft-wraps: a long match line or path
+// scrolls horizontally instead of folding. Geometry mirrors CodeBlock and
+// TerminalBlock so a search card reads as one family with them.
+
+import { useCallback, useState, type ReactNode } from 'react'
+import clsx from 'clsx'
+import { headTailCap } from './head-tail-cap.ts'
+import { useCopyFeedback } from './use-copy-feedback.ts'
+import css from './SearchBlock.module.css'
+
+/**
+ * Result rows shown before the height cap collapses the middle. Matches
+ * {@link DEFAULT_TERMINAL_MAX_LINES} so a search card and a terminal card cut a
+ * long result at the same place.
+ */
+export const DEFAULT_SEARCH_MAX_LINES = 16
+
+/** One matched line inside a {@link SearchFileGroup}: its 1-based line number and text. */
+export interface SearchBlockLineMatch {
+  /** 1-based line number of the match within its file. */
+  lineNumber: number
+  /** The matched line text, as the tool surfaced it. */
+  line: string
+}
+
+/** One file's grouped matches, in first-seen file order. */
+export interface SearchFileGroup {
+  /** The file the matches belong to (the display path). */
+  path: string
+  /** The file's matched lines, in output order. */
+  matches: SearchBlockLineMatch[]
+}
+
+/** Fields both search shapes carry (the render site positions; this component draws). */
+interface SearchBlockCommon {
+  /**
+   * Whether the tool capped the inline result: the shape carries only the
+   * retained results, not every result the search found. The banner summary
+   * folds the pre-cap `total` in (`显示 X / 共 N …`) so the card never presents a
+   * capped result as complete.
+   */
+  truncated: boolean
+  /** Total results the search found before capping (equals the retained count when not `truncated`). */
+  total: number
+  /** Height cap in rows before the middle collapses (default {@link DEFAULT_SEARCH_MAX_LINES}). */
+  maxLines?: number | undefined
+  /** Extra class merged onto the wrapper. */
+  className?: string | undefined
+}
+
+/** Props for the grouped-matches (`grep`) shape. */
+export interface SearchMatchesBlockProps extends SearchBlockCommon {
+  kind: 'matches'
+  /** Matched lines grouped by file, in first-seen file order. */
+  files: SearchFileGroup[]
+}
+
+/** Props for the flat-path (`glob`) shape. */
+export interface SearchPathsBlockProps extends SearchBlockCommon {
+  kind: 'paths'
+  /** The discovered paths, in the tool's result order (the retained page when `truncated`). */
+  paths: string[]
+}
+
+/** {@link SearchBlock} props: one card, two `kind`-discriminated shapes. */
+export type SearchBlockProps = SearchMatchesBlockProps | SearchPathsBlockProps
+
+/**
+ * One flattened render row. A matches card produces a `file` header row per
+ * group followed by a `match` row per retained line while the group is
+ * expanded; a paths card produces one `path` row per path. The height cap
+ * counts these rows uniformly, so a file header costs one row exactly as a
+ * match line or a path does.
+ */
+type SearchRow =
+  | { type: 'file'; path: string; count: number; index: number; collapsed: boolean }
+  | { type: 'match'; lineNumber: number; line: string; key: string; fileIndex: number }
+  | { type: 'path'; path: string }
+
+/**
+ * The plain-text form the copy control writes: the whole structured result
+ * regardless of the height cap or which groups are collapsed, so the clipboard
+ * carries the result rather than what the card happens to be showing.
+ * @param props - the card's props.
+ * @returns the copyable text, or the empty string for an empty result.
+ */
+function copyText(props: SearchBlockProps): string {
+  if (props.kind === 'paths') return props.paths.join('\n')
+  return props.files
+    .map(file => [file.path, ...file.matches.map(m => `${m.lineNumber}: ${m.line}`)].join('\n'))
+    .join('\n\n')
+}
+
+/**
+ * Number of retained results the card holds: the matched-line count across all
+ * files for a matches card, the path count for a paths card. This is the count
+ * the banner summary reports against `total` when the result was capped.
+ * @param props - the card's props.
+ * @returns the retained result count.
+ */
+function shownCount(props: SearchBlockProps): number {
+  return props.kind === 'paths'
+    ? props.paths.length
+    : props.files.reduce((sum, file) => sum + file.matches.length, 0)
+}
+
+/**
+ * The banner summary. When the search was capped it reads `显示 X / 共 N …` so
+ * the retained count and the pre-cap total sit in one clause (mirroring the read
+ * card's `显示 X / Y 行`); when it was not capped it is a plain count of what the
+ * card holds. The unit — `处匹配 · K 个文件` for grep, `个路径` for glob — trails
+ * the count either way.
+ * @param props - the card's props.
+ * @param shown - the retained result count from {@link shownCount}.
+ * @param truncated - whether the search was capped.
+ * @param total - the pre-cap total the truncation clause reports.
+ * @returns the summary text.
+ */
+function summaryText(props: SearchBlockProps, shown: number, truncated: boolean, total: number): string {
+  const count = truncated ? `显示 ${shown} / 共 ${total}` : `${shown}`
+  return props.kind === 'paths'
+    ? `${count} 个路径`
+    : `${count} 处匹配 · ${props.files.length} 个文件`
+}
+
+/**
+ * Flatten a card's shape into its render rows, dropping a collapsed file
+ * group's match rows.
+ * @param props - the card's props.
+ * @param collapsed - the set of collapsed file-group indices (matches only).
+ * @returns the flattened rows in output order.
+ */
+function toRows(props: SearchBlockProps, collapsed: ReadonlySet<number>): SearchRow[] {
+  if (props.kind === 'paths') return props.paths.map((path): SearchRow => ({ type: 'path', path }))
+  const rows: SearchRow[] = []
+  props.files.forEach((file, index) => {
+    const isCollapsed = collapsed.has(index)
+    rows.push({ type: 'file', path: file.path, count: file.matches.length, index, collapsed: isCollapsed })
+    if (isCollapsed) return
+    for (const match of file.matches) {
+      rows.push({ type: 'match', lineNumber: match.lineNumber, line: match.line, key: `${index}:${match.lineNumber}`, fileIndex: index })
+    }
+  })
+  return rows
+}
+
+/**
+ * A stable React key for a flattened render row: the group-scoped match key, a
+ * file-index-scoped header key, or the path itself. Rows of different types
+ * never collide, since each key carries its type prefix or the group index.
+ * @param row - the flattened row.
+ * @returns the key.
+ */
+function rowKey(row: SearchRow): string {
+  switch (row.type) {
+    case 'match': return `match:${row.key}`
+    case 'file': return `file:${row.index}`
+    case 'path': return `path:${row.path}`
+  }
+}
+
+/**
+ * Render a completed search as a grouped-matches or flat-path card.
+ * @param props - see {@link SearchBlockProps}.
+ * @returns the search block element.
+ */
+export function SearchBlock(props: SearchBlockProps) {
+  const { truncated, total, maxLines = DEFAULT_SEARCH_MAX_LINES, className } = props
+  const [expanded, setExpanded] = useState(false)
+  const [collapsed, setCollapsed] = useState<ReadonlySet<number>>(() => new Set())
+
+  // `props` is a fresh object each render, so memoizing on it never hits; the
+  // flatten is cheap, so it runs inline keyed on the collapse set instead.
+  const rows = toRows(props, collapsed)
+  const shown = shownCount(props)
+  const empty = rows.length === 0
+  const { copied, onCopy } = useCopyFeedback(copyText(props))
+
+  const onToggle = useCallback(() => { setExpanded(value => !value) }, [])
+
+  const toggleFile = useCallback((index: number) => {
+    setCollapsed((prev) => {
+      const next = new Set(prev)
+      if (next.has(index)) next.delete(index)
+      else next.add(index)
+      return next
+    })
+  }, [])
+
+  const { hidden, capped, headLines, tailLines } = headTailCap(rows.length, maxLines, expanded)
+  const head = capped ? rows.slice(0, headLines) : rows
+  const naturalTail = capped ? rows.slice(rows.length - tailLines) : []
+  // When the tail slice begins inside a file's matches, its own header sits
+  // above the cut and is not shown, so those rows could not be attributed to a
+  // file. Restore the owning header at the top of the tail — unless the head
+  // slice already carries it (a single large file), where it would duplicate.
+  const tailLead = naturalTail[0]
+  const tailHeader = tailLead?.type === 'match'
+    && !head.some(row => row.type === 'file' && row.index === tailLead.fileIndex)
+    ? rows.find((row): row is Extract<SearchRow, { type: 'file' }> =>
+      row.type === 'file' && row.index === tailLead.fileIndex)
+    : undefined
+  // The restored header is itself a row. Left extra it would push the card to
+  // maxLines + 1 and overstate `hidden` by one, so it consumes a tail slot: drop
+  // the tail's first row (the match whose header this is) for it. Visible rows
+  // hold at maxLines and `hidden` stays exact; the dropped match joins the
+  // hidden middle.
+  const tail = tailHeader === undefined ? naturalTail : naturalTail.slice(1)
+
+  const renderRow = (row: SearchRow): ReactNode => {
+    if (row.type === 'path') return <div className={css.line}>{row.path}</div>
+    if (row.type === 'match') {
+      return (
+        <div className={css.line}>
+          <span className={css.lineNumber}>{row.lineNumber}: </span>
+          {row.line}
+        </div>
+      )
+    }
+    return (
+      <button
+        type="button"
+        className={css.fileHeader}
+        aria-expanded={!row.collapsed}
+        onClick={() => { toggleFile(row.index) }}
+      >
+        <span className={css.filePath}>{row.path}</span>
+        <span className={css.fileCount}>{row.count}</span>
+      </button>
+    )
+  }
+
+  return (
+    <div className={clsx(css.block, className)} data-search={props.kind}>
+      <div className={css.header}>
+        <span className={css.summary}>{summaryText(props, shown, truncated, total)}</span>
+        {!empty && (
+          <button type="button" className={css.copyButton} onClick={onCopy}>
+            {copied ? '复制成功' : '复制'}
+          </button>
+        )}
+      </div>
+      {empty
+        ? <div className={css.empty}>无结果</div>
+        : (
+          <div className={css.body}>
+            {head.map(row => (
+              <div key={rowKey(row)}>{renderRow(row)}</div>
+            ))}
+            {hidden > 0 && (
+              <button
+                type="button"
+                className={css.expand}
+                aria-expanded={expanded}
+                aria-label={expanded ? '收起结果' : `展开其余 ${hidden} 行结果`}
+                onClick={onToggle}
+              >
+                {expanded ? '收起' : `… 其余 ${hidden} 行`}
+              </button>
+            )}
+            {tailHeader !== undefined && (
+              <div key={`tailHeader:${rowKey(tailHeader)}`}>{renderRow(tailHeader)}</div>
+            )}
+            {tail.map(row => (
+              <div key={rowKey(row)}>{renderRow(row)}</div>
+            ))}
+          </div>
+        )}
+    </div>
+  )
+}

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

@@ -8,7 +8,8 @@
 import { useCallback, useMemo, useState } from 'react'
 import clsx from 'clsx'
 import { parseAnsiLines, type AnsiLine } from './ansi.ts'
-import { writeClipboard } from './clipboard.ts'
+import { headTailCap } from './head-tail-cap.ts'
+import { useCopyFeedback } from './use-copy-feedback.ts'
 import { Pill } from './Pill.tsx'
 import { StateDot, type StateDotState } from './StateDot.tsx'
 import css from './TerminalBlock.module.css'
@@ -202,18 +203,9 @@ export function TerminalBlock({
     return terminated ? parsed.slice(0, -1) : parsed
   }, [text])
   const [expanded, setExpanded] = useState(false)
-  const [copied, setCopied] = useState(false)
-
-  const onCopy = useCallback(() => {
-    if (copied) return
-    // The raw output, never the rendered tree: the prompt line and the status
-    // pill are chrome the user did not run.
-    void writeClipboard(text).then((ok) => {
-      if (!ok) return
-      setCopied(true)
-      window.setTimeout(() => { setCopied(false) }, 1000)
-    })
-  }, [copied, text])
+  // The raw output, never the rendered tree: the prompt line and the status pill
+  // are chrome the user did not run.
+  const { copied, onCopy } = useCopyFeedback(text)
 
   const onToggle = useCallback(() => { setExpanded(value => !value) }, [])
 
@@ -232,12 +224,7 @@ export function TerminalBlock({
   // the raw text drew an output box of blank rows plus a copy control for
   // invisible bytes, and hid the placeholder that belongs there.
   const empty = lines.every(line => line.every(span => span.text.trim() === ''))
-  const hidden = lines.length - maxLines
-  const capped = hidden > 0 && !expanded
-  // Same split arithmetic as the TUI transcript's collapsed tool card, so a
-  // command's head and tail slices agree between the two front ends.
-  const headLines = Math.ceil(maxLines / 2)
-  const tailLines = maxLines - headLines
+  const { hidden, capped, headLines, tailLines } = headTailCap(lines.length, maxLines, expanded)
 
   return (
     <div className={clsx(css.block, className)} data-terminal="" data-running={running ? '' : undefined}>

packages/client/ui-primitives/src/head-tail-cap.ts

@@ -0,0 +1,33 @@
+// Head/tail height-cap arithmetic shared by the block primitives (TerminalBlock,
+// SearchBlock) and matching the TUI transcript's collapsed tool card, so a long
+// result's head and tail slices agree across every surface. The split is
+// `ceil(maxLines / 2)` head rows and the remainder as tail rows; a result within
+// the cap shows every row and hides none.
+
+/** The head/tail split metrics for a capped list. */
+export interface HeadTailCap {
+  /** Rows beyond the cap (list length − maxLines); ≤ 0 means nothing is hidden. */
+  hidden: number
+  /** Whether the list is over the cap and not expanded, so it shows a head/tail slice. */
+  capped: boolean
+  /** Head-slice row count: `ceil(maxLines / 2)`. */
+  headLines: number
+  /** Tail-slice row count: the remainder after the head. */
+  tailLines: number
+}
+
+/**
+ * Compute the head/tail cap metrics for a list of `total` rows against `maxLines`,
+ * given whether the surface is expanded. Pure arithmetic; the caller slices its
+ * own rows with `headLines`/`tailLines` so a block can layer its own concerns
+ * (SearchBlock restores a tail file header) on top.
+ * @param total - the list's row count.
+ * @param maxLines - the collapsed-height cap in rows.
+ * @param expanded - whether the surface is expanded (uncaps the list).
+ * @returns the split metrics.
+ */
+export function headTailCap(total: number, maxLines: number, expanded: boolean): HeadTailCap {
+  const hidden = total - maxLines
+  const headLines = Math.ceil(maxLines / 2)
+  return { hidden, capped: hidden > 0 && !expanded, headLines, tailLines: maxLines - headLines }
+}

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

@@ -24,6 +24,12 @@ export { JsonTree } from './JsonTree.tsx'
 export type { JsonTreeProps, JsonTreeLabels } from './JsonTree.tsx'
 export { TerminalBlock, DEFAULT_TERMINAL_MAX_LINES } from './TerminalBlock.tsx'
 export type { TerminalBlockProps, TerminalBlockLabels } from './TerminalBlock.tsx'
+export { SearchBlock, DEFAULT_SEARCH_MAX_LINES } from './SearchBlock.tsx'
+export type {
+  SearchBlockProps, SearchMatchesBlockProps, SearchPathsBlockProps, SearchFileGroup, SearchBlockLineMatch,
+} from './SearchBlock.tsx'
+export { ReadBlock, DEFAULT_READ_MAX_LINES } from './ReadBlock.tsx'
+export type { ReadBlockProps, ReadBlockLine } from './ReadBlock.tsx'
 export { DiffBlock, DEFAULT_DIFF_MAX_LINES } from './DiffBlock.tsx'
 export type { DiffBlockProps, DiffHunk } from './DiffBlock.tsx'
 export { WebBlock, DEFAULT_WEB_MAX_SOURCES } from './WebBlock.tsx'

packages/client/ui-primitives/src/markdown/CodeBlock.tsx

@@ -4,10 +4,10 @@
 // plain fallback for everything else. Chrome (language banner + copy) matches
 // deepsuite `@deepseek/md` code blocks; token colors stay on `--shiki-*`.
 
-import { useCallback, useMemo, useRef, useState } from 'react'
+import { useCallback, useMemo, useRef, useState, useSyncExternalStore } from 'react'
 import clsx from 'clsx'
 import { writeClipboard } from '../clipboard.ts'
-import { highlightToHtml } from './highlight.ts'
+import { grammarLoadCount, highlightToHtml, subscribeGrammarLoaded } from './highlight.ts'
 import css from './CodeBlock.module.css'
 
 export interface CodeBlockProps {
@@ -25,7 +25,11 @@ export interface CodeBlockProps {
 
 export function CodeBlock({ code, lang, className, copyLabel = '复制', copiedLabel = '复制成功' }: CodeBlockProps) {
   const trimmed = code.endsWith('\n') ? code.slice(0, -1) : code
-  const html = useMemo(() => highlightToHtml(trimmed, lang), [trimmed, lang])
+  // Re-render when a lazy grammar finishes loading, so a fence that showed plain
+  // text while its language's grammar imported picks up highlighting. The
+  // snapshot value is opaque; only its change across renders drives the memo.
+  const loaded = useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount, grammarLoadCount)
+  const html = useMemo(() => highlightToHtml(trimmed, lang), [trimmed, lang, loaded])
   const rootRef = useRef<HTMLDivElement>(null)
   const [copied, setCopied] = useState(false)
 

packages/client/ui-primitives/src/markdown/highlight.ts

@@ -5,10 +5,17 @@
  * theme package's token sheets as `--shiki-*` custom properties (light and
  * dark blocks), never here — the repo's tokens-only styling rule.
  *
- * Grammars are the set the harness actually renders: TypeScript programs
- * (`run_code` bodies; TS pulls in JS via grammar embedding), shell commands,
- * and JSON payloads. An unknown or absent language falls back to plain text
- * (no highlighting, still monospace) — never an error.
+ * Only the three markdown-fence and `run_code` grammars (TypeScript, shell,
+ * JSON) load into the singleton at boot — the set every session renders. The
+ * read card's wider extension set (the file-extension language hints the read
+ * tool's `langFromPath` emits — `packages/fs/tool-fs`: python, rust, yaml,
+ * markup, …) is imported lazily and registered the first time such a language
+ * is requested, so a session that never opens a read card in one of those
+ * languages pays neither the ~1.6 MB of grammar modules nor their synchronous
+ * init. The first render of a lazy language falls back to plain text while its
+ * grammar loads, then {@link onGrammarLoaded} notifies subscribers to re-render
+ * with highlighting. An unknown or absent language falls back to plain text (no
+ * highlighting, still monospace) — never an error.
  */
 
 import { createHighlighterCoreSync, createCssVariablesTheme } from 'shiki/core'
@@ -17,12 +24,69 @@ import langTs from '@shikijs/langs/typescript'
 import langBash from '@shikijs/langs/shellscript'
 import langJson from '@shikijs/langs/json'
 import type { HighlighterCore } from 'shiki/core'
+import type { CSSProperties } from 'react'
+
+/** A shiki grammar module's default export (a `LanguageRegistration[]`), taken
+ *  from a boot grammar so no direct `@shikijs/types` dependency is needed. */
+type LangModule = { default: typeof langTs }
 
 /**
- * Language ids (and aliases) the singleton registers; everything else renders
+ * Grammars the singleton loads at boot; each entry's own `name` is the id
+ * `codeToTokens`/`codeToHtml` resolve. The JS-family aliases (js/jsx/ts/tsx)
+ * resolve to the TypeScript grammar rather than a separate one: it tokenizes
+ * plain TS/JS exactly, and JSX/TSX approximately (shiki's TS grammar is not the
+ * dedicated TSX grammar, so JSX elements tokenize imperfectly) — an accepted
+ * trade to keep the boot set to one JS-family grammar. The read card's wider
+ * set loads lazily through {@link LAZY_GRAMMARS}.
+ */
+const LANGS = [langTs, langBash, langJson]
+
+/**
+ * The read card's extension grammars, each behind a dynamic import so its
+ * module stays out of the boot chunk until a read of that language renders.
+ * Keyed by the grammar id (`LanguageRegistration.name`) the aliases resolve to.
+ * `@shikijs/langs`' default export is a `LanguageRegistration[]`; the loader
+ * hands the whole array to `loadLanguageSync`, which registers each entry
+ * (including embedded sub-grammars). The three boot grammars are absent —
+ * already loaded, so no alias value ever points at a missing entry here.
+ */
+const LAZY_GRAMMARS = new Map<string, () => Promise<LangModule>>([
+  ['python', () => import('@shikijs/langs/python')],
+  ['ruby', () => import('@shikijs/langs/ruby')],
+  ['go', () => import('@shikijs/langs/go')],
+  ['rust', () => import('@shikijs/langs/rust')],
+  ['java', () => import('@shikijs/langs/java')],
+  ['c', () => import('@shikijs/langs/c')],
+  ['cpp', () => import('@shikijs/langs/cpp')],
+  ['csharp', () => import('@shikijs/langs/csharp')],
+  ['kotlin', () => import('@shikijs/langs/kotlin')],
+  ['swift', () => import('@shikijs/langs/swift')],
+  ['php', () => import('@shikijs/langs/php')],
+  ['yaml', () => import('@shikijs/langs/yaml')],
+  ['toml', () => import('@shikijs/langs/toml')],
+  ['ini', () => import('@shikijs/langs/ini')],
+  ['markdown', () => import('@shikijs/langs/markdown')],
+  ['mdx', () => import('@shikijs/langs/mdx')],
+  ['html', () => import('@shikijs/langs/html')],
+  ['css', () => import('@shikijs/langs/css')],
+  ['scss', () => import('@shikijs/langs/scss')],
+  ['less', () => import('@shikijs/langs/less')],
+  ['sql', () => import('@shikijs/langs/sql')],
+  ['xml', () => import('@shikijs/langs/xml')],
+  ['lua', () => import('@shikijs/langs/lua')],
+])
+
+/**
+ * Language ids (and aliases) the highlighter accepts; everything else renders
  * plain. A Map, not an object: fence info strings are assistant-authored, so
  * a label like `constructor` or `__proto__` must miss instead of resolving an
- * inherited property and crashing the renderer inside shiki.
+ * inherited property and crashing the renderer inside shiki. Keys cover both
+ * the markdown-fence aliases `CodeBlock` uses and the file-extension hint ids
+ * the read tool's `langFromPath` emits, so both callers resolve the same
+ * grammars. The JS family maps to the TypeScript grammar (see {@link LANGS} for
+ * the JSX/TSX approximation), unchanged from when this was the only
+ * non-shell/JSON grammar. A value not in {@link LANGS} names a
+ * {@link LAZY_GRAMMARS} entry loaded on first use.
  */
 const LANG_ALIASES = new Map<string, string>([
   ['typescript', 'typescript'],
@@ -30,6 +94,7 @@ const LANG_ALIASES = new Map<string, string>([
   ['tsx', 'typescript'],
   ['javascript', 'typescript'],
   ['js', 'typescript'],
+  ['jsx', 'typescript'],
   ['shellscript', 'shellscript'],
   ['bash', 'shellscript'],
   ['sh', 'shellscript'],
@@ -37,6 +102,35 @@ const LANG_ALIASES = new Map<string, string>([
   ['zsh', 'shellscript'],
   ['json', 'json'],
   ['jsonc', 'json'],
+  ['py', 'python'],
+  ['python', 'python'],
+  ['rb', 'ruby'],
+  ['ruby', 'ruby'],
+  ['go', 'go'],
+  ['rs', 'rust'],
+  ['rust', 'rust'],
+  ['java', 'java'],
+  ['c', 'c'],
+  ['cpp', 'cpp'],
+  ['cs', 'csharp'],
+  ['csharp', 'csharp'],
+  ['kotlin', 'kotlin'],
+  ['swift', 'swift'],
+  ['php', 'php'],
+  ['yaml', 'yaml'],
+  ['yml', 'yaml'],
+  ['toml', 'toml'],
+  ['ini', 'ini'],
+  ['md', 'markdown'],
+  ['markdown', 'markdown'],
+  ['mdx', 'mdx'],
+  ['html', 'html'],
+  ['css', 'css'],
+  ['scss', 'scss'],
+  ['less', 'less'],
+  ['sql', 'sql'],
+  ['xml', 'xml'],
+  ['lua', 'lua'],
 ])
 
 /** All token colors resolve through `--shiki-*` custom properties (theme package sheets). */
@@ -52,12 +146,68 @@ let singleton: HighlighterCore | undefined
 function highlighter(): HighlighterCore {
   singleton ??= createHighlighterCoreSync({
     themes: [cssVariablesTheme],
-    langs: [langTs, langBash, langJson],
+    langs: LANGS,
     engine: createJavaScriptRegexEngine({ forgiving: true }),
   })
   return singleton
 }
 
+/** Grammar ids whose lazy import is in flight or done, so it is requested once. */
+const requested = new Set<string>()
+/** Subscribers re-rendered after a lazy grammar registers (React callers). */
+const listeners = new Set<() => void>()
+/** Bumped on each lazy-grammar load; the `useSyncExternalStore` snapshot. */
+let loadCount = 0
+
+/**
+ * Subscribe to lazy-grammar load completions; `listener` fires after a
+ * {@link LAZY_GRAMMARS} grammar finishes registering on the singleton, so a
+ * caller that rendered its plain fallback while the grammar loaded can
+ * re-highlight. Shaped as a `useSyncExternalStore` subscribe: pair it with
+ * {@link grammarLoadCount} as the snapshot. Returns an unsubscribe function.
+ * @param listener - invoked (no args) on each grammar-load completion.
+ * @returns a disposer that removes the listener.
+ */
+export function subscribeGrammarLoaded(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => { listeners.delete(listener) }
+}
+
+/**
+ * The lazy-grammar load counter — a value that changes on every load, so a
+ * `useSyncExternalStore` snapshot re-renders the subscriber when a grammar
+ * registers. Opaque: only its identity across renders matters.
+ * @returns the current load count.
+ */
+export function grammarLoadCount(): number {
+  return loadCount
+}
+
+/**
+ * Ensure the grammar `resolved` names is registered. A boot grammar (not in
+ * {@link LAZY_GRAMMARS}) and an already-loaded lazy grammar report ready
+ * synchronously; a lazy grammar not yet loaded starts its import (once) and
+ * reports not-ready, so the caller renders plain until a
+ * {@link subscribeGrammarLoaded} listener fires.
+ * @param resolved - the grammar id an alias resolved to.
+ * @returns whether the grammar is registered and ready to tokenize now.
+ */
+function ensureGrammar(resolved: string): boolean {
+  const load = LAZY_GRAMMARS.get(resolved)
+  // A boot grammar (already registered) has no lazy loader; it is always ready.
+  if (load === undefined) return true
+  if (highlighter().getLoadedLanguages().includes(resolved)) return true
+  if (!requested.has(resolved)) {
+    requested.add(resolved)
+    void load().then((mod) => {
+      highlighter().loadLanguageSync(mod.default)
+      loadCount += 1
+      for (const listener of listeners) listener()
+    })
+  }
+  return false
+}
+
 // Engine + grammar construction costs a long task (~120-175ms); building it
 // during the first finalized fence's render would jank exactly when a stream
 // completes. Warm the singleton in a deferred task at module load (= plugin
@@ -70,13 +220,59 @@ const warmupTimer = setTimeout(() => { highlighter() }, 0)
 /**
  * Highlight `code` into shiki's HTML (a single `<pre class="shiki">` tree)
  * when `lang` maps to a registered grammar; `undefined` means the caller
- * renders its plain fallback.
+ * renders its plain fallback. A lazy grammar not yet loaded returns `undefined`
+ * for this call and loads in the background; subscribe with
+ * {@link onGrammarLoaded} to re-highlight once it registers.
  * @param code - the source text.
  * @param lang - the language hint (a markdown fence info string or a fixed caller id).
- * @returns the highlighted HTML, or `undefined` for unknown languages.
+ * @returns the highlighted HTML, or `undefined` for unknown or not-yet-loaded languages.
  */
 export function highlightToHtml(code: string, lang: string | undefined): string | undefined {
   const resolved = lang === undefined ? undefined : LANG_ALIASES.get(lang.toLowerCase())
   if (resolved === undefined) return undefined
+  if (!ensureGrammar(resolved)) return undefined
   return highlighter().codeToHtml(code, { lang: resolved, theme: 'css-variables' })
 }
+
+/**
+ * One highlighted run of a line: the text and the inline style shiki assigned
+ * it. The css-variables theme colors every run through a `--shiki-*` custom
+ * property, so `style.color` is always present; it is held as a style object
+ * rather than a bare color so a run spreads onto a `<span style>` uniformly.
+ */
+export interface HighlightSpan {
+  text: string
+  style: CSSProperties
+}
+
+/**
+ * Tokenize `code` into per-line highlighted runs when `lang` maps to a
+ * registered grammar; `undefined` means the caller renders its plain fallback.
+ * A line-numbered view needs the token runs split per line (one gutter number
+ * per line), which the single-`<pre>` {@link highlightToHtml} does not expose,
+ * so this returns shiki's own 2D line/token structure narrowed to what a run
+ * renders. Each run's color is a `--shiki-*` custom property, keeping token
+ * colors on the theme package's sheets exactly as the HTML path does; the
+ * css-variables theme carries no font-style bits, matching that path's
+ * color-only output. The trailing newline shiki appends as a final empty line
+ * is dropped so the run count matches the caller's own line array.
+ * @param code - the source text.
+ * @param lang - the language hint (a file-extension-derived language id).
+ * @returns one entry per source line (each an array of runs), or `undefined` for unknown or not-yet-loaded languages.
+ */
+export function highlightLines(code: string, lang: string | undefined): HighlightSpan[][] | undefined {
+  const resolved = lang === undefined ? undefined : LANG_ALIASES.get(lang.toLowerCase())
+  if (resolved === undefined) return undefined
+  if (!ensureGrammar(resolved)) return undefined
+  const { tokens } = highlighter().codeToTokens(code, { lang: resolved, theme: 'css-variables' })
+  // shiki tokenizes `a\nb` into two lines; a trailing newline (`a\n`) adds a
+  // third, empty line the caller's own line array does not carry. Drop that
+  // one terminator line so the two structures stay in step. The explicit
+  // `last !== undefined` (over `tokens[...]?.length`) keeps a single branch for
+  // per-file coverage, matching TerminalBlock's terminator check.
+  const last = tokens[tokens.length - 1]
+  const lines = tokens.length > 1 && last !== undefined && last.length === 0
+    ? tokens.slice(0, -1)
+    : tokens
+  return lines.map(line => line.map(token => ({ text: token.content, style: { color: token.color } })))
+}

packages/client/ui-primitives/src/use-copy-feedback.ts

@@ -0,0 +1,37 @@
+// The copy-to-clipboard-with-feedback hook shared by the block primitives
+// (TerminalBlock, SearchBlock): write the given text, and on success flip a
+// transient `copied` flag that the caller renders as a "复制成功" label for one
+// second. A refused write leaves the flag untouched, so the control never claims
+// a copy the host declined.
+
+import { useCallback, useState } from 'react'
+import { writeClipboard } from './clipboard.ts'
+
+/** How long the `copied` flag stays true after a successful write, in ms. */
+const COPIED_FEEDBACK_MS = 1000
+
+/** The copy-feedback hook's return: the transient flag and the copy handler. */
+export interface CopyFeedback {
+  /** True for {@link COPIED_FEEDBACK_MS} after a successful write; render the success label off it. */
+  copied: boolean
+  /** Copy the hook's text; no-op while `copied` is still true, silent on a refused write. */
+  onCopy: () => void
+}
+
+/**
+ * Copy `text` to the clipboard with one-second success feedback.
+ * @param text - the text to write on copy.
+ * @returns the `copied` flag and the `onCopy` handler.
+ */
+export function useCopyFeedback(text: string): CopyFeedback {
+  const [copied, setCopied] = useState(false)
+  const onCopy = useCallback(() => {
+    if (copied) return
+    void writeClipboard(text).then((ok) => {
+      if (!ok) return
+      setCopied(true)
+      window.setTimeout(() => { setCopied(false) }, COPIED_FEEDBACK_MS)
+    })
+  }, [copied, text])
+  return { copied, onCopy }
+}

packages/client/ui-primitives/tests/code-block.spec.tsx

@@ -31,6 +31,24 @@ describe('highlightToHtml', () => {
     expect(highlightToHtml('x', 'cobol')).toBeUndefined()
     expect(highlightToHtml('x', undefined)).toBeUndefined()
   })
+
+  // Every read-tool language hint whose grammar loads lazily (the boot set —
+  // ts/js/bash/sh/json — is covered above). Touching each one drives its own
+  // dynamic import thunk, so the whole LAZY_GRAMMARS table is exercised.
+  const LAZY_ALIASES = [
+    'py', 'rb', 'go', 'rs', 'java', 'c', 'cpp', 'cs', 'kotlin', 'swift', 'php',
+    'yaml', 'toml', 'ini', 'md', 'mdx', 'html', 'css', 'scss', 'less', 'sql',
+    'xml', 'lua',
+  ]
+
+  it('lazily loads every read-card grammar: plain first, highlighted after load', async () => {
+    // First touch returns the plain fallback (undefined) and starts the import.
+    for (const alias of LAZY_ALIASES) expect(highlightToHtml('x', alias)).toBeUndefined()
+    // Once every grammar has registered, the same call highlights.
+    await vi.waitFor(() => {
+      for (const alias of LAZY_ALIASES) expect(highlightToHtml('x', alias)).toContain('shiki')
+    })
+  })
 })
 
 describe('CodeBlock', () => {

packages/client/ui-primitives/tests/read-block.spec.tsx

@@ -0,0 +1,241 @@
+// @vitest-environment jsdom
+// ReadBlock + the highlightLines token path: the banner (label, language, the
+// "showing N of M" note only when the read is a window, copy control), the
+// gutter-numbered rows keeping the file's own line numbers, the shiki per-line
+// highlighting resolved to css-variables token spans with an identical-geometry
+// plain fallback for an unknown/absent language, the head/tail height cap and
+// its expand control, and the copy control writing the raw window text on both
+// the accepted and refused clipboard paths.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { DEFAULT_READ_MAX_LINES, ReadBlock, type ReadBlockLine } from '../src/index.ts'
+import { grammarLoadCount, highlightLines, subscribeGrammarLoaded } from '../src/markdown/highlight.ts'
+
+afterEach(cleanup)
+
+beforeEach(() => {
+  vi.useRealTimers()
+})
+
+/** `count` lines starting at `first`, each with distinct text. */
+function lines(count: number, first = 1): ReadBlockLine[] {
+  return Array.from({ length: count }, (_value, index) => ({ number: first + index, text: `line ${first + index}` }))
+}
+
+/** The rendered rows as `<gutter><content>` strings (CSS-module class prefix). */
+function rowTexts(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[class^="_line_"]')].map(row => row.textContent ?? '')
+}
+
+/** The gutter numbers of the rendered rows, in order. */
+function gutters(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[class^="_gutter_"]')].map(cell => cell.textContent ?? '')
+}
+
+describe('highlightLines', () => {
+  it('tokenizes a registered grammar into per-line css-variables runs', () => {
+    const result = highlightLines('const x = 1\n// c', 'ts')
+    expect(result).not.toBeUndefined()
+    expect(result).toHaveLength(2)
+    // The keyword run carries a color style through a --shiki-* custom property.
+    const keyword = result![0]!.find(span => span.text === 'const')
+    expect(keyword?.style?.color).toContain('var(--shiki-')
+    // Whitespace between tokens is a run of its own; the comment is line two.
+    expect(result![0]!.map(span => span.text).join('')).toBe('const x = 1')
+    expect(result![1]!.map(span => span.text).join('')).toBe('// c')
+  })
+
+  it('colors every run through a --shiki-* custom property', () => {
+    // The css-variables theme colors even the whitespace run (as the foreground
+    // token), so every run is a styled span; the plain fallback is the whole
+    // unknown-language path, not a per-run one.
+    const result = highlightLines('const x = 1', 'ts')
+    for (const span of result!) for (const run of span) expect(run.style.color).toContain('var(--shiki-')
+  })
+
+  it('drops the trailing terminator line so the run count matches the source lines', () => {
+    // `a\n` tokenizes to two lines in shiki (the second empty); the caller's own
+    // line array has one entry, so the terminator line is dropped.
+    const result = highlightLines('const a = 1\n', 'ts')
+    expect(result).toHaveLength(1)
+  })
+
+  it('keeps a genuinely blank final line when the source ends in two newlines', () => {
+    const result = highlightLines('a\n\n', 'ts')
+    expect(result).toHaveLength(2)
+    expect(result![1]).toEqual([])
+  })
+
+  it('returns undefined for an unknown or absent language', () => {
+    expect(highlightLines('x', 'cobol')).toBeUndefined()
+    expect(highlightLines('x', undefined)).toBeUndefined()
+  })
+
+  it('loads a lazy grammar on first use: plain first, highlighted after it registers', async () => {
+    // A boot grammar (ts) is ready synchronously; a lazy grammar (python) is
+    // not, so the first call renders plain and imports the grammar, and a
+    // subscriber fires once it registers, after which the same call highlights.
+    let notified = 0
+    const stop = subscribeGrammarLoaded(() => { notified += 1 })
+    // First touch: grammar not loaded yet, so plain fallback while it imports.
+    expect(highlightLines('def f(): pass', 'py')).toBeUndefined()
+    // The import + loadLanguageSync resolve on a microtask; wait for the notify.
+    await vi.waitFor(() => { expect(notified).toBeGreaterThan(0) })
+    expect(grammarLoadCount()).toBeGreaterThan(0)
+    const result = highlightLines('def f(): pass', 'py')
+    expect(result).not.toBeUndefined()
+    // `def` is a python keyword and carries a --shiki-* color once highlighted.
+    const keyword = result!.flat().find(span => span.text === 'def')
+    expect(keyword?.style?.color).toContain('var(--shiki-')
+    stop()
+  })
+})
+
+describe('ReadBlock rows', () => {
+  it('renders one gutter-numbered row per line, keeping the file line numbers', () => {
+    const view = render(<ReadBlock label="a.ts" lines={lines(3, 41)} totalLines={3} />)
+    expect(gutters(view.container)).toEqual(['41', '42', '43'])
+    expect(rowTexts(view.container)).toEqual(['41line 41', '42line 42', '43line 43'])
+  })
+
+  it('highlights the content for a known language into token spans', () => {
+    const view = render(
+      <ReadBlock label="a.ts" lang="ts" lines={[{ number: 1, text: 'const a = 1' }]} totalLines={1} />,
+    )
+    const content = view.container.querySelector('[class^="_content_"]')
+    expect(content?.querySelectorAll('span[style]').length).toBeGreaterThan(1)
+    expect(content?.textContent).toBe('const a = 1')
+  })
+
+  it('renders the content as bare text with no span wrappers for an unknown language', () => {
+    const view = render(
+      <ReadBlock label="a.cob" lang="cobol" lines={[{ number: 1, text: 'IDENT DIVISION.' }]} totalLines={1} />,
+    )
+    const content = view.container.querySelector('[class^="_content_"]')
+    expect(content?.querySelectorAll('span').length).toBe(0)
+    expect(content?.textContent).toBe('IDENT DIVISION.')
+  })
+
+  it('renders bare text when no language is given', () => {
+    const view = render(<ReadBlock label="x" lines={[{ number: 1, text: 'plain' }]} totalLines={1} />)
+    const content = view.container.querySelector('[class^="_content_"]')
+    expect(content?.querySelectorAll('span').length).toBe(0)
+    expect(view.getByText('plain')).toBeTruthy()
+  })
+})
+
+describe('ReadBlock banner', () => {
+  it('shows the label, the language, and the count note when the read is a window', () => {
+    const view = render(<ReadBlock label="src/a.ts" lang="ts" lines={lines(3, 41)} totalLines={180} />)
+    expect(view.getByText('src/a.ts')).toBeTruthy()
+    expect(view.getByText('ts')).toBeTruthy()
+    expect(view.getByText('显示 3 / 180 行')).toBeTruthy()
+  })
+
+  it('omits the count note when the window is the whole file', () => {
+    const view = render(<ReadBlock label="a.ts" lines={lines(3)} totalLines={3} />)
+    expect(view.queryByText(/显示/u)).toBeNull()
+  })
+
+  it('draws an empty label and empty language when neither is given', () => {
+    const view = render(<ReadBlock lines={lines(1)} totalLines={1} />)
+    expect(view.container.querySelector('[class^="_label_"]')?.textContent).toBe('')
+    expect(view.container.querySelector('[class^="_lang_"]')?.textContent).toBe('')
+  })
+})
+
+describe('ReadBlock height cap', () => {
+  it('renders every line and no expand control under the cap', () => {
+    const view = render(<ReadBlock label="a" lines={lines(4)} totalLines={4} maxLines={4} />)
+    expect(rowTexts(view.container)).toHaveLength(4)
+    expect(view.container.querySelector('[aria-expanded]')).toBeNull()
+  })
+
+  it('slices head and tail over the cap and expands on click', () => {
+    const view = render(<ReadBlock label="a" lines={lines(10)} totalLines={10} maxLines={4} />)
+    // maxLines 4: head = ceil(4/2) = 2, tail = 4 - 2 = 2, 6 hidden.
+    expect(gutters(view.container)).toEqual(['1', '2', '9', '10'])
+    const toggle = view.getByRole('button', { name: '展开其余 6 行' })
+    expect(toggle.getAttribute('aria-expanded')).toBe('false')
+    expect(toggle.textContent).toBe('… 其余 6 行')
+
+    fireEvent.click(toggle)
+    expect(rowTexts(view.container)).toHaveLength(10)
+    const collapse = view.getByRole('button', { name: '收起内容' })
+    expect(collapse.getAttribute('aria-expanded')).toBe('true')
+    expect(collapse.textContent).toBe('收起')
+
+    fireEvent.click(collapse)
+    expect(gutters(view.container)).toEqual(['1', '2', '9', '10'])
+  })
+
+  it('renders the head slice alone when the cap leaves no tail', () => {
+    const view = render(<ReadBlock label="a" lines={lines(5)} totalLines={5} maxLines={1} />)
+    expect(gutters(view.container)).toEqual(['1'])
+    expect(view.getByRole('button', { name: '展开其余 4 行' })).toBeTruthy()
+  })
+
+  it('caps at the documented default when maxLines is absent', () => {
+    const view = render(
+      <ReadBlock label="a" lines={lines(DEFAULT_READ_MAX_LINES + 1)} totalLines={DEFAULT_READ_MAX_LINES + 1} />,
+    )
+    expect(rowTexts(view.container)).toHaveLength(DEFAULT_READ_MAX_LINES)
+    expect(view.getByRole('button', { name: '展开其余 1 行' })).toBeTruthy()
+  })
+})
+
+describe('ReadBlock copy', () => {
+  it('copies the raw window text, joined by newlines, never the gutter numbers', async () => {
+    vi.useFakeTimers()
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    render(<ReadBlock label="a" lines={lines(3, 41)} totalLines={180} />)
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    expect(writeText).toHaveBeenCalledWith('line 41\nline 42\nline 43')
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(screen.getByRole('button', { name: '复制成功' })).toBeTruthy()
+    // While the ok label is showing, further clicks are no-ops.
+    fireEvent.click(screen.getByRole('button', { name: '复制成功' }))
+    expect(writeText).toHaveBeenCalledTimes(1)
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
+  })
+
+  it('copies the whole window while the height cap hides its middle', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    render(<ReadBlock label="a" lines={lines(10)} totalLines={10} maxLines={4} />)
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    expect(writeText).toHaveBeenCalledWith(lines(10).map(line => line.text).join('\n'))
+    expect(await screen.findByRole('button', { name: '复制成功' })).toBeTruthy()
+  })
+
+  it('does not claim success when the host refuses the write', async () => {
+    Object.defineProperty(navigator, 'clipboard', {
+      configurable: true,
+      value: { writeText: vi.fn().mockRejectedValue(new Error('denied')) },
+    })
+    render(<ReadBlock label="a" lines={lines(1)} totalLines={1} />)
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
+    expect(screen.queryByRole('button', { name: '复制成功' })).toBeNull()
+  })
+
+  it('merges className onto the wrapper', () => {
+    const view = render(<ReadBlock className="x" label="a" lines={lines(1)} totalLines={1} />)
+    expect(view.container.firstElementChild?.classList.contains('x')).toBe(true)
+  })
+
+  it('hides the copy control for an empty window so it cannot wipe the clipboard', () => {
+    // A successful read of an empty file settles to lines: [] with card:'read',
+    // so this branch is reachable; copying then would clear the clipboard.
+    const view = render(<ReadBlock label="empty.ts" lines={[]} totalLines={0} />)
+    expect(view.queryByRole('button', { name: '复制' })).toBeNull()
+  })
+})

packages/client/ui-primitives/tests/search-block.spec.tsx

@@ -0,0 +1,214 @@
+// @vitest-environment jsdom
+// SearchBlock: both kinds (grouped grep matches and a flat glob path list), the
+// folded truncation summary, the empty arm, per-file collapse/expand, the
+// head/tail height cap and its expand control, the tail slice restoring its
+// owning file header, and the copy control writing the whole structured
+// result on both the accepted and refused clipboard paths.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { DEFAULT_SEARCH_MAX_LINES, SearchBlock } from '../src/index.ts'
+import type { SearchFileGroup } from '../src/index.ts'
+
+afterEach(cleanup)
+
+beforeEach(() => {
+  vi.useRealTimers()
+})
+
+/** The rendered result rows, one string per visible row (CSS-module class prefix). */
+function lines(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[class^="_line_"]')].map(row => row.textContent ?? '')
+}
+
+/** The file-group header rows, one string per header (path + count concatenated). */
+function fileHeaders(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[class^="_fileHeader_"]')].map(row => row.textContent ?? '')
+}
+
+/** `count` numbered match lines under one file, without a terminating newline. */
+function group(path: string, count: number, from = 1): SearchFileGroup {
+  return {
+    path,
+    matches: Array.from({ length: count }, (_v, i) => ({ lineNumber: from + i, line: `hit ${from + i}` })),
+  }
+}
+
+describe('SearchBlock matches kind', () => {
+  it('renders each file as a header group with its matched lines', () => {
+    const view = render(<SearchBlock kind="matches" truncated={false} total={3} files={[
+      { path: 'a.ts', matches: [{ lineNumber: 12, line: 'const a = 1' }, { lineNumber: 40, line: 'return a' }] },
+      { path: 'b.ts', matches: [{ lineNumber: 7, line: 'const b = 2' }] },
+    ]} />)
+    expect(fileHeaders(view.container)).toEqual(['a.ts2', 'b.ts1'])
+    expect(lines(view.container)).toEqual(['12: const a = 1', '40: return a', '7: const b = 2'])
+    // The summary counts matches and files, with no folded pre-cap total below the cap.
+    expect(view.getByText('3 处匹配 · 2 个文件')).toBeTruthy()
+    expect(view.queryByText(/显示|共/u)).toBeNull()
+  })
+
+  it('collapses and re-expands a single file group without touching the others', () => {
+    const view = render(<SearchBlock kind="matches" truncated={false} total={3} files={[
+      { path: 'a.ts', matches: [{ lineNumber: 1, line: 'x' }] },
+      { path: 'b.ts', matches: [{ lineNumber: 2, line: 'y' }] },
+    ]} />)
+    const [headerA] = view.container.querySelectorAll('[class^="_fileHeader_"]')
+    expect(headerA!.getAttribute('aria-expanded')).toBe('true')
+    fireEvent.click(headerA!)
+    // a.ts collapsed: its match row is gone, b.ts's stays.
+    expect(headerA!.getAttribute('aria-expanded')).toBe('false')
+    expect(lines(view.container)).toEqual(['2: y'])
+    fireEvent.click(headerA!)
+    expect(lines(view.container)).toEqual(['1: x', '2: y'])
+  })
+
+  it('folds the pre-cap total into the summary when truncated', () => {
+    const view = render(<SearchBlock kind="matches" truncated total={99} files={[group('a.ts', 2)]} />)
+    expect(view.getByText('显示 2 / 共 99 处匹配 · 1 个文件')).toBeTruthy()
+  })
+})
+
+describe('SearchBlock paths kind', () => {
+  it('renders a flat path list with a path-count summary', () => {
+    const view = render(<SearchBlock kind="paths" truncated={false} total={2} paths={['src/a.ts', 'src/b.ts']} />)
+    expect(lines(view.container)).toEqual(['src/a.ts', 'src/b.ts'])
+    expect(view.getByText('2 个路径')).toBeTruthy()
+    // No file-group headers in the paths shape.
+    expect(fileHeaders(view.container)).toEqual([])
+  })
+
+  it('folds the pre-cap total into the paths summary when truncated', () => {
+    const view = render(<SearchBlock kind="paths" truncated total={50} paths={['a', 'b']} />)
+    expect(view.getByText('显示 2 / 共 50 个路径')).toBeTruthy()
+  })
+})
+
+describe('SearchBlock empty arm', () => {
+  it('shows the placeholder and no copy control for an empty matches result', () => {
+    const view = render(<SearchBlock kind="matches" truncated={false} total={0} files={[]} />)
+    expect(view.getByText('无结果')).toBeTruthy()
+    expect(view.queryByText('复制')).toBeNull()
+    expect(view.getByText('0 处匹配 · 0 个文件')).toBeTruthy()
+  })
+
+  it('shows the placeholder for an empty paths result', () => {
+    const view = render(<SearchBlock kind="paths" truncated={false} total={0} paths={[]} />)
+    expect(view.getByText('无结果')).toBeTruthy()
+    expect(view.queryByText('复制')).toBeNull()
+  })
+})
+
+describe('SearchBlock height cap', () => {
+  it('renders every row and no expand control under the cap', () => {
+    const view = render(<SearchBlock kind="paths" truncated={false} total={4}
+      paths={['a', 'b', 'c', 'd']} maxLines={4} />)
+    expect(lines(view.container)).toHaveLength(4)
+    expect(view.container.querySelector('[aria-label^="展开"]')).toBeNull()
+  })
+
+  it('slices head and tail over the cap and expands on click', () => {
+    const paths = Array.from({ length: 10 }, (_v, i) => `p${i + 1}`)
+    const view = render(<SearchBlock kind="paths" truncated={false} total={10} paths={paths} maxLines={4} />)
+    // maxLines 4: head = ceil(4/2) = 2, tail = 2, 6 hidden.
+    expect(lines(view.container)).toEqual(['p1', 'p2', 'p9', 'p10'])
+    const toggle = view.getByRole('button', { name: '展开其余 6 行结果' })
+    expect(toggle.textContent).toBe('… 其余 6 行')
+    fireEvent.click(toggle)
+    expect(lines(view.container)).toHaveLength(10)
+    const collapse = view.getByRole('button', { name: '收起结果' })
+    expect(collapse.textContent).toBe('收起')
+    fireEvent.click(collapse)
+    expect(lines(view.container)).toEqual(['p1', 'p2', 'p9', 'p10'])
+  })
+
+  it('counts a file header as one capped row alongside its matches', () => {
+    // One file with 10 matches → 11 rows (header + 10). Cap 4: head 2, tail 2.
+    const view = render(<SearchBlock kind="matches" truncated={false} total={10}
+      files={[group('a.ts', 10)]} maxLines={4} />)
+    // Head takes the header then the first match; tail takes the last two matches.
+    expect(lines(view.container)).toEqual(['1: hit 1', '9: hit 9', '10: hit 10'])
+    expect(fileHeaders(view.container)).toEqual(['a.ts10'])
+    expect(view.getByRole('button', { name: '展开其余 7 行结果' })).toBeTruthy()
+  })
+
+  it('renders the head slice alone when the cap leaves no tail', () => {
+    const view = render(<SearchBlock kind="paths" truncated={false} total={5}
+      paths={['a', 'b', 'c', 'd', 'e']} maxLines={1} />)
+    expect(lines(view.container)).toEqual(['a'])
+    expect(view.getByRole('button', { name: '展开其余 4 行结果' })).toBeTruthy()
+  })
+
+  it('restores the owning file header above a tail slice that begins mid-file', () => {
+    // Two files of 10 matches each → 22 rows. Cap 8: head 4 (a.ts header + 3
+    // matches), tail 4. The tail begins mid-b.ts, so its header is restored —
+    // and, being a row itself, it consumes one tail slot rather than pushing the
+    // card to 9 rows: the tail keeps its last 3 matches, total visible = 8.
+    const view = render(<SearchBlock kind="matches" truncated={false} total={20} maxLines={8} files={[
+      group('a.ts', 10), group('b.ts', 10, 11),
+    ]} />)
+    expect(fileHeaders(view.container)).toEqual(['a.ts10', 'b.ts10'])
+    expect(lines(view.container)).toEqual([
+      '1: hit 1', '2: hit 2', '3: hit 3',
+      '18: hit 18', '19: hit 19', '20: hit 20',
+    ])
+    // Visible rows hold at maxLines (2 headers + 6 matches = 8), so the hidden
+    // count stays exact: 22 − 8 = 14.
+    expect(view.getByRole('button', { name: '展开其余 14 行结果' })).toBeTruthy()
+  })
+
+  it('caps at the documented default when maxLines is absent', () => {
+    const paths = Array.from({ length: DEFAULT_SEARCH_MAX_LINES + 1 }, (_v, i) => `p${i}`)
+    const view = render(<SearchBlock kind="paths" truncated={false} total={paths.length} paths={paths} />)
+    expect(lines(view.container)).toHaveLength(DEFAULT_SEARCH_MAX_LINES)
+    expect(view.getByRole('button', { name: '展开其余 1 行结果' })).toBeTruthy()
+  })
+})
+
+describe('SearchBlock copy', () => {
+  it('copies the whole structured matches result, not the collapsed or capped view', async () => {
+    vi.useFakeTimers()
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    const view = render(<SearchBlock kind="matches" truncated total={9} maxLines={2} files={[
+      { path: 'a.ts', matches: [{ lineNumber: 1, line: 'x' }, { lineNumber: 2, line: 'y' }] },
+      { path: 'b.ts', matches: [{ lineNumber: 3, line: 'z' }] },
+    ]} />)
+    // Collapse a group and leave the cap in place: the clipboard still gets it all.
+    fireEvent.click(view.container.querySelector('[class^="_fileHeader_"]')!)
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    expect(writeText).toHaveBeenCalledWith('a.ts\n1: x\n2: y\n\nb.ts\n3: z')
+    await act(async () => { await Promise.resolve() })
+    expect(screen.getByRole('button', { name: '复制成功' })).toBeTruthy()
+    // A second click while the ok label shows is a no-op.
+    fireEvent.click(screen.getByRole('button', { name: '复制成功' }))
+    expect(writeText).toHaveBeenCalledTimes(1)
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
+  })
+
+  it('copies the newline-joined path list for the paths shape', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    render(<SearchBlock kind="paths" truncated={false} total={2} paths={['src/a.ts', 'src/b.ts']} />)
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    expect(writeText).toHaveBeenCalledWith('src/a.ts\nsrc/b.ts')
+    expect(await screen.findByRole('button', { name: '复制成功' })).toBeTruthy()
+  })
+
+  it('does not claim success when the host refuses the write', async () => {
+    Object.defineProperty(navigator, 'clipboard', {
+      configurable: true, value: { writeText: vi.fn().mockRejectedValue(new Error('denied')) },
+    })
+    render(<SearchBlock kind="paths" truncated={false} total={1} paths={['a']} />)
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    await act(async () => { await Promise.resolve() })
+    expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
+    expect(screen.queryByRole('button', { name: '复制成功' })).toBeNull()
+  })
+
+  it('merges className onto the wrapper and tags the wrapper with the kind', () => {
+    const view = render(<SearchBlock kind="paths" truncated={false} total={0} paths={[]} className="x" />)
+    expect(view.container.firstElementChild?.classList.contains('x')).toBe(true)
+    expect(view.container.firstElementChild?.getAttribute('data-search')).toBe('paths')
+  })
+})

packages/client/ui-settings-general/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-settings-general/README.md
-README.md: 3e191b501e69062b671df0f237f2128a4ad086d1
-README.zh.md: 44ba3eba8bfc756a7d68e43a3d34056349f7eaaa
+README.md: 4dbd339c93171b330895ab66366e76fd06013704
+README.zh.md: 8ad6de99ce78d3bdb1e7b35e872e5bfe6790e758

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

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Settings ownerless-copy and product-onboarding plugin: registers everything on the Settings surface that belongs to no single feature — the shell's trigger/header/close chrome content, the General section and its `settings.general.item` slot, the `settings` dictionaries, and the first ordered welcome step. Feature-owned rows (Permission, Language, Appearance), sections (Models), and conditional onboarding steps stay with their feature packages.
 
-`src/onboarding-copy.ts` is the single editable owner of the complete Chinese and English notice plus `WELCOME_NOTICE_VERSION`. The Host half registers `ui-onboarding` in the user-settings seam; the browser compares `welcomeNoticeVersion` for exact equality and writes the current value only after Continue succeeds. The path mutation is idempotent across tabs and preserves sibling settings, while `host/settings-changed` makes an externally acknowledged notice advance without a reload. A different version deliberately presents the notice again. The welcome page preserves every authored paragraph, gives the requested clause in the final paragraph the sole emphasis, initially focuses the title, and has no close, Escape, mask-click, or secondary path. None of its copy or acknowledgement enters a Session log or model request.
+`src/onboarding-copy.ts` is the single editable owner of the complete notice plus `WELCOME_NOTICE_VERSION`; both supported GUI locales intentionally render the same Chinese copy. The Host half registers `ui-onboarding` in the user-settings seam; the browser compares `welcomeNoticeVersion` for exact equality and writes the current value only after Continue succeeds. The path mutation is idempotent across tabs and preserves sibling settings, while `host/settings-changed` makes an externally acknowledged notice advance without a reload. A different version deliberately presents the notice again. The welcome page preserves every authored paragraph, gives the requested clause in the final paragraph the sole emphasis, initially focuses the title, and has no close, Escape, mask-click, or secondary path. None of its copy or acknowledgement enters a Session log or model request. The notice identifies `DSH_TELEMETRY_DISABLED=1` as the telemetry opt-out.
 
 ## Model Experience
 

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

@@ -4,7 +4,7 @@
 
 设置界面无特定功能归属的文案与产品引导插件：在设置界面注册所有不属于单一功能的内容，包括外壳的触发器、标题栏与关闭控件内容，「通用」分区及其 `settings.general.item` slot、`settings` 字典，以及第一个有序欢迎步骤。归具体功能所有的行（「权限」、「语言」、「外观」）、分区（「模型」）和条件式首次使用引导步骤仍由各自的功能包提供。
 
-`src/onboarding-copy.ts` 是完整中英文通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源。宿主端在 user-settings seam 中注册 `ui-onboarding`；浏览器比较 `welcomeNoticeVersion` 是否精确相等，仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等，并会保留同级设置；`host/settings-changed` 则让页面在通知被外部确认后，无需重新加载即可推进。版本不同时，系统会有意重新显示通知。欢迎页保留原文的每个段落，仅强调最后一段中指定的句段，初始焦点落在标题上，并且没有关闭操作、Escape、点击遮罩或次要操作路径。其文案和确认状态均不会进入会话日志或模型请求。
+`src/onboarding-copy.ts` 是完整通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源；GUI 支持的两种 locale 都有意渲染同一份中文文案。宿主端在 user-settings seam 中注册 `ui-onboarding`；浏览器比较 `welcomeNoticeVersion` 是否精确相等，仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等，并会保留同级设置；`host/settings-changed` 则让页面在通知被外部确认后，无需重新加载即可推进。版本不同时，系统会有意重新显示通知。欢迎页保留原文的每个段落，仅强调最后一段中指定的句段，初始焦点落在标题上，并且没有关闭操作、Escape、点击遮罩或次要操作路径。其文案和确认状态均不会进入会话日志或模型请求。通知明确以 `DSH_TELEMETRY_DISABLED=1` 作为遥测关闭方式。
 
 ## 模型体验
 

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

@@ -56,6 +56,7 @@
     "@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-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",

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

@@ -27,7 +27,6 @@
 }
 
 .opening,
-.status,
 .reflection,
 .feedback,
 .error {
@@ -38,10 +37,6 @@
   margin-top: 30px;
 }
 
-.status {
-  margin-top: 18px;
-}
-
 .reflection {
   margin-top: 36px;
   padding: 0;
@@ -52,7 +47,6 @@
 }
 
 .opening,
-.status,
 .reflection,
 .feedback {
   font-size: 16px;
@@ -90,7 +84,6 @@
 .brand,
 .title,
 .opening,
-.status,
 .reflection,
 .feedback,
 .footer {
@@ -99,10 +92,9 @@
 
 .title { animation-delay: 40ms; }
 .opening { animation-delay: 80ms; }
-.status { animation-delay: 120ms; }
-.reflection { animation-delay: 160ms; }
-.feedback { animation-delay: 200ms; }
-.footer { animation-delay: 240ms; }
+.reflection { animation-delay: 120ms; }
+.feedback { animation-delay: 160ms; }
+.footer { animation-delay: 200ms; }
 
 @keyframes welcome-enter {
   from {
@@ -120,7 +112,6 @@
   .brand,
   .title,
   .opening,
-  .status,
   .reflection,
   .feedback,
   .footer {

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

@@ -66,10 +66,9 @@ export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode {
       <div className={css.brand} aria-hidden="true"><BrandWordmark size={24} /></div>
       <h2 ref={titleRef} id="welcome-notice-title" className={css.title} tabIndex={-1}>{t('welcome.title')}</h2>
       <p className={css.opening}>{t('welcome.paragraph.0')}</p>
-      <p className={css.status}>{t('welcome.paragraph.1')}</p>
-      <blockquote className={css.reflection}>{t('welcome.paragraph.2')}</blockquote>
+      <blockquote className={css.reflection}>{t('welcome.paragraph.1')}</blockquote>
       <p className={css.feedback}>
-        {emphasizedFeedback(t('welcome.paragraph.3'), t('welcome.feedbackEmphasis'))}
+        {emphasizedFeedback(t('welcome.paragraph.2'), t('welcome.feedbackEmphasis'))}
       </p>
       {state.error === null ? null : <p className={css.error} role="alert">{t('welcome.error')}</p>}
       <div className={css.footer}>

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

@@ -11,7 +11,6 @@ export const zh = {
   'welcome.paragraph.0': WELCOME_NOTICE_COPY.zh.paragraphs[0],
   'welcome.paragraph.1': WELCOME_NOTICE_COPY.zh.paragraphs[1],
   'welcome.paragraph.2': WELCOME_NOTICE_COPY.zh.paragraphs[2],
-  'welcome.paragraph.3': WELCOME_NOTICE_COPY.zh.paragraphs[3],
   'welcome.feedbackEmphasis': WELCOME_NOTICE_COPY.zh.feedbackEmphasis,
   'welcome.continue': WELCOME_NOTICE_COPY.zh.continueLabel,
   'welcome.error': '暂时无法保存确认状态，请重试。',
@@ -30,7 +29,6 @@ export const en = {
   'welcome.paragraph.0': WELCOME_NOTICE_COPY.en.paragraphs[0],
   'welcome.paragraph.1': WELCOME_NOTICE_COPY.en.paragraphs[1],
   'welcome.paragraph.2': WELCOME_NOTICE_COPY.en.paragraphs[2],
-  'welcome.paragraph.3': WELCOME_NOTICE_COPY.en.paragraphs[3],
   'welcome.feedbackEmphasis': WELCOME_NOTICE_COPY.en.feedbackEmphasis,
   'welcome.continue': WELCOME_NOTICE_COPY.en.continueLabel,
   'welcome.error': 'The acknowledgement could not be saved. Please try again.',

packages/client/ui-settings-general/src/onboarding-copy.ts

@@ -8,30 +8,28 @@ export const WELCOME_NOTICE_ACK_FIELD = 'welcomeNoticeVersion'
  * Bump only when the notice changes materially and every user should see it
  * again. The acknowledgement is compared for exact equality.
  */
-export const WELCOME_NOTICE_VERSION = '2026-07-30.5'
+export const WELCOME_NOTICE_VERSION = '2026-07-30.7'
 
 /** The complete editable welcome notice in both supported GUI locales. */
 export const WELCOME_NOTICE_COPY = {
   zh: {
     title: '内测声明',
     paragraphs: [
-      '感谢您愿意拨冗试用 DeepSeek Harness。',
-      '目前的版本仍处于内部测试阶段，功能仍待完善，体验难免有些粗糙。',
+      '感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能仍待完善，体验难免有些粗糙。',
       '“如切如磋，如琢如磨。” 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的问题，也可能促使我们重新审视，甚至推翻已有的设计。',
-      '我们尤其希望听见那些失败、困惑与不顺手的时刻——如果您有任何反馈与建议，请在企业微信群中留言告诉我们。每一条反馈，都会帮助我们把它打磨得更好。',
+      '为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有 Session Log；如需关闭，可以设置环境变量 DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反馈与建议，请在企业微信群中留言告诉我们。每一条反馈，都会帮助我们把它打磨得更好。',
     ],
     feedbackEmphasis: '如果您有任何反馈与建议，请在企业微信群中留言告诉我们',
     continueLabel: '继续',
   },
   en: {
-    title: 'Internal Testing Notice',
+    title: '内测声明',
     paragraphs: [
-      'Thank you for taking the time to try DeepSeek Harness.',
-      'This version is still in internal testing. Its functionality still needs improvement, and the experience may feel a little rough.',
-      '“As one cuts and files, as one chisels and polishes.” A product grows through real encounters and candid feedback. Problems you discover in real use may prompt us to reconsider—or even overturn—our existing designs.',
-      'We especially want to hear about failures, confusion, and friction. If you have any feedback or suggestions, please leave us a message in the company WeChat group. Every piece of feedback helps us refine it.',
+      '感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能仍待完善，体验难免有些粗糙。',
+      '“如切如磋，如琢如磨。” 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的问题，也可能促使我们重新审视，甚至推翻已有的设计。',
+      '为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有 Session Log；如需关闭，可以设置环境变量 DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反馈与建议，请在企业微信群中留言告诉我们。每一条反馈，都会帮助我们把它打磨得更好。',
     ],
-    feedbackEmphasis: 'If you have any feedback or suggestions, please leave us a message in the company WeChat group',
-    continueLabel: 'Continue',
+    feedbackEmphasis: '如果您有任何反馈与建议，请在企业微信群中留言告诉我们',
+    continueLabel: '继续',
   },
 } as const

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

@@ -4,6 +4,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-settings-general/client'
 import { CloseLabel, HeaderContent, TriggerContent } from '../src/client/chrome.tsx'
 import { GeneralSection } from '../src/client/GeneralSection.tsx'
@@ -11,6 +12,10 @@ import { WelcomeNotice } from '../src/client/WelcomeNotice.tsx'
 import type { WelcomeNoticeInjected } from '../src/client/WelcomeNotice.tsx'
 import { WELCOME_NOTICE_SETTINGS_NAMESPACE } from '../src/onboarding-copy.ts'
 
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
 /** The five seats this plugin fills (slot name → expected component). */
 const SEATS = [
   ['settings.trigger', TriggerContent],

packages/client/ui-settings-general/tests/welcome-notice.spec.tsx

@@ -52,6 +52,10 @@ function mount(version?: string, mutateImpl: () => Promise<unknown> = () => Prom
 }
 
 describe('WelcomeNotice', () => {
+  it('uses the same Chinese owner copy in both GUI locales', () => {
+    expect(WELCOME_NOTICE_COPY.en).toEqual(WELCOME_NOTICE_COPY.zh)
+  })
+
   it('renders the owner copy with one primary action and no dismissal control', async () => {
     const h = mount()
     const page = await screen.findByRole('region', { name: WELCOME_NOTICE_COPY.zh.title })

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

@@ -10,10 +10,14 @@
  */
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, waitFor } from '@testing-library/react'
-import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-sidebar/client'
 
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
 afterEach(cleanup)
 
 /**

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

@@ -8,11 +8,16 @@
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { createScope, scopeOf, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply, inject, SlashService } from '@deepseek-ai/dsh-client-ui-slash/client'
 import type { MenuViewInjected } from '@deepseek-ai/dsh-client-ui-slash/client'
 
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
 const sid = (k: string): SessionId => k as SessionId
 
 async function bench() {

packages/client/ui-theme/package.json

@@ -44,6 +44,7 @@
   "devDependencies": {
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",

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

@@ -5,11 +5,16 @@ 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 { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject, SETTINGS_NS } from '@deepseek-ai/dsh-client-ui-theme/client'
 import type { AppearanceRowInjected, ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
 import { AppearanceRow } from '../src/client/AppearanceRow.tsx'
 import type { createAppearanceRowStore } from '../src/client/settings-store.ts'
 
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
 const SLOT = 'settings.general.item'
 
 async function bench() {

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

@@ -2,11 +2,16 @@ 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 { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-workspace/client'
 import type { WorkspaceBrowserInjected, WorkspacePickerInjected } from '@deepseek-ai/dsh-client-ui-workspace/client'
 import { WorkspaceBrowser } from '../src/client/WorkspaceBrowser.tsx'
 import { WorkspacePicker } from '../src/client/WorkspacePicker.tsx'
 
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
 async function bench() {
   const ctx = new Context()
   await ctx.plugin(SlotsService).await()

packages/client/ui-workspace/tests/rename-assembly.spec.tsx

@@ -14,10 +14,14 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, waitFor, within } from '@testing-library/react'
 import type { ISession, SessionId, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
-import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-workspace/client'
 
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
 const SID = 's1' as SessionId
 
 afterEach(cleanup)