# Speaker Labels

## Objective

Split a transcript by who was speaking and let people rename each speaker once.

Speaker attribution on transcript segments, with editable names, merging and splitting of detected speakers, and labels that survive regeneration.

## 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. Store the speaker as an attribute of each transcript segment on the existing transcript record. Do not fork the transcript into a second speaker-aware copy that then drifts from the original.
2. Give each detected speaker a neutral placeholder name and a consistent colour, and let a user rename any speaker from the transcript itself rather than from a separate settings screen.
3. Make renaming a single action that applies to every segment attributed to that speaker, with an undo, and make it obvious how many segments a rename will touch.
4. Provide merge and split for the cases detection gets wrong: merging two placeholder speakers into one person, and reassigning a run of segments to a different speaker.
5. Do not guess a speaker's real identity from participant lists or account names and present it as fact. Suggest a match if you have one, and require a person to confirm it before it becomes the label.

## 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

- Detection routinely over-segments, splitting one person into three, and under-segments, folding two quiet speakers into one. Both need a repair path: merge several detected speakers into one, and split a speaker's segments apart by reassigning them.
- Renaming a speaker must update every occurrence in one action, including segments not currently on screen, and must be undoable as a single step rather than segment by segment.
- Crosstalk, where two people speak at once, will produce overlapping or interleaved segments. Attribute what is confident, mark the rest as uncertain, and never silently drop the overlapping audio's text.
- Regenerating a transcript must not wipe the names a person has already entered. Key the labels to something durable and re-apply them to the new segmentation, telling the user where re-attachment was not possible.
- When diarisation confidence is poor, present the transcript as a single unlabelled speaker. A transcript wrongly split across five imaginary people is worse than one with no labels at all.
- A speaker name is typed once and then follows the transcript into every export, share link, and quoted excerpt. Cap its length so it does not break the transcript layout, and check it before it travels, because renaming it later does not recall the copies already sent.
- Colours assigned to speakers must stay distinguishable in the app's light and dark themes and must not be the only way a speaker is identified.
- Two people editing the same transcript must not overwrite each other's renames. Apply the app's existing concurrency handling for shared records.

## 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

- [ ] Every transcript segment carries a speaker attribute stored on the existing transcript record.
- [ ] Renaming a speaker updates all of that speaker's segments in one undoable action.
- [ ] Detected speakers can be merged, and runs of segments can be reassigned to another speaker.
- [ ] Regenerating a transcript preserves previously entered speaker names where the segments still match.
- [ ] Low-confidence diarisation falls back to a single unlabelled speaker rather than inventing speakers.
- [ ] A speaker name is length-capped, checked before it travels, and escaped in every export and share view.
- [ ] 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.