@lynn123411/dsh-chat-translate 1.3.2 → 1.7.0

package/lib/types/client/index.d.ts

@@ -3,10 +3,11 @@ export declare const name = "dsh-chat-translate";
 /**
  * Declared services: slots for the shared 「阅读体验」 settings page (page claim
  * plus the card registration), settingsScope for the per-namespace settings
- * mirror, and the remote + remote.credentials pair for the credentials Remote
- * namespace — the runtime withholds any service not declared here, so
- * `ctx.remote.credentials` would be undefined otherwise. The locale service is
- * optional and read through `ctx.get`, like the renderer's slots registry.
+ * mirror, the remote + remote.credentials pair for the credentials Remote
+ * namespace, and locale for the card's own dictionary. The runtime withholds any
+ * service not declared here; `locale` is declared rather than sampled because
+ * `ctx.get('locale')` at apply time can beat the locale plugin's `provide`,
+ * which silently left the card's dictionary unregistered.
  */
 export declare const inject: string[];
 interface ClientContext {
@@ -20,7 +21,7 @@ interface ClientContext {
     };
 }
 /**
- * Mount the tool-call / think-summary translation observer and the settings UI
+ * Mount the tool-call / think-chain translation observer and the settings UI
  * card inside the shared reading-settings page.
  * @param ctx - DSH browser client context.
  */
@@ -30,5 +31,6 @@ export { setupSettingsUi } from './settings/ui.tsx';
 export { NonDestructiveTranslationMount } from './translate/mount.ts';
 export { StreamDebounceViewportObserver } from './translate/viewport-observer.ts';
 export { clientCache } from './translate/client-cache.ts';
+export { rowHold } from './translate/hold.ts';
 export { lazyQueue } from './translate/lazy.ts';
 export { settingsStore } from './settings/store.ts';

package/lib/types/client/locales.d.ts

@@ -1,12 +1,59 @@
 /** Locale bundles for the chat-translate card inside the shared 「阅读体验」 page. */
 /** Dictionary namespace owned by this plugin's settings card. */
 export declare const NS = "settings.chatTranslate";
+/**
+ * Chinese copy — the single source of truth for the key set. `{name}` markers
+ * are either template params filled through `t(key, params)` / `.replace()`, or
+ * inline technical samples rendered by `withSamples` at the call site.
+ */
+export declare const zh: {
+    readonly pageNav: "阅读体验";
+    readonly title: "聊天翻译";
+    readonly masterTitle: "翻译总开关";
+    readonly enableTranslation: "启用翻译";
+    readonly masterDesc: "自动将当前会话中工具调用标题（如 {example}）翻译为中文，点击译文可原地切换原文/译文。思考正文默认不翻译，由 AI 卡片里的「显示思考链翻译按钮」控制：打开后展开的思考卡右侧出现按钮，点击才翻译。思考卡折叠起来的那一行摘要永不翻译。仅作用于当前查看的会话，回答正文永不翻译。";
+    readonly aiTitle: "AI 翻译（OpenAI 兼容协议）";
+    readonly enableAi: "启用 AI 翻译通道";
+    readonly badgeConfigured: "已配置";
+    readonly badgeUnconfigured: "未配置";
+    readonly aiFallbackNote: "未配置时 AI 通道自动跳过，由 Bing 兜底。";
+    readonly apiKeyTitle: "API Key";
+    readonly apiKeyDesc: "保存至 {home} 的 {ref}，保存后立即生效；留空保存 = 清除";
+    readonly apiKeyPlaceholderConfigured: "已配置（如需更换请直接输入）";
+    readonly save: "保存";
+    readonly saving: "保存中…";
+    readonly keySaved: "已保存到 {home}，立即生效";
+    readonly keyCleared: "已清除 API Key（AI 通道将不可用，Bing 兜底）";
+    readonly saveFailed: "保存失败：{error}";
+    readonly unknownError: "未知错误";
+    readonly baseUrlTitle: "Base URL";
+    readonly baseUrlDesc: "任意 OpenAI 兼容服务端点，如 {url1}、{url2}";
+    readonly modelTitle: "模型";
+    readonly modelDesc: "如 {model1}、{model2}；留空视为未配置";
+    readonly test: "测试 AI 通道";
+    readonly testing: "测试中…";
+    readonly testOk: "连接正常，延迟 {latency}ms";
+    readonly testFail: "失败：{error}";
+    readonly thinkEnableTitle: "显示思考链翻译按钮";
+    readonly thinkEnableDesc: "在展开的思考卡的「Think」右侧显示一个按钮，点击才翻译这条思考正文（不会自动翻译）；折叠起来的卡片没有按钮，展开后按钮才出现。翻译中按钮转圈，翻好后实心高亮，再点一下整条切回原文（正文里的点击不切换）。代码块与折叠摘要不动，Bing 通道不参与。关闭此开关会撤掉按钮并还原已翻译内容。";
+    readonly thinkTimeoutTitle: "思考链翻译超时";
+    readonly thinkTimeoutDesc: "单位毫秒，范围 500-900000。整块思考可能要几分钟，默认 600000。";
+    readonly bingTitle: "Bing 网页翻译（免 Key 兜底）";
+    readonly enableBing: "启用 Bing 翻译通道";
+    readonly bingDesc: "内置免 Key 翻译通道，无需任何配置，只翻译工具调用标题。AI 未配置或请求失败时自动兜底；思考链翻译永远不走这条通道。AI 与 Bing 同时关闭则工具调用标题也不翻译。";
+    readonly behaviorTitle: "通道行为";
+    readonly behavior1: "AI 开启且已配置 → AI 优先翻译，失败自动降级 Bing";
+    readonly behavior2: "AI 开启但未配置 + Bing 开启 → 由 Bing 翻译";
+    readonly behavior3: "AI 开启但未配置 + Bing 关闭 → 不翻译";
+    readonly behavior4: "AI 关闭 + Bing 开启 → 直接使用 Bing";
+    readonly behavior5: "AI 关闭 + Bing 关闭 → 不翻译";
+    readonly concurrencyTitle: "最大翻译并发数";
+    readonly concurrencyDesc: "控制视口滚动与多工具卡片时的最大并行请求数（范围 1-100，推荐 3）。";
+};
 /** Locale keys this plugin renders. */
