Add Text to Speech engine and backend roadmap items to planned tools section - PR_26130_014-tools-roadmap-tts-engine-planning

Author: DavidQ

docs/dev/reports/PR_26130_013-text-to-speech-v2-polish.md

@@ -0,0 +1,114 @@
+# PR_26130_013-text-to-speech-v2-polish
+
+## Purpose
+
+Polish the existing `text2speach-V2` tool so user-facing surfaces read as `Text to Speech V2`, the header follows the shared first-class tool shell pattern, named sentence selection fully hydrates Speech Options, and Rate / Speed is capped to the practical browser `speechSynthesis` range used by the tool.
+
+## Scope
+
+Changed only Text to Speech V2 runtime/defaults/schema/UI, the visible tool registry/workspace navigation labels needed for launch surfaces, and targeted Workspace Manager V2 Playwright coverage.
+
+The internal tool id, schema id, DOM ids, path, folder, and workspace toolState key remain `text2speach-V2`.
+
+No `start_of_day` files were changed.
+
+## Implementation Summary
+
+- Updated visible tool title, card/nav labels, how-to/readme naming, sample copy, status messages, queue data name, and schema title to `Text to Speech V2`.
+- Added the shared `toolShellCommon.css` header frame and kept the tool-specific header class for scoped styling/tests.
+- Renamed the left queue accordion to `Named Sentences`.
+- Added complete named sentence defaults so each queue item carries language, voice, gender, age, presets, queue mode, auto speak, repeat, delay, volume, rate, pitch, and text.
+- Fixed named sentence selection hydration by rebinding the requested queue item voice when the selected item changes, preventing the previous voice selection from leaking into the newly selected item.
+- Added `gender` to required queue item options and to the schema/default queue payload.
+- Capped Rate / Speed at `2` in defaults, schema, UI range setup, engine utterance clamping, and Playwright assertions.
+
+## Playwright Impact
+
+Playwright impacted: Yes.
+
+Coverage added/updated for:
+
+- visible `Text to Speech V2` naming on the tools index, direct tool page, and Workspace Manager V2 launch tile
+- shared header layout class on the Text to Speech V2 intro/header
+- `Named Sentences` accordion label
+- schema-complete named sentence defaults including required `gender`
+- named sentence selection hydrating all Speech Options fields from selected JSON data
+- Rate / Speed slider maximum and schema maximum capped at `2`
+- updated status log text using the visible `Text to Speech V2` label
+
+Expected pass behavior: selecting each named sentence updates text, gender, language, voice, age, presets, queue mode, repeat, delay, volume, rate, pitch, and summary state from the selected JSON item.
+
+Expected fail behavior: tests fail if visible naming regresses to `text2speach-V2`, the shared header frame is missing, Rate / Speed exceeds `2`, queue items are schema-incomplete, or named sentence selection preserves stale option values.
+
+## Validation
+
+Passed:
+
+```text
+npm run test:workspace-v2
+```
+
+Result:
+
+```text
+28 passed
+```
+
+Additional checks passed:
+
+```text
+node --check src/engine/audio/TextToSpeechDefaults.js
+node --check src/engine/audio/TextToSpeechEngine.js
+node --check tools/text2speach-V2/js/TextToSpeechToolApp.js
+node --check tools/text2speach-V2/js/controls/SpeechOptionsControl.js
+node --check tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js
+node --check tools/toolRegistry.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'));"
+rg -n -P "<script(?![^>]*\bsrc=)|<style|\son[a-zA-Z]+=" tools/text2speach-V2/index.html tools/text2speach-V2/how_to_use.html
+git diff --check HEAD -- .
+```
+
+The inline HTML restriction scan returned no matches. `git diff --check` reported only the existing Windows line-ending warnings and no whitespace errors.
+
+## Full Samples Smoke Test
+
+Skipped. The full samples smoke test is intentionally out of scope because this PR is limited to Text to Speech V2 polish, schema/default alignment, named sentence hydration, and targeted Workspace Manager V2 Playwright coverage.
+
+## ZIP Artifact
+
+Repo-structured delta ZIP:
+
+```text
+tmp/PR_26130_013-text-to-speech-v2-polish_delta.zip
+```
+
+## Manual Validation Steps
+
+1. Open `tools/text2speach-V2/index.html`.
+2. Confirm the browser title and visible heading read `Text to Speech V2`.
+3. Confirm the intro/header uses the shared first-class tool shell framing and the queue accordion reads `Named Sentences`.
+4. Select `Alert warning`, `Narrator welcome`, and `Hero ready`; Speech Options should update every option from the selected named sentence.
+5. Confirm Rate / Speed cannot exceed `2`.
+
+Expected outcome: user-facing naming is polished, the internal `text2speach-V2` contract is preserved, named sentences hydrate all speech options, and the practical Rate / Speed cap is enforced.
+
+## Changed Files
+
+- `src/engine/audio/TextToSpeechDefaults.js`
+- `src/engine/audio/TextToSpeechEngine.js`
+- `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- `tools/schemas/tools/text2speach-V2.schema.json`
+- `tools/text2speach-V2/README.md`
+- `tools/text2speach-V2/how_to_use.html`
+- `tools/text2speach-V2/index.html`
+- `tools/text2speach-V2/js/TextToSpeechToolApp.js`
+- `tools/text2speach-V2/js/controls/SpeechOptionsControl.js`
+- `tools/text2speach-V2/styles/text2speach-V2.css`
+- `tools/toolRegistry.js`
+- `tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js`
+- `docs/dev/reports/PR_26130_013-text-to-speech-v2-polish.md`
+- `docs/dev/reports/codex_review.diff`
+- `docs/dev/reports/codex_changed_files.txt`
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`

