Clean up Text to Speech V2 browser queue behavior and voice summary - PR_26130_017-text-to-speech-v2-queue-behavior-cleanup

Author: DavidQ

docs/dev/reports/PR_26130_017-text-to-speech-v2-queue-behavior-cleanup.md

@@ -0,0 +1,106 @@
+# PR_26130_017-text-to-speech-v2-queue-behavior-cleanup
+
+## Summary
+
+Updated Text to Speech V2 to match browser `speechSynthesis` queue behavior instead of modeling fake concurrent speakers. Removed Auto Speak from the visible UI, schema, defaults, queue item data, and hydration path while safely stripping legacy `autoSpeak` from older saved queue items.
+
+## Scope
+
+- Tool fixed: Text to Speech V2.
+- Failing behavior before: browser speech queue behavior was represented as active independent speakers, and Auto Speak remained in schema/default/control paths.
+- Remaining failures after this PR: none known in the PR scope.
+- Out of scope: non-browser speech backends, true concurrent speech, sample JSON alignment, and full samples smoke validation.
+
+## Changes
+
+- `src/engine/audio/TextToSpeechEngine.js`
+  - Replaced active speaker tracking with queued speech item tracking.
+  - `append` calls `speechSynthesis.speak()` without global cancel.
+  - `replace` explicitly calls `speechSynthesis.cancel()` and clears tracked queued items before speaking.
+  - Stop now reflects browser-global queue cancellation and logs cleared queued item count.
+- `src/engine/audio/TextToSpeechDefaults.js`
+  - Removed `autoSpeak` from required fields, default options, and default queue data.
+- `tools/schemas/tools/text2speach-V2.schema.json`
+  - Removed `autoSpeak` from schema required fields and properties.
+- `tools/text2speach-V2/index.html`
+  - Removed Auto Speak and Stop All controls.
+- `tools/text2speach-V2/js/TextToSpeechToolApp.js`
+  - Removed auto-speak triggering and Stop All wiring.
+  - Migrates legacy `autoSpeak`, `repeatCount`, and `delayBetweenRepeatsMs` fields out of saved queue items without rendering removed controls.
+  - Logs browser queue-oriented speech status.
+- `tools/text2speach-V2/js/bootstrap.js`
+  - Removed Auto Speak and Stop All element wiring.
+- `tools/text2speach-V2/js/controls/ActionNavControl.js`
+  - Removed Stop All button plumbing.
+- `tools/text2speach-V2/js/controls/SpeechOptionsControl.js`
+  - Removed Auto Speak state from control values.
+  - Changed voice match details to count/filter heading plus language-prefixed bullet list.
+- `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+  - Updated Text to Speech V2 coverage for queue behavior, Auto Speak removal, schema/default cleanup, voice match details, neutral/unknown voice helper buckets, and workspace launch controls.
+
+## Playwright
+
+Playwright impacted: Yes.
+
+Validated behavior:
+- Text to Speech V2 no longer exposes Auto Speak or Stop All controls.
+- Schema/default queue data no longer require or emit `autoSpeak`.
+- Browser queue append can queue multiple utterances without canceling existing queued speech.
+- Replace mode uses global browser cancel and reports the current queue.
+- Stop uses browser-global queue cancellation and reports cleared queued items.
+- Visible text does not claim multi-threaded or concurrent speech support.
+- Voice details render as:
+  - `N voices match <filter>:`
+  - one `- <language>: <voice name>` line per matching voice.
+- Neutral/unknown voices remain available under Any, Male Preferred, and Female Preferred filters.
+
+Expected pass behavior:
+- Queue append keeps previous queued utterances and does not call `cancel()`.
+- Queue replace clears the tracked queue through browser cancel before speaking.
+- Auto Speak is absent from UI, schema, and default queue data.
+
+Expected fail behavior:
+- Missing voices keep Speak disabled with actionable status.
+- Removed controls are not available for interaction.
+
+## Validation
+
+- PASS: `node --check src/engine/audio/TextToSpeechDefaults.js`
+- PASS: `node --check src/engine/audio/TextToSpeechEngine.js`
+- PASS: `node --check tools/text2speach-V2/js/TextToSpeechToolApp.js`
+- PASS: `node --check tools/text2speach-V2/js/bootstrap.js`
+- PASS: `node --check tools/text2speach-V2/js/controls/ActionNavControl.js`
+- PASS: `node --check tools/text2speach-V2/js/controls/SpeechOptionsControl.js`
+- PASS: `node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- PASS: `tools/schemas/tools/text2speach-V2.schema.json` parsed with `JSON.parse`.
+- PASS: `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list -g "Text to Speech V2|text2speach-V2"` passed 5 tests.
+- PASS: `npm run test:workspace-v2` passed 28 tests.
+- PASS: `git diff --check HEAD -- .` passed with only Windows line-ending warnings.
+- PASS: Text to Speech V2 HTML scan found no inline event handlers, no inline styles, and only allowed external module scripts.
+- PASS: Forbidden-scope scan found no `tools/shared`, `imageDataUrl`, or `start_of_day` matches in changed implementation/test scopes.
+
+## Coverage
+
+Playwright V8 coverage was generated by the required Workspace V2 run.
+
+- `(78%) src/engine/audio/TextToSpeechEngine.js - changed JS file with browser V8 coverage`
+- `(100%) src/engine/audio/TextToSpeechDefaults.js - changed JS file with browser V8 coverage`
+- `(100%) tools/text2speach-V2/js/bootstrap.js - changed JS file with browser V8 coverage`
+- `(100%) tools/text2speach-V2/js/controls/ActionNavControl.js - changed JS file with browser V8 coverage`
+- `(100%) tools/text2speach-V2/js/controls/SpeechOptionsControl.js - changed JS file with browser V8 coverage`
+- `(100%) tools/text2speach-V2/js/TextToSpeechToolApp.js - changed JS file with browser V8 coverage`
+
+## Full Samples Smoke Test
+
+Skipped. This PR is limited to Text to Speech V2 browser speech queue behavior, Auto Speak removal, voice match display, and Workspace V2 Playwright coverage. It does not modify shared sample loading, sample JSON, broad game launch behavior, or shared runtime paths that require the full samples smoke test.
+
+## Manual Validation
+
+1. Open `tools/text2speach-V2/index.html`.
+2. Confirm the Speech Options panel has no Auto Speak control and Named Sentences has Speak, Pause, Resume, and Stop only.
+3. Confirm voice details show a heading like `4 voices match Any:` followed by one bullet per voice.
+4. Select Queue Mode `Append to queue`, speak two different named sentences, and confirm the status reports queued item counts without claiming concurrent speakers.
+5. Select Queue Mode `Replace current speech`, speak, and confirm status reports the replacement speech item.
+6. Use Stop and confirm status reports the number of queued items cleared.
+
+Expected outcome: Text to Speech V2 uses browser queue semantics, removed controls stay absent, and no UI copy claims true concurrent speech.

