# Sticky Video Player

## Objective

A playing video shrinks into a corner when scrolled past and keeps playing.

A miniature docked player that takes over when the inline video scrolls out of view, with a close control.

## 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. Dock only when the video is actually playing and the original position has left the viewport, and undock automatically when the user scrolls back to it.
2. Move the same player element rather than creating a second one. Two players means two audio streams the moment the timing is slightly off.
3. Give the docked tile a visible close control and a way to jump back to the video in the page. Closing it must pause playback, not merely hide a video that keeps talking.
4. Position the tile using the same layer and offset tokens as the app's other fixed elements, so it sits above the page but below anything modal.
5. Do not dock on a paused video, on a muted background loop, or on a video the user has never interacted with. An element that follows people down the page uninvited is the behaviour ad blockers exist to remove.

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

- Detach only after playback has genuinely started. Docking a paused or never-played video puts a small black rectangle in the corner of the page for no reason.
- Once the viewer closes the docked tile, remember that for the rest of the page visit. A player that re-docks on the next scroll is worse than one that never docked at all.
- The corner is crowded. Check what else occupies it — sticky footers, chat launchers, cookie banners, toasts — and offset the tile or pick a different corner rather than covering a control the user needs.
- Moving a video element in the DOM can reset it in some browsers. Capture the current time, playback rate, volume, and muted state before the move and restore them after, and verify the video does not restart from zero.
- On a narrow screen a corner tile eats a serious share of the viewport. Either disable docking below a breakpoint or reduce it to an audio-style bar rather than shrinking a video until it is unwatchable.
- Fullscreen and picture-in-picture must take precedence. Do not dock a video that the browser has already handed to another presentation mode.
- The transition must respect reduced motion. Reuse the app's Reduced Motion Support so the tile appears without a flying animation when that preference is set.
- The docked tile must be reachable by keyboard and its controls focusable, and it must not steal focus from wherever the user was reading.

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

- [ ] A video docks only after playback has started and its inline position has scrolled out of view.
- [ ] Scrolling back to the video returns it inline with playback uninterrupted.
- [ ] Playback position, volume, and muted state survive the move in both directions.
- [ ] Closing the tile pauses the video and suppresses docking for the rest of the visit.
- [ ] The tile never covers sticky bars, chat launchers, cookie banners, or toasts.
- [ ] Docking is disabled or reduced on small viewports.
- [ ] Fullscreen and picture-in-picture sessions are left alone.
- [ ] 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.