# Feature Specification: Tag Browser

**Feature Branch**: `007-tag-browser`
**Created**: 2026-05-06
**Status**: Draft
**Input**: User description: "A page that lists all tags with their image counts so that users don't have to guess at searches to find image categories/tags"

## User Scenarios & Testing *(mandatory)*

### User Story 1 — Browse All Tags (Priority: P1)

The owner (or any visitor) wants to know what categories of images exist in the library without having to type guesses into a search box. They navigate to the tag browser page and see every tag in the library alongside the number of images associated with it, sorted so the most-used tags appear first.

**Why this priority**: This is the entire purpose of the feature. A visitor who doesn't know what tags exist has no way to discover them otherwise — the tag filter on the library page only helps when you already know what to type.

**Independent Test**: Navigate to the tag browser page without being logged in. Confirm every tag in the library is shown with its image count, ordered from highest to lowest count.

**Acceptance Scenarios**:

1. **Given** the library contains images with various tags, **When** a visitor opens the tag browser page, **Then** every tag in the library is listed with the number of images that carry that tag.
2. **Given** the tag list is displayed, **When** the visitor looks at the ordering, **Then** tags with more images appear before tags with fewer images.
3. **Given** the visitor is not logged in, **When** they open the tag browser page, **Then** the page loads and displays tags without requiring authentication.

---

### User Story 2 — Navigate from Tag to Library (Priority: P1)

A visitor sees a tag they are interested in and wants to view the images in that category. Clicking a tag on the tag browser page takes them directly to the library filtered to that tag, without requiring them to retype it.

**Why this priority**: The tag browser page has no value as a dead end. Each tag must be a link to the filtered library view — that is the core action the page enables. Treated as P1 because the browse and navigate actions together form the minimum useful feature.

**Independent Test**: Click any tag on the tag browser page. Confirm the library view opens showing only images carrying that tag.

**Acceptance Scenarios**:

1. **Given** the tag browser is showing a list of tags, **When** the visitor clicks a tag, **Then** they are taken to the library view filtered to show only images with that tag.
2. **Given** the visitor clicks a tag with a count of one, **When** the library loads, **Then** exactly one image is shown.

---

### User Story 3 — Reach the Tag Browser from the Library (Priority: P2)

The owner is browsing the image library and wants to switch to the tag browser to explore by category. A navigation element on the library page makes the tag browser discoverable without requiring the visitor to type the URL directly.

**Why this priority**: The tag browser is only useful if visitors can find it. A direct entry point from the library is the most natural discovery path; however, the core value of browsing and navigating tags is independently deliverable without it.

**Independent Test**: Load the library page. Confirm a visible link or button leads to the tag browser and navigates correctly when clicked.

**Acceptance Scenarios**:

1. **Given** the visitor is on the library page, **When** they look for a way to browse by tag, **Then** a visible link or button leads them to the tag browser.
2. **Given** the visitor clicks that link, **When** the tag browser loads, **Then** all tags and counts are shown as expected.

---

### Edge Cases

- What if there are no tags in the library at all? The page displays an appropriate empty state message rather than a blank page or error.
- What if a tag has been removed from all images (count reaches zero)? Tags with a count of zero are not shown on the tag browser page.
- What if the library contains a very large number of distinct tags? The page renders all of them without truncation; pagination is not required at personal library scale.
- What if two tags share the same count? An alphabetical secondary sort is acceptable — no specific tie-breaking order was requested.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: The application MUST provide a dedicated tag browser page accessible at a stable URL.
- **FR-002**: The tag browser page MUST display every tag that exists in the library with at least one associated image, each shown with its current image count.
- **FR-003**: Tags with an image count of zero MUST NOT appear on the tag browser page.
- **FR-004**: Tags MUST be ordered from highest image count to lowest image count.
- **FR-005**: Each tag on the tag browser page MUST be a navigable link that takes the visitor to the library view filtered to that tag.
- **FR-006**: The tag browser page MUST be publicly accessible without authentication.
- **FR-007**: The library page MUST include a discoverable navigation element leading to the tag browser page.

### Key Entities

- **Tag with count**: A tag label paired with the number of images currently carrying that tag. No new stored data — counts are derived from existing image–tag relationships at read time.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Every tag present in the library with at least one image appears on the tag browser page — 0% omission rate.
- **SC-002**: The image count displayed next to each tag matches the actual number of images with that tag — 100% accuracy.
- **SC-003**: Clicking any tag on the tag browser navigates to the correctly filtered library view in 100% of cases.
- **SC-004**: The tag browser page loads successfully without authentication — verified by opening it while logged out.
- **SC-005**: A visitor can go from the library page to the tag browser and on to a filtered library view in three interactions or fewer.

## Assumptions

- Tags are already a first-class concept in the library — images can have multiple tags and the data needed to derive counts already exists. No schema changes are required.
- The library page already supports filtering by tag (via the existing search/filter mechanism); the tag browser links into that existing behaviour.
- Alphabetical secondary sort for equal-count tags is acceptable.
- Pagination of the tag list is out of scope for a personal image library.
- Creating, renaming, or deleting tags from the tag browser page is out of scope; it is a read-only view.
