Merge branch 'main' of https://github.com/ToolboxAid/HTML-JavaScript-Gaming

# Conflicts:
#	docs_build/dev/reports/codex_changed_files.txt
#	docs_build/dev/reports/codex_review.diff

Author: ToolboxAid

docs_build/dev/reports/PR_26171_016-message-studio-speech-test-and-tts-service-picker-manual-validation.txt

@@ -0,0 +1,18 @@
+PR_26171_016-message-studio-speech-test-and-tts-service-picker manual validation notes
+
+Reviewed Message Studio speech test behavior:
+- Speech Test accordion now includes TTS Service and TTS Profile selectors.
+- TTS Service is sourced from the existing TextToSpeechEngine browser path.
+- Test Speech is disabled before a message or segment target is selected.
+- Test Speech uses the selected message row text when a message row is selected.
+- Test Speech uses selected segment text when a segment row is selected.
+- Selected item readout updates between message row and segment row targets.
+- Browser speech synthesis unavailable state is visible and disables the service/test action.
+
+Reviewed prior Text to Speech locations:
+- Active engine remains in src/engine/audio/TextToSpeechEngine.js.
+- toolbox/text-to-speech/index.html is a placeholder Voice Output page.
+- archive/v1-v2/tools/old_text2speech-V2 contains the older full tool implementation.
+- No active toolbox/tts or toolbox/text2speech-V2 folder is present.
+
+No external providers, provider keys, AI voices, server audio generation, or audio persistence were manually exercised because they are out of scope.

docs_build/dev/reports/PR_26171_016-message-studio-speech-test-and-tts-service-picker-validation.txt

@@ -0,0 +1,32 @@
+PR_26171_016-message-studio-speech-test-and-tts-service-picker validation report
+
+Branch:
+PASS - Implemented on pr/26171-016-message-studio-speech-test-and-tts-service-picker.
+
+Static checks:
+PASS - node --check toolbox/messages/message-tts-service-registry.js
+PASS - node --check toolbox/messages/messages.js
+PASS - node --check tests/playwright/tools/MessagesTool.spec.mjs
+PASS - node --check src/engine/audio/TextToSpeechEngine.js
+PASS - git diff --check
+
+Targeted scans:
+PASS - Message Studio contains no external provider/API-key references.
+PASS - No new SQLite persistence was added. Existing SQLite references are limited to the pre-existing Messages Playwright harness/dev adapter path.
+
+Targeted Playwright:
+PASS - npx playwright test tests/playwright/tools/MessagesTool.spec.mjs --workers=1 --reporter=list
+Validated:
+- TTS service selector renders existing Browser Speech Synthesis service.
+- Test Speech button is disabled before required selections exist.
+- Message row speech test calls the existing browser-safe TextToSpeechEngine path.
+- Segment row speech test calls the existing browser-safe TextToSpeechEngine path.
+- No old Preview Message, Preview Segments, or Stop Preview controls are present.
+
+Requested workspace lane:
+FAIL - npm run test:workspace-v2
+Failure scope:
+- RootToolsFutureState.spec.mjs existing root/tool/navigation/API failures outside Message Studio.
+
+Samples:
+SKIPPED - Full samples smoke was out of scope.

docs_build/dev/reports/PR_26171_016-message-studio-speech-test-and-tts-service-picker.md