-export type ChatTranslateLocaleKey = 'pageNav' | 'title';
-/** English copy. */
+export type ChatTranslateLocaleKey = keyof typeof zh;
+/** English copy; the same key set as {@link zh}. */
 export declare const en: Record<ChatTranslateLocaleKey, string>;
-/** Chinese copy. */
-export declare const zh: Record<ChatTranslateLocaleKey, string>;
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
         'settings.chatTranslate': ChatTranslateLocaleKey;

package/lib/types/client/reading-settings-page.d.ts

@@ -19,7 +19,7 @@
  * mounted but hidden, so a card's local state survives a tab switch.
  *
  * Keep this file identical across the participating plugins
- * (`dsh-smooth-stream`, `dsh-oil-sticky-prompt`, `dsh-chat-translate`).
+ * (`dsh-smooth-stream`, `dsh-chat-translate`).
  * Participants own their own card component, locale dictionaries, settings
  * namespace and Host half — only the page shell below is shared, because
  * cross-plugin value imports are forbidden by the client bundle purity gate.

package/lib/types/client/settings/store.d.ts

@@ -3,10 +3,15 @@ export interface ClientSettingsState {
     concurrency: number;
     aiEnabled: boolean;
     bingEnabled: boolean;
+    thinkEnabled: boolean;
+    thinkTimeoutMs: number;
     baseUrl: string;
     model: string;
     aiConfigured: boolean;
 }
+/** 思考链翻译超时的取值范围，与宿主半边保持一致。 */
+export declare const THINK_TIMEOUT_MIN = 500;
+export declare const THINK_TIMEOUT_MAX = 900000;
 /** Settings namespace + credentials ref, mirroring the host constants. */
 export declare const SETTINGS_NAMESPACE = "dsh-chat-translate";
 export declare const TRANSLATE_API_KEY_REF = "TRANSLATE_API_KEY";
@@ -16,6 +21,14 @@ export declare const TRANSLATE_API_KEY_REF = "TRANSLATE_API_KEY";
  * `credentials` Remote namespace. Keeping them structural keeps this bundle
  * free of host-service imports and lets tests inject fakes.
  */
