# Video Playlist

## Objective

Queue videos so one plays after another, with a visible up-next list.

An ordered queue of videos beside the player, with automatic advance and a clear next item.

## 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. Extend the app's Custom Video Player rather than building a second playback surface. The playlist is a queue and a list around the player that already exists.
2. Show the whole queue with the current item marked and the next item obvious. A viewer should never be surprised by what starts playing.
3. Advance automatically only after a short, visible countdown that can be cancelled. Autoadvance that fires the instant a video ends removes the viewer's chance to stop it.
4. Persist the viewer's position in the playlist and within the current item, so returning to the page resumes where they left rather than at the top of the queue.
5. Do not autoadvance when the viewer is not there. A queue that keeps playing into a background tab burns bandwidth and gives false view counts.

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

- Cancel the pending advance when the tab loses visibility or the player has scrolled well out of view, and resume the choice when the viewer comes back rather than skipping ahead in their absence.
- An item that has been removed, made private, or fails to load must be skipped with a visible note, and the queue must carry on to the next playable item rather than stalling on a black frame.
- Keep the list scrolled so the playing item is visible, but do not yank the list back into place while the viewer is deliberately scrolling through it.
- Position in the playlist and within the current video must survive a reload, and must be scoped to the viewer rather than shared across everyone watching the same playlist.
- Give autoadvance an explicit off switch that is remembered. Some viewers want a queue they step through manually, and burying that choice guarantees they leave.
- If every remaining item fails, end the playlist with a clear state rather than an endless skip loop.
- The list must be keyboard navigable, and selecting an item must move playback without moving focus somewhere unexpected.
- A playlist reordered or edited while someone is watching must not jump them to a different video mid-playback.

## 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 queue is visible with the current and next items clearly marked.
- [ ] Autoadvance runs after a cancellable countdown and can be switched off permanently.
- [ ] A pending advance is cancelled when the tab is hidden or the player is out of view.
- [ ] Broken or removed items are skipped with a visible note and the queue continues.
- [ ] Playlist and playback position survive a reload and are per viewer.
- [ ] The list keeps the playing item in view without fighting the viewer's own scrolling.
- [ ] A playlist edited during playback does not interrupt the current item.
- [ ] 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.