# AI Text-to-Speech Playback

## Objective

Read app content and AI answers aloud, with a voice and speed the user controls.

A playback control that speaks selected content aloud with voice, speed, seek, and stop controls.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Pick the content genuinely worth hearing — long answers, articles, briefs — and put the playback control beside the text rather than in place of it.
2. Generate long content as ordered segments and queue the next one while the current is playing, so playback is continuous and a pause and resume returns to the same position instead of restarting a segment.
3. Authorize the text before synthesizing it, using the same permission check that governs reading the record. Otherwise playback becomes a route to hear content the account cannot open.
4. Cache generated audio against the text and the voice settings that produced it, and invalidate that cache when the text changes. Regenerating identical audio on every replay is a bill with no benefit.
5. Do not treat this as the app's accessibility story. Screen reader users need correct semantics and readable markup; spoken playback is a convenience layered on top of that, not a replacement for it.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Segment boundaries are where playback goes wrong. A gap between segments, or a sentence repeated because a segment restarted, is immediately obvious to a listener.
- Changing the underlying content, navigating away, or editing the text mid-playback must stop the audio at once and discard the queued segments, not carry on reading the previous version.
- Only text the current user is permitted to read may be sent for synthesis, and a cached audio file must not be servable to another account by guessing its address.
- Written text, transcripts, and controls must remain on screen. Content that exists only as audio is unreachable for anyone who cannot or does not want to listen.
- Provider failure, an unsupported language, and a voice that has been withdrawn are three different problems. Fall back to another available voice where sensible, and otherwise leave the text readable with the control disabled and explained.
- Mobile browsers block audio that starts without a user gesture, and playback stops when the tab is backgrounded on some platforms. Start only from an explicit action and restore position when the user returns.
- Cap the amount of text synthesized in one request and per account per period, because a listener who starts playback on a very long document can otherwise run up cost in a single click.
- Code blocks, tables, URLs, and markup read aloud badly. Strip or summarize them before synthesis rather than spelling out punctuation.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Playback of long content is continuous, with no gap or repeated passage at segment boundaries.
- [ ] Pause, resume, seek, speed, and voice selection all work and the position survives a pause.
- [ ] Changing or leaving the content stops playback immediately and clears the queue.
- [ ] Synthesis and cached audio are both restricted to text the requesting user may read.
- [ ] Repeated playback of unchanged text serves cached audio rather than generating again.
- [ ] A provider outage, unsupported language, or removed voice leaves the written content fully usable with a clear explanation.
- [ ] Per-request and per-account synthesis limits are enforced.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.