cctrans 0.3.0 → 0.4.0

package/README.hi.md

@@ -28,6 +28,7 @@ Claude Code के लिए एक **द्विभाषी ओवरले**
 ## ✨ विशेषताएँ
 
 - 🪞 **इनलाइन द्विभाषी प्रदर्शन** — अनुवाद जवाब की स्ट्रीमिंग के साथ हर अंग्रेज़ी पंक्ति के नीचे दिखता है
+- 🧩 **दो लेआउट** — पंक्ति-दर-पंक्ति अंतर्संयोजन, या `cctrans mode section`: पहले पूरा अंग्रेज़ी ब्लॉक, फिर उसका समूहीकृत अनुवाद
 - 🧾 **गैर-विनाशकारी** — ट्रांसक्रिप्ट और मॉडल कॉन्टेक्स्ट शुद्ध अंग्रेज़ी में रहते हैं; skills, दस्तावेज़, कोड अप्रभावित
 - 🆓 **मुख्य लूप के शून्य टोकन** — अनुवाद एक अलग सस्ते (मुफ़्त विकल्प सहित) बैकएंड से होता है, Claude Code सत्र से पूरी तरह बाहर
 - ⌨️ **इनपुट अनुवाद (beta)** — अपनी भाषा में लिखें, मॉडल अंग्रेज़ी में काम करता है — और अंग्रेज़ी में जवाब देता है (`cctrans input on`)
@@ -99,9 +100,10 @@ Claude अंग्रेज़ी स्ट्रीम करता है
 | `cctrans on` / `cctrans off` / `cctrans toggle` | अनुवाद चालू / बंद / टॉगल |
 | `cctrans status` | स्थिति देखें (टॉगल, हुक, बैकएंड, भाषा) |
 | `cctrans lang [code]` | लक्ष्य भाषा देखें/सेट करें: `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans mode [line\|section]` | लेआउट: हर पंक्ति के नीचे अनुवाद, या ब्लॉक-वार समूहीकृत |
 | `cctrans backend <id>` | अनुवाद इंजन बदलें |
 | `cctrans backends` | सभी इंजन और उनकी उपलब्धता सूचीबद्ध करें |
-| `cctrans setup` | इंटरैक्टिव विज़ार्ड: भाषा, बैकएंड, API कुंजियाँ |
+| `cctrans setup` | इंटरैक्टिव विज़ार्ड: भाषा, प्रदर्शन मोड, बैकएंड, API कुंजियाँ |
 | `cctrans key [id] [value]` | `~/.cc-translate/keys.json` में API कुंजियाँ प्रबंधित करें |
 | `cctrans input on` / `cctrans input off` | **(beta)** गैर-अंग्रेज़ी इनपुट का अंग्रेज़ी अनुवाद (संदर्भ के रूप में भेजा जाता है) |
 | `cctrans input threshold <n>` | इनपुट अनुवाद ट्रिगर करने वाले गैर-लैटिन वर्णों की संख्या (डिफ़ॉल्ट 4) |
@@ -109,6 +111,28 @@ Claude अंग्रेज़ी स्ट्रीम करता है
 | `cctrans test <टेक्स्ट>` | इंजन जाँचने के लिए कोई टेक्स्ट अनुवाद करें |
 | `cctrans install` / `cctrans uninstall` | हुक पंजीकृत / हटाएँ |
 
+## 🧩 प्रदर्शन मोड
+
+`line` (डिफ़ॉल्ट) अंतर्संयोजन करता है: हर अंग्रेज़ी पंक्ति के नीचे अनुवाद की पंक्ति, जवाब की स्ट्रीमिंग के साथ। `section` अंग्रेज़ी को ठीक वैसे ही रखता है जैसे Claude स्ट्रीम करता है और **ब्लॉक पूरा होने पर एक समूहीकृत अनुवाद** जोड़ देता है — सूची-भारी जवाबों के लिए कहीं ज़्यादा शांत:
+
+```
+Use these flags:
+↳ ये फ़्लैग इस्तेमाल करें:
+
+- Enable the cache
+- Set a small timeout
+- Prefer the batch API
+  ↳ कैश सक्षम करें
+  ↳ छोटा टाइमआउट सेट करें
+  ↳ batch API को प्राथमिकता दें
+```
+
+```bash
+cctrans mode section   # कभी भी वापस जाएँ: cctrans mode line
+```
+
+> section मोड में किसी ब्लॉक का अनुवाद **ब्लॉक पूरा होने पर** दिखता है, स्ट्रीमिंग के दौरान नहीं — धीमे बैकएंड (जैसे `claude-code`, 3–6s/कॉल) के साथ यह ठहराव महसूस होता है, इसलिए यहाँ API बैकएंड सबसे अच्छे रहते हैं। अगर किसी ब्लॉक का अनुवाद विफल हो जाए, तो अंग्रेज़ी अप्रभावित रहती है और वह ब्लॉक बस बिना अनुवाद के रह जाता है।
+
 ## 🌐 अनुवाद बैकएंड
 
 | बैकएंड | आवश्यक | गति | गुणवत्ता | टिप्पणी |
@@ -151,7 +175,8 @@ cctrans lang zh-Hans  # सरलीकृत चीनी (डिफ़ॉल
 
 - हुक **स्ट्रीमिंग के दौरान** हर खंड पर सक्रिय होता है; हर खंड का अनुवाद होकर उसी जगह बदला जाता है — अनुवाद अंग्रेज़ी के साथ-साथ क्रमिक रूप से दिखता है।
 - हुक का टाइमआउट **10 सेकंड** है; यह टूल आंतरिक रूप से 9s पर गार्ड करता है। कोई भी त्रुटि / टाइमआउट / अधिक लंबाई (>9,000 वर्ण) **सुरक्षित रूप से मूल अंग्रेज़ी पर fallback** करती है — सत्र कभी नहीं अटकता।
-- हर अनुवादित पंक्ति सामग्री हैश से **कैश** होती है (`~/.cc-translate/cache`); री-पेंट और दोहराए टेक्स्ट की लागत शून्य।
+- हर अनुवादित पंक्ति सामग्री हैश से **कैश** होती है (`~/.cc-translate/cache`); री-पेंट और दोहराए टेक्स्ट की लागत शून्य। दोनों मोड एक ही कैश साझा करते हैं।
+- section मोड में चल रहे (अभी अधूरे) ब्लॉक का टेक्स्ट `~/.cc-translate/msgstate` में बफ़र होता है (डिस्क पर वही एक्सपोज़र जो कैश का है); संदेश पूरा होने पर फ़ाइल हटा दी जाती है और पुरानी फ़ाइलें 24 घंटे बाद साफ़ कर दी जाती हैं।
 - `openai` के साथ हर खंड लगभग एक API कॉल (~$0.0001) और शुद्ध अंग्रेज़ी की तुलना में ~1s/खंड की देरी; `google` तेज़ है पर गुणवत्ता थोड़ी कम।
 
 ## 🔗 जुड़े रहें

package/README.ja.md

@@ -28,6 +28,7 @@ Claude Code の**バイリンガル表示オーバーレイ**:各英語行の下
 ## ✨ 特長
 
 - 🪞 **インラインのバイリンガル表示** —— 訳文は返信のストリーミングと共に各英語行の下に現れます
+- 🧩 **2 つのレイアウト** —— 行ごとのインターリーブ、または `cctrans mode section`:英語ブロック全体を先に表示し、その後にまとめた訳文を表示
 - 🧾 **非破壊** —— トランスクリプトとモデルコンテキストは純粋な英語のまま;skills、ドキュメント、コードに影響なし
 - 🆓 **メインループのトークン消費ゼロ** —— 翻訳は独立した安価な(無料もある)バックエンドで実行、Claude Code セッションの完全に外側
 - ⌨️ **入力翻訳(beta)** —— 母語で入力し、モデルは英語で動き、英語で返信する(`cctrans input on`)
@@ -99,9 +100,10 @@ Claude が英語をストリーミング出力
 | `cctrans on` / `cctrans off` / `cctrans toggle` | 翻訳のオン / オフ / 切替 |
 | `cctrans status` | 状態表示(トグル、フック、バックエンド、言語) |
 | `cctrans lang [code]` | 目標言語の表示/設定:`zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans mode [line\|section]` | レイアウト:各行の下に訳文、またはブロックごとにまとめて |
 | `cctrans backend <id>` | 翻訳エンジンの切替 |
 | `cctrans backends` | 全エンジンと利用可否を一覧 |
