Merge pull request #985 from deepseek-harness/feat/web-read-card

feat(web): render read tool output as a line-numbered code card

.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
+2026-07-30-web-read-card-frontend.md: f504cab7705d03f6d3e911da05c509da50bb9abe
+2026-07-30-web-read-card-frontend.zh.md: b6314f21ba3eb2283788374b10c77ed22e26d16c

.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md

@@ -0,0 +1,54 @@
+# Agent Note: Web read card frontend — the read tool's line window renders line-numbered and highlighted
+
+Status: implemented
+
+English | [中文](2026-07-30-web-read-card-frontend.zh.md)
+
+## Problem
+
+The [read backend](2026-07-30-web-read-card.md) added a fourth render-intent card, `card: 'read'`, to `ToolResultView`: a settled read now carries `{ path, lines: [{ number, text }], totalLines, lang? }` onto the conversation snapshot as `resultView`. That data reaches the browser, but the Web client had no consumer for it. Every read row derived from args alone and the details panel flattened the result's content blocks into one `<pre>`, so a read showed as `N: text`-prefixed plain text with no gutter, no syntax highlighting, and no "showing N of M" affordance for a windowed read. The [web terminal card](2026-07-28-web-terminal-card.md) established the pattern for consuming a structured card; the read card follows it, result-side only.
+
+## Decision
+
+`ReadBlock` is a `ui-primitives` component that renders a read result as a line-numbered, optionally syntax-highlighted file view, and both Web render sites for a read consume the read render intent through it: the chat tool row (resident under the summary line) and the details panel's Output section. `ui-conversation/src/client/contract/read-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so the two sites cannot disagree.
+
+**A new `ReadBlock` primitive, not an extension of `CodeBlock`.** `CodeBlock` already does shiki highlighting with a language banner and a copy control, but a read view needs a per-line gutter carrying each line's own file number, which `CodeBlock` renders as a single `<pre>` tree with no per-line structure. Extending `CodeBlock` with an optional gutter would push a read-specific concern (windowed line numbers, a "showing N of M" note, a height cap) onto every markdown fence and every `run_code` body that shares that component. Instead `ReadBlock` reuses the part that is genuinely shared: the shiki grammar singleton in `markdown/highlight.ts`. A new `highlightLines(code, lang)` there tokenizes into shiki's own per-line token arrays (`codeToTokens`) rather than the single-`<pre>` HTML `highlightToHtml` produces, so the block can place one gutter number per line and still color the content through the same `--shiki-*` custom properties on the same grammar allowlist. The height cap and its head/tail expand arithmetic are copied from `TerminalBlock` (`ceil(max/2)` head plus the remaining tail), so a long read and a long command output collapse at the same place. The copy control writes the window's raw text (the lines joined by newlines), never the gutter numbers or the banner.
+
+`readCardModel` is result-side only, mirroring the backend: a read call carries no content until `execute` returns, so the pending call stays a `GenericCallView` (`kind: 'read'`) and this returns null for a running read — the row keeps its args-derived summary until the result arrives. It also returns null for 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 a compiled variant) and the read tool's own generic fallback for an error result. The card's banner label is the read view's `title` when the tool supplied one (the contract's replacement-title rule), otherwise the file path relativized to the session workspace so a workspace-rooted absolute path shows the same short form the row summary shows. The model copies the frozen line array into the primitive's own line shape, so the card never holds a reference into the runtime's snapshot cache.
+
+The chat row renders the card **resident** under the summary line, capped at `CHAT_READ_MAX_LINES` (8, half the primitive's default), the same posture `BashRow` gives a terminal card — the block's internal expander keeps a long read from taking over the message flow. Two render sites carry it: the keyed `ReadRow` (registered under `read` in `apply.ts`, the load-order seam being `inject: ['slots', 'conversation']` exactly as the bash sample) whose summary is the file path as an openable host link, and `GenericToolCard`'s fallback for a read-declaring tool without its own keyed row (e.g. `web_fetch`, which classifies to the `read` variant). The details panel renders the same card at the primitive's own full-height cap (16), because the panel is the single-call reading surface.
+
+Whole-row collapse/expand (defaulting every tool call to collapsed) is a separate later change that will flip every resident card at once; this note's card is resident, matching the terminal card it sits beside.
+
+**Read-card grammars load lazily; only the boot three stay eager.** `highlight.ts` is a platform seed `ui-primitives` loads on every Web boot, and its warm-up unconditionally builds the shiki singleton. The read card's `langFromPath` hints span the full source/config/markup extension set (python, rust, yaml, html, …); registering all of them eagerly would add ~1.6 MB of grammar modules to the boot chunk and their synchronous init to every session, including sessions that never open a read card. So only the three grammars every session already renders — TypeScript, shell, JSON (the markdown-fence and `run_code` languages) — load at boot. Each read-card extension grammar sits behind a dynamic `import()` in `LAZY_GRAMMARS`, keyed by the grammar id its aliases resolve to. On the first `highlightLines`/`highlightToHtml` call for a lazy language, `ensureGrammar` starts the import (once) and returns not-ready, so the card renders plain that frame; when the import resolves it registers the grammar with `loadLanguageSync`, bumps a load counter, and notifies subscribers. `ReadBlock` and `CodeBlock` subscribe through `useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount)`, so the card re-renders with highlighting the moment the grammar is ready. An unknown/absent language still returns undefined synchronously (plain, never an error).
+
+**The empty-window copy control is hidden, matching `TerminalBlock`.** A successful read of an empty file returns `lines: []`, `totalLines: 0`, and `presentResult` still projects `card: 'read'`, so the empty-window branch is reachable — the read card is not, as an earlier draft assumed, unreachable for an empty result. `ReadBlock` therefore hides the copy control when `lines` is empty, exactly as `TerminalBlock` hides copy on empty output, so the button can never wipe the clipboard with an empty string.
+
+## Alternatives considered
+
+**Extend `CodeBlock` with an optional line-number gutter and `startLine`.** Rejected: it imposes a read-specific gutter, a windowed-count note, and a height cap on every markdown fence and `run_code` body that shares `CodeBlock`, for no benefit to those callers. The genuinely shared surface is the shiki grammar singleton, which both blocks reuse through `highlight.ts`; the chrome around it differs (a read has a gutter and a window note, a fence has neither), so a second small primitive is the correct split, exactly as `TerminalBlock` is a second primitive over the same tokens rather than a `CodeBlock` mode.
+
+**Reuse `highlightToHtml` and inject gutter numbers with CSS counters.** Rejected: the single-`<pre>` HTML shiki emits has no per-line boundary a gutter can hang a file line number off (a windowed read's numbers start above 1 and are not a simple CSS counter increment), and parsing the numbers back out of the HTML would be fragile. `codeToTokens` gives the per-line token structure directly.
+
+**Register all read-card grammars eagerly in the boot warm-up.** Rejected: it puts ~1.6 MB of grammar modules and their synchronous init on every Web boot for a card most sessions never open. The lazy path costs a single plain-first frame the first time a given language is read, then highlights on the grammar-load re-render; the boot cost is paid only for the three grammars every session already renders.
+
+## Consequences
+
+`ui-primitives` gains `ReadBlock` and `highlightLines`; no new runtime dependency (shiki was already present for `CodeBlock`). `ReadBlock` reads only the read view's fields, so it stays a pure function of what the render intent carries — no session lookups, replay-safe like the presenters that produce the view. A UI without the read capability still gets the backend's `content` fallback (the envelope-stripped text) through the generic card, unchanged.
+
+A read row in the Web chat now carries the file content resident, a deliberate density increase over a summary-only row, bounded by the chat cap. A `run_code` sub-dispatch does not reach a read card on the shipped wire for the same reason a nested bash call does not reach a terminal card: `session.ts` folds `tool/code-dispatch(-start)` with `resultView: null`, so a nested read keeps the generic flattened form.
+
+## Testing
+
+`packages/client/ui-primitives/tests/read-block.spec.tsx` pins the primitive and the token path: `highlightLines`' per-line css-variables runs, its trailing-terminator-line drop and the genuinely-blank-final-line case, its `undefined` for an unknown/absent language, and its lazy path (a lazy grammar returns plain on first touch, then highlights after the import registers and the subscriber fires); and `ReadBlock`'s gutter-numbered rows keeping the file's own numbers, the highlighted-vs-plain content arms, the banner (label, language, the count note only when the read is a window), the head/tail height cap with its `aria-expanded` toggle, the copy control writing the window's raw text on both the accepted and refused clipboard paths, and the empty-window arm hiding the copy control. `code-block.spec.tsx` covers `highlightToHtml` including its lazy path over every read-card grammar (each dynamic import thunk touched once). Both `ReadBlock.tsx` and `highlight.ts` (and `CodeBlock.tsx`) hold per-file 100% coverage across the two specs.
+
+`packages/client/ui-conversation/tests/read-card.spec.tsx` pins the wiring at every render site: `readCardModel`'s derivation and each null arm (running read, no view, generic view, unknown card), the result title replacing the relativized path, the path relativization against the workspace, the copy-not-alias of the frozen line array; the resident card in `GenericToolCard`'s fallback and in the keyed `ReadRow` (plus its path link opening the host, its running/error/stopped states, and its `read`-key registration); and the panel's Output section rendering the read card at full height while keeping the JSON Input section, with the running-read placeholder and non-read flattened-pre arms. That file sits on the coverage `exclude` list (`ui-conversation/src/*`), so it is written against no gate pressure.
+
+The fixture (`packages/client/connection/src/client/fixture.ts`) gains turn 66, a `read` call whose result view is a windowed read (lines starting at file line 41, `totalLines` 180, a `ts` hint), so the built-boot snapshot and a live `?fixture` server show the read card with its gutter numbers, highlighting, and count note. It is named `read` to exercise the keyed `ReadRow`. The turn 64 `run_code` sample's nested read sub-dispatches do not exercise the render-site fallback read card: `session.ts` folds them with `resultView: null`, so they cover only the fallback row's generic row shape, not a read card inside it; the fallback-row read card is pinned by `read-card.spec.tsx`'s `web_fetch` case. Turn 66 is ordered before the todo turn (now 67) for the same reason the terminal sample is: the standing plan retires at the next `turn/start`.
+
+## Related
+
+- [Read card backend](2026-07-30-web-read-card.md) — adds the `card: 'read'` result view this consumes; produces the `lines`/`totalLines`/`lang` this renders.
+- [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent this follows: a `ui-primitives` block, a `contract/*-card-model.ts` derivation, a keyed row, and making `GenericToolCard`/`DetailsPanel` card-aware.
+- [Web client syntax highlighting](../process/2026-07-26-web-syntax-highlighting-shiki.md) — owns `CodeBlock` and the shiki `highlight.ts` singleton this extends with a per-line token path.
+- [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) — the `card`-tagged vocabulary; the Web client is now a full consumer of the `read` arm.

.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md

@@ -0,0 +1,54 @@
+# Agent Note: Web 读取卡片前端 —— 读取工具的行窗口以带行号、语法高亮的形式渲染
+
+Status: implemented
+
+[English](2026-07-30-web-read-card-frontend.md) | 中文
+
+## Problem
+
+[读取后端](2026-07-30-web-read-card.md)给 `ToolResultView` 增加了第四种渲染意图卡片 `card: 'read'`：一次已结算的读取现在会把 `{ path, lines: [{ number, text }], totalLines, lang? }` 作为 `resultView` 带到会话快照上。这份数据能到达浏览器，但 Web 客户端没有消费者。每个读取行都仅从参数派生，详情面板把结果的 content block 摊平进一个 `<pre>`，于是读取显示为带 `N: text` 前缀的纯文本，没有行号栏、没有语法高亮，也没有窗口读取的"显示 N / M"提示。[web 终端卡片](2026-07-28-web-terminal-card.md)确立了消费一个结构化卡片的模式；读取卡片沿用它，只在结果侧。
+
+## Decision
+
+`ReadBlock` 是一个 `ui-primitives` 组件，把一次读取结果渲染成带行号、可选语法高亮的文件视图，读取的两个 Web 渲染点都通过它消费读取渲染意图：聊天工具行（常驻在摘要行之下）与详情面板的 Output 区段。`ui-conversation/src/client/contract/read-card-model.ts` 是把快照的 `resultView` 转成组件 props 的唯一位置，因此两个渲染点不会产生分歧。
+
+**新建一个 `ReadBlock` primitive，而不是扩展 `CodeBlock`。** `CodeBlock` 已经带语言横幅和复制控件做 shiki 高亮，但读取视图需要一个每行带该行自身文件行号的行号栏，而 `CodeBlock` 把内容渲染为单个 `<pre>` 树、没有逐行结构。给 `CodeBlock` 加一个可选行号栏会把读取专属的关切（窗口行号、"显示 N / M"提示、高度上限）强加给共享该组件的每个 markdown 代码围栏和每个 `run_code` 程序体。`ReadBlock` 转而复用真正共享的部分：`markdown/highlight.ts` 里的 shiki 语法单例。那里新增的 `highlightLines(code, lang)` 把代码切成 shiki 自己的逐行 token 数组（`codeToTokens`），而不是 `highlightToHtml` 产出的单 `<pre>` HTML，于是该 block 能每行放一个行号、同时用同一套 `--shiki-*` 自定义属性、同一份语法白名单给内容上色。高度上限及其头/尾展开算法照抄自 `TerminalBlock`（`ceil(max/2)` 行头部加剩余的尾部），因此长读取和长命令输出在同一处折叠。复制控件写入窗口的原始文本（各行以换行拼接），绝不含行号栏或横幅。
+
+`readCardModel` 只在结果侧，与后端对称：一次读取调用在 `execute` 返回前不带任何内容，因此挂起中的调用保持为 `GenericCallView`（`kind: 'read'`），本函数对运行中的读取返回 null —— 该行保持其从参数派生的摘要，直到结果到达。它对结果视图不是读取卡片的已结算调用也返回 null，包括本 UI 版本不认识的 `card` 值（它从线路到来、不能被信任为一个已编译的变体）以及读取工具对错误结果自己的通用回退。卡片横幅标签在工具提供 `title` 时取它（契约的替换标题规则），否则取相对于会话工作区化简后的文件路径，使工作区根下的绝对路径显示为与行摘要相同的短形式。该 model 把冻结的行数组复制进 primitive 自己的行形状，因此卡片绝不持有指向运行时快照缓存的引用。
+
+聊天行把卡片**常驻**渲染在摘要行之下，上限 `CHAT_READ_MAX_LINES`（8，是 primitive 默认值的一半），与 `BashRow` 对终端卡片的姿态相同 —— block 的内部展开器让长读取不会占据整个消息流。两个渲染点承载它：keyed `ReadRow`（在 `apply.ts` 里以 `read` 键注册，加载顺序接缝为 `inject: ['slots', 'conversation']`，与 bash 样例完全一致），其摘要是作为可打开的宿主链接的文件路径；以及 `GenericToolCard` 对没有自己 keyed 行的读取声明工具（例如归到 `read` 变体的 `web_fetch`）的回退。详情面板以 primitive 自己的全高上限（16）渲染同一张卡片，因为面板是单次调用的阅读界面。
+
+整行折叠/展开（把每个工具调用默认折叠）是一个单独的后续改动，它会一次性翻转每张常驻卡片；本 note 的卡片是常驻的，与它旁边的终端卡片一致。
+
+**读取卡片的语法按需 lazy 加载，只有 boot 三种保持 eager。** `highlight.ts` 是 `ui-primitives` 在每次 Web 启动都加载的平台 seed，其预热会无条件构建 shiki 单例。读取卡片的 `langFromPath` 提示覆盖完整的源码/配置/标记扩展集（python、rust、yaml、html……）；把它们全部 eager 注册会给启动 chunk 增加约 1.6 MB 的语法模块、并把它们的同步初始化摊给每个会话，包括从不打开读取卡片的会话。因此只有每个会话本就渲染的三种语法 —— TypeScript、shell、JSON（markdown 围栏与 `run_code` 语言）—— 在 boot 时加载。每种读取卡片扩展语法置于 `LAZY_GRAMMARS` 中一个动态 `import()` 之后，以其别名解析到的语法 id 为键。对某个 lazy 语言首次调用 `highlightLines`/`highlightToHtml` 时，`ensureGrammar` 启动 import（仅一次）并返回未就绪，于是卡片该帧渲染纯文本；import 解析后用 `loadLanguageSync` 注册该语法、递增一个加载计数、并通知订阅者。`ReadBlock` 与 `CodeBlock` 通过 `useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount)` 订阅，因此语法就绪的那一刻卡片就重渲染带上高亮。未知/缺省语言仍同步返回 undefined（纯文本，绝不报错）。
+
+**空窗口的复制控件被隐藏，与 `TerminalBlock` 对齐。** 成功读取一个空文件会返回 `lines: []`、`totalLines: 0`，且 `presentResult` 仍投出 `card: 'read'`，因此空窗口分支是可达的 —— 读取卡片并非如早前草稿所假设的对空结果不可达。故 `ReadBlock` 在 `lines` 为空时隐藏复制控件，正如 `TerminalBlock` 对空输出隐藏复制，使按钮绝不会用空字符串清空剪贴板。
+
+## Alternatives considered
+
+**给 `CodeBlock` 加一个可选行号栏和 `startLine`。** 拒绝：这会把读取专属的行号栏、窗口计数提示和高度上限强加给共享 `CodeBlock` 的每个 markdown 围栏和 `run_code` 程序体，对那些调用者毫无好处。真正共享的界面是 shiki 语法单例，两个 block 都通过 `highlight.ts` 复用它；围绕它的外壳各不相同（读取有行号栏和窗口提示，围栏两者都没有），因此第二个小 primitive 是正确的切分 —— 正如 `TerminalBlock` 是基于同一套 token 的第二个 primitive，而不是 `CodeBlock` 的一种模式。
+
+**复用 `highlightToHtml`，用 CSS counter 注入行号。** 拒绝：shiki 产出的单 `<pre>` HTML 没有可供行号栏挂上文件行号的逐行边界（窗口读取的行号从大于 1 处开始，不是简单的 CSS counter 自增），而从 HTML 里把行号解析回来又很脆弱。`codeToTokens` 直接给出逐行 token 结构。
+
+**在 boot 预热里 eager 注册所有读取卡片语法。** 拒绝：这会给每次 Web 启动摊上约 1.6 MB 语法模块及其同步初始化，只为一张多数会话从不打开的卡片。lazy 路径的代价是某个语言首次被读取时的一帧纯文本，随后在语法加载的重渲染里高亮；boot 代价只为每个会话本就渲染的三种语法付出。
+
+## Consequences
+
+`ui-primitives` 增加 `ReadBlock` 和 `highlightLines`；没有新的运行时依赖（shiki 已因 `CodeBlock` 存在）。`ReadBlock` 只读取读取视图的字段，因此保持为渲染意图所承载内容的纯函数 —— 无会话查询，与产出该视图的 presenter 一样可安全回放。没有读取能力的 UI 仍通过通用卡片拿到后端的 `content` 回退（剥掉外壳的文本），保持不变。
+
+Web 聊天里的读取行现在常驻承载文件内容，是相对纯摘要行的一次刻意的密度增加，受聊天上限约束。`run_code` 子派发在已发布的线路上到不了读取卡片，与嵌套 bash 调用到不了终端卡片同因：`session.ts` 把 `tool/code-dispatch(-start)` 折叠为 `resultView: null`，因此嵌套读取保持通用的摊平形式。
+
+## Testing
+
+`packages/client/ui-primitives/tests/read-block.spec.tsx` 固定 primitive 与 token 路径：`highlightLines` 的逐行 css-variables 运行、它对尾部终止行的丢弃与真正空白末行的情形、它对未知/缺省语言返回 `undefined`、以及它的 lazy 路径（lazy 语法首次触碰返回纯文本，import 注册且订阅者触发后再高亮）；还有 `ReadBlock` 的带行号行保留文件自身编号、高亮与纯文本两条内容分支、横幅（标签、语言、仅当读取是窗口时的计数提示）、头/尾高度上限及其 `aria-expanded` 切换、复制控件在接受与拒绝两条剪贴板路径上写入窗口原始文本、以及空窗口分支隐藏复制控件。`code-block.spec.tsx` 覆盖 `highlightToHtml`，含它对每种读取卡片语法的 lazy 路径（每个动态 import thunk 各触碰一次）。`ReadBlock.tsx`、`highlight.ts`（及 `CodeBlock.tsx`）在这两个 spec 上均保持每文件 100% 覆盖。
+
+`packages/client/ui-conversation/tests/read-card.spec.tsx` 固定每个渲染点的接线：`readCardModel` 的派生与每条 null 分支（运行中读取、无视图、通用视图、未知卡片）、结果标题替换化简后的路径、路径相对工作区的化简、冻结行数组的复制而非别名；`GenericToolCard` 回退中与 keyed `ReadRow` 中的常驻卡片（外加其路径链接打开宿主、其 running/error/stopped 状态、以及其 `read` 键注册）；还有面板 Output 区段以全高渲染读取卡片同时保留 JSON Input 区段，含运行中读取占位与非读取摊平 pre 两条分支。该文件位于覆盖 `exclude` 列表（`ui-conversation/src/*`），因此不承受门槛压力。
+
+fixture（`packages/client/connection/src/client/fixture.ts`）增加 turn 66，一次 `read` 调用，其结果视图是窗口读取（行号从文件行 41 起、`totalLines` 180、`ts` 提示），使内置启动快照和实时 `?fixture` 服务器展示带行号、高亮和计数提示的读取卡片。它命名为 `read` 以驱动 keyed `ReadRow`。turn 64 的 `run_code` 样例中的嵌套读取子派发并不驱动渲染点回退读取卡片：`session.ts` 把它们折叠为 `resultView: null`，因此它们只覆盖回退行的通用行形状，而非回退行内的读取卡片；回退行读取卡片由 `read-card.spec.tsx` 的 `web_fetch` 用例钉住。turn 66 排在 todo turn（现为 67）之前，与终端样例同因：常驻计划在下一次 `turn/start` 退场。
+
+## Related
+
+- [读取卡片后端](2026-07-30-web-read-card.md) —— 增加本文消费的 `card: 'read'` 结果视图；产出本文渲染的 `lines`/`totalLines`/`lang`。
+- [Web 终端卡片](2026-07-28-web-terminal-card.md) —— 本文遵循的先例：一个 `ui-primitives` block、一个 `contract/*-card-model.ts` 派生、一个 keyed 行，以及让 `GenericToolCard`/`DetailsPanel` 感知卡片。
+- [Web 客户端语法高亮](../process/2026-07-26-web-syntax-highlighting-shiki.md) —— 拥有 `CodeBlock` 与 shiki `highlight.ts` 单例，本文以逐行 token 路径扩展它。
+- [工具调用呈现的标签式渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— `card` 标签词汇表；Web 客户端现在是 `read` 分支的完整消费者。

apps/web/tests/snapshots/code-mode-round/ui.expected.md

@@ -20,10 +20,8 @@
   - img
   - text: Code Run bash echo and catch missing file read
 - img
-- text: Bash Echo CODE_ROUND_OK
-- 'button "Read Error: cannot read \"{{cwd}}/workspace/missing.txt\": not found"':
-  - img
-  - text: "Read Error: cannot read \"{{cwd}}/workspace/missing.txt\": not found"
+- text: Bash Echo CODE_ROUND_OK 失败 Read
+- button "missing.txt"
 - button "Think The program ran successfully. Let me now reply DONE as instructed.":
   - img
   - img

apps/web/tests/snapshots/message-actions/ui.expected.md

@@ -16,16 +16,12 @@
   - img
   - img
   - text: Think The user wants me to read a.txt and b.txt, then reply with "DONE". Let me do both reads in parallel.
-- button "Read a.txt":
-  - img
-  - img
-  - text: Read
-  - button "a.txt"
-- button "Read b.txt":
-  - img
-  - img
-  - text: Read
-  - button "b.txt"
+- img
+- text: Read
+- button "a.txt"
+- img
+- text: Read
+- button "b.txt"
 - button "Think Both files have been read. a.txt contains \"alpha\" and b.txt contains \"beta\". I'll now reply with DONE as instructed.":
   - img
   - img

apps/web/tests/snapshots/seeded-history/command-row.expected.md

@@ -15,16 +15,12 @@
   - img
   - img
   - text: Think The user wants me to read a.txt and b.txt, then reply with "DONE". Let me do both reads in parallel.
-- button "Read a.txt":
-  - img
-  - img
-  - text: Read
-  - button "a.txt"
-- button "Read b.txt":
-  - img
-  - img
-  - text: Read
-  - button "b.txt"
+- img
+- text: Read
+- button "a.txt"
+- img
+- text: Read
+- button "b.txt"
 - button "Think Both files have been read. a.txt contains \"alpha\" and b.txt contains \"beta\". I'll now reply with DONE as instructed.":
   - img
   - img

apps/web/tests/snapshots/seeded-history/ui.expected.md

@@ -15,16 +15,12 @@
   - img
   - img
   - text: Think The user wants me to read a.txt and b.txt, then reply with "DONE". Let me do both reads in parallel.
-- button "Read a.txt":
-  - img
-  - img
-  - text: Read
-  - button "a.txt"
-- button "Read b.txt":
-  - img
-  - img
-  - text: Read
-  - button "b.txt"
+- img
+- text: Read
+- button "a.txt"
+- img
+- text: Read
+- button "b.txt"
 - button "Think Both files have been read. a.txt contains \"alpha\" and b.txt contains \"beta\". I'll now reply with DONE as instructed.":
   - img
   - img

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

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).

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

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

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

@@ -7,9 +7,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

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

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

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

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

packages/client/ui-conversation/src/client/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;
 }

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)

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

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

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

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

packages/client/ui-conversation/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()

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: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
+      pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
+      openState: 'open', openError: null, hasMore: false, loadingOlder: false,
+      promptError: null, blank: false, lastAgentError: null, ...over,
+    }
+  }
+
+  const target: SelectionTarget = { turnSeq: 10, callId: 'c1', toolName: 'read' }
+
+  it('renders the read card at full height, keeping the JSON Input section', () => {
+    const long = Array.from({ length: 20 }, (_, i) => ({ number: i + 1, text: `row-${i}` }))
+    const view = mount(snapshot({
+      nodes: [settled({ resultView: resultRead({ lines: long, totalLines: 20 }) })],
+    }), target)
+    expect(view.getByText(/"file_path"/)).toBeTruthy()
+    expect(view.container.querySelector('[data-read]')).not.toBeNull()
+    // The panel takes the primitive's own default cap (16), not the row's.
+    expect(view.getByText(`… 其余 ${20 - 16} 行`)).toBeTruthy()
+    expect(contentTexts(view.container)).toContain('row-0')
+  })
+
+  it('a non-read result keeps the flattened pre form', () => {
+    const view = mount(snapshot({
+      nodes: [settled({
+        callView: null, resultView: null,
+        content: [{ type: 'text', text: 'plain result' }],
+      })],
+    }), target)
+    expect(view.container.querySelector('[data-read]')).toBeNull()
+    expect(view.getByText('输出').closest('section')?.querySelector('pre')?.textContent).toBe('plain result')
+  })
+
+  it('a running read keeps the 运行中… placeholder (no result view)', () => {
+    const view = mount(snapshot({ runningCalls: [running()] }), target)
+    expect(view.getByText('运行中…')).toBeTruthy()
+    expect(view.container.querySelector('[data-read]')).toBeNull()
+  })
+})

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

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

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

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

packages/client/ui-primitives/src/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'

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

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

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

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

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

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

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

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