Merge remote-tracking branch 'origin/master' into fix/web-transcript-projection

# Conflicts: # apps/web/tests/queue-actions.e2e.ts # packages/client/ui-conversation/README.i18n.yaml # packages/client/ui-conversation/src/client/chat/MessageItem.tsx
2026-07-31 17:17:00 +08:00
parent 870c55343d 85e766fa89
commit ab6d77a12d
259 changed files with 72460 additions and 2930 deletions
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -138,7 +138,34 @@ const TERMINAL_EXIT_STATUS: Record<string, { exitCode: number } | { signal: stri
 }

 /**
- * The structured `web_search` result view for fixture turn 66, authored inline
+ * 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 fixture turn 67, 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 +195,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 fixture turn 68, 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,
@@ -315,8 +342,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 +368,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 +377,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 +398,20 @@ 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
+  // Turn 66: 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(66, 'read', `{"file_path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)
+
+  // Turns 67-68: 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 +420,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(67, 'web_search', '{"query":"deepseek harness architecture"}', 'Search results for deepseek harness architecture.')
+  toolTurn(68, '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(69, '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 +459,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.
@@ -455,6 +501,16 @@ 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
+  // 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
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/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: 7752eb98a5e279e541eecb3ef4e7d1ac46729a48
+README.zh.md: ca72222e2f0b8aa69c11a4bbf82d862222f46fa4
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -50,6 +50,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.
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -50,6 +50,7 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插
 - **统计行的耗时只覆盖窗口内消息流**：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 条没有换行或展开入口，完整文本无法在行内读完。
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -20,6 +20,7 @@ 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 { 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 +321,10 @@ export function apply(ctx: Context): void {
  // (ToolRow-matching Bash · {description} chrome; scoped badge in child sessions).
  ctx.plugin(bashToolviewSample)

+  // 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).
--- a/packages/client/ui-conversation/src/client/chat/GenericToolCard.module.css
+++ b/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;
 }
--- a/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
@@ -7,9 +7,10 @@
 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 { 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 +38,7 @@ 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 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
@@ -69,6 +71,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
--- a/packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx
+++ b/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>
  )
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
+++ b/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}
--- a/packages/client/ui-conversation/src/client/contract/read-card-model.ts
+++ b/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,
+  }
+}
--- a/packages/client/ui-conversation/src/client/contract/tool-call-model.ts
+++ b/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)
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
@@ -108,8 +108,9 @@
  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 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;
 }
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -7,10 +7,11 @@
 // 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, 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 { 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,7 +130,9 @@ 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
+ * its alignment and scrolls sideways instead of folding. 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
@@ -153,6 +156,10 @@ function OutputBody({ material, cwd, t }: { material: CallMaterial; cwd: string
      </>
    )
  }
+  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)
--- a/packages/client/ui-conversation/src/client/toolviews/read-row.module.css
+++ b/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;
+}
--- a/packages/client/ui-conversation/src/client/toolviews/read-row.tsx
+++ b/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)
+  },
+}
--- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
@@ -84,14 +84,14 @@ 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 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.
    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', '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()
--- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
+++ b/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')
  })
--- a/packages/client/ui-conversation/tests/read-card.spec.tsx
+++ b/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()
+  })
+})
--- a/packages/client/ui-primitives/src/ReadBlock.module.css
+++ b/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);
+}
--- a/packages/client/ui-primitives/src/ReadBlock.tsx
+++ b/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>
+  )
+}
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -24,6 +24,8 @@ 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 { 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'
--- a/packages/client/ui-primitives/src/markdown/CodeBlock.tsx
+++ b/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)

--- a/packages/client/ui-primitives/src/markdown/highlight.ts
+++ b/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 } })))
+}
--- a/packages/client/ui-primitives/tests/code-block.spec.tsx
+++ b/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', () => {
--- a/packages/client/ui-primitives/tests/read-block.spec.tsx
+++ b/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()
+  })
+})