Filter text2speach-V2 voices by selected language and reorder controls - PR_26130_010-text2speach-v2-language-filtering

Author: DavidQ

docs/dev/reports/PR_26130_010-text2speach-v2-language-filtering.md

@@ -0,0 +1,121 @@
+# PR_26130_010-text2speach-v2-language-filtering
+
+## Purpose
+
+Make `text2speach-V2` match how browser SpeechSynthesis behaves: Language is selected first, and Voice only shows voices whose `SpeechSynthesisVoice.lang` matches that language.
+
+## Scope
+
+Changed only `text2speach-V2` language/voice UI, control filtering, schema/default ordering, and Workspace Manager V2 Playwright coverage.
+
+No `start_of_day` files were changed.
+
+`docs/dev/codex_commands.md` and `docs/dev/commit_comment.txt` were updated locally as required and remain ignored so they cannot be committed.
+
+## Implementation Summary
+
+- Moved Language above Voice in the Speech Options form.
+- Moved `language` before `voice` in the text2speach-V2 required-field/default/schema order.
+- Filtered Voice options to `speechSynthesis.getVoices()` entries whose `lang` matches the selected Language.
+- Added visible voice match details under Voice, including match count and voice names.
+- Auto-selects the first matching voice when a language change invalidates the previous selected voice.
+- Clears Voice, disables Speak, and logs a visible failure when the selected Language has no matching voices.
+- Preserved the existing queue payload shape and required queue item fields.
+
+## Tool Completion Status
+
+Failing behavior before: Language and Voice were independent, so selecting Language did not change audible voice behavior or the Voice dropdown contents.
+
+Tool fixed: `text2speach-V2`.
+
+Remaining failures after targeted validation: none found in `npm run test:workspace-v2`.
+
+## Playwright Impact
+
+Playwright impacted: Yes.
+
+Coverage added/updated for:
+
+- language-first control ordering
+- dynamic Voice filtering by selected Language
+- auto-selection of the first matching voice when the prior Voice becomes invalid
+- invalid voice reset behavior when a language has no matching voices
+- visible Voice match counts/details
+- delayed `voiceschanged` population respecting the selected Language filter
+- existing full TTS options, schema-valid default queue, speech actions, and Workspace Manager V2 launch behavior
+
+Expected pass behavior: Language controls the Voice list, Voice never shows non-matching voices, selection adjustments are logged, and Speak is disabled when no matching voice exists.
+
+Expected fail behavior: tests fail if Language is not first, non-matching voices appear, an invalid selected Voice remains active, Voice match details are missing, or delayed voice population ignores the language filter.
+
+## Validation
+
+Passed:
+
+```text
+npm run test:workspace-v2
+```
+
+Result:
+
+```text
+26 passed
+```
+
+Additional checks:
+
+```text
+node --check src/engine/audio/TextToSpeechDefaults.js
+node --check tools/text2speach-V2/js/controls/SpeechOptionsControl.js
+node --check tools/text2speach-V2/js/TextToSpeechToolApp.js
+node --check tools/text2speach-V2/js/bootstrap.js
+node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs
+node -e "JSON.parse(require('node:fs').readFileSync('tools/schemas/tools/text2speach-V2.schema.json','utf8'));"
+git diff --check
+```
+
+The workspace-v2 Playwright run also generated advisory V8 coverage reports:
+
+- `docs/dev/reports/playwright_v8_coverage_report.txt`
+- `docs/dev/reports/coverage_changed_js_guardrail.txt`
+
+## Full Samples Smoke Test
+
+Skipped. The full samples smoke test is intentionally out of scope because this PR is limited to text2speach-V2 language/voice filtering behavior and targeted Workspace Manager V2 coverage, not broad sample runtime behavior.
+
+## ZIP Artifact
+
+Repo-structured delta ZIP:
+
+```text
+tmp/PR_26130_010-text2speach-v2-language-filtering_delta.zip
+```
+
+## Manual Validation Steps
+
+1. Open `tools/text2speach-V2/index.html`.
+2. Confirm Language appears above Voice in Speech Options.
+3. Confirm the default `en-US` language shows only matching `en-US` voices and the visible Voice details line reports match count/name details.
+4. Change Language to `en-GB`; Voice should auto-select the first matching `en-GB` voice and the status log should report the adjustment.
+5. Change Language to a locale with no available voices; Voice should clear, Speak should disable, and the status log should explain that no matching voice exists.
+6. Change back to a language with matching voices and confirm Speak becomes available again.
+
+Expected outcome: Voice options are always language-filtered, selection changes are visible/logged, and no non-matching or hidden fallback voice is used.
+
+## Changed Files
+
+- `src/engine/audio/TextToSpeechDefaults.js`
+- `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- `tools/schemas/tools/text2speach-V2.schema.json`
+- `tools/text2speach-V2/index.html`
+- `tools/text2speach-V2/js/TextToSpeechToolApp.js`
+- `tools/text2speach-V2/js/bootstrap.js`
+- `tools/text2speach-V2/js/controls/SpeechOptionsControl.js`
+- `tools/text2speach-V2/styles/text2speach-V2.css`
+- `docs/dev/reports/PR_26130_010-text2speach-v2-language-filtering.md`
+- `docs/dev/reports/codex_review.diff`
+- `docs/dev/reports/codex_changed_files.txt`
+- `docs/dev/reports/playwright_v8_coverage_report.txt`
+- `docs/dev/reports/coverage_changed_js_guardrail.txt`
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`

