dsh-plugin-lookatstudy 0.12.5 → 0.13.1

package/lib/client.js

@@ -249,11 +249,18 @@ window.__ModuleLoader__.load({
 /* inline error text (write-action failures) */
 .lks-propcard-err{color:var(--dsw-alias-state-error-primary);font-size:12px;margin-top:6px;flex:none}
 
+/* read-aloud bar (teach pane, under the view tabs) */
+.lks-readbar{display:flex;align-items:center;gap:6px;margin:0 0 8px;min-height:26px}
+.lks-readbar .lks-btn{display:inline-flex;align-items:center;gap:4px}
+.lks-readbar-cur{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:12.5px;color:var(--dsw-alias-label-secondary);border-left:2px solid var(--dsw-alias-state-info-primary,var(--dsw-alias-business-primary));padding-left:8px}
+.lks-readbar-notice{flex:none;font-size:11.5px;color:var(--dsw-alias-label-tertiary)}
+
 /* settings section (settings.section entry inside the host settings shell) */
 .lks-settings{display:flex;flex-direction:column;gap:18px;font-family:var(--dsw-font-family);color:var(--dsw-alias-label-primary)}
 .lks-set-row h3{margin:0 0 4px;font-size:15px;font-weight:600}
 .lks-set-hint{margin:0 0 10px;font-size:13px;color:var(--dsw-alias-label-secondary)}
 .lks-set-state{margin-left:10px;font-size:13px;color:var(--dsw-alias-label-secondary)}
+.lks-set-select{font:inherit;font-size:13px;color:var(--dsw-alias-label-primary);background:var(--dsw-alias-bg-layer-1);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:5px 8px;max-width:100%}
 .lks-set-stats{margin:0;padding-left:18px;font-size:14px;line-height:1.9}
 .lks-set-path{font-family:var(--dsw-font-markdown-code);font-size:12.5px;background:var(--dsw-alias-bg-layer-3);border-radius:6px;padding:3px 8px;word-break:break-all}
 
@@ -730,7 +737,69 @@ window.__ModuleLoader__.load({
 				});
 				this.refresh();
 			}
+			/** Synthesize one speakable chunk to MP3 (host-side Edge TTS, cache-first). */
+			async tts(text, voice) {
+				const body = await fetchJson("/lookatstudy/api/tts", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({
+						text,
+						voice
+					})
+				});
+				const raw = body.dataBase64;
+				if (body.ok !== true || typeof raw !== "string") throw new Error("tts response missing audio payload");
+				const bin = atob(raw);
+				const bytes = new Uint8Array(bin.length);
+				for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+				return bytes.buffer;
+			}
 		};
+		/** The voices the dashboard route accepts (same allowlist server-side). */
+		const TTS_VOICES = [
+			{
+				id: "zh-CN-XiaoxiaoNeural",
+				labelKey: "voice.xiaoxiao"
+			},
+			{
+				id: "zh-CN-YunxiNeural",
+				labelKey: "voice.yunxi"
+			},
+			{
+				id: "zh-CN-YunyangNeural",
+				labelKey: "voice.yunyang"
+			},
+			{
+				id: "zh-CN-XiaoyiNeural",
+				labelKey: "voice.xiaoyi"
+			},
+			{
+				id: "en-US-AriaNeural",
+				labelKey: "voice.aria"
+			},
+			{
+				id: "en-US-GuyNeural",
+				labelKey: "voice.guy"
+			}
+		];
+		const TTS_VOICE_KEY = "dsh-plugin-lookatstudy:tts-voice";
+		/** Narrow a stored voice id to the allowlist; anything else falls back to 晓晓. Pure. */
+		function normalizeStoredVoice(raw) {
+			return TTS_VOICES.some((v) => v.id === raw) ? raw : TTS_VOICES[0].id;
+		}
+		/** The selected read-aloud voice (browser-local preference; host state untouched). */
+		function storedTtsVoice() {
+			try {
+				return normalizeStoredVoice(typeof localStorage === "undefined" ? null : localStorage.getItem(TTS_VOICE_KEY));
+			} catch {
+				return TTS_VOICES[0].id;
+			}
+		}
+		function storeTtsVoice(id) {
+			try {
+				localStorage.setItem(TTS_VOICE_KEY, normalizeStoredVoice(id));
+			} catch {}
+		}
 		/** The one shared store instance backing every study seat component. */
 		const studyStore = new StudyStore();
 		/** React binding: live snapshot plus the write actions. */
