# Fillable PDF Forms

## Objective

Let people fill in a PDF form on screen and download the completed copy.

An on-screen fill layer over a PDF form that writes the entered values back into a downloadable file.

## 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. Render the document and place editable inputs over its real form fields, so the user types on the page they recognise rather than into a separate form beside it.
2. Extend the app's existing PDF Export and document viewing paths rather than introducing a second renderer. Two renderers will disagree about fonts and page size, and the user will see the difference between screen and download.
3. Save progress as the user types using the app's existing Autosave, and restore the partly filled form on return.
4. Flatten the values into the page content on download so the completed copy cannot be edited back into a blank form.
5. Do not attempt a general document editor. Fill the fields that exist, offer a simple positioned overlay for documents that have none, and leave the rest of the file untouched.

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

- Form fields in real documents are frequently unnamed or share a name across pages. Key stored answers to a stable position-based identifier rather than trusting the field name alone.
- Checkbox and radio groups whose members sit on different pages must move together. Selecting one option has to clear the others even when they are not on screen.
- A long form filled over twenty minutes must survive a refresh, a phone call, and a dropped connection. Save as the user goes rather than only on submit.
- A downloaded copy with live fields can be blanked and refilled by whoever receives it. Flatten on export and keep the fillable version separate from the completed one.
- Some documents that look like forms carry no field definitions at all, only printed lines. Fall back to a text overlay the user positions, and say plainly that this is what is happening.
- A value longer than its field must shrink or wrap rather than overflow into the neighbouring box or disappear at the boundary.
- The completed document usually contains personal data. Decide who may read the saved copy back, how long it is kept, and whether the partly filled draft falls under the same rule.
- Required fields must be checked before the download is offered, or people will send an incomplete form believing it is finished.

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

- [ ] Users fill fields directly on the rendered page and see their values in place.
- [ ] Progress saves automatically and is restored after a refresh or a new session.
- [ ] Grouped checkboxes and radios stay consistent across pages.
- [ ] The downloaded copy is flattened and cannot be edited back to blank.
- [ ] Documents without real form fields get a usable overlay rather than an error.
- [ ] Long values fit their field without overflowing or being cut off.
- [ ] A partly filled form is readable only by the person filling it and expires on the app's normal schedule for stored user files.
- [ ] 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.