# Document Scanner

## Objective

Turn a phone photo of a paper document into a straight, readable, multi-page file.

A camera capture flow that detects page edges, corrects perspective, and assembles the shots into one document.

## 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. Lead with the capture screen: live edge detection, a shutter, and a running strip of the pages already taken. Somebody should be able to shoot five pages without leaving the camera.
2. Correct perspective and crop to the detected page before saving, then apply a contrast pass so a grey photo of a page reads as black text on white.
3. Give the user a review step where pages can be reordered, retaken, or deleted before anything is committed.
4. Send the assembled document out through the same upload path a user picking a file would hit. Capturing from the camera changes where the pages came from, not what the app is willing to store, and a camera route that skips the usual checks is exactly the one someone will look for.
5. Do not build a desktop scanner-driver integration. The minimum coherent version is a phone camera with a file picker fallback; anything talking to hardware over USB is a different product.

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

- Edge detection fails on a dark desk, a patterned tablecloth, or a page held over a similarly coloured surface. Always let the user drag the corners by hand instead of blocking the capture.
- Pages captured in sequence must keep their order through the review step and the upload. A contract whose pages arrive shuffled is worse than no scan at all.
- Glare from an overhead light, a shadow cast by the phone itself, and a warm indoor bulb all wreck legibility. Warn on the capture screen rather than saving something the recipient cannot read.
- Compression that looks fine on a full-page view destroys eight-point text. Set the quality floor against the small print, not against the photo as a whole.
- A user who leaves mid-scan must not lose the pages already taken, and abandoned captures must not sit in temporary storage indefinitely.
- A phone rotated between shots produces pages at different orientations. Normalise each page to portrait reading orientation before assembly.
- Camera permission can be denied at the start or revoked mid-session. Fall back to the ordinary file picker with a plain explanation, never a dead screen.
- Scans of identity documents and medical paperwork are sensitive by default. Apply the same retention and read-back rules as any other uploaded file, and do not silently leave copies in the device photo roll.

## 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 user captures several pages in one session and receives a single ordered document.
- [ ] Detected page edges can be adjusted by hand before a page is saved.
- [ ] Pages can be reordered, retaken, and deleted before the document is committed.
- [ ] Small text stays legible in the compressed output.
- [ ] Denied or revoked camera permission falls back to a file picker with an explanation.
- [ ] A scan captured from the camera is subject to the same limits, scanning, and retention as a file chosen from disk.
- [ ] 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.