# Media Library

## Objective

Give every uploaded file one browsable home instead of scattering them across the app.

A single browsable store of every uploaded image, video, and document, with folders, search, and reuse from any upload field in the app.

## 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 app's existing upload path rather than beside it. If File Upload, Avatar Upload, Attachment Gallery, or a hosted media upload already exist, they must all write into the library and read back from it, so a file uploaded in one place is findable in another.
2. Give every upload field a second route: choose an existing file from the library. That is the whole point of the feature, and a library nothing can select from is just a storage report.
3. Record where each file is used. When someone deletes a file that is still referenced, name the pages or records that will break and make them confirm.
4. Deduplicate by hashing file contents on upload. If the same bytes are already stored for that workspace, link to the existing record instead of storing a second copy, but keep the new filename and the new uploader on the reference.
5. Do not load the whole library at once. Paginate or lazily page the grid and defer thumbnail loading until a tile is near the viewport, or the first visit from a workspace with ten thousand files will hang the browser.

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

- Deleting a file that is still referenced by a page, message, or product breaks it silently. Show the usage list before deletion and offer to detach rather than destroy.
- Two people uploading the same file must not produce two stored copies. Hash the content, match against existing records in the same workspace, and reuse the stored object while still logging the second upload.
- The browser cannot preview PDFs, design files, archives, or many video formats inline. Generate a thumbnail server-side for those, and fall back to a typed placeholder icon when generation fails rather than showing a broken image.
- A library with tens of thousands of assets must not fetch every thumbnail on first paint. Page the results and load thumbnails only as tiles approach the viewport, with reserved tile dimensions so the grid does not reflow.
- Storage is finite and someone will fill it. Enforce a per-workspace quota server-side, show consumption before it is reached, and give the over-limit state a clear action: delete files or upgrade, not a generic upload failure.
- Every file in the library must inherit the app's existing access rules. A private attachment must not become readable to the whole workspace merely because it is now listed in a shared browser.
- An upload cancelled or interrupted halfway must not leave a half-written file listed as usable. Mark uploads incomplete until they finish and sweep the abandoned ones.
- Files must carry alt text or a description where the app renders them publicly. Reuse any existing alt text generation rather than leaving the field blank.

## 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 upload surface in the app writes into the library and can select from it.
- [ ] Each file shows where it is used, and deleting a referenced file requires confirmation.
- [ ] Identical uploads are stored once and linked, not duplicated.
- [ ] Formats the browser cannot render inline have server-generated thumbnails or a typed placeholder.
- [ ] The grid pages and lazily loads thumbnails without layout shift on large libraries.
- [ ] Per-workspace storage quotas are enforced server-side with a clear over-limit state.
- [ ] Library access respects the app's existing per-file permissions.
- [ ] 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.