dsh-plugin-lookatstudy 0.13.0 → 0.13.1

package/README.md

@@ -1,6 +1,6 @@
 # dsh-plugin-lookatstudy
 
-Turn any markdown document, local folder, or GitHub learning repository into a guided course inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) — your dsh agent becomes a full AI tutor with the interaction design of [LookatStudy](https://github.com/Kaiji-Z/LookatStudy): per-concept knowledge tracking, mastery-driven progression, spaced repetition, mastery proposals, friction awareness, learner memory, a Cornell notebook, an in-chat proposal card, exam mode with star grades, XP & streak, bilingual lessons, and a rich blackboard (KaTeX math, syntax-highlighted code, mermaid diagrams, mindmap & concept-map views). Learning engine modules are vendored from LookatStudy (MIT).
+Turn any markdown document, local folder, or GitHub learning repository into a guided course inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) — your dsh agent becomes a full AI tutor with the interaction design of [LookatStudy](https://github.com/Kaiji-Z/LookatStudy): per-concept knowledge tracking, mastery-driven progression, spaced repetition, mastery proposals, friction awareness, learner memory, a Cornell notebook, an in-chat proposal card, exam mode with star grades, XP & streak, bilingual lessons, read-aloud (Edge TTS with a system-voice fallback), and a rich blackboard (KaTeX math, syntax-highlighted code, mermaid diagrams, mindmap & concept-map views). Learning engine modules are vendored from LookatStudy (MIT).
 
 ## Screenshots
 
@@ -38,7 +38,7 @@ Works with any profile. In the `web` profile the plugin additionally serves the
 |---|---|
 | 左 · 课程 | Course picker, progress, due box with one-click review kickoff, lesson tree (gating, mastery bars, ⚡😣 weak spots, clickable focus), one-click demo import when empty |
 | 中 · 老师 | A read-only mini transcript of the live tutor conversation (assistant replies rendered through the plugin's markdown pipeline, tool calls as chips, streaming included) plus the soul pills (直讲/引导/实战), the focus lesson's starters, and the mastery-proposal banner (接受/再练练). Typing happens in dsh's own composer below the tab — the plugin never ships its own input; every button lands its text in that native composer and submits through the same path as the Send button |
-| 右 · 黑板 | The focus lesson's 讲解 (server-sanitized markdown, rendered rich on demand: KaTeX / syntax highlighting / mermaid), a 🧠 mindmap and 🕸 concept-map view of the same lesson, and the Cornell 笔记 three zones |
+| 右 · 黑板 | The focus lesson's 讲解 (server-sanitized markdown, rendered rich on demand: KaTeX / syntax highlighting / mermaid), a 🧠 mindmap and 🕸 concept-map view of the same lesson, the Cornell 笔记 three zones (each note deletable with an armed confirm), and the read-aloud bar — 朗读本课 speaks the lesson sentence-by-sentence through Microsoft's Edge neural voices (host-side synthesis, disk-cached; falls back to the browser's system voice offline) with the current sentence highlighted |
 
 The tutor column is a learning surface, not a generic chat: the tutor's quiz options (A–D) render as clickable answer buttons under the latest reply (clicking sends the answer through the native composer), graded answers show as ✓/✗ chips with the tested concept, and every course-tree glyph, tag, and mastery bar carries a hover tooltip explaining its meaning. All content text runs at the dsh chat transcript's own 16 px.
 
@@ -78,13 +78,13 @@ Misc: `study_set_mode`, `study_delete_course`
 
 ## What is intentionally not restored
 
-LookatStudy's Electron-native experiences have no host surface in dsh: the 伴学/voice companion line, persistent text highlighting with DOM anchors, and celebration particles. Everything else — engine, contracts, data models, exam mode with star grades, XP & streak, bilingual translation, image inlining, math/code/diagram rendering — is ported (diagram renderers load from CDN on demand and degrade silently offline).
+LookatStudy's Electron-native experiences have no host surface in dsh: the 伴学 companion creature and its celebration particles, and persistent text highlighting with DOM anchors (the read-aloud bar highlights in its own strip instead). Read-aloud itself IS ported (0.13.0) — Edge neural voices synthesized host-side with the browser's speechSynthesis as fallback. Everything else — engine, contracts, data models, exam mode with star grades, XP & streak, bilingual translation, image inlining, math/code/diagram rendering — is ported (diagram renderers load from CDN on demand and degrade silently offline).
 
 ## Development
 
 ```sh
 pnpm exec tsdown        # build lib/ (host + client entries, peers external)
-pnpm test               # 48 node:test cases over the real source (no key needed)
+pnpm test               # 218 node:test cases over the real source (no key needed)
 
 # iterate against a live dsh (this repo lives beside a deepseek-harness checkout):
 pnpm dsh web --patch ../dsh-plugin-lookatstudy/cordis.dev.yml   # run from the harness checkout

package/lib/client.js

@@ -260,6 +260,7 @@ window.__ModuleLoader__.load({
 .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}
 
@@ -754,6 +755,51 @@ window.__ModuleLoader__.load({
 				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. */
@@ -1664,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": "状态：已关闭",
@@ -1792,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",
@@ -2353,7 +2415,10 @@ window.__ModuleLoader__.load({
 				return this.run;
 			}
 			async speakOn(text) {
-				await (this.engine === "system" ? this.fallback : this.primary).speak(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() {
@@ -3113,15 +3178,33 @@ window.__ModuleLoader__.load({
 				}
 			};
 		}
-		/** Edge-over-dashboard engine: MP3 from /api/tts played through an <audio>. */
+		/** 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 fetchTts(text).then((buf) => new Promise((resolve, reject) => {
-						audio = new Audio(URL.createObjectURL(new Blob([buf], { type: "audio/mpeg" })));
-						audio.onended = () => resolve();
-						audio.onerror = () => reject(/* @__PURE__ */ new Error("audio playback failed"));
+					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);
 					}));
 				},
@@ -3134,6 +3217,9 @@ window.__ModuleLoader__.load({
 				cancel() {
 					audio?.pause();
 					audio = null;
+				},
+				prewarm(text) {
+					load(text);
 				}
 			};
 		}
@@ -3149,7 +3235,9 @@ window.__ModuleLoader__.load({
 			const startReading = () => {
 				if (lesson === null || lesson.speechText.trim() === "") return;
 				readCtl.current?.stop();
-				const controller = new ReadAloudController(speechSentencesOf(lesson.speechText).map((s) => speakMathInSentence(s)), audioSpeechEngine((text) => tts(text)), systemSpeechEngine(), (s) => {
+				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"));
 				});
@@ -3401,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);
@@ -3421,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