src/engine/audio/TextToSpeechDefaults.js

@@ -47,8 +47,8 @@ const TEXT_TO_SPEECH_QUEUE_ITEM_REQUIRED_FIELDS = Object.freeze([
   "id",
   "name",
   "text",
-  "voice",
   "language",
+  "voice",
   "volume",
   "rate",
   "pitch",

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -850,8 +850,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       "id",
       "name",
       "text",
-      "voice",
       "language",
+      "voice",
       "volume",
       "rate",
       "pitch",
@@ -878,11 +878,13 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#text2speach-V2ResumeButton")).toBeEnabled();
       await expect(page.locator("#text2speach-V2StopButton")).toBeEnabled();
       await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Loaded 3 schema-complete text2speach-V2 queue items\./);
-      await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Loaded 3 SpeechSynthesis voices for text2speach-V2\./);
+      await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Loaded 2 matching SpeechSynthesis voices for text2speach-V2 \(3 available; language=en-US\)\./);
       await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK text2speach-V2 ready\. SpeechSynthesis is available\./);
       expect(await page.locator("#text2speach-V2QueueSelect option").evaluateAll((options) => options.map((option) => option.value))).toEqual(["narrator-welcome", "hero-ready", "alert-warning"]);
-      expect(await page.locator("#text2speach-V2VoiceSelect option").evaluateAll((options) => options.map((option) => option.value))).toEqual(["mock-us", "mock-uk", "mock-alert"]);
+      expect(await page.locator("#text2speach-V2SpeechOptionsContent label").evaluateAll((labels) => labels.map((label) => label.getAttribute("for")).slice(0, 2))).toEqual(["text2speach-V2LanguageSelect", "text2speach-V2VoiceSelect"]);
       expect(await page.locator("#text2speach-V2LanguageSelect option").evaluateAll((options) => options.map((option) => option.value))).toEqual(["en-US", "en-GB", "es-ES", "fr-FR", "ja-JP"]);
+      expect(await page.locator("#text2speach-V2VoiceSelect option").evaluateAll((options) => options.map((option) => option.value))).toEqual(["mock-us", "mock-alert"]);
+      await expect(page.locator("#text2speach-V2VoiceDetails")).toHaveText("2 voices match en-US: Mock US Voice, Mock Alert Voice.");
       expect(await page.locator("#text2speach-V2QueueModeSelect option").evaluateAll((options) => options.map((option) => option.value))).toEqual(["replace", "append"]);
       expect(await page.locator("#text2speach-V2RepeatCountSelect option").evaluateAll((options) => options.map((option) => option.value))).toEqual(["1", "2", "3", "loop"]);
       expect(await page.locator("#text2speach-V2CharacterPresetSelect option").evaluateAll((options) => options.map((option) => option.value))).toEqual(["narrator", "hero", "villain", "alert"]);
@@ -934,8 +936,20 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#text2speach-V2SpeechText")).toHaveValue("Systems ready. The hero prompt is queued for an upbeat menu confirmation.");
       await page.locator("#text2speach-V2SpeechText").fill("Mission control confirms launch readiness.");
       await expect(page.locator("#text2speach-V2SpeakButton")).toBeEnabled();
-      await page.locator("#text2speach-V2VoiceSelect").selectOption("mock-uk");
       await page.locator("#text2speach-V2LanguageSelect").selectOption("en-GB");
