PR_26171_006-016 Laptop BUILD docs for Messages, TTS, playback, and MIDI roadmap

Author: ToolboxAid

docs_build/pr/BUILD_PR_26171_006-message-emotion-profile-management.md

@@ -0,0 +1,83 @@
+# BUILD PR_26171_006-message-emotion-profile-management
+
+## Branch Name
+
+`pr/PR_26171_006-message-emotion-profile-management`
+
+## Purpose
+
+Strengthen Messages Emotion Profile management by making profile usage visible and preventing accidental deactivation of profiles that are currently referenced by messages or message segments.
+
+## Exact Scope
+
+- Extend the Messages Local API emotion profile payloads with computed usage diagnostics:
+  - `messageUsageCount`
+  - `segmentUsageCount`
+  - `usageCount`
+  - `references`
+- Count references from `messages_records.emotionProfileKey` and `messages_segments.emotionProfileKey`.
+- Preserve add, edit, and Active/Inactive behavior for unreferenced emotion profiles.
+- Block attempts to deactivate an emotion profile when it is referenced by any message or segment.
+- Display usage counts in the Emotion Profiles table.
+- Display visible actionable diagnostics when profile deactivation is blocked.
+- Add targeted test coverage for profile usage counts and referenced-profile deactivation blocking.
+
+## Out Of Scope
+
+- Delete endpoints.
+- Text To Speech profiles.
+- Speech preview.
+- Voice provider adapters.
+- Runtime playback contracts.
+- Audio generation or playback.
+- Schema changes unless required for computed usage diagnostics.
+- Changes to Messages, Categories, or Segments behavior beyond profile reference diagnostics.
+
+## Files Likely Affected
+
+- `src/dev-runtime/messages/messages-sqlite-service.mjs`
+- `toolbox/messages/messages.js`
+- `toolbox/messages/index.html`
+- `tests/playwright/tools/MessagesTool.spec.mjs`
+- `docs_build/dev/reports/*`
+
+## API/DB Rules
+
+- Browser must keep using the Messages Local API.
+- Browser must not read or write SQLite directly.
+- No delete endpoint may be introduced.
+- Usage diagnostics are computed from existing Messages SQLite tables.
+- No browser-owned product data or local storage source of truth.
+- Server/API retains authoritative key and audit ownership.
+
+## Theme V2 Rules
+
+- Use existing Theme V2 classes only.
+- Do not add page-local CSS, tool-local CSS, inline styles, `<style>` blocks, inline scripts, or inline event handlers.
+- Keep event wiring in external JavaScript.
+
+## Validation
+
+- Verify branch starts from clean `main`.
+- Run `node --check` on touched JavaScript files.
+- Run targeted Messages Local API validation for usage counts and deactivate blocking.
+- Run `npx playwright test tests/playwright/tools/MessagesTool.spec.mjs --project=playwright --workers=1 --reporter=list`.
+- Run `npm run test:workspace-v2`.
+- Run `git diff --check`.
+
+## Manual Test Notes
+
+- Create a message using an active emotion profile.
+- Confirm the profile row shows a nonzero usage count.
+- Attempt to disable the referenced profile.
+- Confirm the save is blocked with a visible actionable message.
+- Confirm an unreferenced profile can still be disabled.
+
+## Required Reports
+
+- `docs_build/dev/reports/codex_review.diff`
+- `docs_build/dev/reports/codex_changed_files.txt`
+- `docs_build/dev/reports/PR_26171_006-message-emotion-profile-management.md`
+- `docs_build/dev/reports/PR_26171_006-message-emotion-profile-management-validation.txt`
+- `docs_build/dev/reports/PR_26171_006-message-emotion-profile-management-manual-validation.md`
+- `tmp/PR_26171_006-message-emotion-profile-management_delta.zip`

docs_build/pr/BUILD_PR_26171_008-message-tts-profile-foundation.md