-| `cctrans setup` | 対話式ウィザード:言語、バックエンド、API キー |
+| `cctrans setup` | 対話式ウィザード:言語、表示モード、バックエンド、API キー |
 | `cctrans key [id] [value]` | `~/.cc-translate/keys.json` の API キーを管理 |
 | `cctrans input on` / `cctrans input off` | **(beta)** 非英語の入力を英語に翻訳(コンテキストとして送信) |
 | `cctrans input threshold <n>` | 入力翻訳を発火させる非ラテン文字数(デフォルト 4) |
@@ -109,6 +111,28 @@ Claude が英語をストリーミング出力
 | `cctrans test <テキスト>` | テキストを翻訳してエンジンを検証 |
 | `cctrans install` / `cctrans uninstall` | フックの登録 / 削除 |
 
+## 🧩 表示モード
+
+`line`(デフォルト)はインターリーブ:各英語行の下に訳文行が一行ずつ、返信のストリーミングと共に表示されます。`section` は Claude のストリーミングどおりに英語をそのまま保ち、**ブロック完成時にまとめた訳文を 1 回**差し込みます——リストの多い返信ではずっと静かになります:
+
+```
+Use these flags:
+↳ 以下のフラグを使用してください:
+
+- Enable the cache
+- Set a small timeout
+- Prefer the batch API
+  ↳ キャッシュを有効にする
+  ↳ 短めのタイムアウトを設定する
+  ↳ バッチ API を優先する
+```
+
+```bash
+cctrans mode section   # いつでも戻せる:cctrans mode line
+```
+
+> section モードではブロックの訳文は**ブロック完成時**に表示され、ストリーミング中には現れません——遅いバックエンド(例:`claude-code`、3–6 秒/呼び出し)ではその間が目立つため、ここでは API バックエンドが最適です。ブロックの翻訳が失敗しても英語は影響を受けず、そのブロックが未翻訳のまま残るだけです。
+
 ## 🌐 翻訳バックエンド
 
 | バックエンド | 前提 | 速度 | 品質 | 備考 |
@@ -151,7 +175,8 @@ cctrans lang zh-Hans  # 簡体字中国語(デフォルト)
 
 - フックは**ストリーミング中**に断片ごとに発火し、断片ごとに翻訳してその場で置換——訳文は英語と並んで段階的に現れます。
 - フックのタイムアウトは **10 秒**;本ツールは内部で 9 秒のガードを持ちます。エラー/タイムアウト/超過(>9,000 文字)はすべて**元の英語に安全にフォールバック**——セッションを止めることはありません。
-- 訳文は内容ハッシュで**キャッシュ**(`~/.cc-translate/cache`);再描画や繰り返しテキストはコストゼロ。
+- 訳文は内容ハッシュで**キャッシュ**(`~/.cc-translate/cache`);再描画や繰り返しテキストはコストゼロ。キャッシュは両モードで共有されます。
+- section モードでは処理中のブロックのテキストが `~/.cc-translate/msgstate` にバッファされます(保存時の露出はキャッシュと同等);ファイルはメッセージ完了時に削除され、古いものは 24 時間後に掃除されます。
 - `openai` 使用時は断片ごとに約 1 回の API 呼び出し(~$0.0001)、純英語より約 1 秒/断片の遅延;`google` はより速いが品質はやや低め。
 
 ## 🔗 プロジェクトをフォロー

package/README.ko.md