@@ -0,0 +1,67 @@
+# PR_26171_016-message-studio-speech-test-and-tts-service-picker
+
+## Branch Validation
+
+PASS - Work was implemented on `pr/26171-016-message-studio-speech-test-and-tts-service-picker` after starting from `main`.
+
+## Summary
+
+Message Studio now exposes a TTS Service picker and guarded Test Speech action. The picker is sourced from the existing browser-safe `TextToSpeechEngine` path, and speech tests run only through browser `SpeechSynthesis` when that engine is available. No external provider calls, API keys, AI voice generation, audio generation, or new database persistence were added.
+
+## Prior Text To Speech Search
+
+- PASS - `src/engine/audio/TextToSpeechEngine.js` exists and still provides the browser-safe speech engine path.
+- PASS - `src/engine/audio/TextToSpeechDefaults.js` exists and still defines Text to Speech V2 defaults.
+- PASS - `toolbox/text-to-speech/index.html` exists as a public Voice Output placeholder/wireframe.
+- PASS - `toolbox/tts/` does not exist.
+- PASS - Active `toolbox/text2speech-V2/` is not present.
+- PASS - The older full Text to Speech V2 implementation is archived under `archive/v1-v2/tools/old_text2speech-V2/`.
+- PASS - Shared Text to Speech contracts/schemas still exist under `src/shared/contracts/tools/textToSpeechContract.js` and `src/shared/schemas/tools/text2speech-V2.schema.json`.
+
+## Requirement Checklist
+
+- PASS - Searched the requested TTS locations and broader speech/TTS references.
+- PASS - Added a TTS Service dropdown to Message Studio.
+- PASS - Service options come from `TextToSpeechEngine` through `toolbox/messages/message-tts-service-registry.js`.
+- PASS - Added unavailable/disabled service state when browser speech synthesis is unavailable.
+- PASS - Added a Test Speech button for the selected Message Row or selected Segment Row.
+- PASS - Button remains disabled until a service, message or segment, emotion profile, active TTS profile, and voice are available.
+- PASS - Test Speech uses browser-local speech only through the existing engine.
+- PASS - No external provider calls, AI voice generation, API keys, or generated audio were introduced.
+- PASS - No new SQLite persistence, SQLite DDL, SQLite seed data, or SQLite service was introduced.
+- PASS - Existing SQLite references remain test/dev technical debt only; the report documents Postgres as authoritative direction.
+
+## Impacted Lane
+
+Message Studio Theme V2 tool, existing browser-safe TTS engine integration, and targeted Message Studio Playwright coverage.
+
+## Validation Summary
+
+- PASS - `node --check toolbox/messages/message-tts-service-registry.js`
+- PASS - `node --check toolbox/messages/messages.js`
+- PASS - `node --check tests/playwright/tools/MessagesTool.spec.mjs`
+- PASS - `node --check src/engine/audio/TextToSpeechEngine.js`
+- PASS - `npx playwright test tests/playwright/tools/MessagesTool.spec.mjs --workers=1 --reporter=list`
+- PASS - External provider/API-key scan returned no Message Studio matches.
+- PASS - `git diff --check`
+- FAIL - `npm run test:workspace-v2` failed in existing `RootToolsFutureState.spec.mjs` coverage outside this PR scope.
+
+## Workspace V2 Failure Details
+
+The required `npm run test:workspace-v2` command failed with five failures:
+
+- `root tools surface links current tool pages without old_* routes`: expected toolbox accordion cards, received zero.
+- `common header renders primary navigation order across active pages`: existing Game Journey/Game Hub alphabetical expectation mismatch.
+- `learn wireframe pages load with shared Theme V2 structure`: unrelated failed requests for `/api/session/current` and `/api/platform-settings/banner`.
+- `tool template future-state page loads from root Theme V2 paths`: unrelated failed requests for `/api/session/current`, `/api/toolbox/registry/snapshot`, and `/api/platform-settings/banner`.
+- `representative active tool pages align center cleanup and registry group colors`: unrelated failed requests for toolbox constants, registry snapshot, session, and banner endpoints.
+
+These failures were not introduced by the Message Studio speech test picker changes and were not fixed because they are outside this PR scope.
+
+## Database Direction
+
+Postgres remains authoritative. This PR did not add SQLite persistence or new SQLite runtime behavior. The existing Message Studio Playwright harness still uses the legacy dev SQLite adapter and is documented as technical debt only.
+
+## Samples Decision
+
+SKIPPED - Full samples validation was not run because samples are outside the Message Studio speech test and TTS service picker scope.

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -8,7 +8,8 @@ Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
 Changed runtime JS files considered:
 (0%) src/dev-runtime/messages/messages-sqlite-service.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (79%) toolbox/messages/messages-api-client.js - executed lines 64/64; executed functions 15/19
