Add pitch gender helper labels and voice age tuning notes - PR_26130_012-text2speach-v2-pitch-age-labels

Author: DavidQ

docs/dev/reports/PR_26130_011-text2speach-v2-control-dependency-order.md

@@ -30,6 +30,7 @@ No `start_of_day` files were changed.
   15. Speak / Pause / Resume / Stop
 - Moved Text into the ordered Speech Options flow.
 - Moved Speak/Pause/Resume/Stop to the end of the ordered control flow.
+- Aligned the `text2speach-V2` second header line with the other V2 tool header pattern: concise context in the eyebrow, operational detail in the meta line.
 - Changed Gender to a helper filter with `Any`, `Male Preferred`, and `Female Preferred`.
 - Included unknown and explicit neutral voices in both preferred Gender buckets so language coverage is not lost.
 - Removed claims of true gender transformation from behavior/logging; Gender is logged as a helper filter only.
@@ -56,6 +57,7 @@ Playwright impacted: Yes.
 Coverage added/updated for:
 
 - exact control ordering from Gender through Speak/Pause/Resume/Stop
+- header eyebrow/meta copy matching the V2 tool header pattern
 - Gender-to-Language filtering through preferred helper buckets
 - unknown and explicit neutral voices remaining available under preferred Gender helper buckets
 - Language-to-Voice filtering within the selected Gender helper bucket
@@ -67,9 +69,9 @@ Coverage added/updated for:
 - Voice Age shaping without filtering or clearing the selected Language/Voice
 - Auto Speak and runtime queue action behavior already covered by the speech action path
 
-Expected pass behavior: controls appear in the requested order, Gender helper filters keep unknown/neutral voices available in preferred buckets, Language narrows Voice choices within the selected Gender helper, invalid selected voices are adjusted and logged, presets visibly update sliders, manual slider edits are preserved against later derived shaping, and runtime speech actions still target the current queue/options.
+Expected pass behavior: header copy follows the other V2 tools' eyebrow/meta pattern, controls appear in the requested order, Gender helper filters keep unknown/neutral voices available in preferred buckets, Language narrows Voice choices within the selected Gender helper, invalid selected voices are adjusted and logged, presets visibly update sliders, manual slider edits are preserved against later derived shaping, and runtime speech actions still target the current queue/options.
 
-Expected fail behavior: tests fail if order regresses, Gender loses unknown/neutral voices, Language/Voice filtering breaks, invalid voice reset is silent, preset slider updates stop applying, manual slider edits are overwritten by later Voice Age shaping, Auto Speak no longer queues valid playback, or Speak/Pause/Resume/Stop stop operating on the runtime queue.
+Expected fail behavior: tests fail if the header copy regresses, order regresses, Gender loses unknown/neutral voices, Language/Voice filtering breaks, invalid voice reset is silent, preset slider updates stop applying, manual slider edits are overwritten by later Voice Age shaping, Auto Speak no longer queues valid playback, or Speak/Pause/Resume/Stop stop operating on the runtime queue.
 
 ## Validation
 
@@ -111,7 +113,7 @@ Skipped. The full samples smoke test is intentionally out of scope because this
 Repo-structured delta ZIP:
 
 ```text
-tmp/PR_26130_011-text2speach-v2-control-dependency-order_delta.zip
+tmp/PR_26130_011-text2speach-v2-control-dependency-order-header_delta.zip
 ```
 
 ## Manual Validation Steps

docs/dev/reports/PR_26130_012-text2speach-v2-pitch-age-labels.md