@@ -28,6 +28,7 @@ Claude Code의 **이중 언어 오버레이**: 각 영어 줄 아래에 번역(
 ## ✨ 특징
 
 - 🪞 **인라인 이중 언어 표시** — 번역이 응답 스트리밍과 함께 각 영어 줄 아래에 나타납니다
+- 🧩 **두 가지 레이아웃** — 줄 단위 인터리브, 또는 `cctrans mode section`: 영어 블록 전체 먼저, 그다음 묶음 번역
 - 🧾 **비파괴적** — 트랜스크립트와 모델 컨텍스트는 순수 영어 유지; skills, 문서, 코드 영향 없음
 - 🆓 **메인 루프 토큰 0** — 번역은 독립적인 저비용(무료 옵션 포함) 백엔드에서 실행, Claude Code 세션 완전 외부
 - ⌨️ **입력 번역 (beta)** — 모국어로 입력하고 모델은 영어로 작동하고 영어로 응답(`cctrans input on`)
@@ -99,9 +100,10 @@ Claude가 영어를 스트리밍 출력
 | `cctrans on` / `cctrans off` / `cctrans toggle` | 번역 켜기 / 끄기 / 전환 |
 | `cctrans status` | 상태 표시 (토글, 훅, 백엔드, 언어) |
 | `cctrans lang [code]` | 대상 언어 표시/설정: `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans mode [line\|section]` | 레이아웃: 각 줄 아래 번역, 또는 블록별 묶음 |
 | `cctrans backend <id>` | 번역 엔진 전환 |
 | `cctrans backends` | 모든 엔진과 가용성 나열 |
-| `cctrans setup` | 대화형 마법사: 언어, 백엔드, API 키 |
+| `cctrans setup` | 대화형 마법사: 언어, 표시 모드, 백엔드, API 키 |
 | `cctrans key [id] [value]` | `~/.cc-translate/keys.json`의 API 키 관리 |
 | `cctrans input on` / `cctrans input off` | **(beta)** 비영어 입력을 영어로 번역 (컨텍스트로 전송) |
 | `cctrans input threshold <n>` | 입력 번역을 트리거하는 비라틴 문자 수 (기본 4) |
@@ -109,6 +111,28 @@ Claude가 영어를 스트리밍 출력
 | `cctrans test <텍스트>` | 텍스트를 번역하여 엔진 검증 |
 | `cctrans install` / `cctrans uninstall` | 훅 등록 / 제거 |
 
+## 🧩 표시 모드
+
+`line`(기본)은 인터리브: 각 영어 줄 아래에 번역 한 줄씩, 응답 스트리밍과 함께 표시됩니다. `section`은 Claude가 스트리밍한 영어를 그대로 유지하고 **블록이 완성될 때 묶음 번역 하나**를 끼워 넣습니다 — 목록이 많은 응답에서 훨씬 차분합니다:
+
+```
+Use these flags:
+↳ 다음 플래그를 사용하세요:
+
+- Enable the cache
+- Set a small timeout
+- Prefer the batch API
+  ↳ 캐시를 활성화
+  ↳ 짧은 타임아웃 설정
+  ↳ 배치 API 우선 사용
+```
+
+```bash
+cctrans mode section   # 언제든 되돌리기: cctrans mode line
+```
+
+> section 모드에서는 블록의 번역이 스트리밍 중이 아니라 **블록이 완성될 때** 나타납니다 — 느린 백엔드(예: `claude-code`, 3–6초/호출)에서는 그 간격이 눈에 띄므로 여기서는 API 백엔드가 가장 적합합니다. 블록 번역이 실패해도 영어는 영향을 받지 않고 해당 블록만 번역 없이 남습니다.
+
 ## 🌐 번역 백엔드
 
 | 백엔드 | 요구사항 | 속도 | 품질 | 비고 |
@@ -151,7 +175,8 @@ cctrans lang zh-Hans  # 간체 중국어 (기본)
 
 - 훅은 **스트리밍 중** 조각마다 발화하며, 조각별로 번역하여 그 자리에서 교체 — 번역이 영어와 함께 점진적으로 나타납니다.
 - 훅 타임아웃은 **10초**; 이 도구는 내부적으로 9초 가드를 둡니다. 오류/타임아웃/초과(>9,000자)는 모두 **원본 영어로 안전하게 폴백** — 세션을 멈추지 않습니다.
-- 모든 번역 줄은 내용 해시로 **캐시**됩니다 (`~/.cc-translate/cache`); 다시 그리기와 반복 텍스트는 비용이 없습니다.
+- 모든 번역 줄은 내용 해시로 **캐시**됩니다 (`~/.cc-translate/cache`); 다시 그리기와 반복 텍스트는 비용이 없습니다. 두 모드는 캐시를 공유합니다.
+- section 모드에서는 진행 중인 블록의 텍스트가 `~/.cc-translate/msgstate`에 버퍼링됩니다(저장 시 노출 수준은 캐시와 동일); 파일은 메시지 완료 시 삭제되고 오래된 파일은 24시간 후 정리됩니다.
 - `openai` 사용 시 조각당 약 1회 API 호출(~$0.0001), 순수 영어 대비 조각당 약 1초 지연; `google`은 더 빠르지만 품질이 약간 낮습니다.
 
 ## 🔗 프로젝트 팔로우

package/README.md

@@ -28,6 +28,7 @@ A **bilingual overlay** for Claude Code: a translated line (Chinese / Japanese /
 ## ✨ Features
 
 - 🪞 **Inline bilingual display** — the translation appears under each English line, in the conversation itself, streaming along with the reply
+- 🧩 **Two layouts** — per-line interleave, or `cctrans mode section`: whole English block first, then its grouped translation
 - 🧾 **Non-destructive** — transcript and model context stay pure English; skills, docs, and code are untouched
 - 🆓 **Zero main-loop tokens** — translation runs through a separate cheap backend (or a free one), completely outside your Claude Code session
 - ⌨️ **Input translation (beta)** — type prompts in your language; the model works — and replies — in English (`cctrans input on`)
@@ -99,9 +100,10 @@ Claude streams English
 | `cctrans on` / `cctrans off` / `cctrans toggle` | turn translation on / off / toggle |
 | `cctrans status` | show state (toggle, hook, backend, language) |
 | `cctrans lang [code]` | show/set target language: `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans mode [line\|section]` | layout: translation under each line, or grouped per block |
 | `cctrans backend <id>` | switch translation engine |
 | `cctrans backends` | list engines and their availability |
-| `cctrans setup` | interactive wizard: language, backend, API keys |
+| `cctrans setup` | interactive wizard: language, display mode, backend, API keys |
 | `cctrans key [id] [value]` | manage API keys in `~/.cc-translate/keys.json` |
 | `cctrans input on` / `cctrans input off` | **(beta)** translate non-English input to English (sent as context) |
 | `cctrans input threshold <n>` | non-Latin characters that trigger input translation (default 4) |
@@ -109,6 +111,28 @@ Claude streams English
 | `cctrans test <text>` | translate ad-hoc text to verify the engine |
 | `cctrans install` / `cctrans uninstall` | register / remove the hooks |
 
+## 🧩 Display modes
+
+`line` (default) interleaves: a translated line under each English line, streaming with the reply. `section` keeps English exactly as Claude streams it and splices in **one grouped translation when a block completes** — much quieter for list-heavy replies:
+
+```
+Use these flags:
+↳ 使用以下参数：
+
+- Enable the cache
+- Set a small timeout
+- Prefer the batch API
+  ↳ 启用缓存
+  ↳ 设置较短的超时
+  ↳ 优先使用批量 API
+```
+
+```bash
+cctrans mode section   # switch back anytime: cctrans mode line
+```
+
+> In section mode a block's translation appears **when the block completes**, not while it streams — with a slow backend (e.g. `claude-code`, 3–6 s/call) that pause is noticeable, so API backends feel best here. If a block's translation fails, the English is unaffected and that block simply stays untranslated.
+
 ## 🌐 Translation backends
 
 | Backend | Requires | Speed | Quality | Notes |
@@ -151,7 +175,8 @@ Chinese uses BCP-47 **script** codes (`zh-Hans`/`zh-Hant`) — Traditional Chine
 
 - The hook fires **per chunk during streaming**; each chunk is translated and replaced in place — translations appear progressively alongside the English.
 - The hook has a **10-second** timeout; this tool guards at 9s internally. Any error / timeout / oversized chunk (>9,000 chars) **falls back safely to the original English** — it never stalls the session.
-- Every translated line is **cached** by content hash (`~/.cc-translate/cache`); repaints and repeated text cost nothing.
+- Every translated line is **cached** by content hash (`~/.cc-translate/cache`); repaints and repeated text cost nothing. Both modes share the cache.
+- In section mode an in-flight block's text is buffered in `~/.cc-translate/msgstate` (same at-rest exposure as the cache); the file is removed when the message completes and stale ones are swept after 24h.
 - With `openai`, each chunk is roughly one API call (~$0.0001) and adds about 1s of latency vs. plain English; `google` is faster with slightly lower quality.
 
 ## 🔗 Stay in the loop

package/README.ru.md

@@ -28,6 +28,7 @@
 ## ✨ Возможности
 
 - 🪞 **Встроенное двуязычное отображение** — перевод появляется под каждой английской строкой по мере стриминга ответа
+- 🧩 **Два варианта компоновки** — построчное чередование или `cctrans mode section`: сначала весь английский блок, затем его сгруппированный перевод
 - 🧾 **Неразрушающий** — транскрипт и контекст модели остаются чисто английскими; skills, документация и код не затронуты
 - 🆓 **Ноль токенов основного цикла** — перевод идёт через отдельный дешёвый (или бесплатный) бэкенд, полностью вне сессии Claude Code
 - ⌨️ **Перевод ввода (beta)** — печатайте на родном языке, модель работает — и отвечает — на английском (`cctrans input on`)
@@ -100,9 +101,10 @@ Claude стримит английский текст
 | `cctrans on` / `cctrans off` / `cctrans toggle` | включить / выключить / переключить перевод |
 | `cctrans status` | показать состояние (переключатель, хук, бэкенд, язык) |
 | `cctrans lang [code]` | показать/задать целевой язык: `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans mode [line\|section]` | компоновка: перевод под каждой строкой или сгруппированно по блокам |
 | `cctrans backend <id>` | сменить движок перевода |
 | `cctrans backends` | список движков и их доступность |
-| `cctrans setup` | интерактивный мастер: язык, бэкенд, API-ключи |
+| `cctrans setup` | интерактивный мастер: язык, режим отображения, бэкенд, API-ключи |
 | `cctrans key [id] [value]` | управление ключами в `~/.cc-translate/keys.json` |
 | `cctrans input on` / `cctrans input off` | **(beta)** переводить неанглийский ввод на английский (отправляется как контекст) |
 | `cctrans input threshold <n>` | число нелатинских символов, запускающее перевод ввода (по умолчанию 4) |
@@ -110,6 +112,28 @@ Claude стримит английский текст
 | `cctrans test <текст>` | перевести произвольный текст для проверки движка |
 | `cctrans install` / `cctrans uninstall` | зарегистрировать / удалить хуки |
 
+## 🧩 Режимы отображения
+
+`line` (по умолчанию) чередует строки: перевод под каждой английской строкой, в потоке вместе с ответом. `section` оставляет английский ровно таким, каким его стримит Claude, и вставляет **один сгруппированный перевод, когда блок завершён** — заметно спокойнее для ответов с большими списками:
+
+```
+Use these flags:
+↳ Используйте эти флаги:
+
+- Enable the cache
+- Set a small timeout
+- Prefer the batch API
+  ↳ Включите кэш
+  ↳ Задайте небольшой таймаут
+  ↳ Предпочитайте batch API
+```
+
+```bash
+cctrans mode section   # вернуться можно в любой момент: cctrans mode line
+```
+
+> В режиме section перевод блока появляется **когда блок завершён**, а не во время стриминга — с медленным бэкендом (например `claude-code`, 3–6 с/вызов) эта пауза заметна, поэтому здесь лучше всего подходят API-бэкенды. Если перевод блока не удался, английский не затрагивается — блок просто остаётся непереведённым.
+
 ## 🌐 Бэкенды перевода
 
 | Бэкенд | Требует | Скорость | Качество | Примечание |
@@ -152,7 +176,8 @@ cctrans lang zh-Hans  # упрощённый китайский (по умолч
 
 - Хук срабатывает **во время стриминга** на каждый фрагмент; каждый фрагмент переводится и заменяется на месте — перевод появляется постепенно вместе с английским.
 - Таймаут хука — **10 секунд**; внутренний гард инструмента — 9с. Любая ошибка / таймаут / превышение размера (>9000 символов) **безопасно откатывается к оригинальному английскому** — сессия никогда не зависает.
-- Каждая переведённая строка **кэшируется** по хэшу содержимого (`~/.cc-translate/cache`); перерисовки и повторяющийся текст бесплатны.
+- Каждая переведённая строка **кэшируется** по хэшу содержимого (`~/.cc-translate/cache`); перерисовки и повторяющийся текст бесплатны. Оба режима используют общий кэш.
+- В режиме section текст ещё не завершённого блока буферизуется в `~/.cc-translate/msgstate` (та же степень раскрытия данных на диске, что и у кэша); файл удаляется по завершении сообщения, а устаревшие файлы вычищаются через 24 ч.
 - С `openai` каждый фрагмент — примерно один вызов API (~$0.0001) и ~1с задержки по сравнению с чистым английским; `google` быстрее, но качество чуть ниже.
 
 ## 🔗 Следите за проектом

package/README.zh-Hans.md

@@ -28,6 +28,7 @@
 ## ✨ 特性
 
 - 🪞 **行内双语显示** —— 译文随回复流式出现在每行英文下方,就在对话里
+- 🧩 **两种排版** —— 逐行对照,或 `cctrans mode section`:整块英文先出,再跟一段成组译文
 - 🧾 **非破坏** —— 转录与模型上下文保持纯英文;skills、文档、代码不受影响
 - 🆓 **主对话零 token** —— 翻译走独立便宜后端(也有免费选项),完全在 Claude Code 会话之外
 - ⌨️ **输入翻译(beta)** —— 用母语打字,模型按英文工作、按英文回复(`cctrans input on`)
@@ -99,9 +100,10 @@ Claude 流式输出英文
 | `cctrans on` / `cctrans off` / `cctrans toggle` | 开 / 关 / 切换翻译 |
 | `cctrans status` | 查看状态(开关、钩子、后端、语言) |
 | `cctrans lang [code]` | 查看/切换目标语言:`zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans mode [line\|section]` | 排版:译文跟在每行下方,或按块成组 |
 | `cctrans backend <id>` | 切换翻译引擎 |
 | `cctrans backends` | 列出所有引擎及其可用性 |
-| `cctrans setup` | 交互式向导:语言、后端、API key |
+| `cctrans setup` | 交互式向导:语言、显示模式、后端、API key |
 | `cctrans key [id] [value]` | 管理 `~/.cc-translate/keys.json` 里的 API key |
 | `cctrans input on` / `cctrans input off` | **(beta)** 把非英文输入翻译成英文(作为上下文发给模型) |
 | `cctrans input threshold <n>` | 触发输入翻译的非拉丁字符数(默认 4) |
@@ -109,6 +111,28 @@ Claude 流式输出英文
 | `cctrans test <文本>` | 翻译一段文本,验证引擎 |
 | `cctrans install` / `cctrans uninstall` | 注册 / 移除钩子 |
 
+## 🧩 显示模式
+
+`line`(默认)逐行对照:每行英文下面一行译文,随回复流式出现。`section` 让英文完全按 Claude 的流式输出原样呈现,在**一个块完成时**插入一段成组译文——对列表很多的回复要安静得多:
+
+```
+Use these flags:
+↳ 使用以下参数：
+
+- Enable the cache
+- Set a small timeout
+- Prefer the batch API
+  ↳ 启用缓存
+  ↳ 设置较短的超时
+  ↳ 优先使用批量 API
+```
+
+```bash
+cctrans mode section   # 随时切回:cctrans mode line
+```
+
+> section 模式下,一个块的译文在**该块完成时**才出现,而不是边流式边出——后端慢时(如 `claude-code`,3–6 秒/次)这个停顿会比较明显,所以这里 API 后端体验最好。某个块翻译失败时,英文不受影响,该块只是保持未翻译。
+
 ## 🌐 翻译后端
 
 | 后端 | 前提 | 速度 | 质量 | 说明 |
@@ -151,7 +175,8 @@ cctrans lang zh-Hans  # 简体中文(默认)
 
 - 钩子在**流式输出中**按片段触发,每段单独翻译并就地替换——所以译文会随英文逐段出现。
 - 钩子有 **10 秒**超时;本工具内部 9 秒兜底。任何错误/超时/超长(>9000 字符)都会**安全回退成原始英文**,绝不卡住会话。
-- 每行译文按内容哈希**缓存**(`~/.cc-translate/cache`),重绘和重复文本零成本。
+- 每行译文按内容哈希**缓存**(`~/.cc-translate/cache`),重绘和重复文本零成本。两种模式共享同一缓存。
+- section 模式下,进行中块的文本会缓冲在 `~/.cc-translate/msgstate`(落盘暴露面与缓存相同);消息完成后该文件即删除,过期残留文件 24 小时后清理。
 - 用 `openai` 时每段约一次 API 调用(~$0.0001),流式输出会比纯英文多约 1 秒/段的延迟;`google` 更快但质量略低。
 
 ## 🔗 关注项目

package/README.zh-Hant.md

@@ -28,6 +28,7 @@
 ## ✨ 特性
 
 - 🪞 **行內雙語顯示** —— 譯文隨回覆串流出現在每行英文下方,就在對話裡
+- 🧩 **兩種排版** —— 逐行對照,或 `cctrans mode section`:整塊英文先出,再跟一段成組譯文
 - 🧾 **非破壞性** —— 轉錄與模型上下文保持純英文;skills、文件、程式碼不受影響
 - 🆓 **主對話零 token** —— 翻譯走獨立低成本後端(也有免費選項),完全在 Claude Code 工作階段之外
 - ⌨️ **輸入翻譯(beta)** —— 用母語打字,模型按英文工作、按英文回覆(`cctrans input on`)
@@ -99,9 +100,10 @@ Claude 串流輸出英文
 | `cctrans on` / `cctrans off` / `cctrans toggle` | 開 / 關 / 切換翻譯 |
 | `cctrans status` | 檢視狀態(開關、鉤子、後端、語言) |
 | `cctrans lang [code]` | 檢視/切換目標語言:`zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans mode [line\|section]` | 排版:譯文跟在每行下方,或按區塊成組 |
 | `cctrans backend <id>` | 切換翻譯引擎 |
 | `cctrans backends` | 列出所有引擎及其可用性 |
-| `cctrans setup` | 互動式精靈:語言、後端、API key |
+| `cctrans setup` | 互動式精靈:語言、顯示模式、後端、API key |
 | `cctrans key [id] [value]` | 管理 `~/.cc-translate/keys.json` 中的 API key |
 | `cctrans input on` / `cctrans input off` | **(beta)** 把非英文輸入翻譯成英文(作為上下文傳給模型) |
 | `cctrans input threshold <n>` | 觸發輸入翻譯的非拉丁字元數(預設 4) |
@@ -109,6 +111,28 @@ Claude 串流輸出英文
 | `cctrans test <文字>` | 翻譯一段文字,驗證引擎 |
 | `cctrans install` / `cctrans uninstall` | 註冊 / 移除鉤子 |
 
+## 🧩 顯示模式
+
+`line`(預設)逐行對照:每行英文下方一行譯文,隨回覆串流出現。`section` 讓英文完全按 Claude 的串流輸出原樣呈現,在**一個區塊完成時**插入一段成組譯文——對列表很多的回覆要安靜得多:
+
+```
+Use these flags:
+↳ 使用以下参数：
+
+- Enable the cache
+- Set a small timeout
+- Prefer the batch API
+  ↳ 启用缓存
+  ↳ 设置较短的超时
+  ↳ 优先使用批量 API
+```
+
+```bash
+cctrans mode section   # 隨時切回:cctrans mode line
+```
+
+> section 模式下,一個區塊的譯文在**該區塊完成時**才出現,而不是邊串流邊出——後端慢時(如 `claude-code`,3–6 秒/次)這個停頓會比較明顯,所以這裡 API 後端體驗最好。某個區塊翻譯失敗時,英文不受影響,該區塊只是保持未翻譯。
+
 ## 🌐 翻譯後端
 
 | 後端 | 前提 | 速度 | 品質 | 說明 |
@@ -151,7 +175,8 @@ cctrans lang zh-Hans  # 簡體中文(預設)
 
 - 鉤子在**串流輸出中**按片段觸發,每段單獨翻譯並就地替換——所以譯文會隨英文逐段出現。
 - 鉤子有 **10 秒**逾時;本工具內部 9 秒保底。任何錯誤/逾時/超長(>9000 字元)都會**安全回退成原始英文**,絕不卡住工作階段。
-- 每行譯文按內容雜湊**快取**(`~/.cc-translate/cache`),重繪與重複文字零成本。
+- 每行譯文按內容雜湊**快取**(`~/.cc-translate/cache`),重繪與重複文字零成本。兩種模式共享同一快取。
+- section 模式下,進行中區塊的文字會緩衝在 `~/.cc-translate/msgstate`(落盤暴露面與快取相同);訊息完成後該檔案即刪除,逾期殘留檔案 24 小時後清理。
 - 用 `openai` 時每段約一次 API 呼叫(~$0.0001),串流輸出會比純英文多約 1 秒/段的延遲;`google` 較快但品質略低。
 
 ## 🔗 關注專案

package/ROADMAP.md

@@ -2,11 +2,14 @@
 
 ## Shipped
 
+### ✅ Section display mode — grouped translation per block
+`cctrans mode section` (default stays `line`): English streams untouched, and a block's translation is spliced in as one grouped `↳` block when the block completes (blank line / code fence / already-target line / end of message) — much quieter for list-heavy replies. Design notes: section boundaries are properties of the **text**, never of delta chunking (deltas batch arbitrarily — verified live), which makes repaint replay byte-identical; the open block buffers in `~/.cc-translate/msgstate` (atomic writes, removed on message end, 24h GC); state is committed **before** translation, so a crash/timeout can only drop a block's translation, never misplace it. Headings close their own section (a displaced `## ↳ 译` would render as a real heading). Translation stays per-line, so both modes share the sha1 cache and the backends are untouched. The boundary machinery trivially supports a future `message` granularity (flush at final only).
+
 ### ✅ Input translation — write in your language, send in English
 `cctrans input on` enables a `UserPromptSubmit` hook: prompts that are mostly non-English get an English translation attached as `additionalContext`, which the model treats as the canonical instruction. Implementation note: Claude Code hooks provably cannot rewrite the prompt itself (verified against the 2.1.169 **and 2.1.170** binaries — the `UserPromptSubmit`/`UserPromptExpansion` output schemas only allow `additionalContext` and block), so attach-as-context is the strongest available form; the original prompt stays in history with the English alongside. If a future CC release adds a prompt-rewrite field, switching to true replacement is a one-line change in `hook/user-prompt-submit.js`.
 
 ### ✅ Interactive setup wizard
-`cctrans install` registers both hooks and launches the wizard; `cctrans setup` re-runs it anytime. Walks through target language → backend selection → key entry for the chosen backend → live translation verification. Non-interactive flags: `--lang`, `--backend`, `--key`, `--yes`.
+`cctrans install` registers both hooks and launches the wizard; `cctrans setup` re-runs it anytime. Walks through target language → display mode → backend selection → key entry for the chosen backend → live translation verification. Non-interactive flags: `--lang`, `--mode`, `--backend`, `--key`, `--yes`.
 
 ### ✅ Per-tool API-key config (no env cross-pollution)
 Keys live **only** in `~/.cc-translate/keys.json` (chmod 600, atomic writes), managed via `cctrans key <id> [value|--clear]`, the setup wizard, or direct file edits. Shell environment variables are **never** consulted — no overrides, no opt-in. All non-secret settings (backend, language, marker, models, Azure endpoint) live in `~/.cc-translate/state.json`. The only env vars the tool reads are internal plumbing: `CCTRANS_HOME` / `CCTRANS_TRANSCRIPT` (tests) and `CCTRANS_DISABLE` / `CCTRANS_DEBUG_STDIN` (hook internals).

package/bin/cctrans.js

@@ -13,8 +13,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const { getState, setState, STATE_FILE } = require('../src/config');
-const { buildDisplayContent } = require('../src/interleave');
+const { getState, setState, STATE_FILE, MODES, sweepMsgState } = require('../src/config');
+const { buildDisplayContent, planSections, renderSections } = require('../src/interleave');
 const { findTranscript, extractReply } = require('../src/transcript');
 const { listBackends, getBackend } = require('../src/backends');
 const { getLang, listLangs, normalizeLang } = require('../src/langs');
@@ -117,6 +117,9 @@ function status() {
   console.log('  hook    : ' + (installed ? C.green('installed') : C.red('not installed') + C.dim('  (run: cctrans install)')));
   console.log('  backend : ' + st.backend + (b ? (b.available() ? C.green('  (ready)') : C.red('  (missing: ' + b.needs + ')')) : C.red('  (unknown backend)')));
   console.log('  lang    : ' + st.target + (lang ? C.dim('  (' + lang.name + ')') : C.red('  (unsupported — see: cctrans lang)')));
+  console.log('  mode    : ' + st.mode + C.dim(st.mode === 'section'
+    ? '  (grouped per block; translation appears when the block completes)'
+    : '  (translation under each English line)'));
   console.log('  input   : ' + (st.inputEn ? C.green('ON') : 'off') + C.dim('  (beta; prompt -> English; toggle: cctrans input on|off; triggers at ' + st.inputMinChars + '+ non-Latin chars)'));
   console.log('  keys    : ' + Object.keys(keys.readKeys()).length + ' in ' + keys.KEYS_FILE + C.dim('  (manage: cctrans key)'));
   console.log('  state   : ' + STATE_FILE);
@@ -150,17 +153,30 @@ function backends() {
 }
 
 function colorizeForTerminal(displayContent, marker) {
+  // Match the marker after optional structure prefixes too ("## ↳", "> ↳",
+  // list-indent "  ↳") so grouped section blocks color consistently.
+  const zhLine = new RegExp('^\\s*(?:#{1,6}\\s+|(?:>\\s*)+)?\\s*' + marker.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
   return displayContent
     .split('\n')
-    .map((l) => (l.startsWith(marker) ? C.cyan(l) : l))
+    .map((l) => (zhLine.test(l) ? C.cyan(l) : l))
     .join('\n');
 }
 
 async function renderText(text) {
   const st = getState();
-  const { displayContent } = await buildDisplayContent(text, {
-    target: st.target, backend: st.backend, model: st.model, marker: st.marker, timeoutMs: 12000,
-  });
+  let displayContent;
+  if (st.mode === 'section') {
+    // The whole text is one final delta, so `cctrans test`/`last` exercise
+    // section mode end-to-end.
+    const planned = planSections(text, { inFence: false, buf: [], target: st.target, final: true });
+    displayContent = await renderSections(planned, {
+      target: st.target, backend: st.backend, model: st.model, marker: st.marker, timeoutMs: 12000,
+    });
+  } else {
+    displayContent = (await buildDisplayContent(text, {
+      target: st.target, backend: st.backend, model: st.model, marker: st.marker, timeoutMs: 12000,
+    })).displayContent;
+  }
   if (displayContent == null) { process.stdout.write(text + '\n'); return; }
   process.stdout.write(colorizeForTerminal(displayContent, st.marker) + '\n');
 }
@@ -183,13 +199,14 @@ ${C.bold('Control')}
   cctrans input threshold <n>    non-Latin chars that trigger input translation (default 4)
   cctrans status                 show current state
   cctrans lang [code]            show/set target language (zh-Hans, zh-Hant, ja, ko, ru, hi)
+  cctrans mode [line|section]    layout: translation under each line, or grouped per block
   cctrans backend <id>           choose translation engine
   cctrans backends               list engines + availability
 
 ${C.bold('Setup')}
   cctrans install                register hooks (+ link cctrans), then run setup
-  cctrans setup                  interactive wizard: language, backend, API keys
-                            (flags: --lang --backend --key --input --yes)
+  cctrans setup                  interactive wizard: language, display mode, backend, API keys
+                            (flags: --lang --mode --backend --key --input --yes)
   cctrans key [id] [value]       manage API keys in ~/.cc-translate/keys.json
                             (ids: openai, anthropic, deepl, azure, azure-region)
   cctrans uninstall              remove the hooks
@@ -204,8 +221,8 @@ ${C.dim('Tip: toggle from inside Claude Code by typing  !cctrans off  /  !cctran
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   switch (cmd) {
-    case 'on': setState({ enabled: true }); console.log(C.green('✓ translation ON')); break;
-    case 'off': setState({ enabled: false }); console.log('✓ translation ' + C.red('OFF')); break;
+    case 'on': setState({ enabled: true }); sweepMsgState(24 * 60 * 60 * 1000); console.log(C.green('✓ translation ON')); break;
+    case 'off': setState({ enabled: false }); sweepMsgState(0); console.log('✓ translation ' + C.red('OFF')); break;
     case 'toggle': { const s = getState(); const n = setState({ enabled: !s.enabled }); console.log('✓ translation ' + (n.enabled ? C.green('ON') : C.red('OFF'))); break; }
     case 'backend': {
       const id = rest[0];
@@ -219,6 +236,20 @@ async function main() {
       break;
     }
     case 'backends': backends(); break;
+    case 'mode': {
+      const m = rest[0];
+      if (!m) {
+        const st = getState();
+        console.log('mode = ' + st.mode + C.dim('  (available: line — translation under each English line; section — grouped per block)'));
+        break;
+      }
+      if (!MODES.includes(m)) { console.error('usage: cctrans mode <' + MODES.join('|') + '>'); process.exit(1); }
+      setState({ mode: m });
+      console.log(C.green('✓') + ' mode = ' + m + C.dim(m === 'section'
+        ? '  (English streams as-is; each block\'s translation appears when the block completes)'
+        : '  (translation under each English line)'));
+      break;
+    }
     case 'lang': {
       const code = rest[0];
       if (!code) { const st = getState(); console.log('lang = ' + st.target + C.dim('  (available: ' + listLangs().join(', ') + '; aliases: zh-CN, zh-TW)')); break; }
@@ -241,6 +272,7 @@ async function main() {
       const flag = (name) => { const i = rest.indexOf(name); return i > -1 ? rest[i + 1] : undefined; };
       await require('../src/setup').runSetup({
         lang: flag('--lang'),
+        mode: flag('--mode'),
         backend: flag('--backend'),
         key: flag('--key'),
         input: flag('--input'),

package/hook/message-display.js

@@ -6,39 +6,67 @@
 //   delta = the newly completed lines of the streaming assistant message.
 //           Deltas are non-overlapping; a code fence (```) can span deltas.
 // stdout (JSON, exit 0): { hookSpecificOutput: { hookEventName: "MessageDisplay",
-//                          displayContent: "<EN line>\n↳ <ZH line> ..." } }
+//                          displayContent: "..." } }
 //   displayContent REPLACES the delta on screen. Display-only: the transcript
 //   and the model's context keep the original English.
 //
+// Two layouts (state.json "mode"):
+//   line     — every prose line gets its "↳ 译" immediately (buildDisplayContent)
+//   section  — English passes through untouched; prose lines buffer in msgstate
+//              and a grouped ZH block is spliced in when the section closes
+//              (planSections + renderSections)
+//
 // Safety contract: on disabled / empty / error / timeout, emit NOTHING and
 // exit 0 so Claude Code renders the original English delta unchanged. This hook
 // must never break or stall the user's session.
 
 const fs = require('fs');
 const path = require('path');
-const { getState, BASE } = require('../src/config');
-const { buildDisplayContent } = require('../src/interleave');
+const { getState, MSGSTATE_DIR, sweepMsgState } = require('../src/config');
+const { buildDisplayContent, planSections, renderSections } = require('../src/interleave');
 
 function showOriginal() { process.exit(0); } // no stdout => CC keeps the original delta
 
-// Per-message code-fence state, so "inside a ``` block?" carries across the
-// deltas of one message. Reset at index 0 (also covers full repaints, which
-// re-send the message from index 0); removed when the message completes.
-const MSGDIR = path.join(BASE, 'msgstate');
-function fenceFile(id) { return path.join(MSGDIR, String(id).replace(/[^\w.-]/g, '_') + '.json'); }
-function loadFence(id, index) {
-  if (!id || index === 0) return false;
-  try { return !!JSON.parse(fs.readFileSync(fenceFile(id), 'utf8')).inFence; } catch (e) { return false; }
+// Per-message state, so "inside a ``` block?" and the open section's buffered
+// lines carry across the deltas of one message (fresh process per delta).
+// Reset at index 0 (also covers full repaints, which re-send the message from
+// index 0); removed when the message completes. Schema {v, mode, index,
+// inFence, buf}; a version/mode mismatch or unparseable file reads as fresh.
+const STATE_V = 2;
+function stateFile(id) { return path.join(MSGSTATE_DIR, String(id).replace(/[^\w.-]/g, '_') + '.json'); }
+function loadMsgState(id, index, mode) {
+  const fresh = { inFence: false, buf: [] };
+  if (!id || index === 0) return fresh;
+  try {
+    const st = JSON.parse(fs.readFileSync(stateFile(id), 'utf8'));
+    if (st.v !== STATE_V || st.mode !== mode) return fresh;
+    // Index gap = an earlier delta crashed before saving. Drop the buffer so
+    // two sections can never be translated as one block at a later boundary;
+    // keep the fence flag best-effort (same exposure line mode has today).
+    if (st.index !== index - 1) return { inFence: !!st.inFence, buf: [] };
+    return { inFence: !!st.inFence, buf: Array.isArray(st.buf) ? st.buf : [] };
+  } catch (e) { return fresh; }
 }
-function saveFence(id, index, inFence, final) {
+function saveMsgState(id, index, mode, inFence, buf, final) {
   if (!id) return;
   try {
-    if (final) { try { fs.unlinkSync(fenceFile(id)); } catch (e) {} return; }
-    fs.mkdirSync(MSGDIR, { recursive: true });
-    fs.writeFileSync(fenceFile(id), JSON.stringify({ index, inFence }));
+    if (final) { try { fs.unlinkSync(stateFile(id)); } catch (e) {} return; }
+    fs.mkdirSync(MSGSTATE_DIR, { recursive: true });
+    const f = stateFile(id);
+    const tmp = f + '.' + process.pid + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify({ v: STATE_V, mode, index, inFence, buf }));
+    fs.renameSync(tmp, f); // atomic: buf files are big enough for torn writes to matter
+    if (index === 0) sweepMsgState(24 * 60 * 60 * 1000); // GC files leaked by killed sessions
   } catch (e) {}
 }
 
+function emit(displayContent) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'MessageDisplay', displayContent: displayContent },
+  }));
+  process.exit(0);
+}
+
 let data = '';
 process.stdin.on('data', (d) => (data += d));
 process.stdin.on('end', async () => {
@@ -49,7 +77,6 @@ process.stdin.on('end', async () => {
   try { inp = JSON.parse(data); } catch (e) { return showOriginal(); }
 
   const delta = typeof inp.delta === 'string' ? inp.delta : '';
-  if (!delta) return showOriginal();
 
   // Recursion guard: the claude-code backend spawns `claude -p` with
   // CCTRANS_DISABLE=1 so a child Claude process can never re-enter this hook.
@@ -62,22 +89,48 @@ process.stdin.on('end', async () => {
   const id = inp.message_id;
   const index = typeof inp.index === 'number' ? inp.index : 0;
   const final = inp.final === true;
-  const inFence0 = loadFence(id, index);
+
+  if (st.mode === 'section') {
+    const ms = loadMsgState(id, index, 'section');
+    // An empty delta still flushes when it is the final one and lines are buffered.
+    if (!delta && !(final && ms.buf.length)) return showOriginal();
+    const guard = setTimeout(showOriginal, 9000);
+    try {
+      const planned = planSections(delta, { inFence: ms.inFence, buf: ms.buf, target: st.target, final: final });
+      // Commit state BEFORE translating (flushed sections already pruned from
+      // buf): a crash/timeout past this point can only drop a section's
+      // translation, never replay it at a wrong position.
+      saveMsgState(id, index, 'section', planned.inFence, planned.buf, final);
+      if (!planned.flushes.length) { clearTimeout(guard); return showOriginal(); }
+      const displayContent = await renderSections(planned, {
+        target: st.target, backend: st.backend, model: st.model, marker: st.marker,
+        timeoutMs: 5500, // smaller than line mode's 8000 so the google fallback keeps ~3s under the 9s guard
+      });
+      clearTimeout(guard);
+      if (displayContent == null) return showOriginal();
+      emit(displayContent);
+    } catch (e) {
+      clearTimeout(guard);
+      return showOriginal();
+    }
+    return;
+  }
+
+  // line mode
+  if (!delta) return showOriginal();
+  const ms = loadMsgState(id, index, 'line');
 
   // Guard below Claude Code's 10s MessageDisplay timeout so we always exit clean.
   const guard = setTimeout(showOriginal, 9000);
   try {
     const { displayContent, inFence } = await buildDisplayContent(delta, {
       target: st.target, backend: st.backend, model: st.model,
-      marker: st.marker, timeoutMs: 8000, inFence: inFence0,
+      marker: st.marker, timeoutMs: 8000, inFence: ms.inFence,
     });
     clearTimeout(guard);
-    saveFence(id, index, inFence, final); // persist even when nothing was translated
+    saveMsgState(id, index, 'line', inFence, [], final); // persist even when nothing was translated
     if (displayContent == null) return showOriginal();
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: { hookEventName: 'MessageDisplay', displayContent: displayContent },
-    }));
-    process.exit(0);
+    emit(displayContent);
   } catch (e) {
     clearTimeout(guard);
     return showOriginal();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctrans",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Bilingual inline translation overlay for Claude Code: a translated line (zh/ja/ko/ru/hi) under each English line, right in the conversation — non-destructive, zero main-loop tokens.",
   "license": "MIT",
   "author": "Roy Jiang",
@@ -39,6 +39,6 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/fence.js"
+    "test": "node test/fence.js && node test/markdown.js && node test/section.js"
   }
 }

package/src/config.js

@@ -14,6 +14,23 @@ const HOME = os.homedir();
 const BASE = process.env.CCTRANS_HOME || path.join(HOME, '.cc-translate');
 const STATE_FILE = path.join(BASE, 'state.json');
 const CACHE_DIR = path.join(BASE, 'cache');
+const MSGSTATE_DIR = path.join(BASE, 'msgstate');
+
+// Display layouts. Validate against this list everywhere (CLI, setup, hook) so
+// a future granularity (e.g. 'message') is a one-line addition.
+const MODES = ['line', 'section'];
+
+// Remove per-message state files older than maxAgeMs (0 = all). Sessions
+// killed mid-message leave their file behind; swept here and on index-0 saves.
+function sweepMsgState(maxAgeMs) {
+  try {
+    const cutoff = Date.now() - (maxAgeMs || 0);
+    for (const f of fs.readdirSync(MSGSTATE_DIR)) {
+      const p = path.join(MSGSTATE_DIR, f);
+      try { if (fs.statSync(p).mtimeMs <= cutoff) fs.unlinkSync(p); } catch (e) {}
+    }
+  } catch (e) {}
+}
 
 function ensureDirs() {
   try { fs.mkdirSync(CACHE_DIR, { recursive: true }); } catch (e) {}
@@ -29,6 +46,7 @@ function defaults() {
     anthropicModel: 'claude-haiku-4-5', // anthropic backend model
     azureEndpoint: 'https://api.cognitive.microsofttranslator.com',
     marker: '↳ ', // prefix on each translated line
+    mode: 'line', // display layout: 'line' (ZH under each line) or 'section' (grouped per block)
     inputEn: false, // input translation (beta, prompt -> English) off until enabled
     inputMinChars: 4, // non-Latin chars in a prompt that trigger input translation
   };
@@ -52,6 +70,7 @@ function setState(patch) {
     anthropicModel: next.anthropicModel,
     azureEndpoint: next.azureEndpoint,
     marker: next.marker,
+    mode: next.mode,
     inputEn: next.inputEn,
     inputMinChars: next.inputMinChars,
   };
@@ -61,4 +80,4 @@ function setState(patch) {
   return next;
 }
 
-module.exports = { HOME, BASE, STATE_FILE, CACHE_DIR, ensureDirs, getState, setState, defaults };
+module.exports = { HOME, BASE, STATE_FILE, CACHE_DIR, MSGSTATE_DIR, MODES, ensureDirs, getState, setState, defaults, sweepMsgState };

package/src/interleave.js

@@ -16,6 +16,22 @@ function looksLikeCodeish(s) {
   return false;
 }
 
+// Leading BLOCK markdown (heading / list marker / blockquote) must be split
+// off before translation: fed to an MT backend it gets kept or mangled, and
+// re-rendered mid-line after the ↳ marker it shows up as literal "##" / "-" /
+// ">" (the translated line no longer starts with the prefix, so the renderer
+// treats it as text). Translate the content only; re-apply structure when
+// building the translated line.
+function splitBlockPrefix(line) {
+  let m = line.match(/^(\s{0,3}#{1,6}\s+)(.*)$/); // heading
+  if (m) return { prefix: m[1], content: m[2], block: 'heading' };
+  m = line.match(/^(\s*(?:[-*+]|\d{1,3}[.)])\s+)(.*)$/); // list item
+  if (m) return { prefix: m[1], content: m[2], block: 'list' };
+  m = line.match(/^(\s*(?:>\s*)+)(.*)$/); // blockquote (possibly nested)
+  if (m) return { prefix: m[1], content: m[2], block: 'quote' };
+  return { prefix: '', content: line, block: null };
+}
+
 // A code fence (```), and therefore "are we inside a code block?", can span
 // multiple MessageDisplay deltas. The caller threads the ending fence state of
 // one delta into the next (keyed by message_id), so classify takes an initial
@@ -30,17 +46,34 @@ function classify(lines, inFenceInit, target) {
     if (line.trim() === '') { plan.push({ line, kind: 'blank' }); continue; }
     if (isProbablyTarget(line, target)) { plan.push({ line, kind: 'target' }); continue; }
     if (looksLikeCodeish(line)) { plan.push({ line, kind: 'code' }); continue; }
-    plan.push({ line, kind: 'prose' });
+    const { prefix, content, block } = splitBlockPrefix(line);
+    if (looksLikeCodeish(content)) { plan.push({ line, kind: 'code' }); continue; } // e.g. "- /path/to/file"
+    plan.push({ line, kind: 'prose', prefix, content, block });
   }
   return { plan, inFence };
 }
 
-// How to place the Chinese line under the English line.
+// The translated line mirrors the English line's block structure:
+//   heading "## T"  -> "## ↳ 译"   (same heading style)
+//   quote   "> T"   -> "> ↳ 译"    (stays inside the quote)
+//   list    "- T"   -> "  ↳ 译"    (same-width indent — a re-applied "- " would
+//                                   render a second bullet)
+//   plain   "T"     -> "↳ 译"
+// demoteStructure drops the heading/quote prefix (plain "↳ 译"): in a grouped
+// section block displaced from its English line, a re-applied "## "/"> " would
+// render a REAL heading / fresh blockquote detached from what it translates.
+function zhLineFor(p, zh, marker, demoteStructure) {
+  if (p.block === 'list') return ' '.repeat(p.prefix.length) + marker + zh;
+  if (demoteStructure && (p.block === 'heading' || p.block === 'quote')) return marker + zh;
+  return p.prefix + marker + zh;
+}
+
+// How to place the Chinese line under the English line (line mode).
 // hardBreak=true uses a CommonMark hard line break (two trailing spaces) so the
 // two lines stay separate even if displayContent is markdown-rendered.
-function pair(enLine, zhLine, marker, hardBreak) {
+function pair(p, zh, marker, hardBreak) {
   const br = hardBreak ? '  \n' : '\n';
-  return enLine + br + marker + zhLine;
+  return p.line + br + zhLineFor(p, zh, marker, false);
 }
 
 // Returns { displayContent, inFence }:
@@ -64,7 +97,7 @@ async function buildDisplayContent(rawDelta, opts) {
   const proseIdx = [];
   const proseLines = [];
   for (let i = 0; i < plan.length; i++) {
-    if (plan[i].kind === 'prose') { proseIdx.push(i); proseLines.push(plan[i].line); }
+    if (plan[i].kind === 'prose') { proseIdx.push(i); proseLines.push(plan[i].content); }
   }
   if (proseLines.length === 0) return { displayContent: null, inFence }; // nothing to translate
 
@@ -79,7 +112,7 @@ async function buildDisplayContent(rawDelta, opts) {
     const p = plan[i];
     if (p.kind === 'prose') {
       const t = zhFor[i];
-      if (t && t.trim() && t.trim() !== p.line.trim()) out.push(pair(p.line, t, marker, hardBreak));
+      if (t && t.trim() && t.trim() !== p.content.trim()) out.push(pair(p, t, marker, hardBreak));
       else out.push(p.line);
     } else {
       out.push(p.line);
@@ -90,4 +123,124 @@ async function buildDisplayContent(rawDelta, opts) {
   return { displayContent: dc, inFence };
 }
 
-module.exports = { buildDisplayContent, classify, looksLikeCodeish };
+// ---------------------------------------------------------------------------
+// Section mode: English streams untouched; a section's translation is spliced
+// in as one grouped "↳" block when the section closes.
+//
+// A section = a maximal run of consecutive prose lines. Boundaries are
+// properties of the TEXT, never of delta chunking (deltas batch arbitrarily —
+// the same reply can arrive as 3 deltas in one run and 5 in another), which is
+// what makes a full repaint (replay from index 0) reproduce identical output:
+//   - a real blank line (the last split element '' merely encodes the delta's
+//     trailing "\n" — a continuing block, not a blank);
+//   - any code/fence/target-language line;
+//   - a heading, which closes the run before it AND itself: a displaced
+//     "## ↳ 译" would render as a real heading below the block it titles;
+//   - the soft buffer cap (deferred past list items so a forced splice never
+//     lands mid-list, with a hard ceiling as backstop);
+//   - final:true.
+
+const SECTION_CAP = 6000; // soft cap on buffered EN chars before a forced flush
+const SECTION_HARD_CAP = 9000; // flush even mid-list past this
+
+// Pure, synchronous segmentation — no I/O, no await, so the hook can persist
+// the resulting buffer BEFORE translation starts (at-most-once flush: a crash
+// or timeout after the save can only drop a section's translation, never
+// replay it at a wrong position).
+// opts: {inFence, buf (pending entries from prior deltas), target, final}
+// Returns:
+//   out      — the delta's own lines, verbatim (splice skeleton)
+//   flushes  — [{pos, entries}]: closed sections and where in `out` their ZH
+//              block goes (right after the section's last English line)
+//   buf      — entries still pending (the open section), to persist
+//   inFence  — fence state at end of delta, to persist
+function planSections(rawDelta, opts) {
+  opts = opts || {};
+  const lines = String(rawDelta).split('\n');
+  const { plan, inFence } = classify(lines, opts.inFence, opts.target || 'zh-Hans');
+  const out = [];
+  const flushes = [];
+  let pending = (opts.buf || []).slice();
+  let pendingChars = pending.reduce((n, e) => n + e.content.length, 0);
+  const flush = () => {
+    if (pending.length) { flushes.push({ pos: out.length, entries: pending }); pending = []; pendingChars = 0; }
+  };
+  for (let i = 0; i < plan.length; i++) {
+    const p = plan[i];
+    if (p.kind === 'prose') {
+      if (p.block === 'heading') flush(); // close the run before the heading
+      out.push(p.line);
+      pending.push({ line: p.line, prefix: p.prefix, content: p.content, block: p.block });
+      pendingChars += p.content.length;
+      if (p.block === 'heading') flush(); // ...and the heading itself
+      else if (pendingChars > SECTION_CAP && (p.block !== 'list' || pendingChars > SECTION_HARD_CAP)) flush();
+      continue;
+    }
+    if (p.kind === 'blank') {
+      const terminalArtifact = i === plan.length - 1 && p.line === '';
+      if (!terminalArtifact) flush();
+      out.push(p.line);
+      continue;
+    }
+    flush(); // code/fence/target line interrupts the section, then passes through
+    out.push(p.line);
+  }
+  if (opts.final) flush();
+  return { out, flushes, buf: pending, inFence };
+}
+
+// Translate all flushed sections (one batch call) and splice each grouped ZH
+// block into the out-skeleton. Returns the displayContent string, or null for
+// "leave this delta as the original English" (nothing survived translation, or
+// over the cap). Translation is per-LINE (prefix-stripped), so the sha1 cache
+// is shared with line mode and the backends' line contracts hold unchanged.
+async function renderSections(planned, opts) {
+  opts = opts || {};
+  const marker = opts.marker || '↳ ';
+  const cap = opts.cap || 9000;
+  if (!planned.flushes.length) return null;
+
+  const contents = [];
+  for (const f of planned.flushes) for (const e of f.entries) contents.push(e.content);
+  const zh = await translateLines(contents, {
+    target: opts.target, backend: opts.backend, model: opts.model, timeoutMs: opts.timeoutMs,
+  });
+
+  let k = 0;
+  const blocks = [];
+  for (const f of planned.flushes) {
+    // Single-line sections keep line-mode structure; a uniform quote run keeps
+    // its "> " (the block continues the same blockquote). Only mixed grouped
+    // blocks demote structure prefixes.
+    const grouped = f.entries.length > 1;
+    const allQuote = grouped && f.entries.every((e) => e.block === 'quote');
+    const blockLines = [];
+    for (const e of f.entries) {
+      const t = zh[k++];
+      if (t && t.trim() && t.trim() !== e.content.trim()) blockLines.push(zhLineFor(e, t, marker, grouped && !allQuote));
+    }
+    if (blockLines.length) blocks.push({ pos: f.pos, lines: blockLines });
+  }
+  if (!blocks.length) return null;
+
+  const splice = () => {
+    const merged = planned.out.slice();
+    for (let i = blocks.length - 1; i >= 0; i--) merged.splice(blocks[i].pos, 0, ...blocks[i].lines);
+    return merged.join('\n');
+  };
+  let dc = splice();
+  // Over the cap: shed whole ZH blocks (largest first) instead of dropping the
+  // delta's entire translation — their sections are already committed out of
+  // the buffer, so a shed block is simply lost, never repositioned.
+  while (dc.length > cap && blocks.length) {
+    let big = 0;
+    for (let i = 1; i < blocks.length; i++) {
+      if (blocks[i].lines.join('\n').length > blocks[big].lines.join('\n').length) big = i;
+    }
+    blocks.splice(big, 1);
+    dc = blocks.length ? splice() : null;
+  }
+  return dc;
+}
+
+module.exports = { buildDisplayContent, classify, looksLikeCodeish, planSections, renderSections };

package/src/setup.js

@@ -1,11 +1,12 @@
 'use strict';
-// Interactive setup wizard: language -> backend -> API-key entry -> input
-// translation (beta) -> live verification -> save. Re-runnable via `cctrans
-// setup`; non-interactive with flags (--lang, --backend, --key, --input,
-// --yes). Keys go to keys.json only — the shell environment is never read.
+// Interactive setup wizard: language -> display mode -> backend -> API-key
+// entry -> input translation (beta) -> live verification -> save. Re-runnable
+// via `cctrans setup`; non-interactive with flags (--lang, --mode, --backend,
+// --key, --input, --yes). Keys go to keys.json only — the shell environment is
+// never read.
 
 const readline = require('node:readline/promises');
-const { getState, setState } = require('./config');
+const { getState, setState, MODES } = require('./config');
 const { listLangs, getLang, normalizeLang } = require('./langs');
 const { listBackends, getBackend } = require('./backends');
 const keys = require('./keys');
@@ -38,7 +39,7 @@ async function runSetup(opts) {
     let lang = opts.lang;
     if (!lang) {
       const codes = listLangs();
-      console.log('\n' + C.bold('Target language') + ' — translations appear under each English line:');
+      console.log('\n' + C.bold('Target language') + ' — replies show English + your language inline:');
       codes.forEach((c, i) => console.log('  ' + (i + 1) + '. ' + c.padEnd(8) + C.dim(getLang(c).name)));
       const cur = getState().target;
       const a = await ask('Pick a number or code', cur);
@@ -47,7 +48,18 @@ async function runSetup(opts) {
     if (!getLang(lang)) { console.error(C.red('unsupported language: ' + lang)); return false; }
     lang = normalizeLang(lang);
 
-    // 2. Backend
+    // 2. Display mode
+    let mode = opts.mode;
+    if (!mode) {
+      console.log('\n' + C.bold('Display mode') + ':');
+      console.log('  1. line     ' + C.dim('translation under each English line, as it streams'));
+      console.log('  2. section  ' + C.dim('English block first, then its translation — appears when the block completes'));
+      const a = await ask('Pick a number or name', getState().mode);
+      mode = a === '1' ? 'line' : a === '2' ? 'section' : a;
+    }
+    if (!MODES.includes(mode)) { console.error(C.red('unknown mode: ' + mode + ' (available: ' + MODES.join(', ') + ')')); return false; }
+
+    // 3. Backend
     let backend = opts.backend;
     if (!backend) {
       console.log('\n' + C.bold('Translation backend') + ':');
@@ -62,7 +74,7 @@ async function runSetup(opts) {
     const b = getBackend(backend);
     if (!b) { console.error(C.red('unknown backend: ' + backend)); return false; }
 
-    // 3. Key entry for the chosen backend, if missing (keys live ONLY in
+    // 4. Key entry for the chosen backend, if missing (keys live ONLY in
     //    keys.json — shell env vars are never read)
     if (!b.available() && keys.KEY_IDS.includes(b.id)) {
       const v = opts.key || (await ask('Paste your ' + b.id + ' API key (enter to skip)', ''));
@@ -73,7 +85,7 @@ async function runSetup(opts) {
       }
     }
 
-    // 4. Input translation (beta, opt-in): prompt -> English as context
+    // 5. Input translation (beta, opt-in): prompt -> English as context
     let inputEn = typeof opts.input === 'string' ? opts.input === 'on' : getState().inputEn;
     if (opts.input === undefined && rl) {
       console.log('\n' + C.bold('Input translation') + ' ' + C.dim('(beta)') +
@@ -84,13 +96,13 @@ async function runSetup(opts) {
       inputEn = /^y(es)?$/i.test(a);
     }
 
-    // 5. Save config
-    setState({ target: lang, backend, inputEn });
-    console.log('\n' + C.green('✓') + ' saved: lang=' + lang + ' (' + getLang(lang).name + '), backend=' + backend +
-      ', input=' + (inputEn ? 'on' : 'off') +
+    // 6. Save config
+    setState({ target: lang, mode, backend, inputEn });
+    console.log('\n' + C.green('✓') + ' saved: lang=' + lang + ' (' + getLang(lang).name + '), mode=' + mode +
+      ', backend=' + backend + ', input=' + (inputEn ? 'on' : 'off') +
       (b.available() ? '' : C.red('  (no key yet — will fall back to google)')));
 
-    // 6. Live verification
+    // 7. Live verification
     process.stdout.write(C.dim('verifying… '));
     try {
       const { displayContent } = await buildDisplayContent('Setup verification: translation works.\n', {