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/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;