-(100%) toolbox/messages/messages.js - executed lines 990/990; executed functions 88/88
+(97%) toolbox/messages/messages.js - executed lines 1183/1183; executed functions 108/111
+(100%) toolbox/messages/message-tts-service-registry.js - executed lines 36/36; executed functions 6/6
 
 Guardrail warnings:
 (0%) src/dev-runtime/messages/messages-sqlite-service.mjs - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -12,23 +12,27 @@ Note: entry percentages use function coverage when available, otherwise line cov
 Note: coverage entries are aggregated across every page/tool where coverageReporter.start(page) and coverageReporter.stop(page) ran.
 
 Exercised tool entry points detected:
-(92%) Toolbox Index - exercised 3 runtime JS files
+(92%) Toolbox Index - exercised 4 runtime JS files
 (0%) Tool Template V2 - not exercised by this Playwright run
 (56%) Theme V2 Shared JS - exercised 2 runtime JS files
 
 Changed runtime JS files covered:
 (0%) src/dev-runtime/messages/messages-sqlite-service.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (79%) toolbox/messages/messages-api-client.js - executed lines 64/64; executed functions 15/19
-(100%) toolbox/messages/messages.js - executed lines 990/990; executed functions 88/88
+(97%) toolbox/messages/messages.js - executed lines 1183/1183; executed functions 108/111
+(100%) toolbox/messages/message-tts-service-registry.js - executed lines 36/36; executed functions 6/6
 
 Files with executed line/function counts where available:
 (36%) src/api/server-api-client.js - executed lines 167/167; executed functions 5/14
 (38%) src/api/public-config-client.js - executed lines 209/209; executed functions 10/26
