Refine Text to Speech V2 layout voices presets and item controls - PR_26130_015-text-to-speech-v2-layout-controls

Author: DavidQ

docs/dev/reports/PR_26130_015-text-to-speech-v2-layout-controls.md

@@ -0,0 +1,143 @@
+# PR_26130_015-text-to-speech-v2-layout-controls
+
+## Purpose
+
+Polish Text to Speech V2 layout controls, queue item actions, and speech option constraints while keeping the internal tool id `text2speach-V2`.
+
+## Scope
+
+Changed Text to Speech V2 runtime, schema/defaults, related shared audio TTS defaults/engine clamp behavior, and Workspace Manager V2 Playwright coverage for this tool only.
+
+No unrelated files were modified. No `start_of_day` files were changed.
+
+## Implementation Summary
+
+- Set Pitch minimum to `0.1` in defaults, schema, and utterance clamp behavior.
+- Restored neutral/unknown voices to helper filtering buckets so preferred gender filters do not hide available language coverage.
+- Replaced the Text to Speech V2 header frame pattern with the same local common header layout pattern used by Palette Manager V2, while keeping the visible title `Text to Speech V2`.
+- Moved Text into the center column as its own accordion, removed the center speech preview div, and renamed the preview area to `Named Sentences`.
+- Replaced the named sentence dropdown with selectable tiles and moved Speak/Pause/Resume/Stop controls to the top of the Named Sentences accordion.
+- Changed the status action order to X then Clear.
+- Added the exact visible character preset label `D&D Dungeon Master`.
+- Added Speech Options Add, Duplicate, and Delete buttons.
+- Wired Add/Duplicate/Delete to maintain a complete schema-valid queue, preserve a selected item, and mark workspace toolState dirty for item and option changes.
+
+## Playwright Impact
+
+Playwright impacted: Yes.
+
+The Workspace Manager V2 Playwright suite validates:
+
+- Text to Speech V2 visible naming and header layout contract.
+- Pitch minimum `0.1` in UI and schema.
+- Neutral/unknown voices restored in preferred gender helper buckets.
+- Text accordion placement in the center column.
+- Named Sentences tiles replacing the old dropdown.
+- Speak/Pause/Resume/Stop at the top of Named Sentences.
+- Status action order as X then Clear.
+- `D&D Dungeon Master` preset presence and slider effects.
+- Add/Duplicate/Delete item behavior and dirty toolState persistence.
+
+Expected pass behavior: controls render in the requested order/layout, speech items hydrate and mutate schema-valid queue data, and dirty state is updated after queue/text/options changes.
+
+Expected fail behavior: Playwright fails if the legacy dropdown/header/preview patterns return, if queue item mutations leave invalid state, or if requested controls are missing or misordered.
+
+## 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/bootstrap.js
+node --check tools/text2speach-V2/js/controls/QueueControl.js
+node --check tools/text2speach-V2/js/controls/OutputSummaryControl.js
+node --check tools/text2speach-V2/js/controls/SpeechOptionsControl.js
+node --check tools/text2speach-V2/js/controls/TextInputControl.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')); console.log('schema ok')"
+git diff --check HEAD -- .
+rg -n -P "<script(?![^>]*\bsrc=)|<style|\son[a-zA-Z]+=" tools/text2speach-V2/index.html
+rg -n "tools/shared|imageDataUrl|start_of_day" src/engine/audio tools/text2speach-V2 tools/schemas/tools/text2speach-V2.schema.json tests/playwright/tools/WorkspaceManagerV2.spec.mjs
+```
+
+The inline HTML restriction scan and forbidden-scope scan returned no matches. `git diff --check` reported only existing Windows line-ending warnings and no whitespace errors.
+
+## V8 Coverage
+
+The `npm run test:workspace-v2` run generated the Playwright V8 coverage report at:
+
+```text
+docs/dev/reports/playwright_v8_coverage_report.txt
+```
+
+Changed runtime JS coverage included:
+
+- `src/engine/audio/TextToSpeechDefaults.js`
+- `src/engine/audio/TextToSpeechEngine.js`
+- `tools/text2speach-V2/js/TextToSpeechToolApp.js`
+- `tools/text2speach-V2/js/bootstrap.js`
+- `tools/text2speach-V2/js/controls/OutputSummaryControl.js`
+- `tools/text2speach-V2/js/controls/QueueControl.js`
+- `tools/text2speach-V2/js/controls/SpeechOptionsControl.js`
+- `tools/text2speach-V2/js/controls/TextInputControl.js`
+
+The coverage guard reported no low-coverage changed runtime JS files.
+
+## Full Samples Smoke Test
+
+Skipped. This PR is limited to Text to Speech V2 layout, schema/defaults, runtime queue controls, and Workspace Manager V2 tool launch coverage. It does not modify the shared sample loader, sample JSON, or broad game launch behavior.
+
+## ZIP Artifact
+
+Repo-structured delta ZIP:
+
+```text
+tmp/PR_26130_015-text-to-speech-v2-layout-controls_delta.zip
+```
+
+## Manual Validation Steps
+
+1. Open `tools/text2speach-V2/index.html`.
+2. Confirm the header matches the Palette Manager V2-style common header layout and the visible title is `Text to Speech V2`.
+3. Confirm the center column shows Text above Named Sentences, with no speech preview div.
+4. Confirm Named Sentences uses selectable tiles and has Speak, Pause, Resume, and Stop at the top.
+5. Confirm Speech Options shows Add, Duplicate, and Delete at the bottom.
+6. Select a named sentence tile and confirm Speech Options and Text hydrate from that item.
+7. Use Add, Duplicate, and Delete and confirm the queue never becomes empty or invalid.
+8. Change text/options and confirm Workspace Manager V2 marks the Text to Speech V2 toolState dirty when launched from the workspace.
+
+Expected outcome: the requested Text to Speech V2 layout and controls are present, queue item actions preserve valid toolState data, and dirty state changes after edits.
+
+## 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/index.html`
+- `tools/text2speach-V2/js/TextToSpeechToolApp.js`
+- `tools/text2speach-V2/js/bootstrap.js`
+- `tools/text2speach-V2/js/controls/OutputSummaryControl.js`
+- `tools/text2speach-V2/js/controls/QueueControl.js`
+- `tools/text2speach-V2/js/controls/SpeechOptionsControl.js`
+- `tools/text2speach-V2/js/controls/TextInputControl.js`
+- `tools/text2speach-V2/styles/text2speach-V2.css`
+- `docs/dev/reports/PR_26130_015-text-to-speech-v2-layout-controls.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

@@ -49,6 +49,7 @@ const TEXT_TO_SPEECH_CHARACTER_PRESET_OPTIONS = Object.freeze([
   Object.freeze({ label: "Manual", value: "manual" }),
   Object.freeze({ label: "Alert", value: "alert" }),
   Object.freeze({ label: "Calm", value: "calm" }),
+  Object.freeze({ label: "D&D Dungeon Master", value: "dnd-dungeon-master" }),
   Object.freeze({ label: "Dramatic", value: "dramatic" }),
   Object.freeze({ label: "Narrator", value: "narrator" }),
   Object.freeze({ label: "Robot", value: "robot" })
@@ -68,14 +69,15 @@ 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 }),
+  pitch: Object.freeze({ max: 2, 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 })
 });
 
 const TEXT_TO_SPEECH_CHARACTER_PRESET_DEFAULTS = Object.freeze({
   alert: Object.freeze({ pitch: 0.9, rate: 1.3, ssmlLikePreset: "normal", volume: 1 }),
   calm: Object.freeze({ pitch: 1, rate: 0.8, ssmlLikePreset: "normal", volume: 1 }),
+  "dnd-dungeon-master": Object.freeze({ pitch: 0.7, rate: 0.9, ssmlLikePreset: "normal", volume: 1 }),
   dramatic: Object.freeze({ pitch: 1.2, rate: 1.1, ssmlLikePreset: "normal", volume: 1 }),
   manual: Object.freeze({ pitch: 1, rate: 1, ssmlLikePreset: "normal", volume: 1 }),
   narrator: Object.freeze({ pitch: 1, rate: 1, ssmlLikePreset: "normal", volume: 1 }),

src/engine/audio/TextToSpeechEngine.js

@@ -133,7 +133,11 @@ class TextToSpeechEngine {
 
     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.pitch = boundedNumber(pitch, {
+      fallback: TEXT_TO_SPEECH_DEFAULTS.pitch,
+      max: TEXT_TO_SPEECH_RANGE_DEFAULTS.pitch.max,
+      min: TEXT_TO_SPEECH_RANGE_DEFAULTS.pitch.min
+    });
     utterance.rate = boundedNumber(rate, {
       fallback: TEXT_TO_SPEECH_DEFAULTS.rate,
       max: TEXT_TO_SPEECH_RANGE_DEFAULTS.rate.max,