# Document Import

## Objective

Turn an uploaded document into editable content instead of a dead attachment.

An import path that converts an uploaded word-processor or rich-text document into the app's own editable content.

## 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. Start from the app's existing File Upload rather than opening a second route with looser rules. A file that is about to be parsed and rendered back as editable content needs the size ceiling and the malware scan more than an ordinary attachment does, not less.
2. Map the imported document onto the content model the app's editor already uses. Anything the editor cannot represent must be dropped deliberately and reported, not smuggled in as raw markup.
3. Run parsing as background work with a visible status, because a large document will exceed a request timeout and the user needs to know whether it is working or stuck.
4. Show the converted result for review before it becomes a saved record, and let the user cancel without leaving a half-imported draft behind.
5. Do not accept the document's own styling wholesale. Inline fonts, colours, and class names from a word processor will fight the app's design and can carry active content.

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

- Flattening everything to plain text destroys the structure that made the document worth importing. Preserve headings, ordered and unordered lists, tables, and emphasis, and map each to the app's equivalent rather than to approximate visual spacing.
- Images embedded in the document will be referenced by internal paths that mean nothing once the file is discarded. Extract each one, store it through the app's normal media path with its size and type checks, and rewrite the references.
- Pasted styles, tracked changes, comments, revision markup, and hidden text will otherwise arrive as visible clutter or invisible payload. Strip markup to an allowlist and decide explicitly whether accepted revisions or the original text is imported.
- Committing straight to a saved record means a bad conversion overwrites good content with no way back. Show a preview with a clear count of what was converted and what was dropped, and require confirmation.
- Some files are corrupt, password protected, or simply too large to parse, and a job that hangs forever looks identical to one that is slow. Set a time limit, fail with a specific reason, and keep the original upload available for download.
- A document containing external links and remote images must not silently fetch from third-party servers when the imported content is later viewed.
- Very large documents can produce a single record too big for the editor to open. Warn at a threshold and offer to split or truncate rather than creating an unopenable page.
- The uploaded original should have a stated fate: kept as an attachment, or deleted after successful import. Leaving it in storage indefinitely is a retention decision made by accident.

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

- [ ] Uploading a document produces editable content in the app's existing editor.
- [ ] Headings, lists, tables, and emphasis survive the conversion.
- [ ] Embedded images are extracted, rehosted through the app's media path, and referenced correctly.
- [ ] Incoming markup is reduced to an allowlist, with tracked changes and comments handled explicitly.
- [ ] The user reviews a preview, with dropped content reported, before anything is saved.
- [ ] Unparseable and oversized files time out with a specific message and the original stays downloadable.
- [ ] Import runs in the background with visible status and can be cancelled.
- [ ] 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.