@@ -0,0 +1,116 @@
+# PR_26130_012-text2speach-v2-pitch-age-labels
+
+## Purpose
+
+Add the requested `text2speach-V2` Pitch helper scale and lock Voice Age simulation behavior to visible Rate/Pitch slider updates without claiming true gender conversion.
+
+## Scope
+
+Changed only the `text2speach-V2` UI, existing speech defaults/schema hooks, targeted Workspace Manager V2 Playwright coverage, and required reports.
+
+No `start_of_day` files were changed.
+
+## Implementation Summary
+
+- Added a centered helper scale directly under the Pitch slider:
+
+```text
+Male < Neutral > Female
+```
+
+- Kept the helper visual-only. It labels the pitch direction and does not claim true gender conversion.
+- Renamed Voice Age option/value `elder` to `elderly` across defaults, schema, labels, and Playwright expectations.
+- Kept Voice Age simulation behavior in the existing preset-derived slider path:
+  - `child`: higher pitch, slightly faster rate
+  - `teen`: slightly higher pitch, normal/slightly faster rate
+  - `adult`: neutral pitch and rate
+  - `elderly`: lower pitch, slower rate
+- Preserved manual Rate and Pitch slider authority: once the user edits those sliders, later Voice Age changes do not overwrite those manual values.
+
+## Playwright Impact
+
+Playwright impacted: Yes.
+
+Coverage added/updated for:
+
+- Pitch helper scale text `Male < Neutral > Female`
+- helper scale placement immediately below the Pitch slider
+- helper scale centered alignment
+- Voice Age enum/options using `elderly`
+- Child, Teen, Adult, Elderly, and Any Voice Age slider updates
+- existing manual Rate/Pitch override behavior after Voice Age changes
+
+Expected pass behavior: the Pitch helper appears centered under the Pitch slider, Voice Age selections visibly update Rate/Pitch when sliders are not manually overridden, and manual Rate/Pitch edits remain authoritative.
+
+Expected fail behavior: tests fail if the helper text is missing/misplaced/not centered, if `elderly` is not present in the schema/UI options, if Voice Age no longer updates sliders, or if manual Rate/Pitch edits are overwritten.
+
+## 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 tools/text2speach-V2/js/controls/SpeechOptionsControl.js
+node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs
+node -e "JSON.parse(require('fs').readFileSync('tools/schemas/tools/text2speach-V2.schema.json','utf8')); console.log('schema json ok')"
+rg -n -P "<script(?![^>]*\bsrc=)|<style|\son[a-zA-Z]+=" tools/text2speach-V2/index.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.
+
+The workspace-v2 Playwright run also regenerated advisory V8 coverage reports:
+
+- `docs/dev/reports/playwright_v8_coverage_report.txt`
+- `docs/dev/reports/coverage_changed_js_guardrail.txt`
+
+Changed runtime JavaScript coverage from the guardrail:
+
+- `(98%) tools/text2speach-V2/js/controls/SpeechOptionsControl.js - executed lines 478/478; executed functions 46/47`
+- `(100%) src/engine/audio/TextToSpeechDefaults.js - executed lines 162/162; executed functions 1/1`
+
+## Full Samples Smoke Test
+
+Skipped. The full samples smoke test is intentionally out of scope because this PR is limited to `text2speach-V2` Pitch helper labeling, Voice Age simulation labels/defaults, schema enum alignment, and targeted Workspace Manager V2 Playwright coverage.
+
+## ZIP Artifact
+
+Repo-structured delta ZIP:
+
+```text
+tmp/PR_26130_012-text2speach-v2-pitch-age-labels_delta.zip
+```
+
+## Manual Validation Steps
+
+1. Open `tools/text2speach-V2/index.html`.
+2. Confirm the Pitch slider shows the centered helper scale `Male < Neutral > Female` directly below the slider.
+3. Select Voice Age `Child`, `Teen`, `Adult`, and `Elderly`; Rate and Pitch should update visibly when those sliders have not been manually edited.
+4. Manually change Rate and Pitch, then select another Voice Age; the manual Rate and Pitch values should remain.
+5. Confirm the UI does not describe the Pitch helper as true gender conversion.
+
+Expected outcome: Pitch direction is visually explained, Voice Age simulation affects default Rate/Pitch only while allowed, and manual slider edits win.
+
+## 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/controls/SpeechOptionsControl.js`
+- `tools/text2speach-V2/styles/text2speach-V2.css`
+- `docs/dev/reports/PR_26130_012-text2speach-v2-pitch-age-labels.md`
+- `docs/dev/reports/playwright_v8_coverage_report.txt`
+- `docs/dev/reports/coverage_changed_js_guardrail.txt`

src/engine/audio/TextToSpeechDefaults.js

