# Highlight Clip Maker

## Objective

Turn a selected passage of a transcript into a short clip that can be shared.

Selection of transcript lines that renders a trimmed, captioned clip of the source media with a shareable link.

## 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 the selection on top of the app's interactive transcript. The user selects a run of lines, sees the resulting start and end time and duration, and adjusts the edges before rendering.
2. Render clips through the app's existing background job system so the user is not held on a progress bar, and notify them through the existing notification centre when the clip is ready or has failed.
3. Burn the transcript text into the clip as captions, since most places a clip is shared autoplay it silently. Give the user a way to turn captions off before rendering.
4. Share clips through the app's existing signed share link mechanism rather than making a new public URL scheme, and honour the source media's visibility when deciding whether sharing is allowed at all.
5. Do not build a general video editor. Trim, captions, and a single output size cover the case; multi-segment editing, overlays, and transitions should be deferred rather than half-built.

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

- Snap the clip edges to sentence boundaries from the transcript rather than to the raw selection, so a clip does not open and close mid-word. Let the user nudge past the snap when they need to.
- Enforce a maximum clip length. Warn as the selection approaches it and block rendering beyond it, because an unbounded selection is really a request to re-encode the whole recording.
- Rendering happens in the background and can take minutes. Show the job's state where the user will see it, notify them on completion, and make the clip retrievable later without repeating the selection.
- Captions burned into the clip must be legible over the underlying video at small sizes, which means a background or outline rather than plain white text on whatever happens to be behind it.
- When the source media is deleted, its clips and their share links must stop working. Revoke or expire them rather than leaving a public URL pointing at content the owner believed they had removed.
- A failed render must report why in plain language and leave the selection intact so the user can retry, not discard the work and return them to the transcript.
- Clips of private media must not become public by being clipped. Default the share link to the same audience as the source and require a deliberate step to widen it.
- The same selection requested twice should reuse the existing rendered clip rather than queueing a second identical job.

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

- [ ] Selecting transcript lines produces a clip with visible start, end, and duration before rendering.
- [ ] Clip edges snap to sentence boundaries and can still be adjusted manually.
- [ ] Clips over the maximum length are warned about and cannot be rendered.
- [ ] Rendering runs as a background job with a completion or failure notification.
- [ ] Captions are burned in by default and remain legible at small sizes.
- [ ] Deleting the source media revokes its clips and their share links.
- [ ] Clip sharing defaults to the source media's audience.
- [ ] 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.