# Feature Specification: Copy URL & Toast Notifications

**Feature Branch**: `016-copy-url-toast`
**Created**: 2026-05-09
**Status**: Draft

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Copy Image URL from Detail Page (Priority: P1)

A user viewing an image on the detail page wants to share the direct link to that image. They click a "Copy URL" button and the image's direct URL is instantly copied to their clipboard, ready to paste anywhere.

**Why this priority**: This is the core feature and the primary user value. Everything else builds on it.

**Independent Test**: Open any image detail page. Click the "Copy URL" button. Paste into a text editor — confirm the pasted value is the direct URL to that image.

**Acceptance Scenarios**:

1. **Given** a user is on an image detail page, **When** they click "Copy URL", **Then** the image's direct URL is copied to their clipboard.
2. **Given** a user clicks "Copy URL", **When** the copy succeeds, **Then** a confirmation toast appears briefly and disappears on its own.
3. **Given** a user clicks "Copy URL", **When** the clipboard is unavailable (e.g. browser denies permission), **Then** a toast appears indicating the copy failed.

---

### User Story 2 - Reusable Toast Notification System (Priority: P2)

Any part of the application can trigger a brief, non-blocking notification (toast) to confirm an action or surface an error. The toast appears, persists for a short time, then disappears automatically without user interaction.

**Why this priority**: The toast infrastructure is needed by US1 and is designed as a foundation for future features (e.g. upload confirmation, filter saved, delete confirmed).

**Independent Test**: Trigger a toast programmatically. Confirm it appears with the correct message, then disappears automatically after a few seconds without any user interaction.

**Acceptance Scenarios**:

1. **Given** a toast is triggered, **When** it appears, **Then** it displays the provided message and is visible above other content.
2. **Given** a toast is visible, **When** sufficient time passes, **Then** it disappears automatically without user interaction.
3. **Given** multiple toasts are triggered in quick succession, **When** they appear, **Then** they stack or queue without overlapping illegibly.
4. **Given** a toast is visible, **When** the user interacts with the rest of the page, **Then** the toast does not block or intercept those interactions.

---

### Edge Cases

- What happens when the clipboard API is not available or permission is denied? → Show an error toast.
- What happens if the user clicks "Copy URL" multiple times rapidly? → Each click copies and shows a toast; toasts queue or stack cleanly.
- What happens on a very long URL? → URL is copied in full; toast message is fixed (not the URL itself).

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: The image detail page MUST display a "Copy URL" button.
- **FR-002**: Clicking "Copy URL" MUST copy the image's direct URL to the system clipboard.
- **FR-003**: A success toast MUST appear after a successful copy, confirming the action to the user.
- **FR-004**: A failure toast MUST appear if the copy cannot be completed (e.g. clipboard permission denied).
- **FR-005**: Toasts MUST disappear automatically after a fixed duration without requiring user interaction.
- **FR-006**: Toasts MUST NOT block user interaction with the rest of the page.
- **FR-007**: The toast system MUST be reusable — any part of the application must be able to trigger a toast with a custom message.
- **FR-008**: Multiple toasts triggered in quick succession MUST display without overlapping illegibly.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: A user can copy an image URL in a single click with no additional steps.
- **SC-002**: Toast confirmation appears within 300ms of the copy action completing.
- **SC-003**: Toasts disappear automatically within 5 seconds of appearing.
- **SC-004**: The toast system can be triggered from any page or component without modifying the toast component itself.

## Assumptions

- The image's direct URL is already available on the detail page (it is — currently displayed or derivable from the current route and API response).
- Users are on modern browsers with Clipboard API support; graceful degradation covers the failure case via an error toast.
- One toast variant is sufficient for v1: a simple text message with success/error styling. No actions, no dismiss button required.
- Toast duration of approximately 3 seconds is appropriate (standard convention).
- The detail page already exists; this feature adds to it without redesigning it.