@@ -20,15 +20,15 @@ const TEXT_TO_SPEECH_AGE_FILTER_OPTIONS = Object.freeze([
   Object.freeze({ label: "Any", value: "any" }),
   Object.freeze({ label: "Adult", value: "adult" }),
   Object.freeze({ label: "Child", value: "child" }),
-  Object.freeze({ label: "Elder", value: "elder" }),
+  Object.freeze({ label: "Elderly", value: "elderly" }),
   Object.freeze({ label: "Teen", value: "teen" })
 ]);
 
 const TEXT_TO_SPEECH_VOICE_AGE_PRESET_DEFAULTS = Object.freeze({
   adult: Object.freeze({ pitchOffset: 0, rateMultiplier: 1 }),
   any: Object.freeze({ pitchOffset: 0, rateMultiplier: 1 }),
   child: Object.freeze({ pitchOffset: 0.4, rateMultiplier: 1.15 }),
-  elder: Object.freeze({ pitchOffset: -0.2, rateMultiplier: 0.85 }),
+  elderly: Object.freeze({ pitchOffset: -0.2, rateMultiplier: 0.85 }),
   teen: Object.freeze({ pitchOffset: 0.2, rateMultiplier: 1.08 })
 });
 

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -91,7 +91,7 @@ const MOCK_TEXT2SPEACH_EN_US_DETAILS = "4 voices match Any / en-US: Google US En
 
 const MOCK_TEXT2SPEACH_GENDER_FILTER_VALUES = ["any", "male-preferred", "female-preferred"];
 
-const MOCK_TEXT2SPEACH_AGE_FILTER_VALUES = ["any", "adult", "child", "elder", "teen"];
+const MOCK_TEXT2SPEACH_AGE_FILTER_VALUES = ["any", "adult", "child", "elderly", "teen"];
 
 const MOCK_TEXT2SPEACH_FEMALE_LANGUAGE_VALUES = [
   "de-DE",
@@ -952,8 +952,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     try {
       await expect(page.locator("body[data-tool-id='text2speach-V2']")).toBeVisible();
       await expect(page.locator("h1")).toHaveText("text2speach-V2");
-      await expect(page.locator(".text2speach-V2__header .tools-platform-frame__eyebrow")).toHaveText("Speech synthesis controls");
-      await expect(page.locator(".text2speach-V2__header .tools-platform-frame__meta")).toHaveText("Configure browser voices, language filters, character presets, and speech controls.");
+      await expect(page.locator(".text2speach-V2__header .tools-platform-frame__eyebrow")).toHaveText("Browser speech synthesis");
+      await expect(page.locator(".text2speach-V2__header .tools-platform-frame__meta")).toHaveText("Configure voices, helper filters, presets, queue behavior, and runtime playback.");
       await expect(page.locator(".text2speach-V2__header .tools-platform-frame__description")).toHaveCount(0);
       await expect(page.locator('[data-launch-mode-nav="tool"]')).toBeVisible();
       await expect(page.locator('[data-launch-mode-nav="workspace"]')).toBeHidden();
@@ -1012,6 +1012,15 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#text2speach-V2PitchSlider")).toHaveAttribute("max", "2");
       await expect(page.locator("#text2speach-V2PitchSlider")).toHaveAttribute("step", "0.1");
       await expect(page.locator("#text2speach-V2PitchSlider")).toHaveValue("1");
+      const pitchHelperScale = page.locator("#text2speach-V2PitchHelperScale");
+      await expect(page.locator("#text2speach-V2PitchSlider + #text2speach-V2PitchHelperScale")).toBeVisible();
+      await expect(pitchHelperScale).toHaveText("Male < Neutral > Female");
+      expect(await pitchHelperScale.evaluate((node) => getComputedStyle(node).textAlign)).toBe("center");
+      const pitchSliderBox = await page.locator("#text2speach-V2PitchSlider").boundingBox();
+      const pitchHelperBox = await pitchHelperScale.boundingBox();
+      expect(pitchSliderBox).not.toBeNull();
+      expect(pitchHelperBox).not.toBeNull();
+      expect(pitchHelperBox.y).toBeGreaterThan(pitchSliderBox.y);
       await expect(page.locator("#text2speach-V2DelayBetweenRepeatsMsSlider")).toHaveAttribute("min", "0");
       await expect(page.locator("#text2speach-V2DelayBetweenRepeatsMsSlider")).toHaveAttribute("max", "5000");
       await expect(page.locator("#text2speach-V2DelayBetweenRepeatsMsSlider")).toHaveAttribute("step", "100");
@@ -1071,6 +1080,22 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#text2speach-V2VoiceSelect")).toHaveValue("mock-google-us-english");
       await expect(page.locator("#text2speach-V2SpeakButton")).toBeEnabled();
       await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Voice Age shaping applied: Any; rate=1\.1; pitch=1\.2\./);
+      await page.locator("#text2speach-V2AgeFilterSelect").selectOption("teen");
+      await expect(page.locator("#text2speach-V2RateSlider")).toHaveValue("1.2");
+      await expect(page.locator("#text2speach-V2PitchSlider")).toHaveValue("1.4");
+      await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Voice Age shaping applied: Teen; rate=1\.2; pitch=1\.4\./);
+      await page.locator("#text2speach-V2AgeFilterSelect").selectOption("adult");
+      await expect(page.locator("#text2speach-V2RateSlider")).toHaveValue("1.1");
+      await expect(page.locator("#text2speach-V2PitchSlider")).toHaveValue("1.2");
+      await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Voice Age shaping applied: Adult; rate=1\.1; pitch=1\.2\./);
+      await page.locator("#text2speach-V2AgeFilterSelect").selectOption("elderly");
+      await expect(page.locator("#text2speach-V2RateSlider")).toHaveValue("0.9");
+      await expect(page.locator("#text2speach-V2PitchSlider")).toHaveValue("1");
+      await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Voice Age shaping applied: Elderly; rate=0\.9; pitch=1\./);
+      await page.locator("#text2speach-V2AgeFilterSelect").selectOption("any");
+      await expect(page.locator("#text2speach-V2RateSlider")).toHaveValue("1.1");
+      await expect(page.locator("#text2speach-V2PitchSlider")).toHaveValue("1.2");
+      await expect(page.locator("#text2speach-V2StatusLog")).toHaveValue(/OK Voice Age shaping applied: Any; rate=1\.1; pitch=1\.2\./);
       await page.locator("#text2speach-V2VoiceSelect").selectOption("mock-microsoft-zira");
       await page.locator("#text2speach-V2GenderFilterSelect").selectOption("male-preferred");
       expect(await page.locator("#text2speach-V2LanguageSelect option").evaluateAll((options) => options.map((option) => option.value))).toEqual(MOCK_TEXT2SPEACH_MALE_LANGUAGE_VALUES);

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