+      await expect(page.locator("#text2speach-V2VoiceSelect option")).toHaveText(["Mock UK Voice (en-GB)"]);
+      await expect(page.locator("#text2speach-V2VoiceSelect")).toHaveValue("mock-uk");
+      await expect(page.locator("#text2speach-V2VoiceDetails")).toHaveText("1 voice matches en-GB: Mock UK Voice.");
+      await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Voice selection adjusted for language en-GB: Mock UK Voice \(en-GB\)\./);
+      await page.locator("#text2speach-V2LanguageSelect").selectOption("es-ES");
+      await expect(page.locator("#text2speach-V2VoiceSelect option")).toHaveText(["No voices for es-ES"]);
+      await expect(page.locator("#text2speach-V2VoiceSelect")).toHaveValue("");
+      await expect(page.locator("#text2speach-V2SpeakButton")).toBeDisabled();
+      await expect(page.locator("#text2speach-V2VoiceDetails")).toHaveText("0 voices match es-ES. 3 total voices loaded.");
+      await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/FAIL Voice selection cleared for language es-ES: no matching SpeechSynthesis voices\./);
+      await page.locator("#text2speach-V2LanguageSelect").selectOption("en-GB");
+      await expect(page.locator("#text2speach-V2VoiceSelect")).toHaveValue("mock-uk");
+      await expect(page.locator("#text2speach-V2SpeakButton")).toBeEnabled();
       await page.locator("#text2speach-V2QueueModeSelect").selectOption("append");
       await page.locator("#text2speach-V2RepeatCountSelect").selectOption("3");
       await page.locator("#text2speach-V2CharacterPresetSelect").selectOption("villain");
@@ -992,11 +1006,12 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#text2speach-V2SpeakButton")).toBeDisabled();
       await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/FAIL text2speach-V2 voice dropdown has no SpeechSynthesis voices; waiting for voiceschanged\. Speak is disabled\./);
       await page.evaluate(() => window["__text2speach-V2LoadVoices"]());
-      await expect(page.locator("#text2speach-V2VoiceSelect option")).toHaveCount(3);
-      expect(await page.locator("#text2speach-V2VoiceSelect option").evaluateAll((options) => options.map((option) => option.value))).toEqual(["mock-us", "mock-uk", "mock-alert"]);
+      await expect(page.locator("#text2speach-V2VoiceSelect option")).toHaveCount(2);
+      expect(await page.locator("#text2speach-V2VoiceSelect option").evaluateAll((options) => options.map((option) => option.value))).toEqual(["mock-us", "mock-alert"]);
       await expect(page.locator("#text2speach-V2VoiceSelect")).toHaveValue("mock-us");
+      await expect(page.locator("#text2speach-V2VoiceDetails")).toHaveText("2 voices match en-US: Mock US Voice, Mock Alert Voice.");
       await expect(page.locator("#text2speach-V2SpeakButton")).toBeEnabled();
-      await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Updated 3 SpeechSynthesis voices for text2speach-V2\./);
+      await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Updated 2 matching SpeechSynthesis voices for text2speach-V2 \(3 available; language=en-US\)\./);
       const summary = JSON.parse(await page.locator("#text2speach-V2SpeechSummary").textContent());
       expect(summary.status).toBe("voices-updated");
       expect(summary.voice).toBe("mock-us");
@@ -2538,7 +2553,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#text2speach-V2WorkspacePauseButton")).toBeEnabled();
       await expect(page.locator("#text2speach-V2WorkspaceResumeButton")).toBeEnabled();
       await expect(page.locator("#text2speach-V2WorkspaceStopButton")).toBeEnabled();
-      await expect(page.locator("#text2speach-V2VoiceSelect option")).toHaveCount(3);
+      await expect(page.locator("#text2speach-V2VoiceSelect option")).toHaveCount(2);
       await page.locator("#text2speach-V2WorkspaceSpeakButton").click();
       await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Speak queued: en-US; voice=Mock US Voice; rate=1; pitch=1; volume=1; repeats=1\./);
       const spoken = await page.evaluate(() => window["__text2speach-V2Spoken"]);

tools/schemas/tools/text2speach-V2.schema.json

@@ -37,8 +37,8 @@
         "id",
         "name",
         "text",
-        "voice",
         "language",
+        "voice",
         "volume",
         "rate",
         "pitch",
@@ -63,13 +63,13 @@
           "type": "string",
           "minLength": 1
         },
-        "voice": {
-          "type": "string"
-        },
         "language": {
           "type": "string",
           "enum": ["en-US", "en-GB", "es-ES", "fr-FR", "ja-JP"]
         },