src/engine/audio/TextToSpeechDefaults.js

@@ -88,13 +88,11 @@ const TEXT_TO_SPEECH_QUEUE_ITEM_REQUIRED_FIELDS = Object.freeze([
   "rate",
   "pitch",
   "queueMode",
-  "autoSpeak",
   "characterPreset",
   "ssmlLikePreset"
 ]);
 
 const TEXT_TO_SPEECH_DEFAULT_OPTIONS = Object.freeze({
-  autoSpeak: false,
   characterPreset: "manual",
   gender: "any",
   language: "en-US",
@@ -123,7 +121,6 @@ const TEXT_TO_SPEECH_DEFAULT_QUEUE = Object.freeze([
   Object.freeze({
     ...TEXT_TO_SPEECH_DEFAULT_OPTIONS,
     ...TEXT_TO_SPEECH_CHARACTER_PRESET_DEFAULTS.dramatic,
-    autoSpeak: false,
     characterPreset: "dramatic",
     gender: "male-preferred",
     id: "hero-ready",
@@ -139,7 +136,6 @@ const TEXT_TO_SPEECH_DEFAULT_QUEUE = Object.freeze([
   Object.freeze({
     ...TEXT_TO_SPEECH_DEFAULT_OPTIONS,
     ...TEXT_TO_SPEECH_CHARACTER_PRESET_DEFAULTS.alert,
-    autoSpeak: false,
     characterPreset: "alert",
     gender: "female-preferred",
     id: "alert-warning",

src/engine/audio/TextToSpeechEngine.js

@@ -18,7 +18,8 @@ class TextToSpeechEngine {
     speechSynthesisRef = globalThis.speechSynthesis,
     utteranceCtor = globalThis.SpeechSynthesisUtterance
   } = {}) {
-    this.activeSpeakers = new Map();
+    this.queueSequence = 0;
+    this.queuedSpeechItems = new Map();
     this.speechSynthesis = speechSynthesisRef;
     this.Utterance = utteranceCtor;
   }
@@ -95,8 +96,8 @@ class TextToSpeechEngine {
     };
   }
 
-  activeSpeakerList() {
-    return Array.from(this.activeSpeakers.values()).map((speaker) => ({ ...speaker }));
+  queuedSpeechItemList() {
+    return Array.from(this.queuedSpeechItems.values()).map((item) => ({ ...item }));
   }
 
   createUtterance({
@@ -146,15 +147,14 @@ class TextToSpeechEngine {
   }
 
   speak({
-    autoSpeak = TEXT_TO_SPEECH_DEFAULTS.autoSpeak,
     characterPreset = TEXT_TO_SPEECH_DEFAULTS.characterPreset,
     gender = TEXT_TO_SPEECH_DEFAULTS.gender,
     language = TEXT_TO_SPEECH_DEFAULTS.language,
     pitch = TEXT_TO_SPEECH_DEFAULTS.pitch,
     queueMode = TEXT_TO_SPEECH_DEFAULTS.queueMode,
     rate = TEXT_TO_SPEECH_DEFAULTS.rate,
-    speakerId = "",
-    speakerName = "",
+    speechItemId = "",
+    speechItemName = "",
     ssmlLikePreset = TEXT_TO_SPEECH_DEFAULTS.ssmlLikePreset,
     text = TEXT_TO_SPEECH_DEFAULTS.sampleText,
     voice = TEXT_TO_SPEECH_DEFAULTS.voice,
@@ -170,47 +170,54 @@ class TextToSpeechEngine {
       return { message: `Unsupported ${TEXT_TO_SPEECH_DISPLAY_NAME} queueMode: ${queueMode}.`, ok: false };
     }
 
-    const activeSpeakerId = String(speakerId || speakerName || `speaker-${Date.now().toString(36)}`);
-    const activeSpeakerName = String(speakerName || activeSpeakerId);
-    const activeSpeaker = {
-      id: activeSpeakerId,
+    if (queueMode === "replace") {
+      this.speechSynthesis.cancel();
+      this.queuedSpeechItems.clear();
+    }
+
+    this.queueSequence += 1;
+    const selectedSpeechItemId = String(speechItemId || speechItemName || `speech-item-${Date.now().toString(36)}`);
+    const queuedSpeechItemId = `${selectedSpeechItemId || "speech-item"}::${this.queueSequence}`;
+    const queuedSpeechItemName = String(speechItemName || selectedSpeechItemId);
+    const queuedSpeechItem = {
+      id: queuedSpeechItemId,
       language: firstUtterance.utterance.lang,
-      name: activeSpeakerName,
+      name: queuedSpeechItemName,
       pitch: firstUtterance.utterance.pitch,
       queueMode,
       rate: firstUtterance.utterance.rate,
+      speechItemId: selectedSpeechItemId,
       status: "queued",
       text: firstUtterance.text,
       voiceName: firstUtterance.voiceName,
       voiceURI: firstUtterance.voiceURI,
       volume: firstUtterance.utterance.volume
     };
     firstUtterance.utterance.onstart = () => {
-      const speaker = this.activeSpeakers.get(activeSpeakerId);
-      if (speaker) {
-        this.activeSpeakers.set(activeSpeakerId, { ...speaker, status: "speaking" });
+      const item = this.queuedSpeechItems.get(queuedSpeechItemId);
+      if (item) {
+        this.queuedSpeechItems.set(queuedSpeechItemId, { ...item, status: "speaking" });
       }
     };
-    const clearSpeaker = () => {
-      this.activeSpeakers.delete(activeSpeakerId);
+    const clearQueuedSpeechItem = () => {
+      this.queuedSpeechItems.delete(queuedSpeechItemId);
     };
-    firstUtterance.utterance.onend = clearSpeaker;
-    firstUtterance.utterance.onerror = clearSpeaker;
-    this.activeSpeakers.set(activeSpeakerId, activeSpeaker);
+    firstUtterance.utterance.onend = clearQueuedSpeechItem;
+    firstUtterance.utterance.onerror = clearQueuedSpeechItem;
+    this.queuedSpeechItems.set(queuedSpeechItemId, queuedSpeechItem);
     this.speechSynthesis.speak(firstUtterance.utterance);
 
     return {
-      activeSpeakers: this.activeSpeakerList(),
-      autoSpeak: autoSpeak === true,
       characterPreset,
       gender,
       language: firstUtterance.utterance.lang,
       ok: true,
       pitch: firstUtterance.utterance.pitch,
+      queuedSpeechItems: this.queuedSpeechItemList(),
       queueMode,
       rate: firstUtterance.utterance.rate,
-      speakerId: activeSpeakerId,
-      speakerName: activeSpeakerName,
+      speechItemId: selectedSpeechItemId,
+      speechItemName: queuedSpeechItemName,
       ssmlLikePreset,
       text: firstUtterance.text,
       voiceAge,
@@ -236,41 +243,19 @@ class TextToSpeechEngine {
     return { ok: true };
   }
 
-  stop({ speakerId = "" } = {}) {
-    if (!this.isSupported()) {
-      return { message: "SpeechSynthesis is unavailable in this browser.", ok: false };
-    }
-    const selectedSpeakerId = String(speakerId || "");
-    const speaker = selectedSpeakerId
-      ? this.activeSpeakers.get(selectedSpeakerId)
-      : this.activeSpeakerList()[0];
-    if (!speaker) {
-      return { message: `No active ${TEXT_TO_SPEECH_DISPLAY_NAME} speaker is tracked for ${selectedSpeakerId || "the current selection"}.`, ok: false };
-    }
-    if (this.activeSpeakers.size > 1) {
-      return {
-        activeSpeakers: this.activeSpeakerList(),
-        message: `Cannot stop only ${speaker.name}: browser SpeechSynthesis exposes global cancel only. No global cancel was called while other speakers are active.`,
-        ok: false
-      };
-    }
-    this.speechSynthesis.cancel();
-    this.activeSpeakers.delete(speaker.id);
-    return { activeSpeakers: this.activeSpeakerList(), ok: true, speakerName: speaker.name };
-  }
-
-  stopAll() {
+  stop() {
     if (!this.isSupported()) {
       return { message: "SpeechSynthesis is unavailable in this browser.", ok: false };
     }
-    const stoppedCount = this.activeSpeakers.size;
+    const stoppedCount = this.queuedSpeechItems.size;
     this.speechSynthesis.cancel();
-    this.activeSpeakers.clear();
+    this.queuedSpeechItems.clear();
     return { ok: true, stoppedCount };
   }
 
-  resetActiveSpeakers() {
-    this.activeSpeakers.clear();
+  resetQueuedSpeechItems() {
+    this.queueSequence = 0;
+    this.queuedSpeechItems.clear();
     return { ok: true };
   }
 }