# Subtitle Editor

## Objective

Fix wrong words and bad timing on a caption track next to the video itself.

A side-by-side editor pairing the video player with an editable, time-aligned list of caption cues.

## 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. Build this on top of the caption tracks produced by Auto Captions rather than as a standalone tool. Editing a machine track is the main reason anyone opens this screen.
2. Show the cue list beside the player, keep the active cue highlighted as the video plays, and make clicking a cue seek the player to its start.
3. Let a cue be retimed by dragging its edges on a timeline and by typing exact timecodes. Dragging is faster; typing is the only way to be precise.
4. Reuse the app's existing Autosave and Unsaved Changes Guard rather than inventing a save model for this screen, and make undo work across both text edits and timing changes.
5. Do not build a full waveform video editor. This screen edits text and cue boundaries; trimming and re-encoding the media belong somewhere else.

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

- Dragging a cue boundary must never produce a cue that overlaps its neighbour or ends before it starts. Clamp the drag at the adjacent boundary rather than accepting the value and failing on save.
- Warn when a cue's reading speed exceeds a comfortable characters-per-second threshold, since a technically valid cue can still be unreadable at playback speed.
- Unsaved edits must survive a tab close or reload. Autosave a draft revision of the track so an accidental navigation does not cost an hour of correction.
- Two people editing the same caption track at once must not silently overwrite each other. Either apply the app's existing record locking or merge per cue and surface the conflict.
- Seeking the player during editing must keep the highlighted cue and the playhead in agreement, including when the user scrubs backwards or edits a cue that is currently on screen.
- Splitting and merging cues are the two operations editors reach for constantly, and both must preserve total coverage of the timeline.
- Keyboard control matters more than the mouse here: play and pause, nudge timing, and move to the next cue must all be reachable without leaving the text field.
- Publishing an edited track must supersede the machine-generated one for viewers, not add a second identical language option to the player menu.

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

- [ ] The cue list and the player stay synchronised in both directions during playback and scrubbing.
- [ ] Cue timings cannot be dragged into an overlap or a negative duration.
- [ ] Cues exceeding the reading speed threshold are flagged in the list.
- [ ] Edits autosave as a draft and survive a reload or tab close.
- [ ] Concurrent editing of one track is either prevented or surfaced as a conflict.
- [ ] Undo covers both text and timing changes.
- [ ] A published edited track replaces the machine-generated track in the player.
- [ ] 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.