@@ -74,7 +74,7 @@
         },
         "voiceAge": {
           "type": "string",
-          "enum": ["any", "adult", "child", "elder", "teen"]
+          "enum": ["any", "adult", "child", "elderly", "teen"]
         },
         "volume": {
           "type": "number",

tools/text2speach-V2/index.html

@@ -21,10 +21,10 @@
               <div class="tools-platform-frame__accordion-summary">
                 <div class="tools-platform-frame__summary-copy">
                   <h1 class="tools-platform-frame__title" data-tool-id="text2speach-V2">text2speach-V2</h1>
-                  <h2 class="tools-platform-frame__eyebrow">Speech synthesis controls</h2>
+                  <h2 class="tools-platform-frame__eyebrow">Browser speech synthesis</h2>
                 </div>
                 <div class="tools-platform-frame__summary-meta">
-                  <div class="tools-platform-frame__meta">Configure browser voices, language filters, character presets, and speech controls.</div>
+                  <div class="tools-platform-frame__meta">Configure voices, helper filters, presets, queue behavior, and runtime playback.</div>
                 </div>
               </div>
             </div>
@@ -110,6 +110,7 @@ <h2 class="tools-platform-frame__eyebrow">Speech synthesis controls</h2>
             <label class="text2speach-V2__field" for="text2speach-V2PitchSlider">
               <span>Pitch <output id="text2speach-V2PitchOutput" for="text2speach-V2PitchSlider"></output></span>
               <input id="text2speach-V2PitchSlider" type="range">
+              <span id="text2speach-V2PitchHelperScale" class="text2speach-V2__pitch-helper">Male &lt; Neutral &gt; Female</span>
             </label>
             <nav class="text2speach-V2__menu" aria-label="Tool actions" data-launch-mode-nav="tool">
               <button id="text2speach-V2SpeakButton" type="button" disabled>Speak</button>

tools/text2speach-V2/js/controls/SpeechOptionsControl.js

@@ -50,8 +50,8 @@ function ageFilterLabel(value) {
   if (value === "child") {
     return "Child";
   }
-  if (value === "elder") {
-    return "Elder";
+  if (value === "elderly") {
+    return "Elderly";
   }
   if (value === "teen") {
     return "Teen";

tools/text2speach-V2/styles/text2speach-V2.css

@@ -89,6 +89,13 @@
   text-align: right;
 }
 
+.text2speach-V2__pitch-helper {
+  color: var(--text-muted, #cbd5e1);
+  font-size: 0.78rem;
+  font-weight: 700;
+  text-align: center;
+}
+
 .text2speach-V2__details {
   margin-top: -4px;
   margin-bottom: 12px;