+export type SettingsPathOpLike = {
+    op: 'set';
+    path: string[];
+    value: unknown;
+} | {
+    op: 'unset';
+    path: string[];
+};
 export interface SettingsScopeLike {
     getSnapshot(): {
         status: string;
@@ -23,8 +36,7 @@ export interface SettingsScopeLike {
         writable: boolean;
     };
     subscribe(listener: () => void): () => void;
-    set(field: string, value: unknown): Promise<unknown>;
-    unset(field: string): Promise<unknown>;
+    mutate(ops: readonly SettingsPathOpLike[]): Promise<unknown>;
 }
 /** Shape of every DSH client Remote call: {ok, value} / {ok, error} wrapper. */
 export type RemoteResult<T> = {
@@ -52,8 +64,9 @@ export interface CredentialsRemoteLike {
  *
  * Since 1.2 there is no localStorage overlay and no custom config HTTP
  * endpoint: the store derives from the bound `settingsScope` (which mirrors
- * the host document and folds every write answer back), and writes go
- * through `scope.set` — serialized, revision-checked, persisted by DSH.
+ * the host document and folds every write answer back), and each debounced
+ * flush commits its touched fields as one `scope.mutate` batch — one
+ * revision fence, serialized and persisted by DSH.
  * Without a bound scope (e.g. non-loopback pages, unit tests) it degrades to
  * an in-memory store with the same semantics DSH itself uses for memory
  * persistence.

package/lib/types/client/settings/ui.d.ts

@@ -1,13 +1,15 @@
 import * as React from 'react';
-import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import { NS } from '../locales.ts';
 /**
  * Chat-translate's card inside the shared 「阅读体验」 settings page. The card
  * keeps its own chrome (title rows, switches, credential form); the shared page
  * only stacks the participants' cards.
- * @param _props - renderer-bound seat of the `reading.settings.item` slot.
+ * @param props - renderer-bound seat of the `reading.settings.item` slot plus
+ * the `t` seat its `locale: NS` registration injects.
  * @returns The card element.
  */
-export declare function TidySettingsPanel(_props: PropsRuntime<'reading.settings.item'>): React.ReactElement;
+export declare function TidySettingsPanel(props: PropsRuntime<'reading.settings.item'> & PropsLocale<typeof NS>): React.ReactElement;
 /**
  * Bind the settings store to DSH's native settings/credentials services and
  * join the shared 「阅读体验」 settings page: whichever participant activates

package/lib/types/client/translate/api.d.ts

@@ -8,7 +8,20 @@ export interface TranslateBatchOptions {
     signal?: AbortSignal;
     timeoutMs?: number;
 }
+/** 思考正文一个块的翻译结果，与请求的块列表按下标对齐。 */
+export interface ThinkBlockResult {
+    original: string;
+    translated: string;
+    ok: boolean;
+    cached: boolean;
+    channel: string;
+}
 export declare function requestTranslateBatch(texts: string[], options?: TranslateBatchOptions): Promise<TranslateItemResult[]>;
+/**
+ * 请求翻译思考正文的块。宿主侧按输入上限打包、串行发送，客户端超时交给
+ * 宿主（思考块可能要几分钟），这里不设自己的截止时间。
+ */
+export declare function requestTranslateThink(blocks: string[]): Promise<ThinkBlockResult[]>;
 export declare function testServerChannel(channel: string): Promise<{
     ok: boolean;
     latencyMs: number;

package/lib/types/client/translate/client-cache.d.ts

@@ -2,7 +2,9 @@ export declare class ClientCache {
     private memCache;
     private dirty;
     private saveTimer;
-    constructor();
+    private storageKey;
+    private maxEntries;
+    constructor(storageKey?: string, maxEntries?: number);
     private load;
     get(text: string): string | undefined;
     set(text: string, translated: string): void;
@@ -11,4 +13,7 @@ export declare class ClientCache {
     clear(): void;
     size(): number;
 }
+/** 工具标题译文缓存。 */
 export declare const clientCache: ClientCache;
+/** 思考正文译文缓存：独立存储键与容量，不挤占工具标题的缓存。 */
+export declare const thinkClientCache: ClientCache;

package/lib/types/client/translate/hold.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 扣留队列：工具调用 / 命令行在标题译文就绪之前整行不可见，原文不落屏。
+ *
+ * 扣留按阅读顺序放行。队首那一行还在等译文时，排在它后面的每个流程条目整条不可见
+ * 并挂上 {@link REVEAL_HOLD_ATTRIBUTE}：标记让 smooth-stream 不再推进条目里的逐字
+ * 揭示（积压原样留着），`display: none` 让条目里的任何东西都上不了屏——不翻译的行、
+ * 宿主直接落盘的文本、已经逐字reveal了一半的正文，都得等轮到它。队首一就绪，它先出现
+ * （译文挂载 + 整行对数淡入），再轮到下一条。没有这层顺序，靠后的行会先占住位置，等
+ * 靠前的行出现时再被顶下去。
+ *
+ * 藏法是整条 `display: none`，不是「占着位置但透明」：条目一旦进入布局就带上了
+ * 会话流的 16px 兄弟间距（`.column > :not(:empty) ~ :not(:empty)`），积压几行就是
+ * 屏幕底部一条几十像素的空白，且这空白要等轮到它才被填上。移除整个盒子，等待期间
+ * 的占位就是零。
+ *
+ * 放行是一步一行：队首解锁时排在它后面的行可能已经积了一长串（工具行、思考行都在
+ * 继续产出），一次全放会让整屏同时淡入。所以解锁的行先进 {@link RowHoldQueue} 的
+ * 放行队列，由定时器逐行吐出，待放行越多步长越短（见 RELEASE_BUDGET_MS），既不
+ * 突兀也不会让长队拖住屏幕。
+ *
+ * 等待有上限：超过 HOLD_DEADLINE_MS 仍无译文就放行原文，译文之后到达时再原地挂载。
+ */
+/** 一行最多被扣留多久，到点放行原文。 */
+export declare const HOLD_DEADLINE_MS = 5000;
+/**
+ * 挂起标记：打在会话流条目（`[data-chat-flow-key]`）上，表示「这条还没轮到上屏」。
+ * smooth-stream 读它来暂停条目内的揭示引擎，字面量在两边各写一份
+ * （`src/client/revealHold.ts`）。
+ */
+export declare const REVEAL_HOLD_ATTRIBUTE = "data-dsh-reveal-hold";
+export interface RowHoldEntry {
+    /** 会话流条目：扣留的边界，挂在它上面的标记决定后面哪些条目被挂起。 */
+    item: HTMLElement;
+    /** 被翻译的摘要 span；React 可能在扣留期间换掉它。工具行本身不翻译时为 null。 */
+    span: HTMLElement | null;
+    /** 行根（`[data-variant]` 卡片）。它只用来辨认「同一行」是否已经入队。 */
+    root: HTMLElement;
+    /** 当前正在等待译文的原文。 */
+    text: string;
+    /** 拿到的译文；null 表示这一行确定没有译文可等（失败 / 超时）。 */
+    translation: string | null;
+    /** 译文（或失败判定）已就绪，只等排到队首。没有译文可等的行入场即就绪。 */
+    ready: boolean;
+    timer: number | null;
+}
+declare class RowHoldQueue {
+    /** 按阅读顺序排列的扣留行。 */
+    private entries;
+    /** 结果回来时只知道 span，不知道条目，所以另留一份索引。 */
+    private bySpan;
+    /** 当前挂起着的流程条目 → 隐藏之前它自己的行内 display。 */
+    private marked;
+    /** 已轮到上屏、正在按阅读顺序逐行吐出的条目。 */
+    private releasing;
+    private releaseTimer;
+    /**
+     * 隐藏整行并启动放行上限。幂等：同一行在途请求期间文本又变了时只更新文本并
+     * 重新等待，不重置不可见窗口。
+     */
+    hold(span: HTMLElement, root: HTMLElement, text: string): void;
+    /** 该文本所属行的扣留状态；返回 undefined 表示没有扣留。 */
+    stateFor(span: HTMLElement): RowHoldEntry | undefined;
+    /**
+     * 译文（或失败判定）就绪。真正上屏要等它排到队首：入队顺序就是阅读顺序。
+     * @param span - 等待中的摘要 span。
+     * @param translation - 译文；null 表示这一行没有译文可等，放行原文。
+     */
+    ready(span: HTMLElement, translation: string | null): void;
+    /**
+     * 扣留期间新出现的会话流内容：排在队首后面的一律先不上屏。
+     *
+     * 藏的是整个流程条目，不是某一张卡片：条目里的东西有的归揭示引擎管（回答正文、
+     * 思考正文、译文，标记会让它们只积压不推进），有的宿主直接落盘（工具卡片正文、
+     * 不翻译的读写文件行），只冻结揭示挡不住后者。整条藏起来两种都覆盖，而且条目
+     * 本身在 React 重渲染里不会被换掉，卡片被换掉也照样藏得住。
+     * @param node - 这次变更里新增的元素，或其祖先所在的那一片子树。
+     */
+    noteAppended(node: HTMLElement): void;
+    /** 挂起一个条目：整条不可见，并且不推进它里面的揭示。 */
+    private holdItem;
+    private follows;
+    /**
+     * 藏住整条流程条目。用 `display: none` 而不是 `opacity`/`visibility`：条目内部的
+     * 节点可以显式声明 `visibility: visible`（系统提示卡片就是这么自管的），那样会从
+     * 隐藏的祖先里逃出来；而且只要条目还参与布局，会话流的 16px 兄弟间距就还在——每
+     * 一条被扣留的行都会在屏幕底部留一段等宽的空白。整个盒子移除，等待期间占位为零，
+     * 轮到它时再连同入场淡入一起撑开。
+     */
+    private mark;
+    /** 解除挂起；`animate` 为真时补一段行入场淡入，避免内容一下子蹦出来。 */
+    private unmark;
+    /**
+     * 排进放行队列。按阅读顺序插入，所以逐行吐出的顺序就是行在流里的顺序。
+     */
+    private enqueueRelease;
+    /**
+     * 取出下一个还连在文档里的待放行条目。
+     * @returns 待放行条目；队列空或只剩已断开节点时返回 undefined。
+     */
+    private takeRelease;
+    /** 队伍越长步长越短：几行时让淡入跑完，几十行时也不至于让读者干等。 */
+    private releaseStepMs;
+    /**
+     * 逐行放行：每一步只让一行出现，然后按当时的队伍长度安排下一步。队首（刚解锁
+     * 的那一行）走的是同步的那一步，所以它不会比译文晚一帧上屏。
+     */
+    private pumpRelease;
+    /** 丢掉逐行放行的进度（关闭、换会话、断开观察器时用）。 */
+    private clearReleases;
+    /** 按阅读顺序入队：入队顺序就是上屏顺序。 */
+    private insert;
+    /** 译文（或超时判定）落地，交给队首判定。 */
+    private readyEntry;
+    /**
+     * 按顺序解锁：队首就绪就挂译文并把它交给逐行放行，然后看新的队首。译文在条目
+     * 仍是 `display: none` 时挂上，所以屏幕上不会出现完整中文被画一帧再被截断的闪烁；
+     * 真正撑开这一行由 {@link pumpRelease} 执行。
+     */
+    private drain;
+    /**
+     * 让挂起标记与队首对齐：队首自己以及排在它后面的每个流程条目都藏起来，其余
+     * 交给逐行放行。放行让队首前移时，之前被它挡住的条目就在这一步进入放行队列。
+     *
+     * 没有「立即恢复」的旁路：放行一律排队逐行吐出，所以放行途中新到的队首不会把
+     * 正在等的那些行一次性抖出来（`releaseAll` 是唯一的立即路径）。
+     */
+    private sync;
+    /**
+     * 全部放行：断开观察器与关闭总开关时用。批量放行不做入场动画，也不排队，
+     * 否则整屏会一起闪一遍、或者留下一个跑不完的定时器。
+     */
+    releaseAll(): void;
+}
+export declare const rowHold: RowHoldQueue;
+export {};

package/lib/types/client/translate/lazy.d.ts

@@ -4,7 +4,15 @@ declare class LazyTranslationQueue {
     constructor();
     setEnabled(enabled: boolean): void;
     observe(element: HTMLElement, text: string, immediate?: boolean): void;
+    /**
+     * 扣留行的取文本路径。命中缓存时同步就绪（没有需要遮住的等待），否则走无可见
+     * 性判定的防抖批次；译文挂载由扣留队列在轮到这一行时执行，好让逐字与对数淡入
+     * 从它真正上屏的那一刻开始。
+     */
+    observeHeld(element: HTMLElement, text: string): void;
     private handleVisibleBatch;
+    /** 元素当前承载的原文是否仍是这次结果对应的那一份。 */
+    private stillMatches;
     private applyTranslation;
     disconnect(): void;
 }

package/lib/types/client/translate/mount.d.ts

@@ -11,6 +11,8 @@
 export declare const CLASS_ORIGINAL_HIDDEN = "dsh-tidy-original-hidden";
 export declare const CLASS_ORIGINAL_SHOWN = "dsh-tidy-original-shown";
 export declare const CLASS_TRANSLATED_BLOCK = "dsh-tidy-translated-block";
+/** 混合块里的行内片段容器（我们自建、自拆）。 */
+export declare const CLASS_RUN = "dsh-tidy-run";
 export interface MountOptions {
     originalText?: string;
     interactive?: boolean;
@@ -20,6 +22,26 @@ export declare class NonDestructiveTranslationMount {
      * Mounts a translated string onto the target element non-destructively.
      */
     static mount(element: HTMLElement, translated: string, options?: MountOptions): void;
+    /**
+     * 把一段连续的行内节点包进自建容器后挂载译文。
+     *
+     * 混合块（列表项文字 + 子列表 / 代码块）里的行内片段没有自己的元素，
+     * 只能先包一层再走同一条非侵入式挂载；嵌套的块级子节点留在容器之外，
+     * 排版原样保留。
+     * @returns 自建容器；节点不再相邻或没有共同父节点时返回 null。
+     */
+    static mountRun(nodes: Node[], translated: string, options?: MountOptions): HTMLElement | null;
+    /** 还原行内片段并撤掉自建容器。 */
+    static unmountRun(run: HTMLElement): void;
+    /** 还原一个作用域内我们挂过的全部译文（元素单位与行内片段都算）。 */
+    static restore(scope: ParentNode): void;
+    /** 我们自己的挂载容器与还原容器，观察器必须跳过它们。 */
+    static isOwnNode(element: HTMLElement): boolean;
+    /**
+     * 把一个作用域里的全部挂载译文一起翻面。思考链只由卡片标题右侧的按钮调用
+     * 它，正文里的点击不再改变原文与译文。
+     */
+    static toggleGroup(scope: ParentNode, showOriginal: boolean): void;
     /**
      * Unmounts translation and restores original DOM nodes completely.
      */

package/lib/types/client/translate/observer.d.ts

@@ -3,9 +3,35 @@ export declare class ChatTranslateObserver {
     private rootElement;
     private rootCheckTimer;
     private isEnabled;
+    /** 设置里的思考链开关；与总开关一起决定按钮是否存在。 */
+    private thinkEnabled;
+    /**
+     * 至少一条工具标题通道可用（AI 配置齐全或 Bing 打开）。两条都关时没有
+     * 可等的译文，扣留立即失去意义。
+     */
+    private channelsAvailable;
+    /**
+     * 每个会话流已经见过的末尾行。追加在它之后的行算「新出现」，插在它之前
+     * 的行（历史回放、加载更早）不算。
+     */
+    private flowTail;
+    /** 初始扫描期间不扣留：那时看到的行都是历史。 */
+    private suppressHold;
     constructor();
     setEnabled(enabled: boolean): void;
     private restoreOriginals;
+    /**
+     * 设置里的思考链开关：关掉就撤掉所有翻译按钮并还原思考卡里的译文，工具标题
+     * 译文不动。
+     */
+    setThinkEnabled(enabled: boolean): void;
+    /**
+     * AI 通道的可用性（通道开关打开且 Key / Base URL / 模型齐全）。不可用时同样
+     * 不注入按钮：思考链翻译只能走这条通道。
+     */
+    setThinkConfigured(configured: boolean): void;
+    /** 工具标题通道可用性：两条都关时不扣留，也没有译文可等。 */
+    setChannelsAvailable(available: boolean): void;
     /**
      * The active session's scroll container. Only the currently-viewed session
      * is translated; switching sessions replaces this subtree and the observer
@@ -17,9 +43,40 @@ export declare class ChatTranslateObserver {
     private scheduleRootCheck;
     private restart;
     private handleMutations;
+    /**
+     * 扣留期间新出现的会话流内容（下一个回答节点、下一个工具行）同样要先挂起：
+     * 它们排在还没上屏的行后面，先出现就会占住那一行的位置。
+     */
+    private noteRevealHold;
+    /**
+     * 变更发生在我们移进隐藏容器的原文里时，返回挂载了译文的那个元素。React
+     * 就地改写它自己创建的文本节点，所以「原文变了」只能从这条路径看到。
+     */
+    private mountedOwner;
+    /**
+     * 已挂载行的隐藏原文被上游改写了（ask_user 计数、失败摘要、todo 计数）：
+     * 命中缓存就原地换译文，否则请求新译文后原地换。行始终可见，不出现英文。
+     */
+    private handleOriginalTextChange;
+    /**
+     * 该行是否该被扣留：当前 turn 仍在产出、这行是新追加到流末尾的、不是后缀、
+     * 通道可用，且不在初始扫描期间。判断顺带把每个会话流见过的末尾行推进到
+     * 最新，供后续判定使用；第一次见到的会话流先按历史处理。
+     */
+    private shouldHold;
     private scanContainer;
     private scanNode;
+    /**
+     * 交给思考正文翻译控制器：命中节点所在的卡片，以及它下面（或它就是）的
+     * 全部思考卡片。
+     */
+    private scanThink;
     private processSpan;
+    /**
+     * 扣留行的取文本路径：命中缓存立即就绪，其余交给懒加载队列。译文真正挂载要等
+     * 队列轮到它——提前挂上去会把逐字与对数淡入在被挂起期间跑完。
+     */
+    private translateHeld;
     disconnect(): void;
 }
 export declare const chatTranslateObserver: ChatTranslateObserver;

package/lib/types/client/translate/think-button.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 思考卡标题右侧的翻译按钮。
+ *
+ * 三态：idle（描边「译」字，点击开始翻译）、working（圈内圆环旋转，点击忽略）、
+ * translated（实心高亮，点击整条切回原文）。样式只在首次使用注入一次，配色沿用
+ * 内核的 dsw-* 变量；系统开启「减弱动态效果」时圆环不旋转。
+ */
+export type ThinkButtonState = 'idle' | 'working' | 'translated';
+export declare const THINK_BUTTON_CLASS = "dsh-tidy-think-button";
+/** 注入按钮样式，重复调用无副作用。 */
+export declare function ensureThinkButtonStyles(): void;
+export interface ThinkButtonHandle {
+    element: HTMLButtonElement;
+    getState(): ThinkButtonState;
+    setState(state: ThinkButtonState): void;
+    setDisabled(disabled: boolean, reason: string): void;
+}
+/** 创建一个按钮实例；onActivate 由调用方决定点下去做什么。 */
+export declare function createThinkButton(onActivate: () => void): ThinkButtonHandle;

package/lib/types/client/translate/think.d.ts

@@ -0,0 +1,55 @@
+/** 稳定的翻译单位：一块级元素，或一段行内节点。 */
+export interface ThinkUnit {
+    element?: HTMLElement;
+    nodes?: Node[];
+    text: string;
+    anchor: Node;
+}
+/** 收集正文里全部可翻译单位，跳过已挂译文的部分与代码块。 */
+export declare function collectThinkUnits(body: HTMLElement): ThinkUnit[];
+/** 按估算 token 把单位切成若干次客户端请求，顺序不变。 */
+export declare function chunkUnits(units: ThinkUnit[], maxTokens?: number): ThinkUnit[][];
+declare class ThinkTranslateController {
+    /** 总开关与设置里的思考链开关同时打开。 */
+    private enabled;
+    /** AI 通道开关打开且已配置；缺任何一条都不注入按钮。 */
+    private configured;
+    private states;
+    private syncTimers;
+    /** 只处理当前会话的容器；由观察器在会话切换时更新。 */
+    private scope;
+    /** 观察器把当前会话的根交给控制器，插入按钮时只看这一棵子树。 */
+    setScope(scope: ParentNode): void;
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    setConfigured(configured: boolean): void;
+    /** 按钮是否可以存在：两个开关与 AI 通道配置缺一不可。 */
+    private usable;
+    private applyVisibility;
+    /** 扫描当前会话里的全部思考卡（开关、配置或会话变化后调用）。 */
+    syncAll(): void;
+    /** 防抖后同步一张卡片。 */
+    syncCard(card: HTMLElement): void;
+    private stateFor;
+    private runSync;
+    private updateDisabled;
+    private ensureButton;
+    /** 折叠或停用时撤掉按钮，卡片的翻译状态不变。 */
+    private removeButton;
+    /** 插件停用：撤掉按钮并还原这张卡片上的全部译文。 */
+    private discardCard;
+    /** 卡片当前显示的是译文（至少有一个译文块可见）。 */
+    private isShowingTranslation;
+    private bodyOf;
+    /** 展开时若整条都命中缓存，直接显示中文，不点按钮也不发请求。 */
+    private showCachedWhenComplete;
+    /** 按钮被点击；按钮只在展开的卡片上存在。 */
+    private activate;
+    /** 翻译这张卡片的全部单位：命中缓存的先挂上，其余按块请求。 */
+    private translateCard;
+    private translateUnits;
+    /** 把译文挂到单位上；期间文本或节点已经变动的单位直接放弃（结果已进缓存）。 */
+    private applyUnit;
+}
+export declare const thinkTranslator: ThinkTranslateController;
+export {};

package/lib/types/client/translate/viewport-observer.d.ts

@@ -5,6 +5,12 @@
  * 1. True IntersectionObserver for viewport visibility detection (rootMargin: '150px 0px').
  * 2. Typing/streaming debounce (default 400ms) to avoid translating partial streaming sentences.
  * 3. Batch queuing to group multiple visible elements into efficient batch requests.
+ *
+ * 扣留行（{@link observeHeld}）复用同一条防抖与批次，只跳过可见性判定：
+ * 行此刻是隐藏的，等不到 IntersectionObserver 回调。注册时再兜一道：
+ * 任何落在被挂起条目（`data-dsh-reveal-hold`）里的元素同样直接进批次——
+ * 整条 `display: none` 的条目永远不 intersecting，包括那些已经过了扣留队列、
+ * 正排在逐行放行队伍里的行。
  */
 export interface ViewportObserverOptions {
     rootMargin?: string;
@@ -20,7 +26,7 @@ export declare class StreamDebounceViewportObserver {
      * Pending per-element streaming debounce timers. A Map (not a WeakMap)
      * because disconnect() must enumerate and clear every pending timer: a
      * WeakMap cannot be iterated, so a debounce armed just before the switch was
-     * turned off would still fire registerForViewport() afterwards.
+     * turned off would still fire register() afterwards.
      */
     private streamingTimers;
     private pendingQueue;
@@ -33,7 +39,13 @@ export declare class StreamDebounceViewportObserver {
      * If streaming updates characterData repeatedly within debounceMs, the timer resets.
      */
     observeWithDebounce(element: HTMLElement, text: string, immediate?: boolean): void;
-    private registerForViewport;
+    /**
+     * 扣留行的取文本路径：保留同一套流式防抖，跳过可见性判定——行此刻是
+     * 隐藏的（永远不进入视口），放行由扣留控制器负责。
+     */
+    observeHeld(element: HTMLElement, text: string): void;
+    private armDebounce;
+    private register;
     private enqueueBatch;
     private flushQueue;
     unobserve(element: HTMLElement): void;

package/lib/types/index.d.ts

@@ -1,30 +1,23 @@
+import type { HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
+import { type SettingsMigrationTarget } from './server/config.ts';
 /** Stable Cordis loader name. */
 export declare const name = "dsh-chat-translate";
 /**
- * Hard dependencies: webServer serves the translation proxy; settings and
- * credentials are the DSH-owned config/secret surfaces this plugin now rides
- * on (no standalone config file since 1.2).
+ * Hard dependencies: settings and credentials are the DSH-owned config/secret
+ * surfaces this plugin rides on (no standalone config file since 1.2). The
+ * translation routes register through the connection service when a Web
+ * carrier composes it, so apply takes that service through ctx.inject and the
+ * plugin still loads in compositions without one.
  */
 export declare const inject: string[];
 interface HostContext {
-    webServer?: {
-        register(route: {
-            kind: 'prefix' | 'exact';
-            path: string;
-            handler: (req: any, res: any) => Promise<void> | void;
-        }): () => void;
-    };
-    settings: {
+    connection: HostConnectionHandle;
+    settings: SettingsMigrationTarget & {
         register(ns: string, schema: unknown): {
             get(): any;
             watch(listener: (config: any) => void): () => void;
             update(patch: Record<string, unknown>): Promise<unknown>;
         };
-        describe(): Array<{
-            ns: string;
-            user?: unknown;
-        }>;
-        update(ns: string, patch: Record<string, unknown>): Promise<unknown>;
     };
     credentials: {
         resolve(ref: string): Promise<{
@@ -40,8 +33,8 @@ interface HostContext {
         unset(ref: string): Promise<void>;
     };
     on(event: string, listener: (...args: any[]) => void): () => void;
-    effect(factory: () => void | (() => void), label: string): void;
-    get?(serviceName: string): any;
+    /** Optional-service injection: the callback runs once connection is present. */
+    inject(names: string[], callback: (ctx: HostContext) => void | (() => void)): void;
 }
 /** Mount the host half; provides the translation proxy and rides DSH config. */
 export declare function apply(ctx: HostContext): void;