src/engine/audio/TextToSpeechDefaults.js

@@ -1,6 +1,7 @@
 const TEXT_TO_SPEECH_TOOL_ID = "text2speach-V2";
 const TEXT_TO_SPEECH_SCHEMA_ID = "tools/schemas/tools/text2speach-V2.schema.json";
 const TEXT_TO_SPEECH_PAYLOAD_SCHEMA = "html-js-gaming.text2speach-V2";
+const TEXT_TO_SPEECH_DISPLAY_NAME = "Text to Speech V2";
 
 const TEXT_TO_SPEECH_LANGUAGE_OPTIONS = Object.freeze([
   Object.freeze({ label: "English (UK)", value: "en-GB" }),
@@ -68,7 +69,7 @@ const TEXT_TO_SPEECH_SSML_LIKE_PRESET_DEFAULTS = Object.freeze({
 const TEXT_TO_SPEECH_RANGE_DEFAULTS = Object.freeze({
   delayBetweenRepeatsMs: Object.freeze({ max: 5000, min: 0, step: 100, value: 0 }),
   pitch: Object.freeze({ max: 2, min: 0, step: 0.1, value: 1 }),
-  rate: Object.freeze({ max: 10, min: 0.1, step: 0.1, value: 1 }),
+  rate: Object.freeze({ max: 2, min: 0.1, step: 0.1, value: 1 }),
   volume: Object.freeze({ max: 1, min: 0, step: 0.01, value: 1 })
 });
 
@@ -85,6 +86,7 @@ const TEXT_TO_SPEECH_QUEUE_ITEM_REQUIRED_FIELDS = Object.freeze([
   "id",
   "name",
   "text",
+  "gender",
   "language",
   "voice",
   "voiceAge",
@@ -103,6 +105,7 @@ const TEXT_TO_SPEECH_DEFAULT_OPTIONS = Object.freeze({
   autoSpeak: false,
   characterPreset: "manual",
   delayBetweenRepeatsMs: TEXT_TO_SPEECH_RANGE_DEFAULTS.delayBetweenRepeatsMs.value,
+  gender: "any",
   language: "en-US",
   pitch: TEXT_TO_SPEECH_CHARACTER_PRESET_DEFAULTS.manual.pitch,
   queueMode: "replace",
@@ -119,33 +122,58 @@ const TEXT_TO_SPEECH_DEFAULT_QUEUE = Object.freeze([
     ...TEXT_TO_SPEECH_DEFAULT_OPTIONS,
     ...TEXT_TO_SPEECH_CHARACTER_PRESET_DEFAULTS.narrator,
     characterPreset: "narrator",
+    gender: "any",
     id: "narrator-welcome",
+    language: "en-US",
     name: "Narrator welcome",
-    text: "Welcome to Toolbox Aid. This is the default text2speach-V2 sample line for previewing narration, prompts, and menu feedback."
+    text: "Welcome to Toolbox Aid. This is the default Text to Speech V2 sample line for previewing narration, prompts, and menu feedback.",
+    voice: "mock-google-us-english",
+    voiceAge: "any"
   }),
   Object.freeze({
     ...TEXT_TO_SPEECH_DEFAULT_OPTIONS,
     ...TEXT_TO_SPEECH_CHARACTER_PRESET_DEFAULTS.dramatic,
+    autoSpeak: false,
     characterPreset: "dramatic",
+    delayBetweenRepeatsMs: 500,
+    gender: "male-preferred",
     id: "hero-ready",
+    language: "en-GB",
     name: "Hero ready",
-    text: "Systems ready. The hero prompt is queued for an upbeat menu confirmation."
+    pitch: 1.4,
+    queueMode: "append",
+    rate: 1.2,
+    repeatCount: 2,
+    text: "Systems ready. The hero prompt is queued for an upbeat menu confirmation.",
+    voice: "mock-google-uk-english-male",
+    voiceAge: "teen"
   }),
   Object.freeze({
     ...TEXT_TO_SPEECH_DEFAULT_OPTIONS,
     ...TEXT_TO_SPEECH_CHARACTER_PRESET_DEFAULTS.alert,
+    autoSpeak: false,
     characterPreset: "alert",
+    delayBetweenRepeatsMs: 1000,
+    gender: "female-preferred",
     id: "alert-warning",
+    language: "en-US",
     name: "Alert warning",
-    text: "Warning. Incoming hazard detected. Please confirm the next action."
+    pitch: 0.9,
+    queueMode: "replace",
+    rate: 1.3,
+    repeatCount: 3,
+    text: "Warning. Incoming hazard detected. Please confirm the next action.",
+    voice: "mock-microsoft-zira",
+    voiceAge: "adult",
+    volume: 0.9
   })
 ]);
 
 const TEXT_TO_SPEECH_DEFAULT_QUEUE_DATA = Object.freeze({
   $schema: TEXT_TO_SPEECH_SCHEMA_ID,
   schema: TEXT_TO_SPEECH_PAYLOAD_SCHEMA,
   version: 1,
-  name: "text2speach-V2 default queue",
+  name: "Text to Speech V2 default queue",
   queue: TEXT_TO_SPEECH_DEFAULT_QUEUE
 });
 
@@ -164,6 +192,7 @@ export {
   TEXT_TO_SPEECH_DEFAULT_QUEUE,
   TEXT_TO_SPEECH_DEFAULT_QUEUE_DATA,
   TEXT_TO_SPEECH_DEFAULTS,
+  TEXT_TO_SPEECH_DISPLAY_NAME,
   TEXT_TO_SPEECH_GENDER_FILTER_OPTIONS,
   TEXT_TO_SPEECH_LANGUAGE_OPTIONS,
   TEXT_TO_SPEECH_PAYLOAD_SCHEMA,

src/engine/audio/TextToSpeechEngine.js

@@ -1,4 +1,8 @@
-import { TEXT_TO_SPEECH_DEFAULTS } from "./TextToSpeechDefaults.js";
+import {
+  TEXT_TO_SPEECH_DEFAULTS,
+  TEXT_TO_SPEECH_DISPLAY_NAME,
+  TEXT_TO_SPEECH_RANGE_DEFAULTS
+} from "./TextToSpeechDefaults.js";
 
 function finiteNumber(value, fallback) {
   const number = Number(value);
@@ -119,18 +123,22 @@ class TextToSpeechEngine {
 
     const normalizedText = String(text || "").trim();
     if (!normalizedText) {
-      return { message: "text2speach-V2 text is required before speaking.", ok: false };
+      return { message: `${TEXT_TO_SPEECH_DISPLAY_NAME} text is required before speaking.`, ok: false };
     }
 
     const selectedVoice = this.voiceForValue(voice);
     if (!selectedVoice) {
-      return { message: `text2speach-V2 voice is required before speaking: ${voice || "(none selected)"}.`, ok: false };
+      return { message: `${TEXT_TO_SPEECH_DISPLAY_NAME} voice is required before speaking: ${voice || "(none selected)"}.`, ok: false };
     }
 
     const utterance = new this.Utterance(normalizedText);
     utterance.lang = String(language || selectedVoice.lang || TEXT_TO_SPEECH_DEFAULTS.language);
     utterance.pitch = boundedNumber(pitch, { fallback: TEXT_TO_SPEECH_DEFAULTS.pitch, max: 2, min: 0 });
-    utterance.rate = boundedNumber(rate, { fallback: TEXT_TO_SPEECH_DEFAULTS.rate, max: 10, min: 0.1 });
+    utterance.rate = boundedNumber(rate, {
+      fallback: TEXT_TO_SPEECH_DEFAULTS.rate,
+      max: TEXT_TO_SPEECH_RANGE_DEFAULTS.rate.max,
+      min: TEXT_TO_SPEECH_RANGE_DEFAULTS.rate.min
+    });
     utterance.volume = boundedNumber(volume, { fallback: TEXT_TO_SPEECH_DEFAULTS.volume, max: 1, min: 0 });
     utterance.voice = selectedVoice;
     return {
@@ -160,6 +168,7 @@ class TextToSpeechEngine {
     autoSpeak = TEXT_TO_SPEECH_DEFAULTS.autoSpeak,
     characterPreset = TEXT_TO_SPEECH_DEFAULTS.characterPreset,
     delayBetweenRepeatsMs = TEXT_TO_SPEECH_DEFAULTS.delayBetweenRepeatsMs,
+    gender = TEXT_TO_SPEECH_DEFAULTS.gender,
     language = TEXT_TO_SPEECH_DEFAULTS.language,
     pitch = TEXT_TO_SPEECH_DEFAULTS.pitch,
     queueMode = TEXT_TO_SPEECH_DEFAULTS.queueMode,
@@ -180,7 +189,7 @@ class TextToSpeechEngine {
       this.clearScheduledRepeats();
       this.speechSynthesis.cancel();
     } else if (queueMode !== "append") {
-      return { message: `Unsupported text2speach-V2 queueMode: ${queueMode}.`, ok: false };
+      return { message: `Unsupported ${TEXT_TO_SPEECH_DISPLAY_NAME} queueMode: ${queueMode}.`, ok: false };
     }
 
     this.loopCanceled = false;
@@ -215,6 +224,7 @@ class TextToSpeechEngine {
       autoSpeak: autoSpeak === true,
       characterPreset,
       delayBetweenRepeatsMs: boundedNumber(delayBetweenRepeatsMs, { fallback: 0, max: 60000, min: 0 }),
+      gender,
       language: firstUtterance.utterance.lang,
       ok: true,
       pitch: firstUtterance.utterance.pitch,