feat: manga collections (0.17.0)

User-owned named lists of mangas with an add-to-collection modal on
the manga page and dedicated /collections and /collections/:id pages.

- Schema (0010): `collections` (per-user case-insensitive name
  uniqueness) + `collection_mangas` join with cascade FKs.
- Endpoints: full CRUD on `/v1/collections`, idempotent add/remove
  for `/v1/collections/:id/mangas`, and `/v1/mangas/:id/my-collections`
  for the modal's pre-checked state. Owner-mismatch surfaces as 404
  (not 403) so the API doesn't disclose collection existence to
  non-owners; the frontend funnels 401 to /login. Three-state PATCH
  via a new shared `domain::patch::Patch<T>` lets clients distinguish
  "leave alone", "clear", and "set" for description.
- Frontend: reusable `Modal` component (focus trap, opt-in
  backdrop close, ESC) and `AddToCollectionModal` with optimistic
  toggling that's race-safe under fast clicks. /collections page
  renders cover-collage cards; /collections/:id is editable with
  per-card remove. Top nav gets a Collections link.

155 backend tests (incl. 21 collection tests covering ownership,
idempotence, sample-cover enrichment, three-state PATCH, FK race);
88 frontend tests; svelte-check clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/Cargo.lock

@@ -1033,7 +1033,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "mangalord"
-version = "0.16.0"
+version = "0.17.0"
 dependencies = [
  "anyhow",
  "argon2",

backend/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mangalord"
-version = "0.16.0"
+version = "0.17.0"
 edition = "2021"
 
 [lib]

backend/migrations/0010_collections.sql

@@ -0,0 +1,31 @@
+-- User-owned manga collections. Each user can curate any number of
+-- named lists (e.g., "Favorites", "Reading list"); mangas can belong
+-- to many collections of many users without restriction.
+
+CREATE TABLE collections (
+    id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id     uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name        text NOT NULL,
+    description text,
+    created_at  timestamptz NOT NULL DEFAULT now(),
+    updated_at  timestamptz NOT NULL DEFAULT now()
+);
+
+-- Per-user case-insensitive name uniqueness so "Favorites" and
+-- "favorites" don't both end up in someone's sidebar.
+CREATE UNIQUE INDEX collections_user_name_lower_uniq
+    ON collections (user_id, lower(name));
+
+CREATE INDEX collections_user_idx ON collections (user_id, created_at DESC);
+
+CREATE TABLE collection_mangas (
+    collection_id uuid NOT NULL REFERENCES collections(id) ON DELETE CASCADE,
+    manga_id      uuid NOT NULL REFERENCES mangas(id) ON DELETE CASCADE,
+    added_at      timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (collection_id, manga_id)
+);
+
+-- Reverse lookup: which collections contain this manga? Used by the
+-- "Add to collection" modal to pre-check the boxes for the user's
+-- collections this manga is already in.
+CREATE INDEX collection_mangas_manga_idx ON collection_mangas (manga_id);

backend/src/api/collections.rs

@@ -0,0 +1,247 @@
+use axum::extract::{Path, Query, State};
+use axum::http::StatusCode;
+use axum::routing::{delete, get, post};
+use axum::{Json, Router};
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use uuid::Uuid;
+
+use crate::api::pagination::PagedResponse;
+use crate::app::AppState;
+use crate::auth::extractor::CurrentUser;
+use crate::domain::collection::{
+    Collection, CollectionPatch, CollectionSummary, NewCollection,
+};
+use crate::domain::manga::Manga;
+use crate::domain::patch::Patch;
+use crate::error::{AppError, AppResult};
+use crate::repo;
+
+pub fn routes() -> Router<AppState> {
+    Router::new()
+        .route("/collections", post(create))
+        .route("/me/collections", get(list_mine))
+        .route("/collections/:id", get(get_one).patch(update).delete(delete_one))
+        .route("/collections/:id/mangas", get(list_mangas).post(add_manga))
+        .route(
+            "/collections/:id/mangas/:manga_id",
+            delete(remove_manga),
+        )
+        .route(
+            "/mangas/:id/my-collections",
+            get(list_my_collections_containing),
+        )
+}
+
+const MAX_NAME_LEN: usize = 64;
+const MAX_DESCRIPTION_LEN: usize = 1024;
+const DEFAULT_LIMIT: i64 = 50;
+
+#[derive(Debug, Deserialize)]
+pub struct ListParams {
+    #[serde(default = "default_limit")]
+    pub limit: i64,
+    #[serde(default)]
+    pub offset: i64,
+}
+
+fn default_limit() -> i64 {
+    DEFAULT_LIMIT
+}
+
+#[derive(Debug, Deserialize)]
+pub struct AddMangaBody {
+    pub manga_id: Uuid,
+}
+
+#[derive(Debug, Serialize)]
+pub struct MangaCollectionIds {
+    pub collection_ids: Vec<Uuid>,
+}
+
+fn validate_name(name: &str) -> AppResult<()> {
+    let trimmed = name.trim();
+    if trimmed.is_empty() {
+        return Err(AppError::ValidationFailed {
+            message: "name is required".into(),
+            details: json!({ "name": "required" }),
+        });
+    }
+    if trimmed.chars().count() > MAX_NAME_LEN {
+        return Err(AppError::ValidationFailed {
+            message: "name too long".into(),
+            details: json!({ "name": format!("max {MAX_NAME_LEN} characters") }),
+        });
+    }
+    Ok(())
+}
+
+fn validate_description(desc: Option<&str>) -> AppResult<()> {
+    if let Some(d) = desc {
+        if d.chars().count() > MAX_DESCRIPTION_LEN {
+            return Err(AppError::ValidationFailed {
+                message: "description too long".into(),
+                details: json!({ "description": format!("max {MAX_DESCRIPTION_LEN} characters") }),
+            });
+        }
+    }
+    Ok(())
+}
+
+async fn create(
+    State(state): State<AppState>,
+    CurrentUser(user): CurrentUser,
+    Json(input): Json<NewCollection>,
+) -> AppResult<(StatusCode, Json<Collection>)> {
+    validate_name(&input.name)?;
+    validate_description(input.description.as_deref())?;
+    let row = repo::collection::create(
+        &state.db,
+        user.id,
+        &input.name,
+        input.description.as_deref(),
+    )
+    .await?;
+    Ok((StatusCode::CREATED, Json(row)))
+}
+
+async fn list_mine(
+    State(state): State<AppState>,
+    CurrentUser(user): CurrentUser,
+    Query(params): Query<ListParams>,
+) -> AppResult<Json<PagedResponse<CollectionSummary>>> {
+    let limit = params.limit.clamp(1, 200);
+    let offset = params.offset.max(0);
+    let (items, total) =
+        repo::collection::list_for_user(&state.db, user.id, limit, offset).await?;
+    Ok(Json(PagedResponse::with_total(items, limit, offset, total)))
+}
+
+async fn get_one(
+    State(state): State<AppState>,
+    CurrentUser(user): CurrentUser,
+    Path(id): Path<Uuid>,
+) -> AppResult<Json<Collection>> {
+    let row = require_owner(&state, user.id, id).await?;
+    Ok(Json(row))
+}
+
+async fn update(
+    State(state): State<AppState>,
+    CurrentUser(user): CurrentUser,
+    Path(id): Path<Uuid>,
+    Json(patch): Json<CollectionPatch>,
+) -> AppResult<Json<Collection>> {
+    require_owner_id(&state, user.id, id).await?;
+    if let Some(ref n) = patch.name {
+        validate_name(n)?;
+    }
+    if let Patch::Set(ref d) = patch.description {
+        validate_description(Some(d.as_str()))?;
+    }
+    // Three-state semantics via `Patch<T>`: omitted → Unchanged
+    // (column untouched), explicit `null` → Clear (NULL), value → Set.
+    let description_provided = patch.description.is_provided();
+    let description_value: Option<&str> = match &patch.description {
+        Patch::Set(s) => Some(s.as_str()),
+        Patch::Clear | Patch::Unchanged => None,
+    };
+    let updated = repo::collection::update(
+        &state.db,
+        id,
+        patch.name.as_deref(),
+        description_provided,
+        description_value,
+    )
+    .await?;
+    Ok(Json(updated))
+}
+
+async fn delete_one(
+    State(state): State<AppState>,
+    CurrentUser(user): CurrentUser,
+    Path(id): Path<Uuid>,
+) -> AppResult<StatusCode> {
+    require_owner_id(&state, user.id, id).await?;
+    repo::collection::delete(&state.db, id).await?;
+    Ok(StatusCode::NO_CONTENT)
+}
+
+async fn list_mangas(
+    State(state): State<AppState>,
+    CurrentUser(user): CurrentUser,
+    Path(id): Path<Uuid>,
+    Query(params): Query<ListParams>,
+) -> AppResult<Json<PagedResponse<Manga>>> {
+    require_owner_id(&state, user.id, id).await?;
+    let limit = params.limit.clamp(1, 200);
+    let offset = params.offset.max(0);
+    let (items, total) =
+        repo::collection::list_mangas(&state.db, id, limit, offset).await?;
+    Ok(Json(PagedResponse::with_total(items, limit, offset, total)))
+}
+
+async fn add_manga(
+    State(state): State<AppState>,
+    CurrentUser(user): CurrentUser,
+    Path(id): Path<Uuid>,
+    Json(body): Json<AddMangaBody>,
+) -> AppResult<StatusCode> {
+    require_owner_id(&state, user.id, id).await?;
+    if !repo::manga::exists(&state.db, body.manga_id).await? {
+        return Err(AppError::NotFound);
+    }
+    let created = repo::collection::add_manga(&state.db, id, body.manga_id).await?;
+    Ok(if created { StatusCode::CREATED } else { StatusCode::OK })
+}
+
+async fn remove_manga(
+    State(state): State<AppState>,
+    CurrentUser(user): CurrentUser,
+    Path((collection_id, manga_id)): Path<(Uuid, Uuid)>,
+) -> AppResult<StatusCode> {
+    require_owner_id(&state, user.id, collection_id).await?;
+    repo::collection::remove_manga(&state.db, collection_id, manga_id).await?;
+    Ok(StatusCode::NO_CONTENT)
+}
+
+async fn list_my_collections_containing(
+    State(state): State<AppState>,
+    CurrentUser(user): CurrentUser,
+    Path(manga_id): Path<Uuid>,
+) -> AppResult<Json<MangaCollectionIds>> {
+    // No 404 if the manga doesn't exist — the empty list is the
+    // correct answer ("you have it in zero of your collections") and
+    // keeps the request side-effect-free.
+    let ids =
+        repo::collection::list_collections_containing(&state.db, user.id, manga_id).await?;
+    Ok(Json(MangaCollectionIds { collection_ids: ids }))
+}
+
+/// Returns the row iff the caller owns it. Both "doesn't exist" and
+/// "exists but belongs to someone else" surface as `NotFound` so the
+/// API doesn't disclose collection existence to non-owners — the
+/// frontend already does this funnelling for URLs, and consistency at
+/// the API matters because the same identifiers travel through bots
+/// and shared links.
+async fn require_owner(
+    state: &AppState,
+    user_id: Uuid,
+    id: Uuid,
+) -> AppResult<Collection> {
+    match repo::collection::get(&state.db, id).await {
+        Ok(row) if row.user_id == user_id => Ok(row),
+        // Either the row doesn't exist (NotFound from `get`) or it
+        // belongs to someone else — both collapse to NotFound.
+        Ok(_) | Err(AppError::NotFound) => Err(AppError::NotFound),
+        Err(other) => Err(other),
+    }
+}
+
+async fn require_owner_id(state: &AppState, user_id: Uuid, id: Uuid) -> AppResult<()> {
+    match repo::collection::find_owner(&state.db, id).await? {
+        Some(owner) if owner == user_id => Ok(()),
+        // Same non-leakage rationale as `require_owner` above.
+        _ => Err(AppError::NotFound),
+    }
+}

backend/src/api/mangas.rs

@@ -9,7 +9,8 @@ use uuid::Uuid;
 use crate::api::pagination::PagedResponse;
 use crate::app::AppState;
 use crate::auth::extractor::CurrentUser;
-use crate::domain::manga::{MangaCard, MangaDetail, MangaPatch, NewManga, Patch};
+use crate::domain::manga::{MangaCard, MangaDetail, MangaPatch, NewManga};
+use crate::domain::patch::Patch;
 use crate::domain::tag::TagRef;
 use crate::error::{AppError, AppResult};
 use crate::repo;

backend/src/api/mod.rs

@@ -2,6 +2,7 @@ pub mod auth;
 pub mod authors;
 pub mod bookmarks;
 pub mod chapters;
+pub mod collections;
 pub mod files;
 pub mod genres;
 pub mod health;
@@ -24,4 +25,5 @@ pub fn routes() -> Router<AppState> {
         .merge(genres::routes())
         .merge(tags::routes())
         .merge(authors::routes())
+        .merge(collections::routes())
 }

backend/src/domain/collection.rs

@@ -0,0 +1,50 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+use super::patch::Patch;
+
+#[derive(Debug, Clone, Serialize, Deserialize, FromRow)]
+pub struct Collection {
+    pub id: Uuid,
+    pub user_id: Uuid,
+    pub name: String,
+    pub description: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// Shape returned by `GET /me/collections`. Enriched with the manga
+/// count and up to three sample cover paths so a collection card can
+/// render without extra round-trips.
+#[derive(Debug, Clone, Serialize, FromRow)]
+pub struct CollectionSummary {
+    pub id: Uuid,
+    pub user_id: Uuid,
+    pub name: String,
+    pub description: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub manga_count: i64,
+    /// Cover image keys of up to three sample mangas (newest-added
+    /// first). `Vec<String>` rather than `Option<...>` so an empty
+    /// collection renders as `[]` rather than `null`.
+    pub sample_covers: Vec<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct NewCollection {
+    pub name: String,
+    #[serde(default)]
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, Default)]
+pub struct CollectionPatch {
+    pub name: Option<String>,
+    /// Three-state: missing key leaves description alone; explicit
+    /// `null` clears it; a string sets it. See `Patch`.
+    #[serde(default)]
+    pub description: Patch<String>,
+}

backend/src/domain/manga.rs

@@ -5,6 +5,7 @@ use uuid::Uuid;
 
 use super::author::AuthorRef;
 use super::genre::GenreRef;
+use super::patch::Patch;
 use super::tag::TagRef;
 
 #[derive(Debug, Clone, Serialize, Deserialize, FromRow)]
@@ -73,82 +74,6 @@ pub struct MangaPatch {
     pub genre_ids: Option<Vec<Uuid>>,
 }
 
-/// Three-state container for nullable PATCH fields.
-///
-/// `serde`'s default behaviour collapses both "field missing" and
-/// "field is `null`" to `Option::None`, which means an `Option<T>`
-/// patch field can't distinguish "leave alone" from "set to NULL".
-/// `Patch<T>` carries that distinction by deserializing JSON `null`
-/// into `Clear` and any value into `Set`; with `#[serde(default)]` on
-/// the field, a missing key falls through to `Unchanged`.
-#[derive(Debug, Clone, Default, PartialEq, Eq)]
-pub enum Patch<T> {
-    /// Field absent from the request — leave the column untouched.
-    #[default]
-    Unchanged,
-    /// Field present and explicitly `null` — set the column to NULL.
-    Clear,
-    /// Field present with a value — set the column to that value.
-    Set(T),
-}
-
-impl<T> Patch<T> {
-    /// Whether the request indicated this field should be written
-    /// (either to a new value or to NULL).
-    pub fn is_provided(&self) -> bool {
-        !matches!(self, Patch::Unchanged)
-    }
-
-    /// The value to bind when writing, or `None` for `Unchanged`/`Clear`.
-    pub fn set_value(&self) -> Option<&T> {
-        match self {
-            Patch::Set(v) => Some(v),
-            _ => None,
-        }
-    }
-}
-
-impl<'de, T> serde::Deserialize<'de> for Patch<T>
-where
-    T: serde::Deserialize<'de>,
-{
-    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
-    where
-        D: serde::Deserializer<'de>,
-    {
-        Option::<T>::deserialize(deserializer).map(|opt| match opt {
-            Some(v) => Patch::Set(v),
-            None => Patch::Clear,
-        })
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use serde_json::json;
-
-    #[derive(Deserialize)]
-    struct Holder {
-        #[serde(default)]
-        desc: Patch<String>,
-    }
-
-    #[test]
-    fn missing_key_is_unchanged() {
-        let h: Holder = serde_json::from_value(json!({})).unwrap();
-        assert_eq!(h.desc, Patch::Unchanged);
-    }
-
-    #[test]
-    fn explicit_null_is_clear() {
-        let h: Holder = serde_json::from_value(json!({ "desc": null })).unwrap();
-        assert_eq!(h.desc, Patch::Clear);
-    }
-
-    #[test]
-    fn value_is_set() {
-        let h: Holder = serde_json::from_value(json!({ "desc": "x" })).unwrap();
-        assert_eq!(h.desc, Patch::Set("x".into()));
-    }
-}
+// `Patch<T>` lives in `super::patch` so other resources (collections,
+// future PATCH endpoints) can reuse the same three-state semantics
+// without re-importing through `manga::`.

backend/src/domain/mod.rs

@@ -2,9 +2,11 @@ pub mod api_token;
 pub mod author;
 pub mod bookmark;
 pub mod chapter;
+pub mod collection;
 pub mod genre;
 pub mod manga;
 pub mod page;
+pub mod patch;
 pub mod session;
 pub mod tag;
 pub mod user;
@@ -14,9 +16,11 @@ pub use api_token::ApiToken;
 pub use author::{Author, AuthorRef, AuthorWithCount};
 pub use bookmark::{Bookmark, BookmarkSummary};
 pub use chapter::Chapter;
+pub use collection::{Collection, CollectionSummary};
 pub use genre::{Genre, GenreRef};
 pub use manga::{Manga, MangaCard, MangaDetail};
 pub use page::Page;
+pub use patch::Patch;
 pub use session::Session;
 pub use tag::{Tag, TagRef};
 pub use user::User;

backend/src/domain/patch.rs

@@ -0,0 +1,81 @@
+//! Three-state container for PATCH fields.
+//!
+//! `serde`'s default behaviour collapses both "field missing" and
+//! "field is `null`" to `Option::None`, which means an `Option<T>`
+//! patch field can't distinguish "leave alone" from "set to NULL".
+//! `Patch<T>` carries that distinction by deserializing JSON `null`
+//! into `Clear` and any value into `Set`; with `#[serde(default)]`
+//! on the field, a missing key falls through to `Unchanged`.
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub enum Patch<T> {
+    /// Field absent from the request — leave the column untouched.
+    #[default]
+    Unchanged,
+    /// Field present and explicitly `null` — set the column to NULL.
+    Clear,
+    /// Field present with a value — set the column to that value.
+    Set(T),
+}
+
+impl<T> Patch<T> {
+    /// Whether the request indicated this field should be written
+    /// (either to a new value or to NULL).
+    pub fn is_provided(&self) -> bool {
+        !matches!(self, Patch::Unchanged)
+    }
+
+    /// The value to bind when writing, or `None` for `Unchanged`/`Clear`.
+    pub fn set_value(&self) -> Option<&T> {
+        match self {
+            Patch::Set(v) => Some(v),
+            _ => None,
+        }
+    }
+}
+
+impl<'de, T> serde::Deserialize<'de> for Patch<T>
+where
+    T: serde::Deserialize<'de>,
+{
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        Option::<T>::deserialize(deserializer).map(|opt| match opt {
+            Some(v) => Patch::Set(v),
+            None => Patch::Clear,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde::Deserialize;
+    use serde_json::json;
+
+    #[derive(Deserialize)]
+    struct Holder {
+        #[serde(default)]
+        desc: Patch<String>,
+    }
+
+    #[test]
+    fn missing_key_is_unchanged() {
+        let h: Holder = serde_json::from_value(json!({})).unwrap();
+        assert_eq!(h.desc, Patch::Unchanged);
+    }
+
+    #[test]
+    fn explicit_null_is_clear() {
+        let h: Holder = serde_json::from_value(json!({ "desc": null })).unwrap();
+        assert_eq!(h.desc, Patch::Clear);
+    }
+
+    #[test]
+    fn value_is_set() {
+        let h: Holder = serde_json::from_value(json!({ "desc": "x" })).unwrap();
+        assert_eq!(h.desc, Patch::Set("x".into()));
+    }
+}

backend/src/repo/collection.rs

@@ -0,0 +1,280 @@
+//! Collection persistence.
+//!
+//! Same plain-function pattern as `repo::bookmark`. Ownership is
+//! tracked via `collections.user_id`; handlers call `find_owner`
+//! before mutations to keep 403/404 honest.
+
+use sqlx::PgPool;
+use uuid::Uuid;
+
+use crate::domain::collection::{Collection, CollectionSummary};
+use crate::domain::manga::Manga;
+use crate::error::{AppError, AppResult};
+
+pub async fn create(
+    pool: &PgPool,
+    user_id: Uuid,
+    name: &str,
+    description: Option<&str>,
+) -> AppResult<Collection> {
+    let row = sqlx::query_as::<_, Collection>(
+        r#"
+        INSERT INTO collections (user_id, name, description)
+        VALUES ($1, $2, $3)
+        RETURNING id, user_id, name, description, created_at, updated_at
+        "#,
+    )
+    .bind(user_id)
+    .bind(name.trim())
+    .bind(description)
+    .fetch_one(pool)
+    .await
+    .map_err(|e| match e {
+        sqlx::Error::Database(ref db_err) if db_err.is_unique_violation() => {
+            AppError::Conflict("a collection with this name already exists".into())
+        }
+        other => AppError::Database(other),
+    })?;
+    Ok(row)
+}
+
+pub async fn get(pool: &PgPool, id: Uuid) -> AppResult<Collection> {
+    sqlx::query_as::<_, Collection>(
+        r#"
+        SELECT id, user_id, name, description, created_at, updated_at
+        FROM collections
+        WHERE id = $1
+        "#,
+    )
+    .bind(id)
+    .fetch_optional(pool)
+    .await?
+    .ok_or(AppError::NotFound)
+}
+
+pub async fn find_owner(pool: &PgPool, id: Uuid) -> AppResult<Option<Uuid>> {
+    let row: Option<(Uuid,)> =
+        sqlx::query_as("SELECT user_id FROM collections WHERE id = $1")
+            .bind(id)
+            .fetch_optional(pool)
+            .await?;
+    Ok(row.map(|(u,)| u))
+}
+
+/// Paged list of one user's collections. Includes `manga_count` and up
+/// to three sample cover image keys (newest-added first) so a card can
+/// render without a follow-up fetch.
+pub async fn list_for_user(
+    pool: &PgPool,
+    user_id: Uuid,
+    limit: i64,
+    offset: i64,
+) -> AppResult<(Vec<CollectionSummary>, i64)> {
+    let rows = sqlx::query_as::<_, CollectionSummary>(
+        r#"
+        SELECT
+            c.id, c.user_id, c.name, c.description, c.created_at, c.updated_at,
+            (SELECT count(*) FROM collection_mangas cm WHERE cm.collection_id = c.id)
+                AS manga_count,
+            COALESCE(
+                (
+                    -- `array_agg(... ORDER BY ...)` is the only
+                    -- spec-guaranteed way to preserve element order;
+                    -- a subquery's ORDER BY isn't a contract the
+                    -- outer aggregate has to honour. Adding manga_id
+                    -- as a tiebreaker keeps the order stable when
+                    -- multiple rows share `added_at` (bulk imports).
+                    SELECT array_agg(cover_image_path ORDER BY added_at DESC, manga_id)
+                    FROM (
+                        SELECT m.cover_image_path, cm2.added_at, cm2.manga_id
+                        FROM collection_mangas cm2
+                        JOIN mangas m ON m.id = cm2.manga_id
+                        WHERE cm2.collection_id = c.id
+                          AND m.cover_image_path IS NOT NULL
+                        ORDER BY cm2.added_at DESC, cm2.manga_id
+                        LIMIT 3
+                    ) p
+                ),
+                ARRAY[]::text[]
+            ) AS sample_covers
+        FROM collections c
+        WHERE c.user_id = $1
+        ORDER BY c.updated_at DESC, c.id
+        LIMIT $2 OFFSET $3
+        "#,
+    )
+    .bind(user_id)
+    .bind(limit)
+    .bind(offset)
+    .fetch_all(pool)
+    .await?;
+
+    let (total,): (i64,) =
+        sqlx::query_as("SELECT count(*) FROM collections WHERE user_id = $1")
+            .bind(user_id)
+            .fetch_one(pool)
+            .await?;
+    Ok((rows, total))
+}
+
+pub async fn update(
+    pool: &PgPool,
+    id: Uuid,
+    name: Option<&str>,
+    description_provided: bool,
+    description: Option<&str>,
+) -> AppResult<Collection> {
+    let row = sqlx::query_as::<_, Collection>(
+        r#"
+        UPDATE collections
+           SET name        = COALESCE($2, name),
+               description = CASE WHEN $3::boolean THEN $4 ELSE description END,
+               updated_at  = now()
+         WHERE id = $1
+        RETURNING id, user_id, name, description, created_at, updated_at
+        "#,
+    )
+    .bind(id)
+    .bind(name.map(str::trim))
+    .bind(description_provided)
+    .bind(description)
+    .fetch_optional(pool)
+    .await
+    .map_err(|e| match e {
+        sqlx::Error::Database(ref db_err) if db_err.is_unique_violation() => {
+            AppError::Conflict("a collection with this name already exists".into())
+        }
+        other => AppError::Database(other),
+    })?
+    .ok_or(AppError::NotFound)?;
+    Ok(row)
+}
+
+pub async fn delete(pool: &PgPool, id: Uuid) -> AppResult<()> {
+    sqlx::query("DELETE FROM collections WHERE id = $1")
+        .bind(id)
+        .execute(pool)
+        .await?;
+    Ok(())
+}
+
+/// Add a manga to a collection. Returns `true` if a new attachment was
+/// created (handler picks 201), `false` if the manga was already in
+/// the collection (handler picks 200). Touches `updated_at` so the
+/// "recent collections" sort reflects activity.
+///
+/// FK violations (manga deleted between the handler's `exists` check
+/// and this insert — a race the API can't fully close from the
+/// outside) are remapped to `NotFound` so the handler returns 404
+/// rather than 500.
+pub async fn add_manga(
+    pool: &PgPool,
+    collection_id: Uuid,
+    manga_id: Uuid,
+) -> AppResult<bool> {
+    let mut tx = pool.begin().await?;
+    let inserted = sqlx::query(
+        r#"
+        INSERT INTO collection_mangas (collection_id, manga_id)
+        VALUES ($1, $2)
+        ON CONFLICT DO NOTHING
+        "#,
+    )
+    .bind(collection_id)
+    .bind(manga_id)
+    .execute(&mut *tx)
+    .await
+    .map_err(|e| match e {
+        sqlx::Error::Database(ref db_err) if db_err.is_foreign_key_violation() => {
+            AppError::NotFound
+        }
+        other => AppError::Database(other),
+    })?;
+    let rows_affected = inserted.rows_affected();
+    if rows_affected > 0 {
+        sqlx::query("UPDATE collections SET updated_at = now() WHERE id = $1")
+            .bind(collection_id)
+            .execute(&mut *tx)
+            .await?;
+    }
+    tx.commit().await?;
+    Ok(rows_affected > 0)
+}
+
+pub async fn remove_manga(
+    pool: &PgPool,
+    collection_id: Uuid,
+    manga_id: Uuid,
+) -> AppResult<()> {
+    let mut tx = pool.begin().await?;
+    let rows_affected = sqlx::query(
+        "DELETE FROM collection_mangas WHERE collection_id = $1 AND manga_id = $2",
+    )
+    .bind(collection_id)
+    .bind(manga_id)
+    .execute(&mut *tx)
+    .await?
+    .rows_affected();
+    if rows_affected > 0 {
+        sqlx::query("UPDATE collections SET updated_at = now() WHERE id = $1")
+            .bind(collection_id)
+            .execute(&mut *tx)
+            .await?;
+    }
+    tx.commit().await?;
+    Ok(())
+}
+
+pub async fn list_mangas(
+    pool: &PgPool,
+    collection_id: Uuid,
+    limit: i64,
+    offset: i64,
+) -> AppResult<(Vec<Manga>, i64)> {
+    let rows = sqlx::query_as::<_, Manga>(
+        r#"
+        SELECT m.id, m.title, m.status, m.alt_titles, m.description,
+               m.cover_image_path, m.created_at, m.updated_at
+          FROM collection_mangas cm
+          JOIN mangas m ON m.id = cm.manga_id
+         WHERE cm.collection_id = $1
+         ORDER BY cm.added_at DESC, m.id
+         LIMIT $2 OFFSET $3
+        "#,
+    )
+    .bind(collection_id)
+    .bind(limit)
+    .bind(offset)
+    .fetch_all(pool)
+    .await?;
+    let (total,): (i64,) =
+        sqlx::query_as("SELECT count(*) FROM collection_mangas WHERE collection_id = $1")
+            .bind(collection_id)
+            .fetch_one(pool)
+            .await?;
+    Ok((rows, total))
+}
+
+/// Which of `user_id`'s collections currently contain `manga_id`?
+/// Used by the "Add to collection" modal to pre-check the boxes.
+pub async fn list_collections_containing(
+    pool: &PgPool,
+    user_id: Uuid,
+    manga_id: Uuid,
+) -> AppResult<Vec<Uuid>> {
+    let rows: Vec<(Uuid,)> = sqlx::query_as(
+        r#"
+        SELECT c.id
+          FROM collections c
+          JOIN collection_mangas cm ON cm.collection_id = c.id
+         WHERE c.user_id = $1
+           AND cm.manga_id = $2
+         ORDER BY c.updated_at DESC
+        "#,
+    )
+    .bind(user_id)
+    .bind(manga_id)
+    .fetch_all(pool)
+    .await?;
+    Ok(rows.into_iter().map(|(id,)| id).collect())
+}

backend/src/repo/mod.rs

@@ -2,6 +2,7 @@ pub mod api_token;
 pub mod author;
 pub mod bookmark;
 pub mod chapter;
+pub mod collection;
 pub mod genre;
 pub mod manga;
 pub mod page;

backend/tests/api_collections.rs

@@ -0,0 +1,605 @@
+mod common;
+
+use axum::http::StatusCode;
+use serde_json::{json, Value};
+use sqlx::PgPool;
+use tower::ServiceExt;
+use uuid::Uuid;
+
+async fn create_collection(
+    app: &axum::Router,
+    cookie: &str,
+    name: &str,
+) -> Value {
+    let resp = app
+        .clone()
+        .oneshot(common::post_json_with_cookie(
+            "/api/v1/collections",
+            json!({ "name": name }),
+            cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::CREATED, "create_collection failed");
+    common::body_json(resp).await
+}
+
+fn id_of(v: &Value) -> String {
+    v["id"].as_str().unwrap().to_string()
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_then_list_returns_only_own(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie_a) = common::register_user(&h.app).await;
+    let (_, cookie_b) = common::register_user(&h.app).await;
+
+    let _favs = create_collection(&h.app, &cookie_a, "Favorites").await;
+    let _read = create_collection(&h.app, &cookie_a, "Reading List").await;
+
+    // User B sees an empty list.
+    let resp = h
+        .app
+        .clone()
+        .oneshot(common::get_with_cookie("/api/v1/me/collections", &cookie_b))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["items"], json!([]));
+    assert_eq!(body["page"]["total"], 0);
+
+    // User A sees both.
+    let resp = h
+        .app
+        .oneshot(common::get_with_cookie("/api/v1/me/collections", &cookie_a))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    let names: Vec<&str> = body["items"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|c| c["name"].as_str().unwrap())
+        .collect();
+    // Newest-updated first; both rows have the same updated_at on
+    // create so we just sanity-check membership.
+    assert_eq!(names.len(), 2);
+    assert!(names.contains(&"Favorites"));
+    assert!(names.contains(&"Reading List"));
+    // Empty collections render with manga_count 0 and an empty
+    // sample_covers array, not `null`.
+    for item in body["items"].as_array().unwrap() {
+        assert_eq!(item["manga_count"], 0);
+        assert_eq!(item["sample_covers"], json!([]));
+    }
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn duplicate_name_for_same_user_is_409(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let _ = create_collection(&h.app, &cookie, "Favorites").await;
+
+    let resp = h
+        .app
+        .oneshot(common::post_json_with_cookie(
+            "/api/v1/collections",
+            json!({ "name": "favorites" }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::CONFLICT);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "conflict");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn two_users_can_share_a_collection_name(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, a) = common::register_user(&h.app).await;
+    let (_, b) = common::register_user(&h.app).await;
+    let _ = create_collection(&h.app, &a, "Favorites").await;
+    // No conflict — uniqueness is per-(user_id, lower(name)).
+    let _ = create_collection(&h.app, &b, "Favorites").await;
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_requires_authentication(pool: PgPool) {
+    let h = common::harness(pool);
+    let resp = h
+        .app
+        .oneshot(common::post_json(
+            "/api/v1/collections",
+            json!({ "name": "Anon" }),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_rejects_blank_name_with_422(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let resp = h
+        .app
+        .oneshot(common::post_json_with_cookie(
+            "/api/v1/collections",
+            json!({ "name": "   " }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn get_one_returns_404_for_non_owner_no_existence_leak(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, a) = common::register_user(&h.app).await;
+    let (_, b) = common::register_user(&h.app).await;
+    let coll = create_collection(&h.app, &a, "Favorites").await;
+    let id = id_of(&coll);
+
+    // Owner-mismatch is collapsed to 404 so the API doesn't disclose
+    // collection existence to non-owners. Otherwise an attacker could
+    // distinguish "exists, not yours" from "doesn't exist" by status.
+    let resp = h
+        .app
+        .oneshot(common::get_with_cookie(
+            &format!("/api/v1/collections/{id}"),
+            &b,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn add_manga_is_idempotent_and_picks_201_then_200(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = common::seed_manga_via_api(&h.app, &cookie, "Berserk").await;
+    let coll = create_collection(&h.app, &cookie, "Favorites").await;
+    let coll_id = id_of(&coll);
+
+    let req = || {
+        common::post_json_with_cookie(
+            &format!("/api/v1/collections/{coll_id}/mangas"),
+            json!({ "manga_id": manga_id.to_string() }),
+            &cookie,
+        )
+    };
+
+    let first = h.app.clone().oneshot(req()).await.unwrap();
+    assert_eq!(first.status(), StatusCode::CREATED);
+    let second = h.app.oneshot(req()).await.unwrap();
+    assert_eq!(second.status(), StatusCode::OK);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn add_manga_returns_404_when_manga_missing(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let coll = create_collection(&h.app, &cookie, "Favorites").await;
+    let coll_id = id_of(&coll);
+
+    let resp = h
+        .app
+        .oneshot(common::post_json_with_cookie(
+            &format!("/api/v1/collections/{coll_id}/mangas"),
+            json!({ "manga_id": Uuid::new_v4().to_string() }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn add_manga_to_someone_elses_collection_is_404(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, a) = common::register_user(&h.app).await;
+    let (_, b) = common::register_user(&h.app).await;
+    let coll_a = create_collection(&h.app, &a, "Mine").await;
+    let coll_a_id = id_of(&coll_a);
+    let manga_id = common::seed_manga_via_api(&h.app, &b, "Anything").await;
+
+    let resp = h
+        .app
+        .oneshot(common::post_json_with_cookie(
+            &format!("/api/v1/collections/{coll_a_id}/mangas"),
+            json!({ "manga_id": manga_id.to_string() }),
+            &b,
+        ))
+        .await
+        .unwrap();
+    // 404 not 403 — same non-existence-leak rationale as `get_one`.
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn patch_on_other_users_collection_is_404(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, a) = common::register_user(&h.app).await;
+    let (_, b) = common::register_user(&h.app).await;
+    let coll = create_collection(&h.app, &a, "Mine").await;
+    let id = id_of(&coll);
+    let resp = h
+        .app
+        .oneshot(common::patch_json_with_cookie(
+            &format!("/api/v1/collections/{id}"),
+            json!({ "name": "Hijacked" }),
+            &b,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn patch_description_null_clears_existing_value(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let coll = create_collection(&h.app, &cookie, "C").await;
+    let id = id_of(&coll);
+    // Seed a description first via PATCH.
+    let _ = h
+        .app
+        .clone()
+        .oneshot(common::patch_json_with_cookie(
+            &format!("/api/v1/collections/{id}"),
+            json!({ "description": "starting desc" }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    // Now PATCH with description=null and expect the column cleared.
+    let resp = h
+        .app
+        .oneshot(common::patch_json_with_cookie(
+            &format!("/api/v1/collections/{id}"),
+            json!({ "description": null }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    assert!(body["description"].is_null(), "expected description cleared");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn patch_description_empty_string_sets_empty_not_null(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let coll = create_collection(&h.app, &cookie, "C").await;
+    let id = id_of(&coll);
+    let resp = h
+        .app
+        .oneshot(common::patch_json_with_cookie(
+            &format!("/api/v1/collections/{id}"),
+            json!({ "description": "" }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    // Empty string is a valid distinct value; only `null` clears.
+    assert_eq!(body["description"], "");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn patch_description_omitted_leaves_value_intact(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let coll = create_collection(&h.app, &cookie, "C").await;
+    let id = id_of(&coll);
+    let _ = h
+        .app
+        .clone()
+        .oneshot(common::patch_json_with_cookie(
+            &format!("/api/v1/collections/{id}"),
+            json!({ "description": "Keep me" }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    // PATCH that doesn't mention description must not touch it.
+    let resp = h
+        .app
+        .oneshot(common::patch_json_with_cookie(
+            &format!("/api/v1/collections/{id}"),
+            json!({ "name": "Renamed" }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    assert_eq!(body["name"], "Renamed");
+    assert_eq!(body["description"], "Keep me");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn patch_with_empty_body_leaves_row_unchanged(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let coll = create_collection(&h.app, &cookie, "Stable").await;
+    let id = id_of(&coll);
+    let resp = h
+        .app
+        .oneshot(common::patch_json_with_cookie(
+            &format!("/api/v1/collections/{id}"),
+            json!({}),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["name"], "Stable");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn my_collections_for_unknown_manga_returns_empty_list(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let resp = h
+        .app
+        .oneshot(common::get_with_cookie(
+            &format!("/api/v1/mangas/{}/my-collections", Uuid::new_v4()),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    // Non-existent manga is treated the same as a manga the user
+    // hasn't collected — empty list. The handler comment documents
+    // this; the test pins it.
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["collection_ids"], json!([]));
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_mangas_returns_collection_contents(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let m1 = common::seed_manga_via_api(&h.app, &cookie, "First").await;
+    let m2 = common::seed_manga_via_api(&h.app, &cookie, "Second").await;
+    let _untagged = common::seed_manga_via_api(&h.app, &cookie, "NotInIt").await;
+    let coll = create_collection(&h.app, &cookie, "Mix").await;
+    let coll_id = id_of(&coll);
+
+    for m in [m1, m2] {
+        let r = h
+            .app
+            .clone()
+            .oneshot(common::post_json_with_cookie(
+                &format!("/api/v1/collections/{coll_id}/mangas"),
+                json!({ "manga_id": m.to_string() }),
+                &cookie,
+            ))
+            .await
+            .unwrap();
+        assert_eq!(r.status(), StatusCode::CREATED);
+    }
+
+    let resp = h
+        .app
+        .oneshot(common::get_with_cookie(
+            &format!("/api/v1/collections/{coll_id}/mangas"),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    let titles: Vec<&str> = body["items"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|m| m["title"].as_str().unwrap())
+        .collect();
+    // Newest-added first.
+    assert_eq!(titles, vec!["Second", "First"]);
+    assert_eq!(body["page"]["total"], 2);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn remove_manga_is_idempotent(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = common::seed_manga_via_api(&h.app, &cookie, "M").await;
+    let coll = create_collection(&h.app, &cookie, "C").await;
+    let coll_id = id_of(&coll);
+
+    let _ = h
+        .app
+        .clone()
+        .oneshot(common::post_json_with_cookie(
+            &format!("/api/v1/collections/{coll_id}/mangas"),
+            json!({ "manga_id": manga_id.to_string() }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+
+    let first = h
+        .app
+        .clone()
+        .oneshot(common::delete_with_cookie(
+            &format!("/api/v1/collections/{coll_id}/mangas/{manga_id}"),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(first.status(), StatusCode::NO_CONTENT);
+    // Removing again is still a 204 — DELETE is idempotent.
+    let second = h
+        .app
+        .oneshot(common::delete_with_cookie(
+            &format!("/api/v1/collections/{coll_id}/mangas/{manga_id}"),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(second.status(), StatusCode::NO_CONTENT);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn my_collections_for_manga_lists_only_owned_containing(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, a) = common::register_user(&h.app).await;
+    let (_, b) = common::register_user(&h.app).await;
+    let manga_id = common::seed_manga_via_api(&h.app, &a, "X").await;
+
+    let a_coll = create_collection(&h.app, &a, "A's").await;
+    let b_coll = create_collection(&h.app, &b, "B's").await;
+    let a_coll_id = id_of(&a_coll);
+    let b_coll_id = id_of(&b_coll);
+
+    for (coll, cookie) in [(&a_coll_id, &a), (&b_coll_id, &b)] {
+        let _ = h
+            .app
+            .clone()
+            .oneshot(common::post_json_with_cookie(
+                &format!("/api/v1/collections/{coll}/mangas"),
+                json!({ "manga_id": manga_id.to_string() }),
+                cookie,
+            ))
+            .await
+            .unwrap();
+    }
+
+    let resp = h
+        .app
+        .oneshot(common::get_with_cookie(
+            &format!("/api/v1/mangas/{manga_id}/my-collections"),
+            &a,
+        ))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    let ids: Vec<&str> = body["collection_ids"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|v| v.as_str().unwrap())
+        .collect();
+    assert_eq!(ids, vec![a_coll_id.as_str()]);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn patch_collection_updates_name_and_description(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let coll = create_collection(&h.app, &cookie, "Old name").await;
+    let id = id_of(&coll);
+
+    let resp = h
+        .app
+        .oneshot(common::patch_json_with_cookie(
+            &format!("/api/v1/collections/{id}"),
+            json!({ "name": "New name", "description": "Some notes" }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["name"], "New name");
+    assert_eq!(body["description"], "Some notes");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn delete_collection_cascades_attachments(pool: PgPool) {
+    let h = common::harness(pool.clone());
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = common::seed_manga_via_api(&h.app, &cookie, "M").await;
+    let coll = create_collection(&h.app, &cookie, "C").await;
+    let coll_id = id_of(&coll);
+
+    let _ = h
+        .app
+        .clone()
+        .oneshot(common::post_json_with_cookie(
+            &format!("/api/v1/collections/{coll_id}/mangas"),
+            json!({ "manga_id": manga_id.to_string() }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+
+    let resp = h
+        .app
+        .oneshot(common::delete_with_cookie(
+            &format!("/api/v1/collections/{coll_id}"),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NO_CONTENT);
+
+    let (count,): (i64,) =
+        sqlx::query_as("SELECT count(*) FROM collection_mangas WHERE collection_id = $1")
+            .bind(Uuid::parse_str(&coll_id).unwrap())
+            .fetch_one(&pool)
+            .await
+            .unwrap();
+    assert_eq!(count, 0, "collection_mangas should cascade-delete with the collection");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn list_summary_carries_sample_covers_when_mangas_attached(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    // Seed a manga with a cover via the upload endpoint so the
+    // cover_image_path column gets populated.
+    let make_metadata = |title: &str| {
+        common::MultipartBuilder::new()
+            .add_json("metadata", json!({ "title": title }))
+            .add_file("cover", "cover.png", "image/png", &common::fake_png_bytes())
+    };
+    let resp = h
+        .app
+        .clone()
+        .oneshot(common::post_multipart_with_cookie(
+            "/api/v1/mangas",
+            make_metadata("With cover"),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    let manga_id = body["id"].as_str().unwrap().to_string();
+
+    let coll = create_collection(&h.app, &cookie, "Visual").await;
+    let coll_id = id_of(&coll);
+    let r = h
+        .app
+        .clone()
+        .oneshot(common::post_json_with_cookie(
+            &format!("/api/v1/collections/{coll_id}/mangas"),
+            json!({ "manga_id": manga_id }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(r.status(), StatusCode::CREATED);
+
+    let resp = h
+        .app
+        .oneshot(common::get_with_cookie("/api/v1/me/collections", &cookie))
+        .await
+        .unwrap();
+    let body = common::body_json(resp).await;
+    let item = &body["items"][0];
+    assert_eq!(item["manga_count"], 1);
+    let covers = item["sample_covers"].as_array().unwrap();
+    assert_eq!(covers.len(), 1);
+    assert!(covers[0]
+        .as_str()
+        .unwrap()
+        .starts_with(&format!("mangas/{manga_id}/cover")));
+}

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mangalord-frontend",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": true,
   "type": "module",
   "scripts": {

frontend/src/lib/api/collections.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
+import {
+    listMyCollections,
+    listMyCollectionsOrEmpty,
+    createCollection,
+    getCollection,
+    updateCollection,
+    deleteCollection,
+    listCollectionMangas,
+    addMangaToCollection,
+    removeMangaFromCollection,
+    getMyCollectionsContaining
+} from './collections';
+
+function ok(body: unknown, status = 200): Response {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' }
+    });
+}
+
+function noContent(): Response {
+    return new Response(null, { status: 204 });
+}
+
+function envelope(status: number, code: string, message: string): Response {
+    return new Response(JSON.stringify({ error: { code, message } }), {
+        status,
+        headers: { 'content-type': 'application/json' }
+    });
+}
+
+function collectionFixture(extra: Record<string, unknown> = {}) {
+    return {
+        id: 'c1',
+        user_id: 'u1',
+        name: 'Favorites',
+        description: null,
+        created_at: '2026-01-01T00:00:00Z',
+        updated_at: '2026-01-01T00:00:00Z',
+        manga_count: 0,
+        sample_covers: [],
+        ...extra
+    };
+}
+
+describe('collections api client', () => {
+    let fetchSpy: MockInstance<typeof globalThis.fetch>;
+
+    beforeEach(() => {
+        fetchSpy = vi.spyOn(globalThis, 'fetch');
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('listMyCollections returns the paged envelope', async () => {
+        fetchSpy.mockResolvedValueOnce(
+            ok({
+                items: [collectionFixture()],
+                page: { limit: 50, offset: 0, total: 1 }
+            })
+        );
+        const result = await listMyCollections();
+        expect(result.items[0].name).toBe('Favorites');
+        const url = fetchSpy.mock.calls[0][0] as string;
+        expect(url).toMatch(/\/v1\/me\/collections$/);
+    });
+
+    it('listMyCollectionsOrEmpty returns empty page on 401', async () => {
+        fetchSpy.mockResolvedValueOnce(envelope(401, 'unauthenticated', 'login required'));
+        const result = await listMyCollectionsOrEmpty();
+        expect(result.items).toEqual([]);
+        expect(result.page.total).toBeNull();
+    });
+
+    it('listMyCollectionsOrEmpty re-throws non-401 errors', async () => {
+        fetchSpy.mockResolvedValueOnce(envelope(500, 'internal_error', 'oops'));
+        await expect(listMyCollectionsOrEmpty()).rejects.toMatchObject({ status: 500 });
+    });
+
+    it('createCollection POSTs JSON to /v1/collections', async () => {
+        fetchSpy.mockResolvedValueOnce(ok(collectionFixture(), 201));
+        const c = await createCollection({ name: 'Favorites' });
+        expect(c.name).toBe('Favorites');
+        const init = fetchSpy.mock.calls[0][1] as RequestInit;
+        expect(init.method).toBe('POST');
+        expect(JSON.parse(init.body as string)).toEqual({ name: 'Favorites' });
+    });
+
+    it('getCollection encodes the id', async () => {
+        fetchSpy.mockResolvedValueOnce(ok(collectionFixture()));
+        await getCollection('id with space');
+        const url = fetchSpy.mock.calls[0][0] as string;
+        expect(url).toContain('/v1/collections/id%20with%20space');
+    });
+
+    it('updateCollection PATCHes with the patch body', async () => {
+        fetchSpy.mockResolvedValueOnce(ok(collectionFixture({ name: 'Read later' })));
+        const updated = await updateCollection('c1', { name: 'Read later' });
+        expect(updated.name).toBe('Read later');
+        const init = fetchSpy.mock.calls[0][1] as RequestInit;
+        expect(init.method).toBe('PATCH');
+        expect(JSON.parse(init.body as string)).toEqual({ name: 'Read later' });
+    });
+
+    it('deleteCollection issues DELETE', async () => {
+        fetchSpy.mockResolvedValueOnce(noContent());
+        await deleteCollection('c1');
+        const init = fetchSpy.mock.calls[0][1] as RequestInit;
+        expect(init.method).toBe('DELETE');
+    });
+
+    it('listCollectionMangas returns the paged envelope of mangas', async () => {
+        fetchSpy.mockResolvedValueOnce(
+            ok({
+                items: [
+                    {
+                        id: 'm1',
+                        title: 'Berserk',
+                        status: 'ongoing',
+                        alt_titles: [],
+                        description: null,
+                        cover_image_path: null,
+                        created_at: '2026-01-01T00:00:00Z',
+                        updated_at: '2026-01-01T00:00:00Z'
+                    }
+                ],
+                page: { limit: 50, offset: 0, total: 1 }
+            })
+        );
+        const r = await listCollectionMangas('c1');
+        expect(r.items[0].title).toBe('Berserk');
+    });
+
+    it('addMangaToCollection POSTs the manga_id', async () => {
+        fetchSpy.mockResolvedValueOnce(ok({}, 201));
+        await addMangaToCollection('c1', 'm9');
+        const init = fetchSpy.mock.calls[0][1] as RequestInit;
+        expect(init.method).toBe('POST');
+        expect(JSON.parse(init.body as string)).toEqual({ manga_id: 'm9' });
+    });
+
+    it('removeMangaFromCollection DELETEs the nested resource', async () => {
+        fetchSpy.mockResolvedValueOnce(noContent());
+        await removeMangaFromCollection('c1', 'm9');
+        const url = fetchSpy.mock.calls[0][0] as string;
+        expect(url).toMatch(/\/v1\/collections\/c1\/mangas\/m9$/);
+    });
+
+    it('getMyCollectionsContaining returns the id list', async () => {
+        fetchSpy.mockResolvedValueOnce(ok({ collection_ids: ['c1', 'c3'] }));
+        const ids = await getMyCollectionsContaining('m1');
+        expect(ids).toEqual(['c1', 'c3']);
+        const url = fetchSpy.mock.calls[0][0] as string;
+        expect(url).toMatch(/\/v1\/mangas\/m1\/my-collections$/);
+    });
+});

frontend/src/lib/api/collections.ts

@@ -0,0 +1,139 @@
+import { ApiError, request, type Manga, type Page } from './client';
+
+export type Collection = {
+    id: string;
+    user_id: string;
+    name: string;
+    description: string | null;
+    created_at: string;
+    updated_at: string;
+};
+
+/** Returned by `GET /v1/me/collections` — enriched for card rendering. */
+export type CollectionSummary = Collection & {
+    manga_count: number;
+    /** Up to 3 cover image keys, newest-added first. */
+    sample_covers: string[];
+};
+
+export type CollectionsPage = {
+    items: CollectionSummary[];
+    page: Page;
+};
+
+export type CollectionMangasPage = {
+    items: Manga[];
+    page: Page;
+};
+
+export type NewCollection = {
+    name: string;
+    description?: string | null;
+};
+
+export type CollectionPatch = {
+    name?: string;
+    description?: string | null;
+};
+
+export type ListMyOptions = { limit?: number; offset?: number };
+
+export async function listMyCollections(
+    opts: ListMyOptions = {}
+): Promise<CollectionsPage> {
+    const params = new URLSearchParams();
+    if (opts.limit != null) params.set('limit', String(opts.limit));
+    if (opts.offset != null) params.set('offset', String(opts.offset));
+    const qs = params.toString();
+    return request<CollectionsPage>(`/v1/me/collections${qs ? `?${qs}` : ''}`);
+}
+
+/** Empty page on 401 so guest-rendering pages don't have to special-case. */
+export async function listMyCollectionsOrEmpty(): Promise<CollectionsPage> {
+    try {
+        return await listMyCollections();
+    } catch (e) {
+        if (e instanceof ApiError && e.status === 401) {
+            return { items: [], page: { limit: 50, offset: 0, total: null } };
+        }
+        throw e;
+    }
+}
+
+export async function createCollection(
+    input: NewCollection
+): Promise<Collection> {
+    return request<Collection>('/v1/collections', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(input)
+    });
+}
+
+export async function getCollection(id: string): Promise<Collection> {
+    return request<Collection>(`/v1/collections/${encodeURIComponent(id)}`);
+}
+
+export async function updateCollection(
+    id: string,
+    patch: CollectionPatch
+): Promise<Collection> {
+    return request<Collection>(`/v1/collections/${encodeURIComponent(id)}`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(patch)
+    });
+}
+
+export async function deleteCollection(id: string): Promise<void> {
+    await request<void>(`/v1/collections/${encodeURIComponent(id)}`, {
+        method: 'DELETE'
+    });
+}
+
+export async function listCollectionMangas(
+    id: string,
+    opts: ListMyOptions = {}
+): Promise<CollectionMangasPage> {
+    const params = new URLSearchParams();
+    if (opts.limit != null) params.set('limit', String(opts.limit));
+    if (opts.offset != null) params.set('offset', String(opts.offset));
+    const qs = params.toString();
+    return request<CollectionMangasPage>(
+        `/v1/collections/${encodeURIComponent(id)}/mangas${qs ? `?${qs}` : ''}`
+    );
+}
+
+export async function addMangaToCollection(
+    collectionId: string,
+    mangaId: string
+): Promise<void> {
+    await request<void>(
+        `/v1/collections/${encodeURIComponent(collectionId)}/mangas`,
+        {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ manga_id: mangaId })
+        }
+    );
+}
+
+export async function removeMangaFromCollection(
+    collectionId: string,
+    mangaId: string
+): Promise<void> {
+    await request<void>(
+        `/v1/collections/${encodeURIComponent(collectionId)}/mangas/${encodeURIComponent(mangaId)}`,
+        { method: 'DELETE' }
+    );
+}
+
+/** Which of the user's collections currently contain this manga. */
+export async function getMyCollectionsContaining(
+    mangaId: string
+): Promise<string[]> {
+    const r = await request<{ collection_ids: string[] }>(
+        `/v1/mangas/${encodeURIComponent(mangaId)}/my-collections`
+    );
+    return r.collection_ids;
+}

frontend/src/lib/components/AddToCollectionModal.svelte

@@ -0,0 +1,279 @@
+<script lang="ts">
+    import Modal from './Modal.svelte';
+    import {
+        addMangaToCollection,
+        createCollection,
+        listMyCollections,
+        getMyCollectionsContaining,
+        removeMangaFromCollection,
+        type CollectionSummary
+    } from '$lib/api/collections';
+    import Plus from '@lucide/svelte/icons/plus';
+
+    let {
+        open,
+        mangaId,
+        onClose
+    }: {
+        open: boolean;
+        mangaId: string;
+        onClose: () => void;
+    } = $props();
+
+    let collections = $state<CollectionSummary[]>([]);
+    let containingIds = $state<Set<string>>(new Set());
+    let busyIds = $state<Set<string>>(new Set());
+    let newName = $state('');
+    let creating = $state(false);
+    let loading = $state(false);
+    let error: string | null = $state(null);
+
+    // Refetch every time the modal opens (and when the manga id changes
+    // mid-session — unlikely but cheap). The data is per-user and per-
+    // manga, so re-fetching is the simplest way to stay in sync with
+    // changes made elsewhere (e.g., a collection deleted on another page).
+    $effect(() => {
+        if (open) {
+            void load();
+        }
+    });
+
+    async function load() {
+        loading = true;
+        error = null;
+        try {
+            const [page, ids] = await Promise.all([
+                listMyCollections({ limit: 200 }),
+                getMyCollectionsContaining(mangaId)
+            ]);
+            collections = page.items;
+            containingIds = new Set(ids);
+        } catch (e) {
+            error = (e as Error).message;
+        } finally {
+            loading = false;
+        }
+    }
+
+    // Functional set updates that read the latest state at mutation
+    // time, so concurrent toggles on different rows don't clobber
+    // each other by building from a stale snapshot.
+    function withAdd<T>(s: Set<T>, v: T): Set<T> {
+        const n = new Set(s);
+        n.add(v);
+        return n;
+    }
+    function withDelete<T>(s: Set<T>, v: T): Set<T> {
+        const n = new Set(s);
+        n.delete(v);
+        return n;
+    }
+
+    async function toggle(collection: CollectionSummary) {
+        if (busyIds.has(collection.id)) return;
+        const wasIn = containingIds.has(collection.id);
+        // Optimistic toggle — local set first; revert on failure.
+        containingIds = wasIn
+            ? withDelete(containingIds, collection.id)
+            : withAdd(containingIds, collection.id);
+        busyIds = withAdd(busyIds, collection.id);
+        try {
+            if (wasIn) {
+                await removeMangaFromCollection(collection.id, mangaId);
+                collection.manga_count = Math.max(0, collection.manga_count - 1);
+            } else {
+                await addMangaToCollection(collection.id, mangaId);
+                collection.manga_count += 1;
+            }
+        } catch (e) {
+            // Revert (read latest containingIds, not the pre-toggle snapshot).
+            containingIds = wasIn
+                ? withAdd(containingIds, collection.id)
+                : withDelete(containingIds, collection.id);
+            error = (e as Error).message;
+        } finally {
+            busyIds = withDelete(busyIds, collection.id);
+        }
+    }
+
+    async function createAndAdd() {
+        const name = newName.trim();
+        if (!name || creating) return;
+        creating = true;
+        error = null;
+        try {
+            const created = await createCollection({ name });
+            // The list endpoint sorts by updated_at DESC; adding the
+            // manga immediately also bumps it. Append a synthetic
+            // summary so the new collection appears checked-on right
+            // away rather than waiting for a refetch.
+            await addMangaToCollection(created.id, mangaId);
+            collections = [
+                {
+                    ...created,
+                    manga_count: 1,
+                    sample_covers: []
+                },
+                ...collections
+            ];
+            containingIds = new Set([...containingIds, created.id]);
+            newName = '';
+        } catch (e) {
+            error = (e as Error).message;
+        } finally {
+            creating = false;
+        }
+    }
+
+    function onCreateSubmit(e: SubmitEvent) {
+        e.preventDefault();
+        void createAndAdd();
+    }
+</script>
+
+<Modal {open} {onClose} title="Add to collection" size="md" testid="add-to-collection-modal">
+    {#if loading}
+        <p class="status">Loading your collections…</p>
+    {:else if error}
+        <p class="error" role="alert" data-testid="add-to-collection-error">{error}</p>
+    {:else if collections.length === 0}
+        <p class="status" data-testid="no-collections">
+            You don't have any collections yet. Create one below to get started.
+        </p>
+    {:else}
+        <ul class="collection-list">
+            {#each collections as c (c.id)}
+                {@const checked = containingIds.has(c.id)}
+                {@const busy = busyIds.has(c.id)}
+                <li>
+                    <label class="row" class:checked>
+                        <input
+                            type="checkbox"
+                            {checked}
+                            disabled={busy}
+                            onchange={() => toggle(c)}
+                            data-testid={`collection-toggle-${c.id}`}
+                        />
+                        <span class="row-label">
+                            <span class="row-name">{c.name}</span>
+                            <span class="row-count">
+                                {c.manga_count}
+                                {c.manga_count === 1 ? 'manga' : 'mangas'}
+                            </span>
+                        </span>
+                    </label>
+                </li>
+            {/each}
+        </ul>
+    {/if}
+
+    <form
+        class="create-form"
+        onsubmit={onCreateSubmit}
+        action="javascript:void(0)"
+    >
+        <input
+            type="text"
+            bind:value={newName}
+            maxlength="64"
+            placeholder="Create new collection"
+            aria-label="New collection name"
+            data-testid="new-collection-name"
+        />
+        <button
+            type="submit"
+            class="create-btn"
+            disabled={!newName.trim() || creating}
+            data-testid="create-collection-btn"
+        >
+            <Plus size={14} aria-hidden="true" />
+            <span>{creating ? 'Creating…' : 'Create + add'}</span>
+        </button>
+    </form>
+</Modal>
+
+<style>
+    .status {
+        color: var(--text-muted);
+    }
+
+    .error {
+        color: var(--danger);
+        margin: 0 0 var(--space-2);
+    }
+
+    .collection-list {
+        list-style: none;
+        padding: 0;
+        margin: 0 0 var(--space-3);
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-1);
+        max-height: 16rem;
+        overflow-y: auto;
+    }
+
+    .row {
+        display: flex;
+        align-items: center;
+        gap: var(--space-2);
+        padding: var(--space-2);
+        border-radius: var(--radius-md);
+        cursor: pointer;
+        transition: background var(--transition);
+    }
+
+    .row:hover {
+        background: var(--surface-elevated);
+    }
+
+    .row.checked {
+        background: var(--primary-soft-bg);
+    }
+
+    .row-label {
+        display: flex;
+        flex-direction: column;
+        min-width: 0;
+    }
+
+    .row-name {
+        color: var(--text);
+        font-weight: var(--weight-medium);
+    }
+
+    .row-count {
+        color: var(--text-muted);
+        font-size: var(--font-xs);
+    }
+
+    .create-form {
+        display: flex;
+        gap: var(--space-2);
+        align-items: center;
+        padding-top: var(--space-3);
+        border-top: 1px solid var(--border);
+    }
+
+    .create-form input {
+        flex: 1;
+        min-width: 0;
+    }
+
+    .create-btn {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--space-1);
+        background: var(--primary);
+        color: var(--primary-contrast);
+        border: 1px solid var(--primary);
+        padding: 0 var(--space-3);
+        height: 36px;
+        white-space: nowrap;
+    }
+
+    .create-btn:hover:not(:disabled) {
+        background: var(--primary-hover);
+        border-color: var(--primary-hover);
+    }
+</style>

frontend/src/lib/components/Modal.svelte

@@ -0,0 +1,221 @@
+<script lang="ts">
+    import { onMount } from 'svelte';
+    import type { Snippet } from 'svelte';
+    import X from '@lucide/svelte/icons/x';
+
+    let {
+        open,
+        title,
+        onClose,
+        children,
+        footer,
+        size = 'md',
+        closeOnBackdrop = false,
+        testid
+    }: {
+        open: boolean;
+        title: string;
+        onClose: () => void;
+        children: Snippet;
+        footer?: Snippet;
+        size?: 'sm' | 'md' | 'lg';
+        /**
+         * Whether clicking the dim backdrop closes the modal. Off by
+         * default — forms with unsaved input would discard typed data
+         * on a misclick. Opt-in for confirm dialogs and read-only
+         * popovers.
+         */
+        closeOnBackdrop?: boolean;
+        testid?: string;
+    } = $props();
+
+    let dialog: HTMLDivElement | undefined = $state();
+
+    // Track previous focus so we can restore it on close — a basic
+    // requirement for any focus-trapping modal.
+    let previouslyFocused: HTMLElement | null = null;
+
+    $effect(() => {
+        if (open) {
+            previouslyFocused = document.activeElement as HTMLElement | null;
+            // Defer until the dialog mounts.
+            queueMicrotask(() => dialog?.focus());
+        } else if (previouslyFocused) {
+            previouslyFocused.focus();
+            previouslyFocused = null;
+        }
+    });
+
+    function focusable(): HTMLElement[] {
+        if (!dialog) return [];
+        // Standard set of "tab can land here" elements, minus those
+        // disabled or with `tabindex=-1`. Sufficient for our forms.
+        const selector = [
+            'a[href]',
+            'button:not([disabled])',
+            'input:not([disabled]):not([type="hidden"])',
+            'select:not([disabled])',
+            'textarea:not([disabled])',
+            '[tabindex]:not([tabindex="-1"])'
+        ].join(',');
+        return Array.from(dialog.querySelectorAll<HTMLElement>(selector));
+    }
+
+    function onKeydown(e: KeyboardEvent) {
+        if (!open) return;
+        if (e.key === 'Escape') {
+            e.stopPropagation();
+            onClose();
+            return;
+        }
+        if (e.key === 'Tab') {
+            // Wrap focus inside the dialog so Tab/Shift+Tab don't
+            // escape to the background page.
+            const items = focusable();
+            if (items.length === 0) {
+                e.preventDefault();
+                dialog?.focus();
+                return;
+            }
+            const first = items[0];
+            const last = items[items.length - 1];
+            const active = document.activeElement as HTMLElement | null;
+            if (e.shiftKey) {
+                if (active === first || !dialog?.contains(active)) {
+                    e.preventDefault();
+                    last.focus();
+                }
+            } else if (active === last) {
+                e.preventDefault();
+                first.focus();
+            }
+        }
+    }
+
+    onMount(() => {
+        document.addEventListener('keydown', onKeydown);
+        return () => document.removeEventListener('keydown', onKeydown);
+    });
+
+    function onBackdropClick(e: MouseEvent) {
+        if (!closeOnBackdrop) return;
+        if (e.target === e.currentTarget) onClose();
+    }
+</script>
+
+{#if open}
+    <div
+        class="backdrop"
+        onclick={onBackdropClick}
+        role="presentation"
+        data-testid={testid ? `${testid}-backdrop` : undefined}
+    >
+        <div
+            class="dialog size-{size}"
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="modal-title"
+            tabindex="-1"
+            bind:this={dialog}
+            data-testid={testid}
+        >
+            <header class="header">
+                <h2 id="modal-title">{title}</h2>
+                <button
+                    type="button"
+                    class="close"
+                    onclick={onClose}
+                    aria-label="Close"
+                    title="Close"
+                    data-testid={testid ? `${testid}-close` : undefined}
+                >
+                    <X size={18} aria-hidden="true" />
+                </button>
+            </header>
+            <div class="body">{@render children()}</div>
+            {#if footer}
+                <footer class="footer">{@render footer()}</footer>
+            {/if}
+        </div>
+    </div>
+{/if}
+
+<style>
+    .backdrop {
+        position: fixed;
+        inset: 0;
+        background: rgba(0, 0, 0, 0.4);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: var(--space-4);
+        z-index: var(--z-modal);
+    }
+
+    .dialog {
+        background: var(--surface);
+        color: var(--text);
+        border: 1px solid var(--border);
+        border-radius: var(--radius-lg);
+        box-shadow: 0 8px 32px rgba(0, 0, 0, 0.2);
+        max-height: 90vh;
+        display: flex;
+        flex-direction: column;
+        width: 100%;
+        outline: none;
+    }
+
+    .size-sm {
+        max-width: 24rem;
+    }
+    .size-md {
+        max-width: 32rem;
+    }
+    .size-lg {
+        max-width: 48rem;
+    }
+
+    .header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: var(--space-3) var(--space-4);
+        border-bottom: 1px solid var(--border);
+    }
+
+    .header h2 {
+        margin: 0;
+        font-size: var(--font-lg);
+    }
+
+    .close {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 32px;
+        height: 32px;
+        padding: 0;
+        background: transparent;
+        color: var(--text-muted);
+        border: 1px solid transparent;
+        border-radius: var(--radius-sm);
+    }
+
+    .close:hover {
+        background: var(--surface-elevated);
+        color: var(--text);
+    }
+
+    .body {
+        padding: var(--space-4);
+        overflow-y: auto;
+    }
+
+    .footer {
+        padding: var(--space-3) var(--space-4);
+        border-top: 1px solid var(--border);
+        display: flex;
+        gap: var(--space-2);
+        justify-content: flex-end;
+    }
+</style>

frontend/src/routes/+layout.svelte

@@ -7,6 +7,7 @@
     import { theme } from '$lib/theme.svelte';
     import Upload from '@lucide/svelte/icons/upload';
     import Bookmark from '@lucide/svelte/icons/bookmark';
+    import FolderOpen from '@lucide/svelte/icons/folder-open';
     import Settings from '@lucide/svelte/icons/settings';
     import LogOut from '@lucide/svelte/icons/log-out';
     import '$lib/styles/tokens.css';
@@ -56,6 +57,10 @@
             <Bookmark size={18} aria-hidden="true" />
             <span>Bookmarks</span>
         </a>
+        <a class="nav-link" href="/collections">
+            <FolderOpen size={18} aria-hidden="true" />
+            <span>Collections</span>
+        </a>
     </nav>
     <div class="session" data-testid="session-area">
         {#if !session.loaded}

frontend/src/routes/collections/+page.svelte

@@ -0,0 +1,158 @@
+<script lang="ts">
+    import { fileUrl } from '$lib/api/client';
+    import FolderOpen from '@lucide/svelte/icons/folder-open';
+
+    let { data } = $props();
+    const collections = $derived(data.collections);
+</script>
+
+<svelte:head>
+    <title>Collections — Mangalord</title>
+</svelte:head>
+
+<h1>Collections</h1>
+
+{#if !data.authenticated}
+    <p class="status">
+        <a href="/login">Sign in</a> to see and manage your collections.
+    </p>
+{:else if data.error}
+    <p class="error" role="alert">{data.error}</p>
+{:else if collections.length === 0}
+    <p class="status" data-testid="collections-empty">
+        You don't have any collections yet. Open any manga and use
+        <strong>Add to collection</strong> to start one.
+    </p>
+{:else}
+    <ul class="grid" data-testid="collections-list">
+        {#each collections as c (c.id)}
+            <li class="card">
+                <a href="/collections/{c.id}" class="cover-link" tabindex="-1" aria-hidden="true">
+                    <div class="collage">
+                        {#if c.sample_covers.length === 0}
+                            <div class="collage-empty">
+                                <FolderOpen size={36} aria-hidden="true" />
+                            </div>
+                        {:else}
+                            {#each c.sample_covers as cover (cover)}
+                                <img
+                                    src={fileUrl(cover)}
+                                    alt=""
+                                    class="collage-cover"
+                                    loading="lazy"
+                                />
+                            {/each}
+                        {/if}
+                    </div>
+                </a>
+                <div class="meta">
+                    <a href="/collections/{c.id}" class="name" data-testid={`collection-${c.id}`}>
+                        {c.name}
+                    </a>
+                    <span class="count">
+                        {c.manga_count}
+                        {c.manga_count === 1 ? 'manga' : 'mangas'}
+                    </span>
+                </div>
+            </li>
+        {/each}
+    </ul>
+{/if}
+
+<style>
+    .status {
+        color: var(--text-muted);
+    }
+
+    .error {
+        color: var(--danger);
+    }
+
+    .grid {
+        list-style: none;
+        padding: 0;
+        margin: 0;
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
+        gap: var(--space-4);
+    }
+
+    .card {
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-2);
+    }
+
+    .cover-link {
+        display: block;
+        line-height: 0;
+    }
+
+    .collage {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        grid-template-rows: 1fr 1fr;
+        gap: 2px;
+        aspect-ratio: 2 / 3;
+        border-radius: var(--radius-md);
+        overflow: hidden;
+        background: var(--surface);
+    }
+
+    .collage-empty {
+        grid-column: 1 / -1;
+        grid-row: 1 / -1;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        color: var(--text-muted);
+    }
+
+    .collage-cover {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+    }
+
+    /* If only one cover, it fills the whole card. */
+    .collage-cover:only-child {
+        grid-column: 1 / -1;
+        grid-row: 1 / -1;
+    }
+
+    /* If two covers, split vertically. */
+    .collage-cover:first-child:nth-last-child(2),
+    .collage-cover:first-child:nth-last-child(2) ~ .collage-cover {
+        grid-row: 1 / -1;
+    }
+
+    /* If three covers: the first spans the left column, the other two stack on the right. */
+    .collage-cover:first-child:nth-last-child(3) {
+        grid-row: 1 / -1;
+    }
+
+    .meta {
+        display: flex;
+        flex-direction: column;
+        min-width: 0;
+        gap: var(--space-1);
+    }
+
+    .name {
+        font-weight: var(--weight-semibold);
+        color: var(--text);
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .name:hover {
+        color: var(--primary);
+        text-decoration: none;
+    }
+
+    .count {
+        color: var(--text-muted);
+        font-size: var(--font-xs);
+    }
+</style>

frontend/src/routes/collections/+page.ts

@@ -0,0 +1,20 @@
+import { ApiError } from '$lib/api/client';
+import { listMyCollections } from '$lib/api/collections';
+import type { PageLoad } from './$types';
+
+export const ssr = false;
+
+export const load: PageLoad = async () => {
+    try {
+        const page = await listMyCollections({ limit: 200 });
+        return { collections: page.items, authenticated: true, error: null };
+    } catch (e) {
+        if (e instanceof ApiError && e.status === 401) {
+            return { collections: [], authenticated: false, error: null };
+        }
+        if (e instanceof ApiError) {
+            return { collections: [], authenticated: true, error: e.message };
+        }
+        throw e;
+    }
+};

frontend/src/routes/collections/[id]/+page.svelte

@@ -0,0 +1,313 @@
+<script lang="ts">
+    import { goto } from '$app/navigation';
+    import {
+        deleteCollection,
+        removeMangaFromCollection,
+        updateCollection
+    } from '$lib/api/collections';
+    import type { Manga } from '$lib/api/client';
+    import MangaCard from '$lib/components/MangaCard.svelte';
+    import ArrowLeft from '@lucide/svelte/icons/arrow-left';
+    import Pencil from '@lucide/svelte/icons/pencil';
+    import Check from '@lucide/svelte/icons/check';
+    import Trash2 from '@lucide/svelte/icons/trash-2';
+    import X from '@lucide/svelte/icons/x';
+
+    let { data } = $props();
+    // svelte-ignore state_referenced_locally
+    let collection = $state({ ...data.collection });
+    // svelte-ignore state_referenced_locally
+    let mangas = $state<Manga[]>([...data.mangas]);
+
+    let editing = $state(false);
+    let editName = $state('');
+    let editDescription = $state('');
+    let editError: string | null = $state(null);
+    let editBusy = $state(false);
+
+    function startEdit() {
+        editName = collection.name;
+        editDescription = collection.description ?? '';
+        editError = null;
+        editing = true;
+    }
+
+    async function saveEdit() {
+        if (editBusy) return;
+        editBusy = true;
+        editError = null;
+        try {
+            const updated = await updateCollection(collection.id, {
+                name: editName.trim(),
+                description: editDescription.trim() || null
+            });
+            collection = updated;
+            editing = false;
+        } catch (e) {
+            editError = (e as Error).message;
+        } finally {
+            editBusy = false;
+        }
+    }
+
+    async function onDeleteCollection() {
+        if (!confirm(`Delete collection "${collection.name}"? This cannot be undone.`)) {
+            return;
+        }
+        try {
+            await deleteCollection(collection.id);
+            goto('/collections');
+        } catch (e) {
+            editError = (e as Error).message;
+        }
+    }
+
+    async function onRemoveManga(m: Manga) {
+        const snapshot = mangas;
+        mangas = mangas.filter((x) => x.id !== m.id);
+        try {
+            await removeMangaFromCollection(collection.id, m.id);
+        } catch (e) {
+            mangas = snapshot;
+            editError = (e as Error).message;
+        }
+    }
+</script>
+
+<svelte:head>
+    <title>{collection.name} — Mangalord</title>
+</svelte:head>
+
+<nav class="back">
+    <a href="/collections" class="back-link">
+        <ArrowLeft size={16} aria-hidden="true" />
+        <span>All collections</span>
+    </a>
+</nav>
+
+<header class="overview">
+    {#if editing}
+        <form
+            class="edit-form"
+            onsubmit={(e) => {
+                e.preventDefault();
+                void saveEdit();
+            }}
+            action="javascript:void(0)"
+        >
+            <input
+                type="text"
+                bind:value={editName}
+                maxlength="64"
+                required
+                aria-label="Collection name"
+                data-testid="collection-edit-name"
+            />
+            <textarea
+                bind:value={editDescription}
+                rows="2"
+                maxlength="1024"
+                placeholder="Description (optional)"
+                aria-label="Collection description"
+                data-testid="collection-edit-description"
+            ></textarea>
+            <div class="edit-actions">
+                <button
+                    type="submit"
+                    class="primary"
+                    disabled={!editName.trim() || editBusy}
+                    data-testid="collection-edit-save"
+                >
+                    <Check size={14} aria-hidden="true" />
+                    <span>Save</span>
+                </button>
+                <button type="button" onclick={() => (editing = false)} disabled={editBusy}>
+                    <X size={14} aria-hidden="true" />
+                    <span>Cancel</span>
+                </button>
+            </div>
+        </form>
+    {:else}
+        <div class="title-row">
+            <h1 data-testid="collection-name">{collection.name}</h1>
+            <button
+                type="button"
+                class="icon-btn"
+                onclick={startEdit}
+                aria-label="Edit collection"
+                title="Edit"
+                data-testid="collection-edit-open"
+            >
+                <Pencil size={16} aria-hidden="true" />
+            </button>
+            <button
+                type="button"
+                class="icon-btn danger"
+                onclick={onDeleteCollection}
+                aria-label="Delete collection"
+                title="Delete"
+                data-testid="collection-delete"
+            >
+                <Trash2 size={16} aria-hidden="true" />
+            </button>
+        </div>
+        {#if collection.description}
+            <p class="description" data-testid="collection-description">
+                {collection.description}
+            </p>
+        {/if}
+    {/if}
+    {#if editError}
+        <p class="error" role="alert">{editError}</p>
+    {/if}
+</header>
+
+{#if mangas.length === 0}
+    <p class="status" data-testid="collection-empty">
+        This collection is empty.
+    </p>
+{:else}
+    <ul class="manga-grid" data-testid="collection-manga-list">
+        {#each mangas as m (m.id)}
+            <li class="card-with-remove">
+                <MangaCard manga={m} testid={`collection-manga-${m.id}`} />
+                <button
+                    type="button"
+                    class="remove"
+                    onclick={() => onRemoveManga(m)}
+                    aria-label={`Remove ${m.title} from collection`}
+                    title="Remove from collection"
+                    data-testid={`collection-remove-manga-${m.id}`}
+                >
+                    <X size={14} aria-hidden="true" />
+                </button>
+            </li>
+        {/each}
+    </ul>
+{/if}
+
+<style>
+    .back {
+        margin-bottom: var(--space-3);
+    }
+
+    .back-link {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--space-1);
+        color: var(--text-muted);
+        font-size: var(--font-sm);
+    }
+
+    .overview {
+        margin-bottom: var(--space-5);
+    }
+
+    .title-row {
+        display: flex;
+        align-items: center;
+        gap: var(--space-2);
+    }
+
+    .title-row h1 {
+        margin: 0;
+        flex: 1;
+    }
+
+    .description {
+        color: var(--text-muted);
+        margin: var(--space-2) 0 0;
+        white-space: pre-wrap;
+    }
+
+    .edit-form {
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-2);
+    }
+
+    .edit-actions {
+        display: flex;
+        gap: var(--space-2);
+    }
+
+    .primary {
+        background: var(--primary);
+        color: var(--primary-contrast);
+        border-color: var(--primary);
+    }
+
+    .primary:hover:not(:disabled) {
+        background: var(--primary-hover);
+        border-color: var(--primary-hover);
+    }
+
+    .error {
+        color: var(--danger);
+        margin: var(--space-2) 0 0;
+    }
+
+    .status {
+        color: var(--text-muted);
+    }
+
+    .manga-grid {
+        list-style: none;
+        padding: 0;
+        margin: 0;
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+        gap: var(--space-4);
+    }
+
+    .card-with-remove {
+        position: relative;
+        list-style: none;
+    }
+
+    .remove {
+        position: absolute;
+        top: var(--space-1);
+        right: var(--space-1);
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 24px;
+        height: 24px;
+        padding: 0;
+        background: rgba(0, 0, 0, 0.6);
+        color: white;
+        border: 0;
+        border-radius: 50%;
+        cursor: pointer;
+        opacity: 0;
+        transition: opacity var(--transition);
+    }
+
+    .card-with-remove:hover .remove,
+    .card-with-remove:focus-within .remove {
+        opacity: 1;
+    }
+
+    .icon-btn {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 32px;
+        height: 32px;
+        padding: 0;
+        background: transparent;
+        color: var(--text-muted);
+        border: 1px solid transparent;
+        border-radius: var(--radius-sm);
+    }
+
+    .icon-btn:hover {
+        background: var(--surface-elevated);
+        color: var(--text);
+    }
+
+    .icon-btn.danger:hover {
+        color: var(--danger);
+    }
+</style>

frontend/src/routes/collections/[id]/+page.ts

@@ -0,0 +1,40 @@
+import { error, redirect } from '@sveltejs/kit';
+import { ApiError } from '$lib/api/client';
+import {
+    getCollection,
+    listCollectionMangas
+} from '$lib/api/collections';
+import type { PageLoad } from './$types';
+
+export const ssr = false;
+
+export const load: PageLoad = async ({ params, url }) => {
+    try {
+        const [collection, mangas] = await Promise.all([
+            getCollection(params.id),
+            listCollectionMangas(params.id, { limit: 200 })
+        ]);
+        return {
+            collection,
+            mangas: mangas.items,
+            total: mangas.page.total
+        };
+    } catch (e) {
+        if (e instanceof ApiError) {
+            // 401 means the user's session is gone — bounce to login
+            // and preserve where they wanted to go.
+            if (e.status === 401) {
+                const next = encodeURIComponent(url.pathname);
+                redirect(302, `/login?next=${next}`);
+            }
+            // 403 (post-Phase-3-polish the backend collapses this to
+            // 404 already, but keep the branch for defense-in-depth)
+            // and 404 both render the standard not-found page so the
+            // URL doesn't disclose collection existence to non-owners.
+            if (e.status === 404 || e.status === 403) {
+                error(404, 'Collection not found');
+            }
+        }
+        throw e;
+    }
+};

frontend/src/routes/manga/[id]/+page.svelte

@@ -11,7 +11,9 @@
     import { listTags, type Tag } from '$lib/api/tags';
     import { session } from '$lib/session.svelte';
     import Chip from '$lib/components/Chip.svelte';
+    import AddToCollectionModal from '$lib/components/AddToCollectionModal.svelte';
     import Plus from '@lucide/svelte/icons/plus';
+    import FolderPlus from '@lucide/svelte/icons/folder-plus';
 
     let { data } = $props();
     const manga = $derived(data.manga);
@@ -148,6 +150,8 @@
     }
 
     const statusLabel = $derived(manga.status === 'completed' ? 'Completed' : 'Ongoing');
+
+    let collectionModalOpen = $state(false);
 </script>
 
 <svelte:head>
@@ -284,25 +288,44 @@
             {/if}
 
             {#if session.user}
-                <button
-                    type="button"
-                    class="bookmark"
-                    class:active={mangaBookmark}
-                    onclick={toggleBookmark}
-                    disabled={busy}
-                    aria-pressed={mangaBookmark ? 'true' : 'false'}
-                    data-testid="bookmark-toggle"
-                >
-                    {mangaBookmark ? '★ Bookmarked' : '☆ Bookmark'}
-                </button>
+                <div class="action-row">
+                    <button
+                        type="button"
+                        class="action"
+                        class:active={mangaBookmark}
+                        onclick={toggleBookmark}
+                        disabled={busy}
+                        aria-pressed={mangaBookmark ? 'true' : 'false'}
+                        data-testid="bookmark-toggle"
+                    >
+                        {mangaBookmark ? '★ Bookmarked' : '☆ Bookmark'}
+                    </button>
+                    <button
+                        type="button"
+                        class="action"
+                        onclick={() => (collectionModalOpen = true)}
+                        data-testid="add-to-collection-open"
+                    >
+                        <FolderPlus size={16} aria-hidden="true" />
+                        <span>Add to collection</span>
+                    </button>
+                </div>
             {:else}
-                <a class="bookmark" href="/login" data-testid="bookmark-signin">
-                    Sign in to bookmark
+                <a class="action" href="/login" data-testid="bookmark-signin">
+                    Sign in to bookmark or collect
                 </a>
             {/if}
         </div>
     </header>
 
+    {#if session.user}
+        <AddToCollectionModal
+            open={collectionModalOpen}
+            mangaId={manga.id}
+            onClose={() => (collectionModalOpen = false)}
+        />
+    {/if}
+
     <section aria-label="chapters">
         <h2>Chapters</h2>
         {#if chapters.length === 0}
@@ -475,11 +498,17 @@
         font-size: var(--font-sm);
     }
 
-    .bookmark {
+    .action-row {
+        display: flex;
+        gap: var(--space-2);
+        margin-top: var(--space-2);
+        flex-wrap: wrap;
+    }
+
+    .action {
         display: inline-flex;
         align-items: center;
         gap: var(--space-2);
-        margin-top: var(--space-2);
         padding: 0 var(--space-3);
         height: 36px;
         border: 1px solid var(--border-strong);
@@ -496,12 +525,12 @@
             color var(--transition);
     }
 
-    .bookmark:hover {
+    .action:hover {
         background: var(--surface-elevated);
         text-decoration: none;
     }
 
-    .bookmark.active {
+    .action.active {
         background: var(--warning-soft-bg);
         border-color: var(--warning-border);
         color: var(--text);