@@ -0,0 +1,98 @@
+# BUILD PR_26171_008-message-tts-profile-foundation
+
+## Branch Name
+
+`pr/PR_26171_008-message-tts-profile-foundation`
+
+## Purpose
+
+Add server-owned Text To Speech profile configuration for Messages so future speech preview and playback can choose reusable speech settings without generating audio yet.
+
+## Exact Scope
+
+- Add `messages_tts_profiles` persistence under the grouped `messages` ownership area.
+- Add Local API contracts for TTS Profiles:
+  - list
+  - get
+  - create
+  - update
+- Add server-seeded default TTS profiles:
+  - Browser Speech Default
+  - Narration Preview
+- TTS profile fields:
+  - Name
+  - Description
+  - Provider Key
+  - Voice Name
+  - Language
+  - Volume
+  - Pitch
+  - Rate
+  - Active / Inactive
+- Add a Theme V2 TTS Profiles management section to the existing Messages tool.
+- TTS profiles are configuration records only in this PR.
+
+## Out Of Scope
+
+- Speech preview.
+- Speech synthesis.
+- Audio playback.
+- Audio file generation.
+- Voice provider adapters beyond storing a provider key string.
+- Runtime message playback.
+- Dialog trees, localization, translation, or AI voices.
+- Delete endpoints.
+
+## Files Likely Affected
+
+- `src/dev-runtime/messages/messages-sqlite-service.mjs`
+- `toolbox/messages/messages-api-client.js`
+- `toolbox/messages/messages.js`
+- `toolbox/messages/index.html`
+- `docs_build/database/ddl/messages.sql`
+- `docs_build/database/dml/messages.sql`
+- `docs_build/database/seed/messages.json`
+- `tests/playwright/tools/MessagesTool.spec.mjs`
+- `docs_build/dev/reports/*`
+
+## API/DB Rules
+
+- Browser must use Local API contracts only.
+- Browser must not generate authoritative keys.
+- SQLite service must generate keys and audit fields.
+- No delete endpoints.
+- TTS profiles must live under the `messages` ownership group.
+- Missing required fields must fail visibly and actionably.
+
+## Theme V2 Rules
+
+- Use existing Theme V2 form, table, card, status, and action classes.
+- Do not add new CSS unless documented as a reusable Theme V2 gap.
+- No inline styles, `<style>` blocks, inline scripts, or inline event handlers.
+
+## Validation
+
+- Verify branch starts from clean `main`.
+- Run `node --check` on touched JavaScript files.
+- Run targeted Local API/SQLite validation for TTS profile seed, create, update, and restart persistence.
+- Run targeted Messages Playwright validation.
+- Run `npm run test:workspace-v2`.
+- Run `git diff --check`.
+
+## Manual Test Notes
+
+- Confirm seeded TTS profiles appear in the Messages UI.
+- Create a custom TTS profile.
+- Edit its voice/configuration fields.
+- Disable and re-enable the profile.
+- Restart Local API against the same SQLite file and confirm persistence.
+- Confirm no speech preview or audio playback occurs in this PR.
+
+## Required Reports
+
+- `docs_build/dev/reports/codex_review.diff`
+- `docs_build/dev/reports/codex_changed_files.txt`
+- `docs_build/dev/reports/PR_26171_008-message-tts-profile-foundation.md`
+- `docs_build/dev/reports/PR_26171_008-message-tts-profile-foundation-validation.txt`
+- `docs_build/dev/reports/PR_26171_008-message-tts-profile-foundation-manual-validation.md`
+- `tmp/PR_26171_008-message-tts-profile-foundation_delta.zip`

docs_build/pr/BUILD_PR_26171_010-message-speech-preview.md

@@ -0,0 +1,84 @@
+# BUILD PR_26171_010-message-speech-preview
+
+## Branch Name
+
+`pr/PR_26171_010-message-speech-preview`
+
+## Purpose
+
+Add a browser-local speech preview workflow for Messages using the existing Message, Segment, Emotion Profile, and TTS Profile configuration records.
+
+## Exact Scope
+
+- Add a Theme V2 Speech Preview section to the Messages tool.
+- Allow previewing:
+  - selected full message text
+  - selected ordered active message segments
+- Use selected or default active TTS Profile settings for preview controls.
+- Use selected segment Emotion Profile settings when previewing segments.
+- Use browser `speechSynthesis` when available.
+- Show a visible actionable diagnostic when browser speech synthesis is unavailable.
+- Add Stop Preview behavior.
+- Add external JavaScript-only preview controller logic inside `toolbox/messages/messages.js`.
+- Add tests that stub browser speech synthesis and validate preview payloads without requiring real audio output.
+
+## Out Of Scope
+
+- Server-side TTS generation.
+- Audio file generation or persistence.
+- External AI voices.
+- Voice provider adapters beyond direct browser speech preview.
+- Runtime playback API.
+- Dialog trees, localization, translation, or game runtime integration.
+- Storing preview history.
+
+## Files Likely Affected
+
+- `toolbox/messages/index.html`
+- `toolbox/messages/messages.js`
+- `tests/playwright/tools/MessagesTool.spec.mjs`
+- `docs_build/dev/reports/*`
+
+## API/DB Rules
+
+- Speech preview reads existing Local API data already loaded by the Messages UI.
+- No new persistence is required.
+- Browser preview state must not become product-data source of truth.
+- No new server endpoint in this PR unless required only for diagnostics.
+
+## Theme V2 Rules
+
+- Use existing Theme V2 UI classes.
+- No page-local CSS or tool-local CSS.
+- No inline styles, `<style>` blocks, inline scripts, or inline event handlers.
+- Stop and preview buttons must be wired from external JavaScript.
+
+## Validation
+
+- Verify branch starts from clean `main`.
+- Run `node --check` on touched JavaScript files.
+- Run targeted Messages Playwright validation with stubbed `speechSynthesis`.
+- Validate preview selected message.
+- Validate preview active ordered segments.
+- Validate Stop Preview.
+- Validate unavailable speech synthesis diagnostic.
+- Run `npm run test:workspace-v2`.
+- Run `git diff --check`.
+
+## Manual Test Notes
+
+- Select or create a message.
+- Create two active segments with different emotion profiles.
+- Click Preview Message and confirm the status log reports a preview request.
+- Click Preview Segments and confirm ordered segment preview is requested.
+- Click Stop Preview and confirm preview stops.
+- Simulate missing browser speech support and confirm visible diagnostic.
+
+## Required Reports
+
+- `docs_build/dev/reports/codex_review.diff`
+- `docs_build/dev/reports/codex_changed_files.txt`
+- `docs_build/dev/reports/PR_26171_010-message-speech-preview.md`
+- `docs_build/dev/reports/PR_26171_010-message-speech-preview-validation.txt`
+- `docs_build/dev/reports/PR_26171_010-message-speech-preview-manual-validation.md`
+- `tmp/PR_26171_010-message-speech-preview_delta.zip`

