sqs-dsh-better-input 0.1.0 → 0.2.0-rc.2

package/README.md

@@ -22,16 +22,33 @@
 
 ## ⚠️ 关于这个版本（二次开发说明）
 
-本仓库是 [`dsh-better-input`](https://github.com/DIAG5/dsh-better-input)（MIT）的**二次开发版本**，由 **sanqianshuang** 维护，专门适配 **DSH `0.1.7-rc.2`**。与原版的主要差别：
+本仓库是 [`dsh-better-input`](https://github.com/DIAG5/dsh-better-input)（MIT）的**二次开发版本**，由 **sanqianshuang** 维护。当前版本 **`0.2.0-rc.2`** —— **与它所适配的 DSH 主线同号**，一眼即可判断该装哪一版（`0.1.0` 适配的是 DSH `0.1.7-rc.2`）。与原版的主要差别：
 
 | 变更 | 说明 |
 | --- | --- |
+| 🔧 **修复「插件被 DSH 静默丢弃」（关键）** | `0.1.0` 声明的 peer 范围是 `>=0.1.7-rc.2 <0.2.0-0`，而 `0.2.0-rc.2` **不满足** `<0.2.0-0`（`0.2.0-0` 是 `0.2.0` 的最小 prerelease）。DSH 的兼容性预检因此把整个 bundle 降级丢弃——插件完全没加载，Host 服务、麦克风按钮、设置页全部消失，而 `npm run build` / `tsc` / 各构建守卫**全部照常通过**。现收紧为 `>=0.2.0-rc.2 <0.3.0-0`，并新增 `npm run check:peers` 守卫（以 DSH 自身的兼容性判定为准）防复发。 |
+| 🎙️ **语音识别改用 DSH 自带的本地识别器** | 不再使用浏览器 Web Speech API（Chrome/Edge 上那其实是**云端识别**，音频会上行给浏览器厂商）。改为把 16 kHz 单声道 PCM16 WAV 交给 dsh 的语音服务，由本地 SenseVoice 在**本机 CPU** 上转写：**离线可用、音频不出机器、无需厂商凭据**。语种随之收窄为 自动 / 中文 / 英语 / 粤语 / 日语 / 韩语。详见 [CHANGELOG](./CHANGELOG.md) `[0.2.0-rc.2]`。 |
+| 🔀 **保留「边说边出字」** | dsh 的语音服务只有整段转写（没有流式接口），所以流式由本插件自己做：录制时按静音优先、默认每 3 秒切段转写并流入输入框；**停止后用整段录音重转一次作为最终稿**再润色 —— 分段只影响预览观感，不会污染最终文本。 |
+| ⏱️ **识别条重做：贴齐输入框 + 计时 + 静音自动停止** | 原识别条是 `conversation.input.dock` 槽位里唯一没有自己做宽度约束的条目，会被 flex 父级拉满整列，**比输入框宽出一大截**；现在按 dsh 自己的 dock 约定（`--dsh-composer-card-max-width` / `--dsh-composer-side-clearance`）居中贴齐输入框。同时条上新增**已监听时长**（`mm:ss`）、**实时音量表**与**静音倒计时**：说话后静音满 10 秒（可调、可关）自动停止并转写。 |
 | 🗑️ **移除「文件输入 / 文件转 Markdown / OCR」整块** | DSH `0.1.7` 已原生支持文件拖拽上传、上传进度、文件卡片与重试（`conversation.input.attachments` / `DropOverlay` / `FileCard`），插件再挂一套 📎 文件面板与 `@` 引用芯片属于重复实现，故整体删除。 |
-| 🔧 **修复 Typert 兼容性（关键）** | `0.1.7` 收紧了 Typert 边界：`mode: 'strict'` 的 codec 必须带 **`create()` 工厂**；旧版把 schema 直接放在 `schema` 属性上，会被 `requireStrictCodec` 拒绝（报 `strict codec has no create() factory`），导致整个 entry 无法激活、插件根本不加载。现已全部改为工厂形式。 |
-| 🔧 **修复设置存储被移除的 API** | `0.1.7` 删除了 `settings.register(namespace, schema)`，改为按 profile entry 的 `SettingsForms`（带 revision CAS）。本插件的设置改为**自持 JSON 文件**，不再依赖该 API，因而不会被后续版本反复打破。 |
-| 🔧 **对齐依赖版本** | `@deepseek-ai/cordis` → `~4.0.4`、`@deepseek-ai/schemastery` → `~3.18.4`，与 `0.1.7-rc.2` 的 peer 要求一致。 |
+| 🔧 **修复 Typert 兼容性** | `0.1.7` 收紧了 Typert 边界：`mode: 'strict'` 的 codec 必须带 **`create()` 工厂**；旧版把 schema 直接放在 `schema` 属性上，会被 `requireStrictCodec` 拒绝（报 `strict codec has no create() factory`），导致整个 entry 无法激活、插件根本不加载。现已全部改为工厂形式。 |
+| 🔧 **修复设置存储被移除的 API** | `0.1.7` 删除了 `settings.register(namespace, schema)`（`0.2.0` 仍无此 API），改为按 profile entry 的 `SettingsForms`（带 revision CAS）。本插件的设置改为**自持 JSON 文件**，不再依赖该 API，因而不会被后续版本反复打破。 |
+| 🔧 **对齐依赖版本** | `@deepseek-ai/cordis` → `~4.0.4`、`@deepseek-ai/schemastery` → `~3.18.4`；全部 `@deepseek-ai/dsh-*` 类型包钉到 `0.2.0-rc.2`，peer 范围 `>=0.2.0-rc.2 <0.3.0-0`。 |
 | 🏷️ **身份与命名** | 包名 `sqs-dsh-better-input`（npm 同名）、作者 `sanqianshuang`；设置与模板数据目录为 `~/.dsh/sqs-dsh-better-input/`（与原版互不干扰，可并存安装）。 |
 
+> **从 `0.1.0` 升级**：设置项、数据目录与用户可见行为**向下兼容**，不需要迁移任何数据；本版新增的设置键（`streamingPreview` / `segmentSeconds` / `autoStopSeconds`）在读取旧 `settings.json` 时自动补齐，越界值读取即修复。
+
+> **与 DSH 自带的语音输入的关系（重要）**：`0.2.0` 增加了一个**可选且默认关闭**的 bundle
+> `@deepseek-ai/dsh-experimental-voice-input-bundle`，它带来 DSH 自己的麦克风
+> （`conversation.input.activity` 槽位，位于模型选择器与发送按钮之间）与**本地 SenseVoice 识别器**。
+>
+> 本插件的麦克风在 `conversation.input.right`（模型选择器左侧），两者**槽位不冲突、可同时开启**；
+> 但**功能上重叠**：本版起本插件也用同一个本地识别器。区别在于本插件额外提供
+> **分段流式上屏**、识别后的 **AI 润色**、**提示词优化**与**模板库** —— DSH 自带的那个转写完就直接进草稿，没有任何后处理。
+>
+> 因此：**本插件必须依赖该 bundle 提供的识别服务**（在插件管理页启用「语音输入」并完成约 239 MB 的模型准备）。
+> 未启用时本插件其余功能完全正常，只是麦克风会提示"本地识别不可用"。
+
 > 原版的 LICENSE 与版权声明已在 [LICENSE](./LICENSE) 中保留，符合 MIT 要求。
 
 ## ✨ 功能
@@ -40,7 +57,7 @@
 <tr><th align="center" width="120">模块</th><th align="left">说明</th></tr>
 <tr>
 <td align="center">🎙️<br/><b>语音输入</b></td>
-<td>点击麦克风，边说边转写，文字<strong>实时流式</strong>进入输入框。浏览器原生识别（Web Speech API），<strong>无需 API Key</strong>、不走服务器。识别因静音自行中断时会自动重启。</td>
+<td>点击麦克风，边说边转写，文字<strong>分段流式</strong>进入输入框。识别由 <strong>dsh 自带的本地识别器（SenseVoice）</strong> 在本机 CPU 完成 —— <strong>离线可用、音频不出机器、无需 API Key</strong>。停止后再用整段录音重转一次作为最终稿，然后才进入 AI 润色。</td>
 </tr>
 <tr>
 <td align="center">🤖<br/><b>AI 润色</b></td>
@@ -59,8 +76,8 @@
 <td>润色 / 优化进行中你手动改了草稿，结果<strong>不会覆盖</strong>你的编辑；失败保留原文。</td>
 </tr>
 <tr>
-<td align="center">⏱️<br/><b>录音自动停止</b></td>
-<td>可自定义单次录音上限（1–600 秒，默认 120），到点自动停止，不占麦克风。</td>
+<td align="center">⏱️<br/><b>计时与自动停止</b></td>
+<td>输入框上方的识别条实时显示<strong>已监听时长</strong>与音量表；说话后一旦静音，条上出现 <strong>倒计时</strong>（默认 10 秒），归零即自动停止、转写、润色。单次录音另有 1–120 秒硬上限兜底（可自定义）。两者都在设置页可调。</td>
 </tr>
 <tr>
 <td align="center">⚙️<br/><b>可视化设置页</b></td>
@@ -74,7 +91,7 @@
 
 ## 🚀 安装
 
-前置：[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`0.1.7-rc.2`）+ Node.js `^22.19.0 || >=24.0.0` + Chrome/Edge 浏览器（语音识别需要 Chromium 内核）。
+前置：[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`0.2.0-rc.2`）+ Node.js `^22.19.0 || >=24.0.0`，并在 profile 中启用 DSH 的语音 bundle（插件管理页的「语音输入」，首次使用需准备约 239 MB 模型）。浏览器只需支持 `getUserMedia` 与 Web Audio，不再需要 Chromium 专有的 Web Speech API。
 
 ### 方式 A：从 npm 安装（推荐）
 
@@ -115,7 +132,7 @@ npm run build
 dsh plugin --profile web add "$PWD"
 ```
 
-> `--legacy-peer-deps`：`0.1.7` 的这批类型包（dev 依赖）之间存在 npm 难以自解的 peer 链（如 `dsh-api-remotes` → `dsh-scope`）。它们只用于编译期类型、不会被打进产物（客户端 bundle 已把 `@deepseek-ai/*` 全部外置），因此放宽 peer 校验是安全的。
+> `--legacy-peer-deps`：`0.2.0-rc.2` 的这批类型包（dev 依赖）之间存在 npm 难以自解的 peer 链（如 `dsh-api-remotes` → `dsh-scope`）。它们只用于编译期类型、不会被打进产物（客户端 bundle 已把 `@deepseek-ai/*` 全部外置），因此放宽 peer 校验是安全的。
 
 ### 备选：不装依赖，写进 preset 的 `cordis.yml`
 
@@ -133,10 +150,16 @@ dsh plugin --profile web add "$PWD"
 
 1. 打开任意对话，点击输入框右侧的**麦克风按钮**
 2. 开始说话，识别文字**实时流入**输入框
+
+> 输入框上方会出现识别条：`正在聆听… 00:12` 是**已监听时长**，后面的波形是你的**实时音量**（能一眼看出麦克风是否收到声音）。
+> 说完停下后，条上出现倒计时 `10 秒后自动停止`（设置里可改，也可设为 0 关闭）；倒计时归零就自动停止并开始转写，不用再点一次按钮。你随时可以手动点**停止语音输入**提前结束。
+
 3. 再点按钮（或识别条上的**停止**）结束
 4. 检查、修改、发送
 
-> 识别完全在浏览器本地完成（Web Speech API）。Firefox / Safari 不支持时按钮自动禁用。
+> 识别在**你的机器上**完成：浏览器只负责录音，转写由 dsh 的语音服务（本地 SenseVoice）完成，音频不上行到任何云端。
+> 首次录音会唤醒识别进程（约 1 秒），之后更快。
+> 若提示"本地识别不可用"，去 设置 → **BetterInput** → 「本地识别器」查看状态并点「下载并准备模型」。
 
 ### 2. AI 润色
 
@@ -167,8 +190,12 @@ dsh plugin --profile web add "$PWD"
 | 设置项 | 说明 |
 | --- | --- |
 | 界面语言 | 插件界面文案支持中文 / 英文，跟随 DSH 界面语言切换，即时生效 |
-| 识别语言 | 留空自动跟随浏览器语言（如 `zh-CN`、`en-US`） |
-| 单次录音上限 | 1–600 秒，默认 120，到点自动停止 |
+| 本地识别器 | 显示 dsh 语音服务的识别器与就绪状态；未准备时提供「下载并准备模型」 |
+| 识别语言 | 自动检测 / 中文 / English / 粤语 / 日本語 / 한국어（旧版填写的 `zh-CN` 这类值会自动映射） |
+| 单次录音上限 | 1–120 秒，默认 120，到点自动停止 |
+| 静音自动停止 | 0 = 关闭；3–120 秒，默认 **10**。说话后静音满这么久即自动停止并转写（倒计时显示在识别条上） |
+| 边录边出字（分段预览） | 开（默认）/ 关。关闭后只在停止时转写一次 |
+| 分段长度 | 1–10 秒，默认 3。优先在静音处切分；越短上屏越快、越容易切断词 |
 | AI 润色 | 开 / 关；开启后每次语音识别结束自动润色进草稿 |
 | 润色模型 / 思考强度 / 自定义提示词 | 各自独立配置 |
 | 优化模型 / 思考强度 / 自定义提示词 | 各自独立配置 |
@@ -180,9 +207,13 @@ dsh plugin --profile web add "$PWD"
 
 ## 🧩 兼容性
 
-- DeepSeek Harness `0.1.7-rc.2`（peer 范围 `>=0.1.7-rc.2 <0.2.0-0`）
+- DeepSeek Harness `0.2.0-rc.2`（peer 范围 `>=0.2.0-rc.2 <0.3.0-0`）
 - Node.js `^22.19.0 || >=24.0.0`
-- Chromium 内核浏览器（Chrome / Edge）
+- 任意支持 `getUserMedia` + Web Audio 的现代浏览器（Chrome / Edge / Firefox；不再需要 Chromium 专有的 Web Speech API）
+- profile 中启用 DSH 语音 bundle，并完成本地识别模型准备（约 239 MB）
+
+> peer 范围必须容纳正在运行的 dsh 版本，否则 DSH 会**静默丢弃整个插件**（详见
+> [AGENTS.md](./AGENTS.md) 硬规则 1）。`npm run check:peers` 以 DSH 自身的判定逻辑校验这一点。
 
 ## 🛠️ 开发
 
@@ -190,6 +221,7 @@ dsh plugin --profile web add "$PWD"
 npm install --legacy-peer-deps
 npm run check    # 类型检查
 npm run build    # 构建 lib/（Host ESM + 浏览器 bundle）
+npm run verify   # 构建 + 三条构建后守卫（bundle / typert / peers）—— 提交前请跑
 ```
 
 改 Client 端：`npm run dev:watch` 后刷新 UI；改 Host 端：重启 `dsh web`。
@@ -200,10 +232,11 @@ npm run build    # 构建 lib/（Host ESM + 浏览器 bundle）
 - `src/identity.ts` — 包名 / 作者 / 仓库等身份信息的唯一来源
 - `src/polish/service.ts` — `BetterInputPolishService`（Typert remote）：设置读写、dsh 模型路由发现、LLM 润色与提示词优化、提示词模板存取
 - `src/polish/prompts.ts` — 内置润色 / 优化提示词与输出契约守卫
-- `src/settings/store.ts` — 插件自持设置的 JSON 存储（原子写入、损坏自愈）
+- `src/settings/store.ts` — 插件自持设置的 JSON 存储（原子写入、损坏自愈、越界值读取即修复）
+- `src/speech/` — Host 端语音入口：`service.ts`（`BetterInputSpeech`：状态 / 准备模型 / 转写）与 `wave.ts`（逐字段镜像 dsh 的 WAV 校验）
 - `src/templates/` — 提示词模板的数据模型与宿主端 JSON 存储
 - `src/about.ts` — 插件身份读取与 npm 版本检查
-- `src/client/` — 浏览器端：麦克风 / 优化按钮（`conversation.input.right`）、识别条（`conversation.input.dock`）、设置页与模板管理（`settings.section`）、`/` 模板候选源
+- `src/client/` — 浏览器端：麦克风 / 优化按钮（`conversation.input.right`）、识别条（`conversation.input.dock`）、设置页与模板管理（`settings.section`）、`/` 模板候选源；`audio-capture.ts`（采集 → 16 kHz WAV）、`native-speech.ts`（分段预览 + 终稿 + `SilenceWatch` 静音倒计时）、`styles.ts`（识别条样式，按 dsh 的 dock 宽度约定贴齐输入框）
 - `src/typert.ts` / `src/remote.ts` — Client↔Host 类型化通信契约
 
 ## 📄 License

package/lib/client/MicrophoneButton.d.ts

@@ -25,10 +25,15 @@ export type SettingsFace = {
     readonly settings: BetterInputSettings;
 };
 /**
- * The microphone button in the composer tool row. Click to start listening,
- * click again to stop. Transcripts stream into the draft in real time; when
- * polishing is enabled, the committed transcript is polished through the Host
- * LLM route and replaces the draft (unless the user edited it meanwhile).
+ * The microphone button in the composer tool row. Click to start recording,
+ * click again to stop.
+ *
+ * The recording is transcribed by dsh's own local recognizer
+ * (`remote.transcribeSpeech` → `ctx.speechToText`, the SenseVoice provider from
+ * the optional voice-input bundle) instead of the browser's Web Speech API.
+ * While recording, the text of each finished segment streams into the draft;
+ * when the user stops, one pass over the whole recording produces the
+ * authoritative transcript and AI polishing runs on that.
  */
 export declare function MicrophoneButton({ useInput, inputActions, voiceSession, remote, useSettings, t }: InputZoneLikeProps): import("react").JSX.Element;
 export interface PolishDraftOptions {
@@ -53,9 +58,15 @@ export interface PolishDraftOptions {
 }
 export declare function polishDraft(options: PolishDraftOptions): Promise<void>;
 /**
- * Only replace the draft when the user has not edited it since the transcript
- * landed. Both the transcript-at-stop and the base draft count as unchanged
- * (the user may have reverted the interim edits).
+ * Only replace the draft when the user has not edited it since our own last
+ * write. Both the text we wrote last (`draftAtStop` — the finished transcript,
+ * or the last streamed preview segment) and the untouched base draft count as
+ * unchanged.
+ *
+ * This matters more since the preview became segmented: the text on screen
+ * while recording is a *preview*, and the authoritative transcript that arrives
+ * after stopping can differ from it. Comparing against the text this session
+ * wrote is what keeps a user's mid-recording edit from being overwritten.
  */
 export declare function shouldApplyPolishResult(currentDraft: string, draftAtStop: string, baseDraft: string): boolean;
 /** Append transcript to a base draft with one space separator. */

package/lib/client/VoiceRecognitionBar.d.ts

@@ -7,8 +7,17 @@ export type RecognitionBarProps = {
     readonly t: Translate;
 };
 /**
- * The recognition status bar above the composer. Shows live state and a stop
- * button while recording; the bar renders nothing when idle.
+ * The recognition status bar above the composer.
+ *
+ * Shows the live state, a stopwatch for the current listening session, a level
+ * meter fed by the capture's own RMS, and — once the user has spoken and gone
+ * quiet — the countdown to the silence auto-stop. Renders nothing when idle.
+ *
+ * Timer and level come from `session.meter`, a store that only this component
+ * subscribes to: they change five times a second, which would otherwise
+ * re-render the microphone button (and every other session subscriber) too.
  */
 export declare function VoiceRecognitionBar({ voiceSession, t }: RecognitionBarProps): import("react").JSX.Element | null;
+/** `mm:ss`, the stopwatch shown next to the listening label. */
+export declare function formatClock(seconds: number): string;
 export {};

package/lib/client/audio-capture.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Browser microphone capture for the native dsh recognizers.
+ *
+ * dsh's speech service accepts exactly one audio format: a canonical 16 kHz
+ * mono PCM16 WAV (`@deepseek-ai/dsh-experimental-speech-to-text/wave`). This
+ * module owns that contract on the browser side — capture, resample, encode —
+ * and keeps the recorded samples so a finished recording can still be sliced
+ * (preview segments) or re-encoded (the final authoritative pass) after the
+ * microphone itself has been released.
+ *
+ * The previous implementation used the Web Speech API, which streamed results
+ * out of the browser and never owned the audio. Recognising locally means we do
+ * own the audio, hence the explicit format handling here.
+ */
+/** Why capture could not start, for localized messaging by the caller. */
+export type CaptureFailureKind = 'unavailable' | 'permission' | 'interrupted';
+/** Capture failure whose `kind` the caller maps onto a localized string. */
+export declare class CaptureError extends Error {
+    readonly kind: CaptureFailureKind;
+    constructor(kind: CaptureFailureKind, message?: string);
+}
+/**
+ * One microphone acquisition.
+ *
+ * Samples are retained at the rate the AudioContext actually runs at and are
+ * converted to 16 kHz on demand, so a browser that ignores the requested
+ * sample rate still produces a valid recording.
+ */
+export declare class MicrophoneCapture {
+    private stream;
+    private context;
+    private source;
+    private processor;
+    private sink;
+    private samples;
+    private frames;
+    private captureRate;
+    private released;
+    private disposed;
+    /** Acquire the microphone and start buffering samples. */
+    start(): Promise<void>;
+    /** Seconds captured so far, in capture-rate terms. */
+    secondsRecorded(): number;
+    /** Root-mean-square level of the trailing window, 0 when idle. */
+    level(windowSeconds?: number): number;
+    /** Largest absolute sample in a range, used to skip silent segments. */
+    peak(fromSeconds: number, toSeconds: number): number;
+    /** Copy a capture-time range as 16 kHz mono samples. */
+    slice(fromSeconds: number, toSeconds: number): Float32Array;
+    /**
+     * Release the microphone and the audio graph, keeping the samples.
+     *
+     * Called as soon as the user stops speaking so the browser indicator goes
+     * away while the final transcription is still running.
+     */
+    release(): Promise<void>;
+    /** Release the microphone and drop the buffered samples. */
+    dispose(): Promise<void>;
+    private collect;
+    private ensure;
+    private range;
+}
+/** Whether this browser can capture at all (secure context + Web Audio). */
+export declare function isCaptureSupported(): boolean;
+/**
+ * Encode 16 kHz mono samples as the canonical PCM16 WAV the Host validates.
+ *
+ * Field for field: RIFF/WAVE/`fmt `/16/PCM=1/mono/16000/byteRate 32000/
+ * blockAlign 2/bits 16/`data`, RIFF size = length - 8, data size =
+ * length - 44, an even PCM length, and at least one sample.
+ */
+export declare function encodeWave(samples: Float32Array): Uint8Array;
+/** Base64 for the JSON Remote carrier, chunked to avoid argument-count limits. */
+export declare function audioBase64(bytes: Uint8Array): string;
+/** Linear resampling; adequate for a fallback path off the 16 kHz happy path. */
+export declare function resampleLinear(samples: Float32Array, fromRate: number, toRate: number): Float32Array;

package/lib/client/native-speech.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Native speech session: dsh's local recognizers with segment-level streaming.
+ *
+ * dsh's speech service transcribes one complete recording — its own README says
+ * streaming recognition has no service method — so "text appears while you
+ * speak" is emulated here: the recording is cut into segments (preferably at
+ * silence boundaries), each segment is transcribed over the plugin's Remote and
+ * its text is appended to the draft, and when the user stops, the whole
+ * recording is transcribed once more to produce an authoritative transcript
+ * before polishing runs on it.
+ *
+ * The two-pass design is what keeps the streamed preview cheap: a mis-split
+ * segment can only make the *preview* worse, never the finished text.
+ */
+import { type BetterInputSettings } from '../config.js';
+import { CaptureError } from './audio-capture.js';
+/** How often the segment cutter inspects the recording. */
+export declare const TICK_MS = 200;
+export type NativeSpeechPhase = 'capturing' | 'finalizing';
+/** What one {@link SilenceWatch} frame reported. */
+export type SilenceReading = {
+    /** True once any frame has been loud enough — the countdown arms on this. */
+    readonly hasSpoken: boolean;
+    /** Seconds of continuous quiet since the last sound. */
+    readonly quietSeconds: number;
+    /** Seconds left before the auto-stop, `null` while no countdown runs. */
+    readonly remainingSeconds: number | null;
+    /** Whether the quiet window has fully elapsed. */
+    readonly elapsed: boolean;
+};
+/**
+ * The silence auto-stop timer: "speak, then stop talking, and the recording
+ * finishes by itself".
+ *
+ * Deliberately pure and free of Web Audio so the guard script can drive it:
+ * the whole user-visible contract is here — the countdown never runs before the
+ * first sound (`hasSpoken`), any new sound resets it to the full window, and it
+ * cannot fire at all when the window is `0` (disabled).
+ */
+export declare class SilenceWatch {
+    /** Quiet window in seconds; `0` disables the auto-stop. */
+    private readonly limitSeconds;
+    /** Frame length in seconds. */
+    private readonly tickSeconds;
+    private spoken;
+    private quiet;
+    constructor(
+    /** Quiet window in seconds; `0` disables the auto-stop. */
+    limitSeconds: number, 
+    /** Frame length in seconds. */
+    tickSeconds: number);
+    observe(sounding: boolean): SilenceReading;
+    /** Seconds left in the window, `null` while counting is not allowed. */
+    remainingSeconds(): number | null;
+}
+/**
+ * One 200 ms telemetry frame for the status bar: how long the microphone has
+ * been open, the current input level (for the level meter) and — once speech
+ * has been heard — how long is left before the silence auto-stop.
+ */
+export type SpeechTick = {
+    readonly elapsedSeconds: number;
+    /** Root-mean-square of the trailing window, ~0 while silent. */
+    readonly level: number;
+    /** Configured silence window in seconds, `0` when the auto-stop is off. */
+    readonly autoStopSeconds: number;
+    /** Seconds left before the auto-stop, `null` when no countdown is running. */
+    readonly autoStopRemainingSeconds: number | null;
+};
+/** The shape this session needs from `remote.transcribeSpeech`. */
+export type TranscribeOutcome = {
+    readonly ok: true;
+    readonly value: {
+        readonly text: string;
+    };
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly message: string;
+    };
+};
+export type TranscribeCall = (audioBase64: string, language: string, signal: AbortSignal) => Promise<TranscribeOutcome>;
+export type NativeSpeechSessionOptions = {
+    /** SenseVoice language hint; empty means automatic detection. */
+    language: string;
+    /** Cut a preview segment once this many seconds have accumulated. */
+    segmentSeconds: number;
+    /** Stream segment transcripts into the draft while the user is still speaking. */
+    streamingPreview: boolean;
+    /**
+     * Stop after this many seconds without speech once the user has spoken.
+     * `0` disables it; the hard recording ceiling still applies either way.
+     */
+    autoStopSeconds: number;
+    /** Plugin Remote call that performs one transcription on the Host. */
+    transcribe: TranscribeCall;
+    /** Growing preview text, called after every completed segment. */
+    onPreview: (text: string) => void;
+    /** Authoritative transcript after the recording stopped. */
+    onEnd: (text: string) => void;
+    /** Capture and transcription failures; the session decides whether to continue. */
+    onError: (error: Error) => void;
+    /** Phase changes, for the surrounding status UI. */
+    onPhase?: (phase: NativeSpeechPhase) => void;
+    /** Timer/level telemetry, every {@link TICK_MS}, for the status bar. */
+    onTick?: (tick: SpeechTick) => void;
+    /** Called just before the session stops itself on the silence timeout. */
+    onAutoStop?: () => void;
+};
+/** Settings face this session reads; kept structural so tests need no defaults. */
+export type SpeechSessionSettings = Pick<BetterInputSettings, 'language' | 'segmentSeconds' | 'streamingPreview' | 'autoStopSeconds'>;
+export declare function sessionOptionsFor(settings: SpeechSessionSettings, transcribe: TranscribeCall, callbacks: Pick<NativeSpeechSessionOptions, 'onPreview' | 'onEnd' | 'onError' | 'onPhase' | 'onTick' | 'onAutoStop'>): NativeSpeechSessionOptions;
+export declare class NativeSpeechSession {
+    private readonly options;
+    private readonly capture;
+    private readonly segments;
+    private timer;
+    /** Seconds already submitted as preview segments. */
+    private cursor;
+    private speechSeen;
+    /** Silence since the last cut, used by the segment cutter. */
+    private silenceSeconds;
+    /**
+     * The auto-stop timer, replaced on every `start()`.
+     *
+     * Kept separate from `silenceSeconds` on purpose: cutting a segment resets
+     * that one, and the countdown the user is watching must not jump back to the
+     * full window every time a preview segment is cut.
+     */
+    private watch;
+    /** Serialises transcriptions: the native worker is serial anyway. */
+    private queue;
+    private inFlight;
+    private stopping;
+    private aborted;
+    private ended;
+    constructor(options: NativeSpeechSessionOptions);
+    get active(): boolean;
+    /** Acquire the microphone and begin cutting preview segments. */
+    start(): Promise<void>;
+    /** Finish the recording: flush the tail, then transcribe the whole thing. */
+    stop(): void;
+    /** Discard everything: no callbacks, no transcript, microphone released. */
+    abort(): void;
+    private tick;
+    /** One telemetry frame for the status bar (timer, level, countdown). */
+    private publishTick;
+    /** Submit `[cursor, endSeconds)` as one preview segment. */
+    private cutSegment;
+    private submit;
+    private finish;
+    private clearTimer;
+}
+/** Localized by the caller: capture failures carry a kind, others their message. */
+export declare function captureFailureMessage(error: Error): {
+    kind: CaptureError['kind'] | '';
+    message: string;
+};

package/lib/client/settings-controller.d.ts

@@ -1,5 +1,5 @@
 import { type BetterInputSettingsPatch, type BetterInputSettingsView, type PolishRoute, type ReasoningEffortInfo } from '../config.js';
-import type { AboutInfoWire, UpdateCheckResultWire } from '../remote-contract.js';
+import type { AboutInfoWire, SpeechStatusWire, UpdateCheckResultWire } from '../remote-contract.js';
 import type { BetterInputRemote } from '../remote.js';
 export type SettingsStatus = 'loading' | 'ready' | 'error';
 export type SettingsSnapshot = {
@@ -31,6 +31,13 @@ export type UpdateSnapshot = {
     readonly update: UpdateCheckResultWire | null;
     readonly detail: string;
 };
+export type SpeechSnapshot = {
+    readonly status: 'loading' | 'ready' | 'error';
+    readonly view: SpeechStatusWire;
+    /** True while a prepare request is in flight, so the button can be disabled. */
+    readonly preparing: boolean;
+    readonly detail: string;
+};
 type Listener = () => void;
 /**
  * Settings read/write controller for the settings page and the microphone
@@ -46,6 +53,7 @@ export declare class SettingsController {
     private effortsSnapshot;
     private aboutSnapshot;
     private updateSnapshot;
+    private speechSnapshot;
     private readonly listeners;
     private disposed;
     constructor(remote: BetterInputRemote);
@@ -54,8 +62,19 @@ export declare class SettingsController {
     readonly getEffortsSnapshot: () => EffortsSnapshot;
     readonly getAboutSnapshot: () => AboutSnapshot;
     readonly getUpdateSnapshot: () => UpdateSnapshot;
+    readonly getSpeechSnapshot: () => SpeechSnapshot;
     readonly subscribe: (listener: Listener) => (() => void);
     refreshSettings(): Promise<void>;
+    /**
+     * Read dsh's speech service status through the plugin's Remote.
+     *
+     * Never fails the page: an unavailable or provider-less speech service is a
+     * legitimate state (`available: false`), so the page explains it instead of
+     * showing a request error.
+     */
+    refreshSpeechStatus(): Promise<void>;
+    /** Start (or join) dsh's provider-owned preparation task, then re-read status. */
+    prepareSpeech(providerId: string): Promise<boolean>;
     refreshRoutes(): Promise<void>;
     private readonly autoPopulateDefaultRoutesIfNeeded;
     update(patch: BetterInputSettingsPatch): Promise<boolean>;
@@ -77,4 +96,5 @@ export declare function useRoutesSnapshot(controller: SettingsController): Route
 export declare function useEffortsSnapshot(controller: SettingsController): EffortsSnapshot;
 export declare function useAboutSnapshot(controller: SettingsController): AboutSnapshot;
 export declare function useUpdateSnapshot(controller: SettingsController): UpdateSnapshot;
+export declare function useSpeechSnapshot(controller: SettingsController): SpeechSnapshot;
 export {};

package/lib/client/strings.d.ts

@@ -8,8 +8,14 @@ export type BetterInputStrings = {
     voiceStart: string;
     voiceStop: string;
     voiceBusy: string;
-    voiceUnavailable: string;
+    voicePermissionDenied: string;
+    voiceCaptureUnavailable: string;
     listening: string;
+    voiceCancel: string;
+    autoStopIn: string;
+    autoStopTitle: string;
+    autoStopLabel: string;
+    autoStopHint: string;
     transcribing: string;
     polishing: string;
     voiceFailed: string;
@@ -21,9 +27,20 @@ export type BetterInputStrings = {
     saveFailed: string;
     languageLabel: string;
     languageHint: string;
-    languagePlaceholder: string;
+    languageAuto: string;
+    languageCantonese: string;
+    speechStatusLabel: string;
+    speechStatusReady: string;
+    speechStatusUnavailable: string;
+    speechStatusPreparing: string;
+    speechPrepareButton: string;
+    speechPrepareBusy: string;
     recordingLimitLabel: string;
     recordingLimitHint: string;
+    streamingPreviewLabel: string;
+    streamingPreviewHint: string;
+    segmentSecondsLabel: string;
+    segmentSecondsHint: string;
     polishLabel: string;
     polishHint: string;
     on: string;

package/lib/client/styles.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Plugin-owned stylesheet, injected once into `document.head`.
+ *
+ * The status bar lives in `conversation.input.dock`, the same slot dsh's own
+ * QueueDock occupies. A dock child is stretched to the **full width of the
+ * conversation column** by the flex parent, so it must constrain itself or it
+ * draws wider than the composer card above which it sits — dsh's QueueDock does
+ * exactly this:
+ *
+ *   width: calc(100% - 2 * clearance - 2 * inset); max-width: card - 2 * inset
+ *
+ * We mirror the same two custom properties (`--dsh-composer-card-max-width`,
+ * `--dsh-composer-side-clearance`) without the extra dock inset, so the bar lines
+ * up edge to edge with the composer card in every layout, including the narrow
+ * `embedded` variant. Fallbacks keep it sane if a future dsh drops the names.
+ */
+export declare const PLUGIN_CSS = "\n.sqs-bi-bar {\n  box-sizing: border-box;\n  width: calc(100% - 2 * var(--dsh-composer-side-clearance, 16px));\n  max-width: var(--dsh-composer-card-max-width, 952px);\n  margin: 0 auto;\n  flex: none;\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  min-height: 32px;\n  padding: 3px 8px;\n  border-radius: var(--dsw-radius-lg, 12px);\n  background: var(--dsw-alias-interactive-bg-hover, rgba(128, 128, 128, 0.1));\n  color: var(--dsw-alias-label-secondary, inherit);\n  font-size: 12px;\n  line-height: 18px;\n  position: relative;\n  overflow: hidden;\n}\n.sqs-bi-bar:after {\n  content: \"\";\n  position: absolute;\n  inset: 0;\n  border: 0.5px solid var(--dsw-alias-border-l1, transparent);\n  border-radius: inherit;\n  pointer-events: none;\n}\n.sqs-bi-dot {\n  flex: none;\n  width: 8px;\n  height: 8px;\n  border-radius: 50%;\n  background: var(--dsw-alias-state-error-secondary, #e5484d);\n  animation: sqs-bi-pulse 1.2s ease-in-out infinite;\n}\n.sqs-bi-spin {\n  flex: none;\n  width: 11px;\n  height: 11px;\n  border: 1.5px solid currentColor;\n  border-top-color: transparent;\n  border-radius: 50%;\n  opacity: 0.7;\n  animation: sqs-bi-spin 0.9s linear infinite;\n}\n.sqs-bi-label {\n  flex: none;\n  max-width: 40%;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n  color: var(--dsw-alias-label-primary, inherit);\n  font-weight: 500;\n}\n.sqs-bi-detail {\n  flex: 0 1 auto;\n  min-width: 0;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n  opacity: 0.75;\n}\n.sqs-bi-clock {\n  flex: none;\n  font-variant-numeric: tabular-nums;\n  font-feature-settings: \"tnum\";\n  padding: 0 6px;\n  border-radius: 5px;\n  background: var(--dsw-alias-bg-layer-1, rgba(128, 128, 128, 0.16));\n  color: var(--dsw-alias-label-primary, inherit);\n}\n.sqs-bi-meter {\n  flex: 0 1 108px;\n  min-width: 0;\n  display: flex;\n  align-items: center;\n  gap: 2px;\n  height: 18px;\n  overflow: hidden;\n  opacity: 0.55;\n}\n.sqs-bi-meter i {\n  flex: none;\n  display: block;\n  width: 3px;\n  border-radius: 2px;\n  background: currentColor;\n  transition: height 0.12s linear;\n}\n.sqs-bi-space {\n  flex: 1 1 auto;\n  min-width: 4px;\n}\n.sqs-bi-count {\n  flex: none;\n  display: inline-flex;\n  align-items: center;\n  gap: 5px;\n  white-space: nowrap;\n  padding: 0 6px 0 4px;\n  border-radius: 5px;\n  background: var(--dsw-alias-bg-layer-1, rgba(128, 128, 128, 0.16));\n  color: var(--dsw-alias-label-primary, inherit);\n}\n.sqs-bi-count[data-urgent=\"true\"] {\n  color: var(--dsw-alias-state-error-secondary, #e5484d);\n}\n.sqs-bi-ring {\n  flex: none;\n  transform: rotate(-90deg);\n}\n.sqs-bi-ring circle {\n  fill: none;\n  stroke: currentColor;\n  stroke-width: 2;\n}\n.sqs-bi-ring .sqs-bi-ring-track {\n  opacity: 0.25;\n}\n.sqs-bi-btn {\n  flex: none;\n  appearance: none;\n  border: 0;\n  border-radius: 6px;\n  padding: 3px 10px;\n  font: inherit;\n  line-height: 16px;\n  white-space: nowrap;\n  cursor: pointer;\n  background: transparent;\n  color: inherit;\n}\n.sqs-bi-btn[data-tone=\"ghost\"]:hover {\n  background: var(--dsw-alias-bg-layer-1, rgba(128, 128, 128, 0.16));\n}\n.sqs-bi-btn[data-tone=\"danger\"] {\n  background: var(--dsw-alias-state-error-secondary, #e5484d);\n  color: #fff;\n}\n.sqs-bi-btn[data-tone=\"danger\"]:hover {\n  filter: brightness(1.06);\n}\n.sqs-bi-bar[data-state=\"error\"] .sqs-bi-label,\n.sqs-bi-bar[data-state=\"polish-error\"] .sqs-bi-label {\n  color: var(--dsw-alias-state-error-secondary, #e5484d);\n}\n@keyframes sqs-bi-pulse {\n  0%, 100% { opacity: 1; }\n  50% { opacity: 0.3; }\n}\n@keyframes sqs-bi-spin {\n  to { transform: rotate(360deg); }\n}\n";

package/lib/client/voice-session.d.ts

@@ -6,12 +6,42 @@ export type VoiceInputSessionSnapshot = {
 type Listener = () => void;
 type StopListener = () => void;
 export declare const VOICE_ERROR_DISMISS_MS = 2600;
+/**
+ * Live recording telemetry for the status bar: elapsed time, input level and
+ * the silence auto-stop countdown.
+ *
+ * Deliberately a **separate** store from the session state: it updates five
+ * times a second while recording, and the microphone button (which also
+ * subscribes to the session) has no use for it. `getSnapshot` returns a cached
+ * object so an unchanged frame does not re-render anything — required by
+ * `useSyncExternalStore`.
+ */
+export type VoiceMeterSnapshot = {
+    readonly elapsedSeconds: number;
+    readonly level: number;
+    /** Configured silence window in seconds, `0` when the auto-stop is off. */
+    readonly autoStopSeconds: number;
+    /** Seconds left before the auto-stop, `null` when no countdown is running. */
+    readonly autoStopRemainingSeconds: number | null;
+};
+export declare const EMPTY_VOICE_METER: VoiceMeterSnapshot;
+export declare class VoiceMeter {
+    private snapshot;
+    private readonly listeners;
+    readonly getSnapshot: () => VoiceMeterSnapshot;
+    readonly subscribe: (listener: Listener) => (() => void);
+    publish(next: VoiceMeterSnapshot): void;
+    reset(): void;
+    dispose(): void;
+}
 /**
  * Shared voice-input state for one session, written from scratch for
  * sqs-dsh-better-input. The microphone button and the recognition bar both
  * subscribe; the bar can request stop/cancel through the same instance.
  */
 export declare class VoiceInputSession {
+    /** Recording telemetry, subscribed to only by the recognition bar. */
+    readonly meter: VoiceMeter;
     private snapshot;
     private readonly listeners;
     private readonly stopListeners;
@@ -32,4 +62,6 @@ export declare class VoiceInputSession {
     private emit;
 }
 export declare function useVoiceInputSession(session: VoiceInputSession): VoiceInputSessionSnapshot;
+/** Subscribe to the live recording telemetry of one session. */
+export declare function useVoiceMeter(session: VoiceInputSession): VoiceMeterSnapshot;
 export {};