+(50%) src/engine/audio/TextToSpeechEngine.js - executed lines 229/229; executed functions 13/26
 (54%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 977/977; executed functions 46/85
 (64%) assets/theme-v2/js/tool-display-mode.js - executed lines 209/209; executed functions 9/14
 (76%) toolbox/tool-registry-api-client.js - executed lines 155/155; executed functions 22/29
 (79%) toolbox/messages/messages-api-client.js - executed lines 64/64; executed functions 15/19
-(100%) toolbox/messages/messages.js - executed lines 990/990; executed functions 88/88
+(97%) toolbox/messages/messages.js - executed lines 1183/1183; executed functions 108/111
+(100%) src/engine/audio/TextToSpeechDefaults.js - executed lines 108/108; executed functions 1/1
+(100%) toolbox/messages/message-tts-service-registry.js - executed lines 36/36; executed functions 6/6
 
 Uncovered or low-coverage changed JS files:
 (0%) src/dev-runtime/messages/messages-sqlite-service.mjs - WARNING: uncovered changed runtime JS file; advisory only
@@ -37,4 +41,5 @@ Changed JS files considered:
 (0%) src/dev-runtime/messages/messages-sqlite-service.mjs - changed JS file not collected as browser runtime coverage
 (0%) tests/playwright/tools/MessagesTool.spec.mjs - changed JS file not collected as browser runtime coverage
 (79%) toolbox/messages/messages-api-client.js - changed JS file with browser V8 coverage
-(100%) toolbox/messages/messages.js - changed JS file with browser V8 coverage
+(97%) toolbox/messages/messages.js - changed JS file with browser V8 coverage
+(100%) toolbox/messages/message-tts-service-registry.js - changed JS file with browser V8 coverage

tests/playwright/tools/MessagesTool.spec.mjs

@@ -43,7 +43,7 @@ test.afterAll(async () => {
   await workspaceV2CoverageReporter.writeReport();
 });
 
-async function openMessagesPage(page, sqlitePath) {
+async function openMessagesPage(page, sqlitePath, options = {}) {
   const previousMessagesSqlitePath = process.env.GAMEFOUNDRY_MESSAGES_SQLITE_PATH;
   process.env.GAMEFOUNDRY_MESSAGES_SQLITE_PATH = sqlitePath;
   const server = await startRepoServer();
@@ -73,13 +73,18 @@ async function openMessagesPage(page, sqlitePath) {
     failures.failedRequests.push(`FAILED ${request.url()}`);
   });
 
-  await page.addInitScript(({ apiUrl }) => {
+  await page.addInitScript(({ apiUrl, speechAvailable }) => {
     window.GameFoundryPublicConfig = {
       apiUrl,
       environmentLabel: "Development Environment",
       siteUrl: window.location.origin,
     };
     window.__messagesSpeechCalls = [];
+    if (!speechAvailable) {
+      Object.defineProperty(window, "SpeechSynthesisUtterance", { configurable: true, value: undefined });
+      Object.defineProperty(window, "speechSynthesis", { configurable: true, value: undefined });
+      return;
+    }
     Object.defineProperty(window, "SpeechSynthesisUtterance", {
       configurable: true,
       value: class SpeechSynthesisUtterance {
@@ -95,15 +100,24 @@ async function openMessagesPage(page, sqlitePath) {
           window.__messagesSpeechCalls.push({ type: "cancel" });
         },
         getVoices() {
-          return [{ lang: "en-US", name: "Test Voice" }];
+          return [{ lang: "en-US", name: "Test Voice", voiceURI: "test-voice-uri" }];
         },
         speak(utterance) {
-          window.__messagesSpeechCalls.push({ text: utterance.text, type: "speak" });
+          window.__messagesSpeechCalls.push({
+            lang: utterance.lang,
+            pitch: utterance.pitch,
+            rate: utterance.rate,
+            text: utterance.text,
+            type: "speak",
+            voiceName: utterance.voice?.name || "",
+            volume: utterance.volume,
+          });
         },
       },
     });
   }, {
     apiUrl: `${server.baseUrl}/api`,
+    speechAvailable: options.speechAvailable !== false,
   });
   await workspaceV2CoverageReporter.start(page);
   await page.goto(`${server.baseUrl}/tools/messages/index.html`, { waitUntil: "networkidle" });
@@ -168,7 +182,9 @@ test("Message Studio uses table governance, validates rows, and persists through
     await expect(page.locator("[data-messages-category]")).toHaveCount(0);
     await expect(page.getByRole("button", { name: /delete/i })).toHaveCount(0);
     await expect(page.locator("[data-messages-persistence-engine]")).toHaveText("Postgres target");
-    await expect(page.locator("[data-messages-preview-status]")).toHaveText("No playback, provider calls, or audio generation run from Message Studio.");
+    await expect(page.locator("[data-messages-tts-service]")).toHaveValue("browser-speech-synthesis");
+    await expect(page.locator("[data-messages-preview-status]")).toHaveText("Select a message row or segment row before testing speech.");
+    await expect(page.locator("[data-messages-test-speech]")).toBeDisabled();
     await expect(page.locator("[data-messages-preview-message], [data-messages-preview-segments], [data-messages-preview-stop]")).toHaveCount(0);
 
     await expect(page.locator("[data-messages-emotions]")).toContainText("Calm");
@@ -191,15 +207,14 @@ test("Message Studio uses table governance, validates rows, and persists through
     await page.locator("[data-messages-tts-row]").filter({ hasText: "Arcade Browser Voice" }).getByRole("button", { name: "Edit" }).click();
     await page.locator("[data-messages-tts-editor] [data-tts-language]").fill("en-GB");
     await page.locator("[data-messages-tts-editor] [data-messages-tts-commit]").click();
-    await page.locator("[data-messages-tts-row]").filter({ hasText: "Arcade Browser Voice" }).getByRole("button", { name: "Disable" }).click();
-    await expect(page.locator("[data-messages-tts-row]").filter({ hasText: "Arcade Browser Voice" })).toContainText("Inactive");
+    await expect(page.locator("[data-messages-tts-row]").filter({ hasText: "Arcade Browser Voice" })).toContainText("Active");
 
     const ttsProfilesResult = await jsonRequest(`${failures.server.baseUrl}/api/messages/tts-profiles`);
     expect(ttsProfilesResult.response.ok).toBe(true);
     expect(ttsProfilesResult.payload.ok).toBe(true);
     const createdTtsProfile = ttsProfilesResult.payload.data.ttsProfiles.find((profile) => profile.name === "Arcade Browser Voice");
     expect(createdTtsProfile).toEqual(expect.objectContaining({
-      active: false,
+      active: true,
       language: "en-GB",
       providerKey: "browser-speech",
       voiceName: "Test Voice",
@@ -266,9 +281,41 @@ test("Message Studio uses table governance, validates rows, and persists through
     await expect(page.locator("[data-messages-log]")).toHaveText("Updated segment row 2.");
     await expect(page.locator("[data-messages-segment-row]")).toHaveCount(2);
 
-    const speechCalls = await page.evaluate(() => window.__messagesSpeechCalls);
+    let speechCalls = await page.evaluate(() => window.__messagesSpeechCalls);
     expect(speechCalls).toEqual([]);
 
+    await page.locator("[data-messages-preview-tts-profile]").selectOption({ label: "Arcade Browser Voice" });
+    await page.locator("[data-messages-row]").filter({ hasText: "Forest Warning" }).click();
+    await expect(page.locator("[data-messages-speech-test-target]")).toHaveText("Message Row: Forest Warning");
+    await expect(page.locator("[data-messages-test-speech]")).toBeEnabled();
+    await page.locator("[data-messages-test-speech]").click();
+    await expect(page.locator("[data-messages-preview-status]")).toHaveText("Speech test started for Message Row: Forest Warning using Browser Speech Synthesis.");
+    speechCalls = await page.evaluate(() => window.__messagesSpeechCalls);
+    expect(speechCalls.at(-1)).toEqual(expect.objectContaining({
+      lang: "en-GB",
+      pitch: 1.08,
+      rate: 1.15,
+      text: "The forest gets darker beyond this point.\nWe are being attacked by bats.",
+      type: "speak",
+      voiceName: "Test Voice",
+      volume: 1,
+    }));
+
+    await page.locator("[data-messages-segment-row]").filter({ hasText: "The forest gets darker beyond this point." }).click();
+    await expect(page.locator("[data-messages-speech-test-target]")).toHaveText("Segment 1");
+    await page.locator("[data-messages-test-speech]").click();
+    await expect(page.locator("[data-messages-preview-status]")).toHaveText("Speech test started for Segment 1 using Browser Speech Synthesis.");
+    speechCalls = await page.evaluate(() => window.__messagesSpeechCalls);
+    expect(speechCalls.at(-1)).toEqual(expect.objectContaining({
+      lang: "en-GB",
+      pitch: 1,
+      rate: 1,
+      text: "The forest gets darker beyond this point.",
+      type: "speak",
+      voiceName: "Test Voice",
+      volume: 1,
+    }));
+
     const segmentsResult = await jsonRequest(`${failures.server.baseUrl}/api/messages/segments`);
     expect(segmentsResult.response.ok).toBe(true);
     expect(segmentsResult.payload.ok).toBe(true);
@@ -325,6 +372,10 @@ test("Message Studio uses table governance, validates rows, and persists through
       name: "Forest Warning Updated",
     }));
 
+    await page.locator("[data-messages-tts-row]").filter({ hasText: "Arcade Browser Voice" }).getByRole("button", { name: "Disable" }).click();
+    await expect(page.locator("[data-messages-log]")).toHaveText("Disabled TTS profile Arcade Browser Voice.");
+    await expect(page.locator("[data-messages-tts-row]").filter({ hasText: "Arcade Browser Voice" })).toContainText("Inactive");
+
     for (const url of [
       `${failures.server.baseUrl}/api/messages/messages/${createdMessage.key}`,
       `${failures.server.baseUrl}/api/messages/segments/${disabledSegment.key}`,