# Image Markup Comments

## Objective

Let teammates pin a comment to an exact spot on an image and discuss it there.

Positioned comment pins on an image, each opening a threaded discussion anchored to that point.

## 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 the visible loop first: click a point on the image, type, post, and the pin appears with a thread behind it. Everything else is secondary to that being fast and obvious.
2. Extend the app's existing Comments and Mentions feature rather than creating a second commenting system. A pinned comment is an ordinary comment with a position attached, so it inherits the same threading, mentions, notifications, editing, and moderation.
3. Store each pin as a proportional position within the image, so it lands on the same detail regardless of the size the image is rendered at.
4. Anchor pins to a specific version of the image. When someone uploads a replacement, keep the old comments attached to the version they were made against instead of scattering them across new content.
5. Do not build a general drawing and shape editor. Pins and threads are the minimum coherent version; regions, arrows, and freehand markup can wait until people ask for them.

## 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 pin recorded in screen pixels lands in the wrong place for every other viewer. Store positions relative to the image's own coordinate space and convert only at render time.
- Pins must stay glued to their detail while the image is resized, zoomed, or viewed on a phone. Reposition them on every layout change rather than placing them once on load.
- Several pins on the same detail overlap into an unclickable pile. Cluster them into a single marker with a count that expands, so every thread stays reachable.
- When an image is replaced, existing comments still refer to the old picture. Keep them bound to that version and make it clear in the UI which version a thread was written against.
- Notify the people mentioned and the thread participants, not everyone who has ever opened the image. Blanket notification is how a review tool becomes something people mute.
- Pinned comments on anything publicly visible need the same spam and abuse handling as the rest of the app's user-generated content, including reporting and removal.
- A pin placed while the image is still loading must not be recorded against a zero-sized element.
- Every pin needs a keyboard path: a list of comments beside the image, ordered and focusable, that highlights the corresponding point.

## 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 can place a pin on an image and start a thread at that point.
- [ ] Pins render at the same detail across screen sizes, zoom levels, and devices.
- [ ] Overlapping pins cluster into an expandable marker and remain individually reachable.
- [ ] Comments stay attached to the image version they were written against when the image is replaced.
- [ ] Notifications reach mentioned users and thread participants only.
- [ ] Pinned comments use the app's existing comment storage, mentions, and moderation.
- [ ] All threads are reachable and navigable by keyboard.
- [ ] 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.