# Paste Image From Clipboard

## Objective

Let people paste a copied image straight into a field instead of saving a file first.

Clipboard image paste support on the app's existing upload and editor fields.

## 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. Add paste handling to the surfaces where people already attach images: the comment box, the rich text or markdown editor, and any file drop zone. Do not create a separate paste-only widget.
2. Route pasted images through the app's existing File Upload path so they inherit the same size ceiling, accepted types, storage location, malware scanning, and access rules as a chosen file.
3. Show the image locally the moment it is pasted, with a visible progress state and a way to cancel or remove it while the upload is still running.
4. Give each pasted image a meaningful, unique filename derived from the context and the time, since clipboard images arrive with no name of their own.
5. Do not accept whatever the clipboard offers. When the paste is text or markup that merely references an image, insert the text as text — silently fetching a remote URL on the user's behalf is a request the app should not be making.

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

- A copied image from a web page often arrives as HTML containing a link rather than image data. Detect that and paste it as a link or plain text, never as a server-side fetch of a third-party URL.
- Clipboard images have no filename. Generate one that is unique and human-readable, so a folder of attachments is not twelve files all called image.
- The same limits must apply as any other upload. Enforce type and size checks on the server as well as the client, because a paste is just another request.
- Show the pasted image immediately from local data while the upload runs, and make plain whether it has finished. A preview that looks identical before and after upload leads people to submit too early.
- One paste can carry several images. Handle them all, in order, rather than taking the first and dropping the rest without a word.
- A cancelled or failed paste upload must remove the local preview and leave no partial file in storage or stray reference in the editor content.
- Pasting into a text field that has no attachment support must fall back to the default text behaviour instead of doing nothing.
- Pasted screenshots frequently contain other people's data. Apply the same retention and read permissions as the record they are attached to.

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

- [ ] Pasting an image into a comment box, editor, or drop zone attaches it.
- [ ] Pasted images go through the same upload path, limits, scanning, and permissions as chosen files.
- [ ] A local preview appears instantly and shows upload progress and completion.
- [ ] Multiple images in a single paste are all attached in order.
- [ ] Pasted text or markup referencing an image is inserted as text, with no remote fetch.
- [ ] Each pasted image gets a unique, meaningful filename.
- [ ] Cancelling or failing an upload removes the preview and leaves no orphaned file.
- [ ] 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.