docs_build/pr/BUILD_PR_26171_012-message-voice-provider-adapters.md

@@ -0,0 +1,86 @@
+# BUILD PR_26171_012-message-voice-provider-adapters
+
+## Branch Name
+
+`pr/PR_26171_012-message-voice-provider-adapters`
+
+## Purpose
+
+Introduce a small browser-side voice provider adapter registry for Messages speech preview so provider behavior is explicit and future providers can be added without rewriting the Messages UI.
+
+## Exact Scope
+
+- Add a Messages voice provider adapter module.
+- Supported adapters in this PR:
+  - `browser-speech`
+  - `diagnostic-only`
+- Adapter contract:
+  - provider key
+  - display name
+  - availability check
+  - preview method
+  - stop method
+  - diagnostic message
+- Route Speech Preview through the adapter registry.
+- Keep the existing TTS Profile `providerKey` as the selector.
+- Show visible diagnostics for unknown providers and unavailable providers.
+- Add targeted tests for browser-speech, diagnostic-only, and unknown-provider behavior.
+
+## Out Of Scope
+
+- Network providers.
+- AI voices.
+- Secret/API-key handling.
+- Server-side speech generation.
+- Audio file persistence.
+- Runtime playback API.
+- New database tables.
+- Local storage.
+
+## Files Likely Affected
+
+- `toolbox/messages/message-voice-provider-adapters.js`
+- `toolbox/messages/messages.js`
+- `toolbox/messages/index.html`
+- `tests/playwright/tools/MessagesTool.spec.mjs`
+- `docs_build/dev/reports/*`
+
+## API/DB Rules
+
+- No new persistence.
+- No secrets exposed to the browser.
+- Provider adapters must not require environment variables.
+- Browser must continue using safe public UI data only.
+- TTS Profile provider keys remain configuration only.
+
+## Theme V2 Rules
+
+- Use existing Theme V2 status/logging patterns.
+- No inline styles, `<style>` blocks, inline scripts, or inline event handlers.
+- No tool-local CSS.
+
+## Validation
+
+- Verify branch starts from clean `main`.
+- Run `node --check` on touched JavaScript files.
+- Run targeted adapter unit/static validation if added.
+- Run targeted Messages Playwright validation for provider routing.
+- Run `npm run test:workspace-v2`.
+- Run `git diff --check`.
+
+## Manual Test Notes
+
+- Select a TTS Profile with `browser-speech`.
+- Confirm preview routes through the browser-speech adapter.
+- Select or create a profile with `diagnostic-only`.
+- Confirm no audio is attempted and a visible diagnostic is shown.
+- Use an unknown provider key and confirm an actionable error.
+
+## Required Reports
+
+- `docs_build/dev/reports/codex_review.diff`
+- `docs_build/dev/reports/codex_changed_files.txt`
+- `docs_build/dev/reports/PR_26171_012-message-voice-provider-adapters.md`
+- `docs_build/dev/reports/PR_26171_012-message-voice-provider-adapters-validation.txt`
+- `docs_build/dev/reports/PR_26171_012-message-voice-provider-adapters-manual-validation.md`
+- `tmp/PR_26171_012-message-voice-provider-adapters_delta.zip`