@@ -1585,6 +1654,12 @@ window.__ModuleLoader__.load({
 			"rail.delete.title.confirm": "再点一次确认删除(含全部进度与笔记)。反悔前可先在设置页备份状态文件",
 			"note.delete": "删除本条笔记",
 			"note.delete.confirm": "确认删除?",
+			"read.play": "朗读本课",
+			"read.stop": "停止朗读",
+			"read.pause": "暂停朗读",
+			"read.resume": "继续朗读",
+			"read.engine.system": "网络合成不可用，已切换为系统语音",
+			"read.unavailable": "朗读不可用",
 			"rail.section.collapse": "折叠本章节",
 			"rail.section.expand": "展开本章节({count} 课时)",
 			"rail.section.count": "{count} 课",
@@ -1635,6 +1710,14 @@ window.__ModuleLoader__.load({
 			"settings.mode": "教学风格",
 			"settings.mode.hint": "导师的讲解风格;也可在学习页随时切换",
 			"settings.studyMode": "学习模式",
+			"settings.voice": "朗读语音",
+			"settings.voice.hint": "「朗读本课」使用的神经网络声音（浏览器本地偏好）",
+			"voice.xiaoxiao": "晓晓 · 中文女声",
+			"voice.yunxi": "云希 · 中文男声",
+			"voice.yunyang": "云扬 · 中文男声（新闻）",
+			"voice.xiaoyi": "晓伊 · 中文女声（轻快）",
+			"voice.aria": "Aria · English female",
+			"voice.guy": "Guy · English male",
 			"settings.studyMode.hint": "开启后注册 study_* 工具并载入导师人格;进度与笔记始终保留",
 			"settings.on": "状态：已开启",
 			"settings.off": "状态：已关闭",
@@ -1707,6 +1790,12 @@ window.__ModuleLoader__.load({
 			"rail.delete.title.confirm": "Click again to confirm (all progress and notes included). Back up via the state file in Settings first",
 			"note.delete": "Delete this note",
 			"note.delete.confirm": "Delete?",
+			"read.play": "Read aloud",
+			"read.stop": "Stop reading",
+			"read.pause": "Pause reading",
+			"read.resume": "Resume reading",
+			"read.engine.system": "Network synthesis unavailable — switched to the system voice",
+			"read.unavailable": "Read-aloud unavailable",
 			"rail.section.collapse": "Collapse this section",
 			"rail.section.expand": "Expand this section ({count} lessons)",
 			"rail.section.count": "{count} lessons",
@@ -1757,6 +1846,14 @@ window.__ModuleLoader__.load({
 			"settings.mode": "Teaching style",
 			"settings.mode.hint": "The tutor's explanation style; switchable anytime in the study tab too",
 			"settings.studyMode": "Study mode",
+			"settings.voice": "Read-aloud voice",
+			"settings.voice.hint": "The neural voice used by 朗读本课 (a browser-local preference)",
+			"voice.xiaoxiao": "Xiaoxiao · Chinese female",
+			"voice.yunxi": "Yunxi · Chinese male",
+			"voice.yunyang": "Yunyang · Chinese male (news)",
+			"voice.xiaoyi": "Xiaoyi · Chinese female (lively)",
+			"voice.aria": "Aria · English female",
+			"voice.guy": "Guy · English male",
 			"settings.studyMode.hint": "On registers the study_* tools and the tutor persona; progress and notes are always kept",
 			"settings.on": "Status: on",
 			"settings.off": "Status: off",
@@ -1925,6 +2022,436 @@ window.__ModuleLoader__.load({
 			container.append(legend);
 		}
 		//#endregion
+		//#region src/vendor/speech-text.ts
+		/**
+		* Vendored from LookatStudy shared/speech-text.ts (MIT License,
+		* https://github.com/Kaiji-Z/LookatStudy), upstream v0.28.0 — includes the
+		* v11.5 whole-display-group avoidance fix era. Unmodified except this
+		* provenance header.
+		*
+		* speech-text —— TTS 朗读文本处理(纯函数,渲染层/主进程共用)。
+		*
+		* normalizeSpeechText: markdown → 可朗读纯文本。代码不读(围栏/行内整体移除),
+		* 链接留文字,强调/标题/列表/引用/表格标记剥离 —— 导师"念的是话,不是版面"。
+		*
+		* splitSentences: 流式友好的切句。每次喂"累积文本"返回完整句 + 余量(幂等,StrictMode 安全);
+		* flush=true 时尾句强制吐出。终止标点:中英句号/叹/问/分号 + 省略号;ASCII '.' 要求后跟
+		* 空白且前字符非数字(3.14 不切)。超过 maxBuffer 仍无终止标点 → 在最后的软标点(、,;: 空白)
+		* 处断开,再无则硬断 —— 保证"导师边生成边念"的流式管线永远不会饿死。
+		*
+		* v11.2 表意分隔:换行与 emoji 也是句界。无标点的段落/列表/短句流文本,
+		* 旧逻辑的强制断句块会在显示层并组吞整段(高亮整段到结尾);现在逐行/逐 emoji
+		* 成句,显示组另加长度上限兜底 —— karaoke 高亮粒度永远可控。
+		*/
+		/** 终止标点(出现即成句,连续终止/右引号并吞进句尾) */
+		const HARD = /* @__PURE__ */ new Set([
+			"。",
+			"!",
+			"?",
+			"！",
+			"？",
+			";",
+			"；",
+			"…"
+		]);
+		/** 软标点(超长兜底断句位) */
+		const SOFT = /* @__PURE__ */ new Set([
+			",",
+			"，",
+			"、",
+			":",
+			"：",
+			" ",
+			"	"
+		]);
+		/** v11.2 emoji 基字符范围(表意/象形/杂项符号/箭头符号区);修饰符(VS16/ZWJ/肤色)不单独成界 */
+		const EMOJI_CP_RE = /[\u{1F000}-\u{1FAFF}\u{2600}-\u{27BF}\u{2B00}-\u{2BFF}]/u;
+		function isEmojiCp(cp) {
+			return cp != null && EMOJI_CP_RE.test(String.fromCodePoint(cp));
+		}
+		/** 句尾可并吞的右闭合符 */
+		const CLOSERS = /* @__PURE__ */ new Set([
+			"”",
+			"\"",
+			"」",
+			"』",
+			"》",
+			")",
+			"】",
+			"])".slice(0, 1)
+		]);
+		function normalizeSpeechText(md) {
+			let s = md;
+			s = s.replace(/\r\n?/g, "\n");
+			s = s.replace(/(?:^|\n)[ \t]*(?:```|~~~)[^\n]*\n[\s\S]*?(?:\n[ \t]*(?:```|~~~)[^\n]*|\n?$)/g, "\n");
+			s = s.replace(/`[^`\n]*`/g, "");
+			s = s.replace(/!\[[^\]]*\]\([^)\n]*\)/g, "");
+			s = s.replace(/\[([^\]]+)\]\([^)\n]*\)/g, "$1");
+			s = s.replace(/^[ \t]{0,3}#{1,6}[ \t]+/gm, "");
+			s = s.replace(/^[ \t]*(?:[-*+]|\d+\.)[ \t]+/gm, "");
+			s = s.replace(/^[ \t]*>[ \t]?/gm, "");
+			s = s.replace(/\|/g, " ");
+			s = s.replace(/^[ \t]*[-: ]{3,}[ \t]*$/gm, "");
+			s = s.replace(/(\*\*|__)(.*?)\1/g, "$2");
+			s = s.replace(/(?<![*\w])(\*|_)(?!\s)(.+?)(?<!\s)\1(?![*\w])/g, "$2");
+			s = s.replace(/~~(.+?)~~/g, "$1");
+			s = s.replace(/\n{3,}/g, "\n\n");
+			return s.trim();
+		}
+		/**
+		* v11.2 朗读句表单一入口(v11.4 起仅合成侧使用):tts-service 用它切段;
+		* 渲染层 karaoke **不再调用**(改吃 ttsAudio.sentence 权威原文,见
+		* playedSentencePrefix)——句表从合成侧单向流出,显示侧零复算零分叉。
+		*/
+		function speechSentencesOf(text) {
+			return splitSentences(normalizeSpeechText(text), { flush: true }).sentences;
+		}
+		function splitSentences(text, opts = {}) {
+			const maxBuffer = Math.max(8, opts.maxBuffer ?? 120);
+			const flush = opts.flush ?? false;
+			const out = [];
+			const n = text.length;
+			let start = 0;
+			let i = 0;
+			let lastSoft = -1;
+			const emit = (end) => {
+				const piece = text.slice(start, end).trim();
+				if (piece) out.push(piece);
+				start = end;
+				lastSoft = -1;
+			};
+			while (i < n) {
+				const ch = text[i];
+				const cp = text.codePointAt(i);
+				if (isEmojiCp(cp)) {
+					let j = i + (cp > 65535 ? 2 : 1);
+					while (j < n) {
+						const cj = text.codePointAt(j);
+						const ul = cj > 65535 ? 2 : 1;
+						if (cj === 65039 || cj === 8205 || cj >= 127995 && cj <= 127999 || isEmojiCp(cj)) {
+							j += ul;
+							continue;
+						}
+						break;
+					}
+					emit(j);
+					i = j;
+					continue;
+				}
+				if (ch === "\n") {
+					const piece = text.slice(start, i + 1).replace(/[^\S\n]+$/, "");
+					if (piece.trim()) out.push(piece);
+					start = i + 1;
+					lastSoft = -1;
+					i++;
+					continue;
+				}
+				if (HARD.has(ch)) {
+					let j = i + 1;
+					while (j < n && (HARD.has(text[j]) || CLOSERS.has(text[j]))) j++;
+					emit(j);
+					i = j;
+					continue;
+				}
+				if (ch === ".") {
+					const prev = i > 0 ? text[i - 1] : "";
+					const next = i + 1 < n ? text[i + 1] : "";
+					if ((next === "" || /\s/.test(next)) && !/\d/.test(prev)) {
+						let j = i + 1;
+						while (j < n && (CLOSERS.has(text[j]) || HARD.has(text[j]))) j++;
+						emit(j);
+						i = j;
+						continue;
+					}
+				}
+				if (SOFT.has(ch)) lastSoft = i;
+				if (i - start + 1 > maxBuffer) {
+					if (lastSoft > start) {
+						const cut = lastSoft;
+						emit(cut);
+						start = cut + 1;
+					} else {
+						emit(i + 1);
+						i++;
+						continue;
+					}
+				}
+				i++;
+			}
+			const rest = text.slice(start).trim();
+			if (flush && rest) out.push(rest);
+			return {
+				sentences: out,
+				rest: flush ? "" : rest
+			};
+		}
+		//#endregion
+		//#region src/vendor/math-speech.ts
+		/**
+		* Vendored from LookatStudy shared/math-speech.ts (MIT License,
+		* https://github.com/Kaiji-Z/LookatStudy), upstream v0.28.0. Unmodified
+		* except this provenance header. zh-only by design upstream — the plugin's
+		* read-aloud pipeline applies it for zh and strips $..$ delimiters for other
+		* locales (conversion for more languages is future work).
+		*
+		* math-speech —— LaTeX 公式 → 中文口语(v0.19 朗读口语化,纯函数,verify 直测)。
+		*
+		* 只在**合成侧**应用(真正念出来的文本);karaoke 高亮/匹配层继续吃 `$..$` 原文
+		* (DOM 侧 getTextModel 收 KaTeX annotation 的 TeX 源,两侧在 canonical 空间对齐)
+		* ——念的是人话,亮的是原文,互不干扰。
+		*
+		* 规则表起步:常见记号(分式/根号/上下标/希腊字母/关系与算符)覆盖优先,
+		* 未覆盖宏退化为逐字母(好于念"反斜杠 f-r-a-c")。
+		*/
+		/** 单符号命令 → 中文(长命令先试,避免 \le 被 \leq 截断)。 */
+		const SYMBOLS = [
+			["\\leq", "小于等于"],
+			["\\le", "小于等于"],
+			["\\geq", "大于等于"],
+			["\\ge", "大于等于"],
+			["\\neq", "不等于"],
+			["\\ne", "不等于"],
+			["\\approx", "约等于"],
+			["\\equiv", "恒等于"],
+			["\\pm", "正负"],
+			["\\times", "乘以"],
+			["\\cdot", "点乘"],
+			["\\div", "除以"],
+			["\\to", "趋于"],
+			["\\rightarrow", "趋于"],
+			["\\Rightarrow", "推出"],
+			["\\infty", "无穷"],
+			["\\sum", "求和"],
+			["\\prod", "连乘"],
+			["\\int", "积分"],
+			["\\lim", "极限"],
+			["\\log", "对数"],
+			["\\ln", "自然对数"],
+			["\\exp", "指数"],
+			["\\in", "属于"],
+			["\\subset", "包含于"],
+			["\\cup", "并"],
+			["\\cap", "交"],
+			["\\forall", "任意"],
+			["\\exists", "存在"],
+			["\\partial", "偏导"],
+			["\\nabla", "梯度"],
+			["\\angle", "角"],
+			["\\degree", "度"],
+			["\\cdots", "点点点"],
+			["\\ldots", "点点点"]
+		];
+		const GREEK = {
+			alpha: "阿尔法",
+			beta: "贝塔",
+			gamma: "伽马",
+			delta: "德尔塔",
+			epsilon: "艾普西隆",
+			zeta: "泽塔",
+			eta: "伊塔",
+			theta: "西塔",
+			iota: "约塔",
+			kappa: "卡帕",
+			lambda: "拉姆达",
+			mu: "缪",
+			nu: "纽",
+			xi: "克西",
+			pi: "派",
+			rho: "柔",
+			sigma: "西格马",
+			tau: "陶",
+			phi: "斐",
+			chi: "凯",
+			psi: "普西",
+			omega: "欧米伽"
+		};
+		/** 读取 `{...}` 花括号组(从 openIdx 的下一个字符起,返回内容与结束下标)。 */
+		function readGroup(s, i) {
+			if (s[i] !== "{") return null;
+			let depth = 0;
+			for (let j = i; j < s.length; j++) if (s[j] === "{") depth++;
+			else if (s[j] === "}") {
+				depth--;
+				if (depth === 0) return {
+					body: s.slice(i + 1, j),
+					end: j + 1
+				};
+			}
+			return null;
+		}
+		/** 单 token(花括号组或单字符)读取:返回 {body, end}。 */
+		function readAtom(s, i) {
+			const g = readGroup(s, i);
+			if (g) return g;
+			return {
+				body: s[i] ?? "",
+				end: i + 1
+			};
+		}
+		/** LaTeX 片段 → 中文口语(递归:命令参数体内再走一遍)。 */
+		function mathToSpokenZH(tex) {
+			let s = tex;
+			s = s.replace(/\\(?:left|right|displaystyle|limits)\b/g, " ");
+			s = s.replace(/\\[,;!\s]|\\quad|\\qquad|~/g, " ");
+			for (let guard = 0; guard < 12; guard++) {
+				let next = s;
+				next = next.replace(/\\[dt]?frac(?![A-Za-z])/g, "\\frac");
+				{
+					let i;
+					while ((i = next.indexOf("\\frac")) >= 0) {
+						const a = readAtom(next, i + 5);
+						const b = readAtom(next, a.end);
+						next = next.slice(0, i) + `${a.body} 分之 ${b.body} ` + next.slice(b.end);
+					}
+				}
+				{
+					let i;
+					while ((i = next.indexOf("\\binom")) >= 0) {
+						const a = readAtom(next, i + 6);
+						const b = readAtom(next, a.end);
+						next = next.slice(0, i) + `${a.body} 取 ${b.body} ` + next.slice(b.end);
+					}
+				}
+				next = next.replace(/\\sqrt\s*\[( {[^{}]*} |[^\s\\]+)\s*\]\s*/g, (_m, n) => `${n.trim()} 次根号 `);
+				{
+					let i;
+					while ((i = next.indexOf("\\sqrt")) >= 0) {
+						const a = readAtom(next, i + 5);
+						next = next.slice(0, i) + `根号 ${a.body} ` + next.slice(a.end);
+					}
+				}
+				next = next.replace(/\\(?:mathbf|mathbb|mathrm|mathit|boldsymbol|text|operatorname)\s*/g, (m) => m.startsWith("\\text") ? "" : " ");
+				if (next === s) {
+					s = next;
+					break;
+				}
+				s = next;
+			}
+			for (let guard = 0; guard < 8; guard++) {
+				const next = s.replace(/(\\frac|[\w)\]}]|\s)\s*\^\s*(\{[^{}]*\}|[^\s])|(\\frac|[\w)\]}]| )\s*_\s*(\{[^{}]*\}|[^\s])/g, (_m, base1, sup, base2, sub) => {
+					if (sup !== void 0) return `${base1} 的 ${sup.replace(/[{}]/g, "")} 次方`;
+					return `${base2} 下标 ${sub.replace(/[{}]/g, "")}`;
+				});
+				if (next === s) break;
+				s = next;
+			}
+			for (const [cmd, zh] of SYMBOLS) s = s.split(cmd).join(` ${zh} `);
+			s = s.replace(/\\([A-Za-z]+)\b/g, (_m, name) => ` ${GREEK[name] ?? name} `);
+			s = s.replace(/[{}]/g, " ");
+			return s.replace(/\s+/g, " ").trim();
+		}
+		/** 句子级入口:把 `$..$`/`$$..$$` 段替换为口语;段外文本逐字节不变。 */
+		function speakMathInSentence(sentence) {
+			return sentence.replace(/\$\$([^$]+)\$\$|\$([^$]+)\$/g, (_m, block, inline) => {
+				const spoken = mathToSpokenZH(block ?? inline ?? "");
+				return spoken ? ` ${spoken} ` : "";
+			});
+		}
+		//#endregion
+		//#region src/client/readaloud.ts
+		const sleep = (ms) => new Promise((resolve) => {
+			setTimeout(resolve, ms);
+		});
+		var ReadAloudController = class {
+			sentences;
+			primary;
+			fallback;
+			notify;
+			index = 0;
+			stopped = false;
+			paused = false;
+			engine = null;
+			degraded = false;
+			run = null;
+			constructor(sentences, primary, fallback, notify) {
+				this.sentences = sentences;
+				this.primary = primary;
+				this.fallback = fallback;
+				this.notify = notify;
+			}
+			emit(state) {
+				this.notify?.({
+					index: this.index,
+					total: this.sentences.length,
+					engine: this.engine,
+					state,
+					degraded: this.degraded
+				});
+			}
+			/** Speak the whole queue; the returned promise settles when done or stopped. */
+			start() {
+				if (this.run !== null) return this.run;
+				this.stopped = false;
+				this.run = (async () => {
+					this.engine = "edge";
+					this.emit("speaking");
+					while (!this.stopped && this.index < this.sentences.length) {
+						const text = this.sentences[this.index];
+						try {
+							await this.speakOn(text);
+						} catch {
+							if (this.stopped) return;
+							if (this.engine === "edge") {
+								this.degraded = true;
+								this.engine = "system";
+								this.emit("speaking");
+								try {
+									await this.speakOn(text);
+								} catch {
+									this.emit("idle");
+									return;
+								}
+							} else {
+								this.emit("idle");
+								return;
+							}
+						}
+						if (this.stopped) return;
+						this.index += 1;
+						this.emit("speaking");
+					}
+					this.emit("idle");
+				})();
+				return this.run;
+			}
+			async speakOn(text) {
+				const impl = this.engine === "system" ? this.fallback : this.primary;
+				const next = this.sentences[this.index + 1];
+				if (next !== void 0) impl.prewarm?.(next);
+				await impl.speak(text);
+				while (this.paused && !this.stopped) await sleep(120);
+			}
+			pause() {
+				if (this.stopped || this.paused) return;
+				this.paused = true;
+				(this.engine === "system" ? this.fallback : this.primary).pause();
+				this.emit("paused");
+			}
+			resume() {
+				if (!this.paused) return;
+				this.paused = false;
+				(this.engine === "system" ? this.fallback : this.primary).resume();
+				this.emit("speaking");
+			}
+			/** Stop everything; the controller is single-use — build a fresh one to replay. */
+			stop() {
+				this.stopped = true;
+				this.paused = false;
+				this.primary.cancel();
+				this.fallback.cancel();
+				this.emit("idle");
+			}
+			get status() {
+				return {
+					index: this.index,
+					total: this.sentences.length,
+					engine: this.engine,
+					state: this.stopped ? "idle" : this.paused ? "paused" : "speaking",
+					degraded: this.degraded
+				};
+			}
+		};
+		//#endregion
 		//#region src/client/views.tsx
 		/**
 		* The study tab: one `conversation.view` entry rendering the whole plugin —
@@ -2623,11 +3150,108 @@ window.__ModuleLoader__.load({
 				}
 			}, s.label))) : null, (0, react.createElement)(ActionError, { error }));
 		}
+		/** Browser speechSynthesis engine — the offline/endpoint-gone fallback voice. */
+		function systemSpeechEngine() {
+			return {
+				speak(text) {
+					return new Promise((resolve, reject) => {
+						const synth = typeof window === "undefined" ? void 0 : window.speechSynthesis;
+						if (synth === void 0) {
+							reject(/* @__PURE__ */ new Error("no speechSynthesis"));
+							return;
+						}
+						const utterance = new SpeechSynthesisUtterance(text);
+						utterance.lang = "zh-CN";
+						utterance.onend = () => resolve();
+						utterance.onerror = () => reject(/* @__PURE__ */ new Error("speechSynthesis failed"));
+						synth.speak(utterance);
+					});
+				},
+				pause() {
+					window.speechSynthesis?.pause();
+				},
+				resume() {
+					window.speechSynthesis?.resume();
+				},
+				cancel() {
+					window.speechSynthesis?.cancel();
+				}
+			};
+		}
+		/** Edge-over-dashboard engine: MP3 from /api/tts played through an <audio>, with per-session prefetch. */
+		function audioSpeechEngine(fetchTts) {
+			let audio = null;
+			const prefetch = /* @__PURE__ */ new Map();
+			const load = (text) => {
+				let pending = prefetch.get(text);
+				if (pending === void 0) {
+					pending = fetchTts(text);
+					pending.catch(() => prefetch.delete(text));
+					prefetch.set(text, pending);
+				}
+				return pending;
+			};
+			return {
+				speak(text) {
+					return load(text).then((buf) => new Promise((resolve, reject) => {
+						const blobUrl = URL.createObjectURL(new Blob([buf], { type: "audio/mpeg" }));
+						audio = new Audio(blobUrl);
+						const done = () => {
+							URL.revokeObjectURL(blobUrl);
+							resolve();
+						};
+						audio.onended = done;
+						audio.onerror = () => {
+							URL.revokeObjectURL(blobUrl);
+							reject(/* @__PURE__ */ new Error("audio playback failed"));
+						};
+						audio.play().catch(reject);
+					}));
+				},
+				pause() {
+					audio?.pause();
+				},
+				resume() {
+					audio?.play();
+				},
+				cancel() {
+					audio?.pause();
+					audio = null;
+				},
+				prewarm(text) {
+					load(text);
+				}
+			};
+		}
 		/** Right column: the blackboard — focus-lesson 讲解/脑图/概念图 plus the Cornell 笔记. */
 		function BlackboardColumn({ data, deleteNote }) {
 			const lesson = data?.lesson ?? null;
+			const { tts } = useStudy();
 			const [pane, setPane] = (0, react.useState)("teach");
 			const [error, setError] = (0, react.useState)(null);
+			const [read, setRead] = (0, react.useState)(null);
+			const readCtl = (0, react.useRef)(null);
+			const [readError, setReadError] = (0, react.useState)(null);
+			const startReading = () => {
+				if (lesson === null || lesson.speechText.trim() === "") return;
+				readCtl.current?.stop();
+				const sentences = speechSentencesOf(lesson.speechText);
+				const voice = storedTtsVoice();
+				const controller = new ReadAloudController(sentences.map((s) => speakMathInSentence(s)), audioSpeechEngine((text) => tts(text, voice)), systemSpeechEngine(), (s) => {
+					setRead(s);
+					if (s.degraded && s.engine === "system" && !readError) setReadError(tr("read.engine.system"));
+				});
+				readCtl.current = controller;
+				setReadError(null);
+				controller.start().catch((err) => {
+					setReadError(err instanceof Error ? err.message : String(err));
+				});
+			};
+			const stopReading = () => {
+				readCtl.current?.stop();
+				setRead(null);
+				setReadError(null);
+			};
 			const [armedNote, setArmedNote] = (0, react.useState)(null);
 			(0, react.useEffect)(() => {
 				if (armedNote === null) return;
@@ -2690,7 +3314,35 @@ window.__ModuleLoader__.load({
 				onClick: () => {
 					setPane("cmap");
 				}
-			}, (0, react.createElement)(IconGlobeOutline14, { size: 13 }), tr("viewtab.cmap"))), pane === "teach" ? (0, react.createElement)("div", {
+			}, (0, react.createElement)(IconGlobeOutline14, { size: 13 }), tr("viewtab.cmap"))), pane === "teach" ? (0, react.createElement)("div", { className: "lks-readbar" }, (0, react.createElement)("button", {
+				className: "lks-btn ghost",
+				style: {
+					padding: "3px 8px",
+					fontSize: "12.5px",
+					flex: "none"
+				},
+				title: read !== null && read.state === "speaking" ? tr("read.pause") : tr("read.play"),
+				onClick: () => {
+					if (read !== null && read.state === "speaking") {
+						readCtl.current?.pause();
+						return;
+					}
+					if (read !== null && read.state === "paused") {
+						readCtl.current?.resume();
+						return;
+					}
+					startReading();
+				}
+			}, (0, react.createElement)(IconPlayOutline16, { size: 12 }), read !== null && read.state === "speaking" ? tr("read.pause") : read !== null && read.state === "paused" ? tr("read.resume") : tr("read.play")), read !== null ? (0, react.createElement)("button", {
+				className: "lks-btn ghost",
+				style: {
+					padding: "3px 8px",
+					fontSize: "12.5px",
+					flex: "none"
+				},
+				title: tr("read.stop"),
+				onClick: stopReading
+			}, tr("read.stop")) : null, read !== null && read.state !== "idle" && lesson !== null ? (0, react.createElement)("span", { className: "lks-readbar-cur" }, (speechSentencesOf(lesson.speechText)[read.index] ?? "").slice(0, 80)) : null, readError !== null ? (0, react.createElement)("span", { className: "lks-readbar-notice" }, readError) : null) : null, pane === "teach" ? (0, react.createElement)("div", {
 				className: "lks-prose",
 				ref: proseRef,
 				dangerouslySetInnerHTML: { __html: lesson.html }
@@ -2837,6 +3489,7 @@ window.__ModuleLoader__.load({
 		function StudySettingsSection() {
 			const { data, setMode, activate } = useStudy();
 			const [error, setError] = (0, react.useState)(null);
+			const [voice, setVoice] = (0, react.useState)(storedTtsVoice);
 			const fire = (action) => {
 				action.then(() => {
 					setError(null);
@@ -2857,7 +3510,17 @@ window.__ModuleLoader__.load({
 				onClick: () => {
 					if (data !== null) fire(activate(!data.active));
 				}
-			}, data?.active === true ? tr("settings.turnOff") : tr("settings.turnOn")), (0, react.createElement)("span", { className: "lks-set-state" }, data?.active === true ? tr("settings.on") : tr("settings.off")))), progress === void 0 ? null : (0, react.createElement)("section", { className: "lks-set-row" }, (0, react.createElement)("h3", null, tr("settings.stats")), (0, react.createElement)("ul", { className: "lks-set-stats" }, (0, react.createElement)("li", null, tr("settings.stats.courses", { count: data?.courses.length ?? 0 })), (0, react.createElement)("li", null, tr("settings.stats.xp", {
+			}, data?.active === true ? tr("settings.turnOff") : tr("settings.turnOn")), (0, react.createElement)("span", { className: "lks-set-state" }, data?.active === true ? tr("settings.on") : tr("settings.off")))), (0, react.createElement)("section", { className: "lks-set-row" }, (0, react.createElement)("h3", null, tr("settings.voice")), (0, react.createElement)("p", { className: "lks-set-hint" }, tr("settings.voice.hint")), (0, react.createElement)("div", null, (0, react.createElement)("select", {
+				className: "lks-set-select",
+				value: voice,
+				onChange: (e) => {
+					storeTtsVoice(e.target.value);
+					setVoice(e.target.value);
+				}
+			}, ...TTS_VOICES.map((v) => (0, react.createElement)("option", {
+				key: v.id,
+				value: v.id
+			}, tr(v.labelKey)))))), progress === void 0 ? null : (0, react.createElement)("section", { className: "lks-set-row" }, (0, react.createElement)("h3", null, tr("settings.stats")), (0, react.createElement)("ul", { className: "lks-set-stats" }, (0, react.createElement)("li", null, tr("settings.stats.courses", { count: data?.courses.length ?? 0 })), (0, react.createElement)("li", null, tr("settings.stats.xp", {
 				xp: progress.totalXp,
 				level: progress.level,
 				pct: progress.levelPct