+        "voice": {
+          "type": "string"
+        },
         "volume": {
           "type": "number",
           "minimum": 0,

tools/text2speach-V2/index.html

@@ -85,14 +85,15 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
             <span class="accordion-v2__icon" aria-hidden="true">+</span>
           </button>
           <div id="text2speach-V2SpeechOptionsContent" class="accordion-v2__content text2speach-V2__options">
-            <label class="text2speach-V2__field" for="text2speach-V2VoiceSelect">
-              <span>Voice</span>
-              <select id="text2speach-V2VoiceSelect"></select>
-            </label>
             <label class="text2speach-V2__field" for="text2speach-V2LanguageSelect">
               <span>Language</span>
               <select id="text2speach-V2LanguageSelect"></select>
             </label>
+            <label class="text2speach-V2__field" for="text2speach-V2VoiceSelect">
+              <span>Voice</span>
+              <select id="text2speach-V2VoiceSelect"></select>
+            </label>
+            <div id="text2speach-V2VoiceDetails" class="text2speach-V2__details" aria-live="polite">No voice data loaded.</div>
             <label class="text2speach-V2__field" for="text2speach-V2VolumeSlider">
               <span>Volume <output id="text2speach-V2VolumeOutput" for="text2speach-V2VolumeSlider"></output></span>
               <input id="text2speach-V2VolumeSlider" type="range">

tools/text2speach-V2/js/TextToSpeechToolApp.js

@@ -79,7 +79,10 @@ export class TextToSpeechToolApp {
       onInput: () => this.refreshOutputSummary("text-updated")
     });
     this.speechOptions.mount({
-      onChange: () => {
+      onChange: ({ controlId } = {}) => {
+        if (controlId === "language") {
+          this.refreshVoices("language-changed");
+        }
         this.refreshOutputSummary("settings-updated");
         if (this.speechOptions.value().autoSpeak) {
           this.speak();
@@ -140,11 +143,23 @@ export class TextToSpeechToolApp {
 
   refreshVoices(source = "initial") {
     const result = this.speechOptions.populateVoices(this.engine.voiceOptions(), this.speechOptions.value().voice);
-    if (result.voiceCount > 0) {
-      const action = source === "voiceschanged" ? "Updated" : "Loaded";
-      this.statusLog.ok(`${action} ${result.voiceCount} SpeechSynthesis voices for text2speach-V2.`);
+    if (result.matchingVoiceCount > 0) {
+      const action = source === "voiceschanged"
+        ? "Updated"
+        : source === "initial" ? "Loaded" : "Filtered";
+      this.statusLog.ok(`${action} ${result.matchingVoiceCount} matching SpeechSynthesis voices for text2speach-V2 (${result.voiceCount} available; language=${result.language}).`);
     } else {
-      this.statusLog.fail("text2speach-V2 voice dropdown has no SpeechSynthesis voices; waiting for voiceschanged. Speak is disabled.");
+      const message = result.voiceCount === 0
+        ? "text2speach-V2 voice dropdown has no SpeechSynthesis voices; waiting for voiceschanged. Speak is disabled."
+        : `text2speach-V2 voice dropdown has no SpeechSynthesis voices matching ${result.language}; voice selection cleared. Speak is disabled.`;
+      this.statusLog.fail(message);
+    }
+    if (source === "language-changed" && result.selectionAdjusted) {
+      if (result.selectedVoice) {
+        this.statusLog.ok(`Voice selection adjusted for language ${result.language}: ${result.selectedVoiceLabel}.`);
+      } else {
+        this.statusLog.fail(`Voice selection cleared for language ${result.language}: no matching SpeechSynthesis voices.`);
+      }
     }
     this.refreshActionState();
     return result;
@@ -157,6 +172,9 @@ export class TextToSpeechToolApp {
     }
     this.textInput.setText(item.text);
     this.speechOptions.setValue(item);
+    if (status !== "queue-loaded") {
+      this.refreshVoices(status);
+    }
     this.refreshOutputSummary(status);
   }
 

tools/text2speach-V2/js/bootstrap.js

@@ -61,6 +61,7 @@ window.addEventListener("DOMContentLoaded", () => {
       rateSlider: requireElement("#text2speach-V2RateSlider"),
       repeatCountSelect: requireElement("#text2speach-V2RepeatCountSelect"),
       ssmlLikePresetSelect: requireElement("#text2speach-V2SsmlLikePresetSelect"),
+      voiceDetails: requireElement("#text2speach-V2VoiceDetails"),
       voiceSelect: requireElement("#text2speach-V2VoiceSelect"),
       volumeOutput: requireElement("#text2speach-V2VolumeOutput"),
       volumeSlider: requireElement("#text2speach-V2VolumeSlider")