feat(scanner): store EPUB reading direction at scan time

Fixed-layout EPUBs lean on the reading_direction column (the web reader
forces book.dir = rtl from it when the file didn't set direction
itself), but the scanner never populated it for EPUBs - only ComicInfo
fed it. Meanwhile real Japanese EPUBs declare page-progression-direction
on the OPF spine, which foliate reads client-side but nothing stored.

Read the spine attribute in the structured OPF parser and map it into
ReadingDirection in parseOPFContent (EPUB2/3, case-insensitive, plus
'right-to-left'/'left-to-right' spellings); undeclared stays empty
rather than forcing ltr, preserving the editor's Auto default. Sidecar
OPFs are metadata-only documents without spines, so the Calibre path is
a no-op. The merge gap-fill copies an embedded-only direction into a
blank sidecar field, and hand-set values keep winning through the
existing OverrideReadingDirection protection.

Tests: declared rtl/RTL/ltr, undeclared and unknown values staying
empty, plus sidecar-wins vs embedded-fills merge cases. Existing manga
EPUBs declaring rtl (verified live in-library) pick the value up on
their next scan, feeding the API and reader config mobile clients
consume.

.env.example

@@ -35,5 +35,9 @@ DBPASS=your-secure-database-password-here
 # BOOKHOARD_CONVERSION_TOOL=/usr/bin/ebook-convert
 # Conversion Cache TTL: Override default 24h
 # BOOKHOARD_CONVERSION_CACHE_TTL=48h
+# Archive Retention: days to keep archived items (files missing from disk for
+# 2+ scans) before they are purged, deleting their reading history with them.
+# Set 0 to keep archived items until purged manually on the library admin page.
+# ARCHIVE_RETENTION_DAYS=90
 # System timezone (fallback for server-side time operations, defaults to UTC)
 # TZ=America/New_York

database/schema/schema.sql

@@ -213,6 +213,13 @@ CREATE TABLE IF NOT EXISTS media_items (
     -- reset-to-scanned-defaults action clears them.
     metadata_overrides TEXT[] NOT NULL DEFAULT '{}',
 
+    -- Archive lifecycle: a file missing from disk for two consecutive scans
+    -- gets archived_at set (hidden from all browsing, reading history kept).
+    -- If the file returns, the row is un-archived. Archived rows are purged
+    -- after ARCHIVE_RETENTION_DAYS (0 = manual purge only).
+    missing_scan_count INT NOT NULL DEFAULT 0,
+    archived_at TIMESTAMPTZ,
+
     -- Chapter metadata for reader navigation and progress tracking
         -- Caches detected chapter structure to avoid re-parsing files
         -- Populated by ReaderService.DetectChapters() on first read
@@ -243,6 +250,11 @@ ALTER TABLE media_items ADD COLUMN IF NOT EXISTS contributors_search TEXT[];
 -- definition above for fresh databases)
 ALTER TABLE media_items ADD COLUMN IF NOT EXISTS metadata_overrides TEXT[] NOT NULL DEFAULT '{}';
 
+-- Archive lifecycle (idempotent backfill for existing installs)
+ALTER TABLE media_items ADD COLUMN IF NOT EXISTS missing_scan_count INT NOT NULL DEFAULT 0;
+ALTER TABLE media_items ADD COLUMN IF NOT EXISTS archived_at TIMESTAMPTZ;
+CREATE INDEX IF NOT EXISTS idx_media_items_archived ON media_items (archived_at) WHERE archived_at IS NOT NULL;
+
 -- Create GIN indexes for fast search field searches
 CREATE INDEX IF NOT EXISTS idx_media_items_tags_search ON media_items USING GIN (tags_search);
 CREATE INDEX IF NOT EXISTS idx_media_items_contributors_search ON media_items USING GIN (contributors_search);

docker-compose.yml

@@ -61,6 +61,12 @@ services:
       BOOKHOARD_CONVERSION_TOOL: ${BOOKHOARD_CONVERSION_TOOL:-/usr/bin/kepubify}
       BOOKHOARD_CONVERSION_CACHE_TTL: ${BOOKHOARD_CONVERSION_CACHE_TTL:-24h}
 
+      # Library Maintenance
+      # Days an archived item (file missing from disk for 2+ scans) is kept,
+      # with its reading history, before library scans purge it for good.
+      # Set 0 to keep archived items until purged manually on the library admin page.
+      ARCHIVE_RETENTION_DAYS: ${ARCHIVE_RETENTION_DAYS:-90}
+
       # System timezone (fallback for server-side time operations)
       TZ: ${TZ:-UTC}
     ports:

internal/config/config.go

@@ -84,3 +84,14 @@ func getEnvInt(key string, defaultValue int) int {
 	}
 	return defaultValue
 }
+
+// ArchiveRetentionDays returns how many days a media item stays archived
+// (file missing from disk for two consecutive scans) before library scans
+// purge it for good. Reading progress, notes, and highlights survive the
+// archive window and are restored if the file returns; the purge deletes
+// them along with the row.
+// Configure via ARCHIVE_RETENTION_DAYS (default 90); 0 keeps archived items
+// until an admin purges them manually from the library admin page.
+func ArchiveRetentionDays() int {
+	return getEnvInt("ARCHIVE_RETENTION_DAYS", 90)
+}

internal/database/models.go

@@ -307,6 +307,8 @@ type MediaItems struct {
 	// Summary from ComicInfo.xml (may be merged with description from Calibre)
 	Summary            pgtype.Text        `db:"summary" json:"summary"`
 	MetadataOverrides  []string           `db:"metadata_overrides" json:"metadata_overrides"`
+	MissingScanCount   int32              `db:"missing_scan_count" json:"missing_scan_count"`
+	ArchivedAt         pgtype.Timestamptz `db:"archived_at" json:"archived_at"`
 	ChapterMetadata    []byte             `db:"chapter_metadata" json:"chapter_metadata"`
 	LibraryTypeName    pgtype.Text        `db:"library_type_name" json:"library_type_name"`
 	TagsSearch         []string           `db:"tags_search" json:"tags_search"`

internal/database/querier.go

@@ -20,6 +20,9 @@ type Querier interface {
 	AddBookToKoboShelf(ctx context.Context, arg AddBookToKoboShelfParams) (KoboShelves, error)
 	// Library Folders queries
 	AddLibraryFolder(ctx context.Context, arg AddLibraryFolderParams) (LibraryFolders, error)
+	// Second consecutive missing scan: hide the item from all browsing while
+	// preserving reading history in case the file returns.
+	ArchiveMediaItem(ctx context.Context, id pgtype.UUID) error
 	// Bulk update format group for all media items
 	BulkUpdateFormatGroups(ctx context.Context) error
 	BulkUpdateProgressFromSync(ctx context.Context, arg BulkUpdateProgressFromSyncParams) ([]interface{}, error)
@@ -30,10 +33,14 @@ type Querier interface {
 	ClearDeviceSyncQueue(ctx context.Context, deviceID pgtype.UUID) error
 	ClearKoboShelf(ctx context.Context, deviceID pgtype.UUID) error
 	ClearKoboShelfByName(ctx context.Context, arg ClearKoboShelfByNameParams) error
+	// File is back on disk (by path or content hash): restore visibility and
+	// reset the missing-scan counter. No-op for items that were never archived.
+	ClearMediaItemArchive(ctx context.Context, id pgtype.UUID) error
 	// Reset an item to scanned defaults: clears per-field user overrides so the
 	// next rescan can freely overwrite user-customized metadata.
 	ClearMediaItemMetadataOverrides(ctx context.Context, id pgtype.UUID) error
 	CountAdmins(ctx context.Context) (int64, error)
+	CountArchivedMediaItems(ctx context.Context) (int64, error)
 	// Count unlinked books for a device
 	CountUnlinkedBooks(ctx context.Context, deviceID pgtype.UUID) (int64, error)
 	CountUserDevices(ctx context.Context, userID pgtype.UUID) (int64, error)
@@ -340,9 +347,14 @@ type Querier interface {
 	ListDeletedAnnotationsForBook(ctx context.Context, arg ListDeletedAnnotationsForBookParams) ([]ListDeletedAnnotationsForBookRow, error)
 	ListDevicesByType(ctx context.Context, deviceType string) ([]Devices, error)
 	ListDevicesByUser(ctx context.Context, userID pgtype.UUID) ([]Devices, error)
+	// Items hidden from libraries: either missing from disk (waiting on the
+	// second scan that archives them) or already archived and pending purge.
+	// Feeds the admin archived-items page.
+	ListHiddenMediaItems(ctx context.Context) ([]ListHiddenMediaItemsRow, error)
 	ListLibraries(ctx context.Context) ([]ListLibrariesRow, error)
 	ListMediaItems(ctx context.Context, arg ListMediaItemsParams) ([]ListMediaItemsRow, error)
 	ListMediaItemsByLibrary(ctx context.Context, libraryID pgtype.UUID) ([]ListMediaItemsByLibraryRow, error)
+	ListMediaItemsByLibraryIncludingArchived(ctx context.Context, libraryID pgtype.UUID) ([]ListMediaItemsByLibraryIncludingArchivedRow, error)
 	// List all media items sharing a SHA-256 hash within a library (hash conflict group)
 	ListMediaItemsBySHA256AndLibrary(ctx context.Context, arg ListMediaItemsBySHA256AndLibraryParams) ([]MediaItems, error)
 	// List media items that have no stored SHA-256 (imported before hashing existed)
@@ -356,6 +368,17 @@ type Querier interface {
 	// List unresolved unlinked books with pagination
 	ListUnresolvedUnlinkedBooks(ctx context.Context, arg ListUnresolvedUnlinkedBooksParams) ([]ListUnresolvedUnlinkedBooksRow, error)
 	ListUsers(ctx context.Context) ([]ListUsersRow, error)
+	// First consecutive scan that cannot find the file on disk.
+	MarkMediaItemMissing(ctx context.Context, id pgtype.UUID) error
+	// Content reappeared at a new location while the old path vanished: treat as
+	// a move. Repoints the row (and refreshes file-level fields) so reading
+	// history follows the book; archive/missing state is cleared separately.
+	MoveMediaItemFilePath(ctx context.Context, arg MoveMediaItemFilePathParams) error
+	// Manual bulk purge from the library admin page.
+	PurgeAllArchivedMediaItems(ctx context.Context) ([]PurgeAllArchivedMediaItemsRow, error)
+	// Retention sweep at library-scan time: hard-delete archived items older
+	// than the cutoff. Cascades remove reading history with the row.
+	PurgeExpiredArchivedMediaItems(ctx context.Context, archivedAt pgtype.Timestamptz) ([]PurgeExpiredArchivedMediaItemsRow, error)
 	PurgeExpiredBookmarkTombstones(ctx context.Context, deletedAt pgtype.Timestamptz) error
 	PurgeExpiredHighlightTombstones(ctx context.Context, deletedAt pgtype.Timestamptz) error
 	PurgeExpiredNoteTombstones(ctx context.Context, deletedAt pgtype.Timestamptz) error

internal/database/queries/queries.sql

@@ -141,7 +141,9 @@ ORDER BY l.created_at ASC;
 SELECT l.id, COUNT(mi.id) as media_count
 FROM libraries l
 LEFT JOIN library_visibility lv ON l.id = lv.library_id AND lv.user_id = $1
-LEFT JOIN media_items mi ON mi.library_id = l.id
+LEFT JOIN media_items mi ON mi.library_id = l.id AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
+  AND mi.missing_scan_count = 0
 WHERE COALESCE(lv.is_visible, true) = true
 GROUP BY l.id;
 
@@ -160,6 +162,8 @@ SELECT mi.*, l.name as library_name, lt.name as library_type_name
 FROM media_items mi
 JOIN libraries l ON mi.library_id = l.id
 JOIN library_types lt ON l.library_type_id = lt.id
+WHERE mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
 ORDER BY mi.created_at DESC LIMIT $1 OFFSET $2;
 
 -- name: ListMediaItemsByLibrary :many
@@ -167,6 +171,16 @@ SELECT mi.*, l.name as library_name, lt.name as library_type_name
 FROM media_items mi
 JOIN libraries l ON mi.library_id = l.id
 JOIN library_types lt ON l.library_type_id = lt.id
+WHERE mi.library_id = $1
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
+ORDER BY mi.created_at DESC;
+
+-- name: ListMediaItemsByLibraryIncludingArchived :many
+SELECT mi.*, l.name as library_name, lt.name as library_type_name
+FROM media_items mi
+JOIN libraries l ON mi.library_id = l.id
+JOIN library_types lt ON l.library_type_id = lt.id
 WHERE mi.library_id = $1
 ORDER BY mi.created_at DESC;
 
@@ -175,7 +189,9 @@ SELECT mi.*, l.name as library_name, lt.name as library_type_name
 FROM media_items mi
 JOIN libraries l ON mi.library_id = l.id
 JOIN library_types lt ON l.library_type_id = lt.id
-WHERE mi.library_id = sqlc.narg('library_id')
+WHERE mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
+  AND mi.library_id = sqlc.narg('library_id')
 ORDER BY
     CASE
         WHEN sqlc.narg('sort') = 'title ASC' THEN mi.title
@@ -293,6 +309,58 @@ RETURNING *;
 UPDATE media_items SET metadata_overrides = '{}', updated_at = NOW()
 WHERE id = $1;
 
+-- name: MarkMediaItemMissing :exec
+-- First consecutive scan that cannot find the file on disk.
+UPDATE media_items SET missing_scan_count = missing_scan_count + 1, updated_at = NOW()
+WHERE id = $1;
+
+-- name: MoveMediaItemFilePath :exec
+-- Content reappeared at a new location while the old path vanished: treat as
+-- a move. Repoints the row (and refreshes file-level fields) so reading
+-- history follows the book; archive/missing state is cleared separately.
+UPDATE media_items SET file_path = $2, file_size = $3, missing_scan_count = 0,
+  archived_at = NULL, updated_at = NOW()
+WHERE id = $1;
+
+-- name: ArchiveMediaItem :exec
+-- Second consecutive missing scan: hide the item from all browsing while
+-- preserving reading history in case the file returns.
+UPDATE media_items SET archived_at = NOW(), updated_at = NOW()
+WHERE id = $1;
+
+-- name: ClearMediaItemArchive :exec
+-- File is back on disk (by path or content hash): restore visibility and
+-- reset the missing-scan counter. No-op for items that were never archived.
+UPDATE media_items SET archived_at = NULL, missing_scan_count = 0, updated_at = NOW()
+WHERE id = $1 AND (archived_at IS NOT NULL OR missing_scan_count > 0);
+
+-- name: PurgeExpiredArchivedMediaItems :many
+-- Retention sweep at library-scan time: hard-delete archived items older
+-- than the cutoff. Cascades remove reading history with the row.
+DELETE FROM media_items
+WHERE archived_at IS NOT NULL AND archived_at < $1
+RETURNING id, title;
+
+-- name: PurgeAllArchivedMediaItems :many
+-- Manual bulk purge from the library admin page.
+DELETE FROM media_items
+WHERE archived_at IS NOT NULL
+RETURNING id, title;
+
+-- name: CountArchivedMediaItems :one
+SELECT COUNT(*) FROM media_items WHERE archived_at IS NOT NULL;
+
+-- name: ListHiddenMediaItems :many
+-- Items hidden from libraries: either missing from disk (waiting on the
+-- second scan that archives them) or already archived and pending purge.
+-- Feeds the admin archived-items page.
+SELECT mi.*, l.name as library_name, lt.name as library_type_name
+FROM media_items mi
+JOIN libraries l ON mi.library_id = l.id
+JOIN library_types lt ON l.library_type_id = lt.id
+WHERE mi.archived_at IS NOT NULL OR mi.missing_scan_count > 0
+ORDER BY mi.archived_at NULLS LAST, mi.updated_at DESC;
+
 -- name: DeleteMediaItem :exec
 DELETE FROM media_items WHERE id = $1;
 
@@ -441,6 +509,8 @@ JOIN libraries l ON mi.library_id = l.id
 JOIN library_types lt ON l.library_type_id = lt.id
 LEFT JOIN library_visibility lv ON l.id = lv.library_id AND lv.user_id = sqlc.narg('user_id')
  WHERE COALESCE(lv.is_visible, true) = true
+   AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
    AND (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
    AND (
        mi.title ILIKE sqlc.narg('search_pattern') OR
@@ -513,6 +583,8 @@ JOIN libraries l ON mi.library_id = l.id
 JOIN library_types lt ON l.library_type_id = lt.id
 LEFT JOIN library_visibility lv ON l.id = lv.library_id AND lv.user_id = sqlc.narg('user_id')
 WHERE COALESCE(lv.is_visible, true) = true
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
   AND (sqlc.narg('library_id')::uuid IS NULL
   OR mi.library_id = sqlc.narg('library_id')::uuid)
   -- Fuzzy author filter
@@ -646,6 +718,8 @@ FROM media_items mi
 JOIN libraries l ON mi.library_id = l.id
 LEFT JOIN library_visibility lv ON l.id = lv.library_id AND lv.user_id = sqlc.narg('user_id')
 WHERE COALESCE(lv.is_visible, true) = true
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
   AND mi.library_id = sqlc.narg('library_id')
   AND word_similarity(sqlc.narg('search_query'), COALESCE(mi.author, '')) > 0.3
   AND mi.author IS NOT NULL
@@ -663,6 +737,8 @@ FROM media_items mi
 JOIN libraries l ON mi.library_id = l.id
 LEFT JOIN library_visibility lv ON l.id = lv.library_id AND lv.user_id = sqlc.narg('user_id')
 WHERE COALESCE(lv.is_visible, true) = true
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
   AND mi.library_id = sqlc.narg('library_id')
   AND word_similarity(sqlc.narg('search_query'), COALESCE(mi.genre, '')) > 0.3
   AND mi.genre IS NOT NULL
@@ -697,6 +773,8 @@ FROM media_items mi
 JOIN libraries l ON mi.library_id = l.id
 LEFT JOIN library_visibility lv ON l.id = lv.library_id AND lv.user_id = sqlc.narg('user_id')
 WHERE COALESCE(lv.is_visible, true) = true
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
   AND mi.library_id = sqlc.narg('library_id')
   AND word_similarity(sqlc.narg('search_query'), COALESCE(mi.series, '')) > 0.3
   AND mi.series IS NOT NULL
@@ -714,6 +792,8 @@ FROM media_items mi
 JOIN libraries l ON mi.library_id = l.id
 LEFT JOIN library_visibility lv ON l.id = lv.library_id AND lv.user_id = sqlc.narg('user_id')
 WHERE COALESCE(lv.is_visible, true) = true
+  AND mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
   AND mi.library_id = sqlc.narg('library_id')
   AND word_similarity(sqlc.narg('search_query'), COALESCE(mi.language, '')) > 0.3
   AND mi.language IS NOT NULL
@@ -2461,7 +2541,9 @@ next_books AS (
            usp.last_read_at
     FROM media_items mi
     JOIN user_series_progress usp ON mi.series = usp.series
-    WHERE (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
+    WHERE mi.archived_at IS NULL
+  AND mi.missing_scan_count = 0
+      AND (sqlc.narg('library_id')::uuid IS NULL OR mi.library_id = sqlc.narg('library_id')::uuid)
       AND (mi.series_number > usp.max_read_number OR usp.max_read_number IS NULL)
     ORDER BY mi.series, mi.series_number ASC NULLS LAST
 )

internal/handlers/media.go

@@ -1330,6 +1330,51 @@ func (mh *MediaHandler) UpdateMediaItem(c *echo.Context) error {
 	return c.JSON(http.StatusOK, item)
 }
 
+// UnarchiveMediaItem handles POST /api/media-items/:id/unarchive (admin
+// only). Manually restores a hidden/archived item to library visibility
+// without waiting for its file to return. If the file is still gone, the
+// next scan hides it again.
+func (mh *MediaHandler) UnarchiveMediaItem(c *echo.Context) error {
+	user := MustGetAuthenticatedUser(c)
+
+	if user.Role != "admin" {
+		return c.JSON(http.StatusForbidden, map[string]string{"error": "admin access required"})
+	}
+
+	mediaID := c.Param("id")
+	mediaUUID, err := uuid.Parse(mediaID)
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid media item id"})
+	}
+
+	if err := mh.db.ClearMediaItemArchive(c.Request().Context(), pgtype.UUID{Bytes: mediaUUID, Valid: true}); err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.NoContent(http.StatusNoContent)
+}
+
+// PurgeArchivedMediaItems handles POST /api/media-items/purge-archived
+// (admin only). Hard-deletes every archived item (files missing from disk for
+// 2+ scans) together with its reading history. The archive retention window
+// eventually does the same automatically; this is the manual bulk escape hatch.
+func (mh *MediaHandler) PurgeArchivedMediaItems(c *echo.Context) error {
+	user := MustGetAuthenticatedUser(c)
+
+	if user.Role != "admin" {
+		return c.JSON(http.StatusForbidden, map[string]string{"error": "admin access required"})
+	}
+
+	purged, err := mh.db.PurgeAllArchivedMediaItems(c.Request().Context())
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, map[string]interface{}{
+		"purged": len(purged),
+	})
+}
+
 // RescanMediaItem handles POST /api/media-items/:id/rescan (admin only)
 func (mh *MediaHandler) RescanMediaItem(c *echo.Context) error {
 	user := MustGetAuthenticatedUser(c)

internal/router/frontend.go

@@ -12,6 +12,7 @@ import (
 	"strconv"
 	"time"
 
+	"bookhoard/internal/config"
 	"bookhoard/internal/database"
 	"bookhoard/internal/handlers"
 	"bookhoard/internal/services"
@@ -295,6 +296,18 @@ func registerFrontendRoutes(cfg *Config) {
 		libraryID := libRes.LibraryID
 		libData := libRes.Libraries
 
+		// Steam Deck behavior: an offline library (all folders missing, e.g.
+		// an unmounted external drive) shows an empty shelf with a notice
+		// instead of querying items. Nothing is marked or purged.
+		if !libRes.IsAll {
+			for _, l := range libData {
+				if l.ID == libraryID && l.Offline {
+					errorMsg = l.Name + " is currently unavailable - its storage is not connected. Your books are safe and will return when the drive is reattached."
+					break
+				}
+			}
+		}
+
 		// Fetch saved filters for SSR
 		userUUID, _ := uuid.Parse(user.ID)
 		var savedFilters []database.SavedFilters
@@ -836,6 +849,54 @@ func registerFrontendRoutes(cfg *Config) {
 		return c.HTML(http.StatusOK, buf.String())
 	}))
 
+	frontendProtected.GET("/admin/archived", handlers.AdminMiddleware(func(c *echo.Context) error {
+		user, err := getTemplateUserWithTheme(c, cfg)
+		if err != nil {
+			return renderErrorPage(c, "Error loading user", "user_load_error")
+		}
+
+		rows, err := cfg.Queries.ListHiddenMediaItems(c.Request().Context())
+		if err != nil {
+			log.Printf("ListHiddenMediaItems failed: %v", err)
+			rows = []database.ListHiddenMediaItemsRow{}
+		}
+
+		retentionDays := config.ArchiveRetentionDays()
+		items := make([]templates.ArchivedItem, 0, len(rows))
+		for _, row := range rows {
+			itemUUID, _ := uuid.FromBytes(row.ID.Bytes[0:16])
+			item := templates.ArchivedItem{
+				ID:           itemUUID.String(),
+				Title:        row.Title,
+				Author:       getText(row.Author),
+				LibraryName:  row.LibraryName,
+				FilePath:     row.FilePath,
+				MissingScans: row.MissingScanCount,
+			}
+			if row.ArchivedAt.Valid {
+				archived := row.ArchivedAt.Time
+				item.ArchivedAt = &archived
+				switch {
+				case retentionDays <= 0:
+					item.Status = "Archived - kept until manually purged (retention disabled)"
+				default:
+					purge := archived.AddDate(0, 0, retentionDays)
+					item.PurgeAt = &purge
+					item.Status = "Archived - permanently deleted " + purge.Format("Jan 2, 2006")
+				}
+			} else {
+				item.Status = fmt.Sprintf("Missing from disk - archives on the next scan (%d/2)", row.MissingScanCount)
+			}
+			items = append(items, item)
+		}
+
+		var buf bytes.Buffer
+		if err := templates.AdminArchived(user, items, retentionDays).Render(c.Request().Context(), &buf); err != nil {
+			return err
+		}
+		return c.HTML(http.StatusOK, buf.String())
+	}))
+
 	frontendProtected.GET("/admin/library", handlers.AdminMiddleware(func(c *echo.Context) error {
 		user, err := getTemplateUserWithTheme(c, cfg)
 		if err != nil {
@@ -884,7 +945,8 @@ func registerFrontendRoutes(cfg *Config) {
 		}
 
 		var buf bytes.Buffer
-		err = templates.AdminLibrary(user, libData, userData).Render(c.Request().Context(), &buf)
+		archivedCount, _ := cfg.Queries.CountArchivedMediaItems(c.Request().Context())
+		err = templates.AdminLibrary(user, libData, userData, archivedCount).Render(c.Request().Context(), &buf)
 		if err != nil {
 			return err
 		}

internal/router/helpers.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"log"
 	"net/url"
+	"os"
 	"time"
 
 	"bookhoard/internal/database"
@@ -132,12 +133,30 @@ func resolveLibrary(c *echo.Context, cfg *Config, userUUID string) LibraryResolu
 	res.Libraries = make([]templates.LibraryData, len(libraries))
 	for i, lib := range libraries {
 		libUUID, _ := uuid.FromBytes(lib.ID.Bytes[0:16])
+		// Steam Deck SD-card behavior: a library whose folders are all
+		// missing (unmounted drive) renders offline - hidden contents, no
+		// marking, no purging - and returns when the storage does.
+		offline := false
+		folders, folderErr := cfg.Queries.GetLibraryFolders(c.Request().Context(), lib.ID)
+		if folderErr != nil || len(folders) == 0 {
+			offline = true
+		} else {
+			anyFolderExists := false
+			for _, folder := range folders {
+				if _, statErr := os.Stat(folder.FolderPath); statErr == nil {
+					anyFolderExists = true
+					break
+				}
+			}
+			offline = !anyFolderExists
+		}
 		res.Libraries[i] = templates.LibraryData{
 			ID:          libUUID.String(),
 			Name:        lib.Name,
 			Description: getText(lib.Description),
 			TypeName:    lib.TypeName,
 			MediaCount:  countMap[libUUID.String()],
+			Offline:     offline,
 		}
 	}
 

internal/router/media.go

@@ -62,6 +62,8 @@ func registerMediaRoutes(cfg *Config) {
 	admin.PUT("/media-items/:id", cfg.MediaHandler.UpdateMediaItem)
 	admin.POST("/media-items/:id/rescan", cfg.MediaHandler.RescanMediaItem)
 	admin.DELETE("/media-items/:id", cfg.MediaHandler.DeleteMediaItem)
+	admin.POST("/media-items/purge-archived", cfg.MediaHandler.PurgeArchivedMediaItems)
+	admin.POST("/media-items/:id/unarchive", cfg.MediaHandler.UnarchiveMediaItem)
 
 	// Shelf management (protected)
 	protected.POST("/devices/:id/shelves", cfg.MediaHandler.AddToShelf)

internal/services/media_scanner.go

@@ -5,6 +5,7 @@ package services
 import (
 	"archive/tar"
 	"archive/zip"
+	"bookhoard/internal/config"
 	"bookhoard/internal/database"
 	"bookhoard/internal/utils"
 	"bytes"
@@ -22,8 +23,10 @@ import (
 	_ "image/png"
 	"io"
 	"io/fs"
+	"net/url"
 	"os"
 	"os/exec"
+	"path"
 	"path/filepath"
 	"regexp"
 	"strconv"
@@ -112,6 +115,7 @@ type MediaScanner struct {
 	defaultLibraryID     pgtype.UUID
 	libraryTypes         map[string][]string
 	forceRescan          bool
+	archiveRetentionDays int
 	logger               *ScannerLogger
 	dirtyDirs            map[string]time.Time
 	dirtyDirsMu          sync.RWMutex
@@ -159,6 +163,7 @@ func NewMediaScanner(db *database.Queries) *MediaScanner {
 	return &MediaScanner{
 		db:                   db,
 		watcher:              nil,
+		archiveRetentionDays: config.ArchiveRetentionDays(),
 		settingsCache:        NewSettingsCache(30 * time.Second),
 		dirtyDirs:            make(map[string]time.Time),
 		fileStability:        make(map[string]*atomic.Bool),
@@ -476,17 +481,23 @@ func (s *MediaScanner) ScanFolders(ctx context.Context) error {
 	fmt.Printf("Scan completed: %d total files scanned, %d media files found, %d new items, %d errors\n",
 		processedFiles, mediaFiles, s.newItems, s.errors)
 
-	// Clean up: Find media items in DB that no longer exist on filesystem
+	// Archive lifecycle pass. Items whose files vanished from disk are
+	// archived after two consecutive missing scans (reading history kept,
+	// item hidden), and purged for good once archived older than the
+	// retention window (ARCHIVE_RETENTION_DAYS; 0 = manual purge only).
+	// Every branch logs - the previous hard-delete cleanup failed silently
+	// and left orphaned rows undetected.
 	for _, folder := range s.folders {
 		lib, err := s.db.GetLibraryByFolder(ctx, folder)
 		if err != nil {
+			fmt.Printf("[ARCHIVE] Warning: no library found for folder %s, skipping archive pass: %v\n", folder, err)
 			continue
 		}
 		libraryID := lib.LibraryID
 
-		dbItems, err := s.db.ListMediaItemsByLibrary(ctx, libraryID)
+		dbItems, err := s.db.ListMediaItemsByLibraryIncludingArchived(ctx, libraryID)
 		if err != nil {
-			fmt.Printf("Warning: failed to get library items for cleanup: %v\n", err)
+			fmt.Printf("[ARCHIVE] Warning: failed to get library items for archive pass: %v\n", err)
 			continue
 		}
 
@@ -501,28 +512,46 @@ func (s *MediaScanner) ScanFolders(ctx context.Context) error {
 			}
 			return nil
 		}); err != nil {
-			fmt.Printf("[RESCAN-CLEANUP] Warning: failed to walk directory %s, skipping orphan cleanup: %v\n", folder, err)
+			fmt.Printf("[ARCHIVE] Warning: failed to walk directory %s, skipping archive pass: %v\n", folder, err)
-			continue // Skip to next folder to avoid false deletions
+			continue // Skip to next folder to avoid false archivals
 		}
 
-		// Delete items whose files no longer exist - with safety logging
 		for _, item := range dbItems {
-			filePath := item.FilePath
+			if item.FilePath == "" || scannedPaths[item.FilePath] {
-			if filePath != "" && !scannedPaths[filePath] {
+				continue // File present; unarchive is handled in processMediaFile
-				msg := fmt.Sprintf("[RESCAN-CLEANUP] Orphaned media item found: ID=%s, Title=%s, Path=%s",
+			}
-					item.ID, item.Title, filePath)
-				s.logger.LogDelete(msg)
-
-				delMsg := fmt.Sprintf("[RESCAN-CLEANUP] Deleting orphaned item '%s' (file no longer exists at %s)",
-					item.Title, filePath)
-				s.logger.LogDelete(delMsg)
 
+			if item.ArchivedAt.Valid {
+				// Still missing and already archived: purge once past the
+				// retention window (0 = keep until manual purge).
+				if s.archiveRetentionDays > 0 && time.Now().AddDate(0, 0, -s.archiveRetentionDays).After(item.ArchivedAt.Time) {
 					if err := s.db.DeleteMediaItem(ctx, item.ID); err != nil {
-					errMsg := fmt.Sprintf("[RESCAN-CLEANUP] ERROR: failed to delete orphaned item %s: %v", item.Title, err)
+						fmt.Printf("[ARCHIVE] Error: failed to purge archived item %s: %v\n", item.Title, err)
-					s.logger.LogDelete(errMsg)
+						s.logger.LogError(fmt.Sprintf("[ARCHIVE] ERROR: failed to purge archived item '%s': %v", item.Title, err))
-					s.logger.LogError(errMsg)
 					} else {
-					s.logger.LogDelete(fmt.Sprintf("[RESCAN-CLEANUP] SUCCESS: deleted orphaned item '%s'", item.Title))
+						fmt.Printf("[ARCHIVE] Purged archived item '%s' (retention %d days): %s\n", item.Title, s.archiveRetentionDays, item.FilePath)
+						s.logger.LogDelete(fmt.Sprintf("[ARCHIVE] Purged archived item '%s' after retention window (file missing at %s)", item.Title, item.FilePath))
+					}
+				}
+				continue
+			}
+
+			// Missing but not yet archived.
+			if item.MissingScanCount >= 1 {
+				// Second consecutive missing scan: archive it.
+				if err := s.db.ArchiveMediaItem(ctx, item.ID); err != nil {
+					fmt.Printf("[ARCHIVE] Error: failed to archive item %s: %v\n", item.Title, err)
+					s.logger.LogError(fmt.Sprintf("[ARCHIVE] ERROR: failed to archive item '%s': %v", item.Title, err))
+				} else {
+					fmt.Printf("[ARCHIVE] Archived item '%s' (missing from disk for %d scans): %s\n", item.Title, item.MissingScanCount+1, item.FilePath)
+					s.logger.LogDelete(fmt.Sprintf("[ARCHIVE] Archived item '%s' (file missing from disk at %s)", item.Title, item.FilePath))
+				}
+			} else {
+				// First missing scan: mark, archive on the next one.
+				if err := s.db.MarkMediaItemMissing(ctx, item.ID); err != nil {
+					fmt.Printf("[ARCHIVE] Warning: failed to mark item missing %s: %v\n", item.Title, err)
+				} else {
+					fmt.Printf("[ARCHIVE] Item missing from disk (1/2 scans before archiving): %s\n", item.FilePath)
 				}
 			}
 		}
@@ -693,6 +722,17 @@ func (s *MediaScanner) processMediaFile(ctx context.Context, path string) (bool,
 	if err == nil {
 		fmt.Printf("Media item already exists in database: %s (size: %d vs %d)\n", path, existingItem.FileSize.Int64, info.Size())
 
+		// The file is back on disk: lift any archive/missing state so the
+		// item reappears in libraries and future missing scans start fresh.
+		if existingItem.ArchivedAt.Valid || existingItem.MissingScanCount > 0 {
+			if err := s.db.ClearMediaItemArchive(ctx, existingItem.ID); err != nil {
+				fmt.Printf("Warning: failed to unarchive media item %s: %v\n", existingItem.FilePath, err)
+			} else if existingItem.ArchivedAt.Valid {
+				fmt.Printf("[ARCHIVE] Restored from archive, file is back: %s\n", existingItem.FilePath)
+				s.logger.LogDelete(fmt.Sprintf("[ARCHIVE] Restored archived item '%s' (file returned at %s)", existingItem.Title, existingItem.FilePath))
+			}
+		}
+
 		// If force rescan is enabled, always re-process
 		if s.forceRescan {
 			fmt.Printf("Force rescan enabled, updating existing media item: %s\n", path)
@@ -755,8 +795,50 @@ func (s *MediaScanner) processMediaFile(ctx context.Context, path string) (bool,
 			LibraryID:  libraryID,
 		})
 		if err == nil && existingByHash.ID.Valid {
+			// Same content at a different path. If the old location is gone,
+			// the book was MOVED: repoint the row so history follows it and
+			// the archive pass doesn't cycle it into missing/archived. Only
+			// treat it as a duplicate copy when the old path still exists.
+			oldPathStillExists := false
+			for _, folder := range s.folders {
+				if _, statErr := os.Stat(filepath.Join(folder, existingByHash.FilePath)); statErr == nil {
+					oldPathStillExists = true
+					break
+				}
+			}
+
+			if !oldPathStillExists {
+				if err := s.db.MoveMediaItemFilePath(ctx, database.MoveMediaItemFilePathParams{
+					ID:       existingByHash.ID,
+					FilePath: s.getRelativePath(path),
+					FileSize: pgtype.Int8{Int64: info.Size(), Valid: true},
+				}); err != nil {
+					fmt.Printf("Warning: failed to repoint moved media item %s -> %s: %v\n", existingByHash.FilePath, path, err)
+				} else {
+					fmt.Printf("[MOVE] Item content moved: %q -> %s (history preserved)\n", existingByHash.FilePath, path)
+					s.logger.LogDelete(fmt.Sprintf("[MOVE] Repointed item '%s' from %q to %s", existingByHash.Title, existingByHash.FilePath, path))
+				}
+				if s.forceRescan {
+					moved := existingByHash
+					moved.FilePath = s.getRelativePath(path)
+					moved.ArchivedAt = pgtype.Timestamptz{}
+					moved.MissingScanCount = 0
+					_ = s.updateMediaItem(ctx, moved, path)
+				}
+				return false, nil
+			}
+
 			fmt.Printf("Media item with same SHA-256 already exists in library (path %q), skipping duplicate: %s\n",
 				existingByHash.FilePath, path)
+			// Content returned (possibly at a new path): restore archived rows.
+			if existingByHash.ArchivedAt.Valid || existingByHash.MissingScanCount > 0 {
+				if err := s.db.ClearMediaItemArchive(ctx, existingByHash.ID); err != nil {
+					fmt.Printf("Warning: failed to unarchive media item %s: %v\n", existingByHash.FilePath, err)
+				} else if existingByHash.ArchivedAt.Valid {
+					fmt.Printf("[ARCHIVE] Restored from archive, identical content found at %s\n", path)
+					s.logger.LogDelete(fmt.Sprintf("[ARCHIVE] Restored archived item '%s' (identical content found at %s)", existingByHash.Title, path))
+				}
+			}
 			if s.forceRescan {
 				_ = s.updateMediaItem(ctx, existingByHash, path)
 			}
@@ -958,6 +1040,115 @@ func (s *MediaScanner) extractCalibreSidecar(path string) *MediaMetadata {
 	return metadata
 }
 
+// applyEmbeddedCoverFallback extracts a cover from the media file itself when
+// a metadata sidecar (metadata.opf / metadata.json) supplied the metadata but
+// no sidecar cover (cover.jpg etc.) exists. Without this, a full rescan would
+// clear cover_image_path for sidecar-managed PDFs and EPUBs - mergeMetadata
+// has no PDF/EPUB cover logic of its own.
+func (s *MediaScanner) applyEmbeddedCoverFallback(path string, metadata *MediaMetadata) {
+	if metadata.CoverPath != "" {
+		return
+	}
+	switch strings.ToLower(filepath.Ext(path)) {
+	case ".pdf":
+		if coverPath, err := s.extractPDFCover(path); err == nil && coverPath != "" {
+			metadata.CoverPath = s.getRelativePath(coverPath)
+		}
+	case ".epub", ".kepub":
+		if coverPath, err := s.extractEPUBCover(path); err == nil && coverPath != "" {
+			metadata.CoverPath = s.getRelativePath(coverPath)
+		}
+	}
+}
+
+// extractAudiobookshelfSidecar checks for and parses an Audiobookshelf-style
+// metadata.json sidecar next to the media file. Only fields with a matching
+// media_items column are mapped; narrators, subtitle, explicit, abridged and
+// chapters are deliberately skipped. Returns nil when no sidecar exists.
+func extractAudiobookshelfSidecar(path string) *MediaMetadata {
+	jsonPath := filepath.Join(filepath.Dir(path), "metadata.json")
+	if _, err := os.Stat(jsonPath); os.IsNotExist(err) {
+		return nil
+	}
+
+	data, err := os.ReadFile(jsonPath)
+	if err != nil {
+		fmt.Printf("Warning: failed to read metadata.json sidecar for %s: %v\n", path, err)
+		return nil
+	}
+
+	var sidecar struct {
+		Title    string   `json:"title"`
+		Subtitle string   `json:"subtitle"`
+		Authors  []string `json:"authors"`
+		Series   []struct {
+			Series   string `json:"series"`
+			Sequence string `json:"sequence"`
+		} `json:"series"`
+		Genres        []string `json:"genres"`
+		Tags          []string `json:"tags"`
+		PublishedYear *int     `json:"publishedYear"`
+		PublishedDate *string  `json:"publishedDate"`
+		Publisher     *string  `json:"publisher"`
+		Description   *string  `json:"description"`
+		ISBN          *string  `json:"isbn"`
+		ASIN          *string  `json:"asin"`
+		Language      *string  `json:"language"`
+	}
+	if err := json.Unmarshal(data, &sidecar); err != nil {
+		fmt.Printf("Warning: failed to parse metadata.json sidecar for %s: %v\n", path, err)
+		return nil
+	}
+
+	metadata := &MediaMetadata{
+		Title: strings.TrimSpace(sidecar.Title),
+	}
+	// Subtitle joins the title Calibre-style ("Main: Subtitle") - there is no
+	// separate subtitle column, and Calibre-sidecar books arrive pre-joined.
+	if subtitle := strings.TrimSpace(sidecar.Subtitle); subtitle != "" && metadata.Title != "" {
+		metadata.Title = metadata.Title + ": " + subtitle
+	}
+	if len(sidecar.Authors) > 0 {
+		metadata.Author = strings.TrimSpace(sidecar.Authors[0])
+	}
+	if len(sidecar.Series) > 0 {
+		metadata.Series = strings.TrimSpace(sidecar.Series[0].Series)
+		if index, err := strconv.ParseFloat(strings.TrimSpace(sidecar.Series[0].Sequence), 32); err == nil {
+			metadata.SeriesNumber = int32(index)
+		}
+	}
+	if tags := append(append([]string{}, sidecar.Genres...), sidecar.Tags...); len(tags) > 0 {
+		metadata.Tags = utils.NormalizeTags(tags)
+	}
+	if sidecar.PublishedDate != nil {
+		if date, err := time.Parse("2006-01-02", strings.TrimSpace(*sidecar.PublishedDate)); err == nil {
+			metadata.PublishDate = date
+		}
+	}
+	if metadata.PublishDate.IsZero() && sidecar.PublishedYear != nil && *sidecar.PublishedYear > 0 {
+		metadata.PublishDate = time.Date(*sidecar.PublishedYear, 1, 1, 0, 0, 0, 0, time.UTC)
+	}
+	if sidecar.Publisher != nil {
+		metadata.Publisher = strings.TrimSpace(*sidecar.Publisher)
+	}
+	if sidecar.Description != nil {
+		metadata.Description = strings.TrimSpace(*sidecar.Description)
+	}
+	if sidecar.ISBN != nil {
+		metadata.ISBN = utils.NormalizeISBNSafe(strings.TrimSpace(*sidecar.ISBN))
+	}
+	if sidecar.ASIN != nil {
+		metadata.ASIN = strings.TrimSpace(*sidecar.ASIN)
+	}
+	if sidecar.Language != nil {
+		metadata.Language = strings.TrimSpace(*sidecar.Language)
+	}
+
+	return metadata
+}
+
+// extractAudiobookshelfSidecar-TMP-END
+
 // mergeMetadata intelligently merges metadata from multiple sources
 // Priority: metadata.opf (Calibre) → embedded metadata → folder structure → filename
 // For comics: metadata.opf → ComicInfo.xml → folder structure → filename
@@ -970,7 +1161,7 @@ func (s *MediaScanner) mergeMetadata(path string, calibreMetadata *MediaMetadata
 	ext := strings.ToLower(filepath.Ext(path))
 
 	// For EPUB files
-	if ext == ".epub" {
+	if ext == ".epub" || ext == ".kepub" {
 		book, err := epub.ReadBook(path)
 		if err == nil {
 			genreTags := extractGenreTagsFromEPUB(book)
@@ -986,6 +1177,76 @@ func (s *MediaScanner) mergeMetadata(path string, calibreMetadata *MediaMetadata
 				metadata.PageCount = int32(pageCount)
 			}
 		}
+
+		// Gap-fill: sidecar-sourced metadata wins, but blanks are filled from
+		// the book's own OPF so a sparse metadata.opf/metadata.json doesn't
+		// hide data the file carries. Never overwrites sidecar values.
+		if embedded, err := s.extractEPUBMetadata(path); err == nil && embedded != nil {
+			if metadata.Title == "" && embedded.Title != "" {
+				metadata.Title = embedded.Title
+			}
+			if metadata.Author == "" && embedded.Author != "" {
+				metadata.Author = embedded.Author
+			}
+			if metadata.Description == "" && embedded.Description != "" {
+				metadata.Description = embedded.Description
+			}
+			if metadata.Publisher == "" && embedded.Publisher != "" {
+				metadata.Publisher = embedded.Publisher
+			}
+			if metadata.Language == "" && embedded.Language != "" {
+				metadata.Language = embedded.Language
+			}
+			if metadata.ISBN == "" && embedded.ISBN != "" {
+				metadata.ISBN = embedded.ISBN
+			}
+			if metadata.ASIN == "" && embedded.ASIN != "" {
+				metadata.ASIN = embedded.ASIN
+			}
+			if metadata.Series == "" && embedded.Series != "" {
+				metadata.Series = embedded.Series
+			}
+			if metadata.SeriesNumber == 0 && embedded.SeriesNumber != 0 {
+				metadata.SeriesNumber = embedded.SeriesNumber
+			}
+			if metadata.ReadingDirection == "" && embedded.ReadingDirection != "" {
+				metadata.ReadingDirection = embedded.ReadingDirection
+			}
+			if metadata.PublishDate.IsZero() && !embedded.PublishDate.IsZero() {
+				metadata.PublishDate = embedded.PublishDate
+			}
+			if len(metadata.Tags) == 0 && len(embedded.Tags) > 0 {
+				metadata.Tags = embedded.Tags
+			}
+			if len(metadata.Contributors) == 0 && len(embedded.Contributors) > 0 {
+				metadata.Contributors = embedded.Contributors
+			}
+		}
+	}
+
+	// For PDFs: fill blanks from the embedded Info dictionary. Same rule as
+	// EPUBs - sidecar values win, the file only fills gaps.
+	if ext == ".pdf" {
+		if embedded, err := s.readPDFInfoDict(path); err == nil && embedded != nil {
+			if metadata.Title == "" && embedded.Title != "" {
+				metadata.Title = embedded.Title
+			}
+			if metadata.Author == "" && embedded.Author != "" {
+				metadata.Author = embedded.Author
+			}
+			if metadata.Description == "" && embedded.Description != "" {
+				metadata.Description = embedded.Description
+			}
+			if metadata.Publisher == "" && embedded.Publisher != "" {
+				metadata.Publisher = embedded.Publisher
+			}
+			if len(metadata.Tags) == 0 && len(embedded.Tags) > 0 {
+				metadata.Tags = embedded.Tags
+			}
+			if metadata.PageCount == 0 && embedded.PageCount > 0 {
+				metadata.PageCount = embedded.PageCount
+			}
+		}
 	}
 
 	// For comic archives, try to extract ComicInfo.xml
@@ -1265,6 +1526,8 @@ func extractGenreTagsFromComicInfo(comicInfo *ComicInfo) []string {
 }
 
 func (s *MediaScanner) extractMetadata(path string) (*MediaMetadata, error) {
+	// Metadata sidecar priority: Calibre metadata.opf, then Audiobookshelf
+	// metadata.json, then the media file's own embedded metadata.
 	// Try Calibre sidecar first
 	calibreMetadata := s.extractCalibreSidecar(path)
 	if calibreMetadata != nil {
@@ -1275,11 +1538,27 @@ func (s *MediaScanner) extractMetadata(path string) (*MediaMetadata, error) {
 		if coverPath != "" {
 			calibreMetadata.CoverPath = s.getRelativePath(coverPath)
 		}
+		s.applyEmbeddedCoverFallback(path, calibreMetadata)
 
 		return s.mergeMetadata(path, calibreMetadata)
 	}
 
-	// EXISTING: Fallback to embedded metadata
+	// Audiobookshelf-style metadata.json sidecar (fields without a DB column
+	// - narrators, subtitle, explicit, abridged, chapters - are skipped)
+	abMetadata := extractAudiobookshelfSidecar(path)
+	if abMetadata != nil {
+		fmt.Printf("Using metadata.json sidecar for %s\n", path)
+
+		coverPath := findSidecarCover(path)
+		if coverPath != "" {
+			abMetadata.CoverPath = s.getRelativePath(coverPath)
+		}
+		s.applyEmbeddedCoverFallback(path, abMetadata)
+
+		return s.mergeMetadata(path, abMetadata)
+	}
+
+	// Fallback to embedded metadata
 	ext := strings.ToLower(filepath.Ext(path))
 
 	switch ext {
@@ -1347,89 +1626,38 @@ func (s *MediaScanner) extractMetadata(path string) (*MediaMetadata, error) {
 	}
 }
 
+// extractEPUBMetadata extracts metadata from an EPUB by parsing its embedded
+// OPF document directly (container.xml → OPF → Dublin Core elements).
+//
+// It deliberately does NOT use a full-book parser: the previous go-epub
+// implementation parsed every spine chapter and failed the whole call when any
+// single chapter (or the TOC) was malformed, discarding perfectly good OPF
+// metadata and leaving rescans writing blanks. The OPF holds all the metadata
+// we need; chapter damage can no longer affect it.
 func (s *MediaScanner) extractEPUBMetadata(path string) (*MediaMetadata, error) {
-	book, err := epub.ReadBook(path)
+	r, err := zip.OpenReader(path)
 	if err != nil {
 		return nil, fmt.Errorf("failed to open EPUB: %v", err)
 	}
+	defer func() {
+		if err := r.Close(); err != nil {
+			fmt.Printf("Warning: failed to close EPUB zip reader for %s: %v\n", path, err)
+		}
+	}()
 
-	metadata := &MediaMetadata{}
+	opfPath := findOPFPathInZip(r.File)
-
+	if opfPath == "" {
-	// Title
+		return nil, fmt.Errorf("no OPF document found in EPUB %s", path)
-	if title, err := book.Title(); err == nil && title != "" {
+	}
-		metadata.Title = title
+	opfContent, err := readFileFromZip(r.File, opfPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read OPF %s from EPUB: %v", opfPath, err)
 	}
 
-	// Author
+	metadata, err := parseOPFContent(opfContent)
-	if authors, err := book.MetadataByKey("creator"); err == nil && len(authors) > 0 {
+	if err != nil {
-		metadata.Author = authors[0]
+		return nil, fmt.Errorf("failed to parse OPF in EPUB %s: %v", path, err)
 	}
-
-	// Description
-	if descriptions, err := book.MetadataByKey("description"); err == nil && len(descriptions) > 0 {
-		metadata.Description = descriptions[0]
-	}
-
-	// Publisher
-	if publishers, err := book.MetadataByKey("publisher"); err == nil && len(publishers) > 0 {
-		metadata.Publisher = publishers[0]
-	}
-
-	// Series and series number (Calibre specific metadata)
-	if series, err := book.MetadataByKey("calibre:series"); err == nil && len(series) > 0 {
-		metadata.Series = series[0]
-	}
-	if seriesIndex, err := book.MetadataByKey("calibre:series_index"); err == nil && len(seriesIndex) > 0 {
-		if index, err := strconv.ParseFloat(seriesIndex[0], 32); err == nil {
-			metadata.SeriesNumber = int32(index)
-		}
-	}
-
-	// Publish date
-	if dates, err := book.MetadataByKey("date"); err == nil && len(dates) > 0 {
-		if date, err := time.Parse("2006-01-02", dates[0]); err == nil {
-			metadata.PublishDate = date
-		} else {
-			// Try alternative date formats
-			if date, err := time.Parse("2006", dates[0]); err == nil {
-				metadata.PublishDate = date
-			}
-		}
-	}
-
-	// Contributors
-	if contributors, err := book.MetadataByKey("contributor"); err == nil && len(contributors) > 0 {
-		// Normalize contributors for display
-		metadata.Contributors = utils.NormalizeContributors(contributors)
-	}
-
-	// ISBN
-	if isbns, err := book.MetadataByKey("identifier"); err == nil && len(isbns) > 0 {
-		for _, isbn := range isbns {
-			if strings.Contains(strings.ToLower(isbn), "isbn") {
-				// Extract ISBN number from identifier like "isbn:978-3-16-148410-0"
-				isbnParts := strings.SplitN(isbn, ":", 2)
-				if len(isbnParts) == 2 {
-					metadata.ISBN = isbnParts[1]
-					break
-				}
-			}
-			if strings.Contains(strings.ToLower(isbn), "asin") {
-				// Extract ASIN from identifier like "asin:B08XXXXX"
-				asinParts := strings.SplitN(isbn, ":", 2)
-				if len(asinParts) == 2 {
-					metadata.ASIN = asinParts[1]
-				}
-			}
-		}
-	}
-
-	// Tags
-	if tags, err := book.MetadataByKey("subject"); err == nil && len(tags) > 0 {
-		// Normalize tags for display
-		metadata.Tags = utils.NormalizeTags(tags)
-	}
-
 	return metadata, nil
 }
 
@@ -1604,7 +1832,7 @@ func (s *MediaScanner) LogProcessingIssue(
 	return err
 }
 
-// parseCalibreMetadataOPF parses a Calibre metadata.opf file and extracts metadata
+// parseCalibreMetadataOPF parses a Calibre metadata.opf sidecar file.
 func (s *MediaScanner) parseCalibreMetadataOPF(opfPath string) (*MediaMetadata, error) {
 	// Open file
 	file, err := os.Open(opfPath)
@@ -1616,94 +1844,122 @@ func (s *MediaScanner) parseCalibreMetadataOPF(opfPath string) (*MediaMetadata,
 			fmt.Printf("Warning: failed to close metadata.opf: %v\n", err)
 		}
 	}()
-	// Define XML structure for parsing with full Dublin Core namespace URLs
+	content, err := io.ReadAll(file)
-	var opf struct {
+	if err != nil {
-		XMLName  xml.Name `xml:"package"`
+		return nil, fmt.Errorf("failed to read metadata.opf: %v", err)
-		Metadata struct {
-			XMLName     xml.Name `xml:"metadata"`
-			Titles      []string `xml:"http://purl.org/dc/elements/1.1/ title"`
-			Creators    []string `xml:"http://purl.org/dc/elements/1.1/ creator"`
-			Subjects    []string `xml:"http://purl.org/dc/elements/1.1/ subject"`
-			Desc        []string `xml:"http://purl.org/dc/elements/1.1/ description"`
-			Publisher   []string `xml:"http://purl.org/dc/elements/1.1/ publisher"`
-			Dates       []string `xml:"http://purl.org/dc/elements/1.1/ date"`
-			Language    []string `xml:"http://purl.org/dc/elements/1.1/ language"`
-			Identifiers []struct {
-				Scheme string `xml:"http://www.idpf.org/2007/opf scheme,attr"`
-				Value  string `xml:",chardata"`
-			} `xml:"http://purl.org/dc/elements/1.1/ identifier"`
-			Contributors []string `xml:"http://purl.org/dc/elements/1.1/ contributor"`
-			// Calibre-specific meta tags - capture all, filter later
-			MetaTags []struct {
-				Name  string `xml:"name,attr"`
-				Value string `xml:"content,attr"`
-			} `xml:"meta"`
-		} `xml:"metadata"`
 	}
-	// Parse XML
+	return parseOPFContent(content)
-	if err := xml.NewDecoder(file).Decode(&opf); err != nil {
-		return nil, fmt.Errorf("failed to parse metadata.opf XML: %v", err)
 }
+
+// parseOPFContent parses an OPF document (Dublin Core metadata) into
+// MediaMetadata. Used for both Calibre metadata.opf sidecars and the OPF
+// embedded inside an EPUB - the dc:* vocabulary is identical. Parsing is
+// attribute-order agnostic and namespace aware (see media_scanner_opf.go);
+// title selection and series detection follow Calibre's behavior.
+func parseOPFContent(content []byte) (*MediaMetadata, error) {
+	opf, err := parseOPFXML(content)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse OPF XML: %v", err)
+	}
+	md := opf.Metadata
+
 	// Map to MediaMetadata struct
 	metadata := &MediaMetadata{}
-	// Title (required)
+	// Title: EPUB3 title-type main selection with Calibre-style subtitle join
-	if len(opf.Metadata.Titles) > 0 {
+	if title := opf.selectTitle(); title != "" {
-		metadata.Title = opf.Metadata.Titles[0]
+		metadata.Title = title
+	}
+	// Reading direction from the OPF spine's page-progression-direction.
+	// Sidecar OPFs are metadata-only documents without a spine, so this is a
+	// no-op for them and only fires on real books.
+	if dir := opf.pageProgressionDirection(); dir != "" {
+		metadata.ReadingDirection = dir
 	}
 	// Author (first creator)
-	if len(opf.Metadata.Creators) > 0 {
+	if len(md.Creators) > 0 {
-		metadata.Author = opf.Metadata.Creators[0]
+		metadata.Author = md.Creators[0]
+	}
+	// Tags (all subjects; one element = one tag, commas are legal inside
+	// subject headings like "Holmes, Sherlock (Fictitious character)").
+	// Genre mirrors the sidecar path's processGenresAndTags: first subject.
+	if len(md.Subjects) > 0 {
+		metadata.Tags = utils.NormalizeTags(md.Subjects)
+		if len(metadata.Tags) > 0 {
+			metadata.Genre = metadata.Tags[0]
 		}
-	// Tags (all subjects)
-	if len(opf.Metadata.Subjects) > 0 {
-		metadata.Tags = utils.NormalizeTags(opf.Metadata.Subjects)
 	}
 	// Description
-	if len(opf.Metadata.Desc) > 0 {
+	if len(md.Descriptions) > 0 {
-		metadata.Description = opf.Metadata.Desc[0]
+		metadata.Description = md.Descriptions[0]
 	}
 	// Publisher
-	if len(opf.Metadata.Publisher) > 0 {
+	if len(md.Publishers) > 0 {
-		metadata.Publisher = opf.Metadata.Publisher[0]
+		metadata.Publisher = md.Publishers[0]
+	}
+	// Language
+	if len(md.Languages) > 0 && md.Languages[0] != "" {
+		metadata.Language = md.Languages[0]
 	}
 	// Publish date
-	if len(opf.Metadata.Dates) > 0 {
+	if len(md.Dates) > 0 {
-		if date, err := time.Parse("2006-01-02T15:04:05Z07:00", opf.Metadata.Dates[0]); err == nil {
+		if date, err := time.Parse("2006-01-02T15:04:05Z07:00", md.Dates[0]); err == nil {
 			metadata.PublishDate = date
-		} else if date, err := time.Parse("2006-01-02", opf.Metadata.Dates[0]); err == nil {
+		} else if date, err := time.Parse("2006-01-02", md.Dates[0]); err == nil {
 			metadata.PublishDate = date
 		} else {
 			// Try alternative date formats
-			if date, err := time.Parse("2006", opf.Metadata.Dates[0]); err == nil {
+			if date, err := time.Parse("2006", md.Dates[0]); err == nil {
 				metadata.PublishDate = date
 			}
 		}
 	}
-	// Identifiers (ISBN, ASIN)
+	// Identifiers: opf:scheme attribute first, then URN-prefixed values
-	for _, id := range opf.Metadata.Identifiers {
+	// (urn:isbn:...), then bare values that normalize to a valid ISBN.
-		switch strings.ToUpper(id.Scheme) {
+	for _, id := range md.Identifiers {
+		value := strings.TrimSpace(id.Value)
+		scheme := strings.ToUpper(strings.TrimSpace(id.Scheme))
+		if scheme == "" {
+			if lower := strings.ToLower(value); strings.HasPrefix(lower, "urn:") {
+				rest := value[4:]
+				if prefix, val, ok := strings.Cut(rest, ":"); ok {
+					scheme = strings.ToUpper(prefix)
+					value = strings.TrimSpace(val)
+				}
+			}
+		}
+		switch scheme {
 		case "ISBN":
-			metadata.ISBN = utils.NormalizeISBNSafe(id.Value)
+			metadata.ISBN = utils.NormalizeISBNSafe(value)
 		case "ASIN":
-			metadata.ASIN = id.Value
+			metadata.ASIN = value
 		case "UUID", "CALIBRE":
 			// Store UUID in hash info, not metadata
 			// Will be extracted by extractHashInfo()
+		default:
+			// EPUB3 identifiers often carry no opf:scheme attribute; accept a
+			// bare value only when it is ISBN-shaped (rejects the URIs and
+			// UUIDs that commonly share the identifier list).
+			if metadata.ISBN == "" && scheme == "" && isISBNLike(value) {
+				if normalized, err := utils.NormalizeISBN(value); err == nil {
+					metadata.ISBN = normalized
+				}
+			}
 		}
 	}
 	// Contributors
-	if len(opf.Metadata.Contributors) > 0 {
+	if len(md.Contributors) > 0 {
-		metadata.Contributors = utils.NormalizeContributors(opf.Metadata.Contributors)
+		metadata.Contributors = utils.NormalizeContributors(md.Contributors)
 	}
-	// Calibre-specific meta tags (filter by name attribute)
+	// Series: EPUB3 belongs-to-collection, then calibre:series metas
-	for _, meta := range opf.Metadata.MetaTags {
+	if series, index := opf.readSeries(); series != "" {
-		switch meta.Name {
+		metadata.Series = series
-		case "calibre:series":
+		if index > 0 {
-			metadata.Series = meta.Value
-		case "calibre:series_index":
-			if index, err := strconv.ParseFloat(meta.Value, 32); err == nil {
 			metadata.SeriesNumber = int32(index)
 		}
+	}
+	// Calibre-specific meta tags (filter by name attribute)
+	for _, meta := range md.Metas {
+		switch meta.Name {
 		case "calibre:rating":
 			// Not imported (ratings are per-user in Bookhoard)
 		case "calibre:title_sort":
@@ -1715,6 +1971,45 @@ func (s *MediaScanner) parseCalibreMetadataOPF(opfPath string) (*MediaMetadata,
 	return metadata, nil
 }
 
+// findOPFPathInZip locates the OPF document inside an EPUB by reading
+// META-INF/container.xml (string-scraped; we only need the rootfile
+// full-path attribute). Returns "" when absent.
+func findOPFPathInZip(files []*zip.File) string {
+	for _, f := range files {
+		if f.Name != "META-INF/container.xml" {
+			continue
+		}
+		rc, err := f.Open()
+		if err != nil {
+			return ""
+		}
+		content, readErr := io.ReadAll(rc)
+		if closeErr := rc.Close(); closeErr != nil {
+			fmt.Printf("Warning: failed to close META-INF/container.xml reader: %v\n", closeErr)
+		}
+		if readErr != nil {
+			return ""
+		}
+		opfStart := bytes.Index(content, []byte("<rootfile "))
+		if opfStart == -1 {
+			return ""
+		}
+		opfStartAttr := bytes.Index(content[opfStart:], []byte("full-path="))
+		if opfStartAttr == -1 {
+			return ""
+		}
+		opfStartAttr += len("full-path=")
+		quote := content[opfStart+opfStartAttr]
+		opfStartQuote := opfStart + opfStartAttr + 1
+		opfEndQuote := bytes.Index(content[opfStartQuote:], []byte{quote})
+		if opfEndQuote == -1 {
+			return ""
+		}
+		return string(content[opfStartQuote : opfStartQuote+opfEndQuote])
+	}
+	return ""
+}
+
 // extractEPUBCover extracts the cover image from an EPUB file.
 // It looks for:
 // 1. An item with properties="cover-image" in the manifest
@@ -1736,43 +2031,7 @@ func (s *MediaScanner) extractEPUBCover(epubPath string) (string, error) {
 	// Try to find cover image from OPF metadata
 	coverImageName := ""
 
-	// Attempt to read the OPF file to find cover reference
+	opfPath := findOPFPathInZip(r.File)
-	// First, find container.xml to locate the OPF
-	var opfPath string
-	for _, f := range r.File {
-		if f.Name == "META-INF/container.xml" {
-			rc, err := f.Open()
-			if err != nil {
-				continue
-			}
-			content, readErr := io.ReadAll(rc)
-			if closeErr := rc.Close(); closeErr != nil {
-				fmt.Printf("Warning: failed to close META-INF/container.xml reader in %s: %v\n", epubPath, closeErr)
-			}
-			if readErr != nil {
-				continue
-			}
-			// Parse container.xml to find OPF path
-			// Simple string search since we just need the path
-			opfStart := bytes.Index(content, []byte("<rootfile "))
-			if opfStart == -1 {
-				continue
-			}
-			opfStartAttr := bytes.Index(content[opfStart:], []byte("full-path="))
-			if opfStartAttr == -1 {
-				continue
-			}
-			opfStartAttr += len("full-path=")
-			quote := content[opfStart+opfStartAttr]
-			opfStartQuote := opfStart + opfStartAttr + 1
-			opfEndQuote := bytes.Index(content[opfStartQuote:], []byte{quote})
-			if opfEndQuote == -1 {
-				continue
-			}
-			opfPath = string(content[opfStartQuote : opfStartQuote+opfEndQuote])
-			break
-		}
-	}
 
 	if opfPath == "" {
 		// No OPF found, try common cover image paths
@@ -1827,7 +2086,47 @@ func findCoverImageInZip(files []*zip.File) string {
 }
 
 // findCoverInOPF parses OPF content to find cover image reference
-func findCoverInOPF(opfContent []byte, files []*zip.File, opfDir string) string {
+// findCoverInOPF locates the cover image for an EPUB, following Calibre's
+// read_raster_cover resolution order (see media_scanner_opf.go):
+//  1. manifest item with properties="cover-image"
+//  2. <meta name="cover"> resolved through the manifest
+//  3. the first spine item being a raster image itself (store manga)
+//  4. NEW: the cover page (guide type="cover" or first spine item) mined for
+//     <img src> / SVG <image xlink:href> - covers books that declare no
+//     raster cover at all, e.g. classic EPUB2/Adobe cover.xhtml wrappers
+//  5. filename guessing in the zip (pre-existing fallback)
+//
+// XML parsing is attribute-order agnostic; if the OPF is too malformed for
+// encoding/xml, the legacy regex chain runs as a compatibility fallback.
+func findCoverInOPF(opfContent []byte, files []*zip.File, opfPath string) string {
+	opf, err := parseOPFXML(opfContent)
+	if err != nil {
+		return findCoverInOPFLegacy(opfContent, files, opfPath)
+	}
+
+	if href := opf.findRasterCoverInOPF(); href != "" {
+		return resolveOPFPath(opfPath, href)
+	}
+
+	// Cover-page fallback: Calibre renders the page; we extract the image it
+	// references (the practical case - the page wraps a raster in img/SVG).
+	if pageHref := opf.coverPageHref(); pageHref != "" {
+		if pageContent, err := readFileFromZip(files, resolveOPFPath(opfPath, pageHref)); err == nil {
+			if imgRef := findImageReferenceInPage(pageContent); imgRef != "" {
+				imgPath := resolveOPFPath(resolveOPFPath(opfPath, pageHref), imgRef)
+				if zipHasFile(files, imgPath) {
+					return imgPath
+				}
+			}
+		}
+	}
+
+	return findCoverImageInZip(files)
+}
+
+// findCoverInOPFLegacy is the pre-XML cover lookup, kept solely as a
+// fallback for OPFs too malformed for a real XML parse.
+func findCoverInOPFLegacy(opfContent []byte, files []*zip.File, opfPath string) string {
 	contentStr := string(opfContent)
 
 	// Look for item with properties="cover-image"
@@ -1839,7 +2138,7 @@ func findCoverInOPF(opfContent []byte, files []*zip.File, opfDir string) string
 		hrefRE := regexp.MustCompile(fmt.Sprintf(`<item[^>]*id="%s"[^>]*href="([^"]+)"`, coverID))
 		hrefMatches := hrefRE.FindStringSubmatch(contentStr)
 		if len(hrefMatches) > 1 {
-			return resolveOPFPath(opfDir, hrefMatches[1])
+			return resolveOPFPath(opfPath, hrefMatches[1])
 		}
 	}
 
@@ -1853,7 +2152,7 @@ func findCoverInOPF(opfContent []byte, files []*zip.File, opfDir string) string
 			hrefRE := regexp.MustCompile(fmt.Sprintf(`<item[^>]*id="%s"[^>]*href="([^"]+)"`, coverID))
 			hrefMatches := hrefRE.FindStringSubmatch(contentStr)
 			if len(hrefMatches) > 1 {
-				return resolveOPFPath(opfDir, hrefMatches[1])
+				return resolveOPFPath(opfPath, hrefMatches[1])
 			}
 		}
 	}
@@ -1862,18 +2161,34 @@ func findCoverInOPF(opfContent []byte, files []*zip.File, opfDir string) string
 	return findCoverImageInZip(files)
 }
 
-// resolveOPFPath resolves a relative path against the OPF directory
+// zipHasFile reports whether the zip contains an entry with exactly this name.
-func resolveOPFPath(opfDir, href string) string {
+func zipHasFile(files []*zip.File, name string) bool {
-	if opfDir == "" {
+	name = filepath.ToSlash(name)
-		return href
+	for _, f := range files {
+		if filepath.ToSlash(f.Name) == name {
+			return true
 		}
-	// Handle ../ in href
-	if strings.HasPrefix(href, "../") {
-		// Simple case: just use the href as-is for now
-		return href
 	}
-	// Join the directory with the href
+	return false
-	return filepath.Join(filepath.Dir(opfDir), href)
+}
+
+// resolveOPFPath resolves an OPF-relative href against the OPF document's own
+// path inside the zip. Hrefs are URL-decoded and normalized with posix path
+// semantics ("../" walks up), matching Calibre's
+// posixpath.normpath(posixpath.join(base, href)).
+func resolveOPFPath(opfPath, href string) string {
+	if unescaped, err := url.PathUnescape(href); err == nil {
+		href = unescaped
+	}
+	href = strings.TrimPrefix(filepath.ToSlash(href), "/")
+	base := ""
+	if dir := path.Dir(filepath.ToSlash(opfPath)); dir != "." {
+		base = dir
+	}
+	if base == "" {
+		return path.Clean(href)
+	}
+	return path.Clean(path.Join(base, href))
 }
 
 // readFileFromZip reads a file from the zip by name
@@ -1987,6 +2302,51 @@ func findSidecarCover(mediaPath string) string {
 	return ""
 }
 
+// readPDFInfoDict reads a PDF's embedded Info dictionary into MediaMetadata,
+// using the same field conventions as extractPDFMetadata (creator falls back
+// to author, subject maps to description, producer to publisher, keywords to
+// tags). No cover or filename logic - purely the document's own metadata, for
+// filling sidecar gaps in mergeMetadata.
+func (s *MediaScanner) readPDFInfoDict(path string) (*MediaMetadata, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer func() {
+		if err := f.Close(); err != nil {
+			fmt.Printf("Warning: failed to close PDF file %s: %v\n", path, err)
+		}
+	}()
+
+	pdfInfo, err := pdfcpuapi.PDFInfo(f, filepath.Base(path), nil, false, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	metadata := &MediaMetadata{}
+	if pdfInfo.Title != "" {
+		metadata.Title = pdfInfo.Title
+	}
+	if pdfInfo.Author != "" {
+		metadata.Author = pdfInfo.Author
+	} else if pdfInfo.Creator != "" {
+		metadata.Author = pdfInfo.Creator
+	}
+	if pdfInfo.Subject != "" {
+		metadata.Description = pdfInfo.Subject
+	}
+	if pdfInfo.Producer != "" {
+		metadata.Publisher = pdfInfo.Producer
+	}
+	if len(pdfInfo.Keywords) > 0 {
+		metadata.Tags = utils.NormalizeTags(pdfInfo.Keywords)
+	}
+	if pdfInfo.PageCount > 0 {
+		metadata.PageCount = int32(pdfInfo.PageCount)
+	}
+	return metadata, nil
+}
+
 func (s *MediaScanner) extractPDFMetadata(path string) (*MediaMetadata, error) {
 	metadata := &MediaMetadata{}
 
@@ -2664,8 +3024,10 @@ func (s *MediaScanner) updateMediaItem(ctx context.Context, existing database.Me
 	}
 
 	// Keep user-customized fields, and keep the override set itself intact.
+	// MergeOverrides guarantees a non-nil slice: a nil []string would encode
+	// as SQL NULL and violate metadata_overrides' NOT NULL constraint.
 	utils.ApplyMetadataOverrides(&params, existing)
-	params.MetadataOverrides = existing.MetadataOverrides
+	params.MetadataOverrides = utils.MergeOverrides(existing.MetadataOverrides)
 
 	_, err = s.db.UpdateMediaItem(ctx, params)
 	return err
@@ -2686,7 +3048,10 @@ func (s *MediaScanner) RescanMediaItem(ctx context.Context, mediaItemID pgtype.U
 		if err := s.db.ClearMediaItemMetadataOverrides(ctx, mediaItemID); err != nil {
 			return fmt.Errorf("failed to clear metadata overrides: %w", err)
 		}
-		item.MetadataOverrides = nil
+		// Empty - not nil: pgx encodes a nil []string parameter as SQL NULL,
+		// which would violate the column's NOT NULL constraint when
+		// updateMediaItem writes the row back.
+		item.MetadataOverrides = []string{}
 	}
 
 	folders, err := s.db.GetLibraryFolders(ctx, item.LibraryID)

internal/services/media_scanner_metadata_test.go

@@ -0,0 +1,410 @@
+package services
+
+import (
+	"archive/zip"
+	"bytes"
+	"fmt"
+	"image"
+	"image/jpeg"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// createTestJPEGBytes returns the bytes of a minimal valid JPEG.
+func createTestJPEGBytes() string {
+	var buf bytes.Buffer
+	img := image.NewRGBA(image.Rect(0, 0, 1, 1))
+	if err := jpeg.Encode(&buf, img, nil); err != nil {
+		return ""
+	}
+	return buf.String()
+}
+
+// createPragmaticStyleEPUB builds an EPUB modeled on Pragmatic Bookshelf
+// output: the dc namespace declared on the <metadata> element (not on
+// <package>), a scheme-less ISBN identifier, an OPF-declared cover, and a
+// deliberately malformed chapter body. The malformed chapter is the
+// regression trigger: the previous go-epub-based extractor failed the whole
+// book when any chapter was unparseable and wrote blank metadata.
+func createPragmaticStyleEPUB(epubPath string) error {
+	file, err := os.Create(epubPath)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+
+	zipWriter := zip.NewWriter(file)
+	defer zipWriter.Close()
+
+	mimetypeW, err := zipWriter.CreateHeader(&zip.FileHeader{
+		Name:   "mimetype",
+		Method: zip.Store,
+	})
+	if err != nil {
+		return err
+	}
+	mimetypeW.Write([]byte("application/epub+zip"))
+
+	files := map[string]string{
+		"META-INF/container.xml": `<?xml version="1.0"?><container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container"><rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles></container>`,
+		// dc namespace declared on <metadata>; identifiers carry no scheme attr
+		"OEBPS/content.opf": `<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="PubID">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:language>en</dc:language>
+    <dc:title>A Common-Sense Guide</dc:title>
+    <dc:creator>Jay Wengrow</dc:creator>
+    <dc:publisher>The Pragmatic Bookshelf, LLC</dc:publisher>
+    <dc:description>Content that makes you a better programmer.</dc:description>
+    <dc:subject>Programming</dc:subject>
+    <dc:identifier id="PubID">978-1-68050-722-8</dc:identifier>
+    <meta name="cover" content="cover-image"/>
+  </metadata>
+  <manifest>
+    <item id="cover-image" href="images/cover.jpg" media-type="image/jpeg"/>
+    <item id="ch1" href="ch1.xhtml" media-type="application/xhtml+xml"/>
+  </manifest>
+  <spine><itemref idref="ch1"/></spine>
+</package>`,
+		// Malformed on purpose: unclosed tags
+		"OEBPS/ch1.xhtml":        `<html><body><p>unclosed paragraph`,
+		"OEBPS/images/cover.jpg": createTestJPEGBytes(),
+	}
+
+	for name, content := range files {
+		w, err := zipWriter.Create(name)
+		if err != nil {
+			return err
+		}
+		if _, err := w.Write([]byte(content)); err != nil {
+			return err
+		}
+	}
+	return zipWriter.Close()
+}
+
+// TestExtractEPUBMetadataBrokenChapter guards the regression where one
+// unparseable chapter made the extractor return nothing at all: metadata must
+// come from the OPF regardless of chapter-body damage.
+func TestExtractEPUBMetadataBrokenChapter(t *testing.T) {
+	tmpDir := t.TempDir()
+	epubPath := filepath.Join(tmpDir, "book.epub")
+	if err := createPragmaticStyleEPUB(epubPath); err != nil {
+		t.Fatalf("failed to create test EPUB: %v", err)
+	}
+
+	s := NewMediaScanner(nil)
+	metadata, err := s.extractEPUBMetadata(epubPath)
+	if err != nil {
+		t.Fatalf("extractEPUBMetadata() error: %v", err)
+	}
+	if metadata.Title != "A Common-Sense Guide" {
+		t.Errorf("Title = %q, want %q", metadata.Title, "A Common-Sense Guide")
+	}
+	if metadata.Author != "Jay Wengrow" {
+		t.Errorf("Author = %q, want %q", metadata.Author, "Jay Wengrow")
+	}
+	if metadata.Publisher != "The Pragmatic Bookshelf, LLC" {
+		t.Errorf("Publisher = %q, want %q", metadata.Publisher, "The Pragmatic Bookshelf, LLC")
+	}
+	if metadata.Description == "" {
+		t.Error("Description missing")
+	}
+	if metadata.Language != "en" {
+		t.Errorf("Language = %q, want %q", metadata.Language, "en")
+	}
+	// Scheme-less identifier that normalizes to a valid ISBN must be picked up
+	if metadata.ISBN == "" {
+		t.Error("ISBN missing (scheme-less dc:identifier fallback failed)")
+	}
+}
+
+func TestParseOPFContentCalibreSeries(t *testing.T) {
+	opf := `<?xml version="1.0"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="2.0" unique-identifier="id">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf">
+    <dc:title>Test Book</dc:title>
+    <dc:creator>Some Author</dc:creator>
+    <dc:date>2020-03-15</dc:date>
+    <dc:subject>Fiction</dc:subject>
+    <dc:subject>Classic</dc:subject>
+    <dc:identifier opf:scheme="ISBN">978-3-16-148410-0</dc:identifier>
+    <meta name="calibre:series" content="Great Series"/>
+    <meta name="calibre:series_index" content="2.5"/>
+  </metadata>
+</package>`
+	metadata, err := parseOPFContent([]byte(opf))
+	if err != nil {
+		t.Fatalf("parseOPFContent() error: %v", err)
+	}
+	if metadata.Series != "Great Series" || metadata.SeriesNumber != 2 {
+		t.Errorf("Series = %q/%d, want Great Series/2", metadata.Series, metadata.SeriesNumber)
+	}
+	if metadata.ISBN == "" {
+		t.Error("schemed ISBN not extracted")
+	}
+	wantDate := time.Date(2020, 3, 15, 0, 0, 0, 0, time.UTC)
+	if !metadata.PublishDate.Equal(wantDate) {
+		t.Errorf("PublishDate = %v, want %v", metadata.PublishDate, wantDate)
+	}
+	if len(metadata.Tags) != 2 {
+		t.Errorf("Tags = %v, want 2 subjects", metadata.Tags)
+	}
+}
+
+func TestExtractAudiobookshelfSidecar(t *testing.T) {
+	tests := []struct {
+		name     string
+		json     string
+		validate func(t *testing.T, m *MediaMetadata)
+	}{
+		{
+			name: "full sidecar",
+			json: `{
+				"title": "An Book",
+				"authors": ["Author One", "Author Two"],
+				"series": [{"series": "The Series", "sequence": "4.5"}],
+				"genres": ["Fantasy"],
+				"tags": ["tag1"],
+				"publishedYear": 2019,
+				"publisher": "ACME Books",
+				"description": "A very good book.",
+				"isbn": "978-3-16-148410-0",
+				"asin": "B08XYZ",
+				"language": "en"
+			}`,
+			validate: func(t *testing.T, m *MediaMetadata) {
+				if m.Title != "An Book" || m.Author != "Author One" {
+					t.Errorf("Title/Author = %q/%q", m.Title, m.Author)
+				}
+				if m.Series != "The Series" || m.SeriesNumber != 4 {
+					t.Errorf("Series = %q/%d, want The Series/4", m.Series, m.SeriesNumber)
+				}
+				if len(m.Tags) != 2 {
+					t.Errorf("Tags = %v, want genres+tags merged", m.Tags)
+				}
+				if m.PublishDate.Year() != 2019 {
+					t.Errorf("PublishDate year = %d, want 2019", m.PublishDate.Year())
+				}
+				if m.Publisher != "ACME Books" || m.Description != "A very good book." {
+					t.Errorf("Publisher/Description = %q/%q", m.Publisher, m.Description)
+				}
+				if m.ISBN == "" || m.ASIN != "B08XYZ" || m.Language != "en" {
+					t.Errorf("ISBN/ASIN/Language = %q/%q/%q", m.ISBN, m.ASIN, m.Language)
+				}
+			},
+		},
+		{
+			name: "sparse sidecar (real-world Audiobookshelf export)",
+			json: `{"title": "Sparse (1234)", "authors": ["X"], "tags": [], "description": null}`,
+			validate: func(t *testing.T, m *MediaMetadata) {
+				if m.Title != "Sparse (1234)" || m.Author != "X" {
+					t.Errorf("Title/Author = %q/%q", m.Title, m.Author)
+				}
+				if m.Description != "" || m.Tags != nil {
+					t.Error("null/empty sidecar fields must stay unset")
+				}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			dir := t.TempDir()
+			if err := os.WriteFile(filepath.Join(dir, "metadata.json"), []byte(tt.json), 0644); err != nil {
+				t.Fatal(err)
+			}
+			m := extractAudiobookshelfSidecar(filepath.Join(dir, "book.epub"))
+			if m == nil {
+				t.Fatal("extractAudiobookshelfSidecar() = nil, want metadata")
+			}
+			tt.validate(t, m)
+		})
+	}
+
+	t.Run("no sidecar returns nil", func(t *testing.T) {
+		dir := t.TempDir()
+		if m := extractAudiobookshelfSidecar(filepath.Join(dir, "book.epub")); m != nil {
+			t.Errorf("extractAudiobookshelfSidecar() = %v, want nil", m)
+		}
+	})
+}
+
+// createTestPDFWithImage builds a minimal one-page PDF embedding a JPEG
+// XObject, so pdfcpu-based cover extraction has an image to find.
+func createTestPDFWithImage() []byte {
+	jpegData := []byte(createTestJPEGBytes())
+	content := "q 100 0 0 100 0 0 cm /Im0 Do Q"
+
+	var buf bytes.Buffer
+	offsets := []int{0} // object numbers are 1-based
+	buf.WriteString("%PDF-1.4\n")
+
+	writeObj := func(n int, body func(w *bytes.Buffer)) {
+		offsets = append(offsets, buf.Len())
+		fmt.Fprintf(&buf, "%d 0 obj\n", n)
+		body(&buf)
+		buf.WriteString("endobj\n")
+	}
+
+	writeObj(1, func(w *bytes.Buffer) { w.WriteString("<< /Type /Catalog /Pages 2 0 R >>\n") })
+	writeObj(2, func(w *bytes.Buffer) { w.WriteString("<< /Type /Pages /Kids [3 0 R] /Count 1 >>\n") })
+	writeObj(3, func(w *bytes.Buffer) {
+		w.WriteString("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 100 100] /Resources << /XObject << /Im0 4 0 R >> >> /Contents 5 0 R >>\n")
+	})
+	writeObj(4, func(w *bytes.Buffer) {
+		fmt.Fprintf(w, "<< /Type /XObject /Subtype /Image /Width 1 /Height 1 /ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /DCTDecode /Length %d >>\nstream\n", len(jpegData))
+		w.Write(jpegData)
+		w.WriteString("\nendstream\n")
+	})
+	writeObj(5, func(w *bytes.Buffer) {
+		fmt.Fprintf(w, "<< /Length %d >>\nstream\n%s\nendstream\n", len(content), content)
+	})
+	writeObj(6, func(w *bytes.Buffer) {
+		// Info dictionary deliberately richer than the sidecars in gap-fill
+		// tests: gap-fill must use these, never overwrite with them.
+		w.WriteString("<< /Title (Embedded Title) /Author (Embedded Author) /Subject (Embedded Subject) /Producer (Embedded Producer) /Keywords (embedded-kw) >>\n")
+	})
+
+	xrefStart := buf.Len()
+	fmt.Fprintf(&buf, "xref\n0 %d\n0000000000 65535 f \n", len(offsets))
+	for _, off := range offsets[1:] {
+		fmt.Fprintf(&buf, "%010d 00000 n \n", off)
+	}
+	fmt.Fprintf(&buf, "trailer\n<< /Size %d /Root 1 0 R /Info 6 0 R >>\nstartxref\n%d\n%%%%EOF\n", len(offsets), xrefStart)
+	return buf.Bytes()
+}
+
+// TestSidecarCoverFallback guards the regression where a metadata.json
+// sidecar (no cover.jpg next to the book) made extractMetadata return an
+// empty CoverPath for PDFs - mergeMetadata has no PDF/EPUB cover logic, so a
+// full rescan wiped cover_image_path for sidecar-managed books.
+func TestSidecarCoverFallback(t *testing.T) {
+	dir := t.TempDir()
+	pdfPath := filepath.Join(dir, "book.pdf")
+	if err := os.WriteFile(pdfPath, createTestPDFWithImage(), 0644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "metadata.json"), []byte(`{"title":"Sidecar Book","authors":["A"]}`), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	s := NewMediaScanner(nil)
+	s.folders = []string{dir} // SetFolders requires a live DB; tests only need path relativization
+	metadata, err := s.extractMetadata(pdfPath)
+	if err != nil {
+		t.Fatalf("extractMetadata() error: %v", err)
+	}
+	if metadata.Title != "Sidecar Book" {
+		t.Errorf("Title = %q, want sidecar title", metadata.Title)
+	}
+	if metadata.CoverPath == "" {
+		t.Fatal("CoverPath empty - sidecar branch skipped embedded cover extraction")
+	}
+	if _, err := os.Stat(filepath.Join(dir, metadata.CoverPath)); err != nil {
+		t.Errorf("extracted cover not on disk: %v", err)
+	}
+}
+
+// TestMergeMetadataEPUBGapFill verifies that a sparse sidecar (metadata.opf
+// with only a title) gets its blanks filled from the book's own embedded OPF
+// while sidecar-set fields are never overwritten.
+func TestMergeMetadataEPUBGapFill(t *testing.T) {
+	dir := t.TempDir()
+	epubPath := filepath.Join(dir, "gappy.epub")
+	f, err := os.Create(epubPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	zipWriter := zip.NewWriter(f)
+	mimetype, _ := zipWriter.CreateHeader(&zip.FileHeader{Name: "mimetype", Method: zip.Store})
+	mimetype.Write([]byte("application/epub+zip"))
+	epubFiles := map[string]string{
+		"META-INF/container.xml": `<?xml version="1.0"?><container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container"><rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles></container>`,
+		"OEBPS/content.opf": `<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="u">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:title>Embedded Title</dc:title>
+    <dc:creator>Embedded Author</dc:creator>
+    <dc:description>Embedded description from the book.</dc:description>
+    <dc:publisher>Embedded Publisher</dc:publisher>
+    <dc:language>en</dc:language>
+    <dc:date>2021-06-01</dc:date>
+  </metadata>
+  <manifest/>
+  <spine/>
+</package>`,
+	}
+	for name, content := range epubFiles {
+		w, err := zipWriter.Create(name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		w.Write([]byte(content))
+	}
+	if err := zipWriter.Close(); err != nil {
+		t.Fatal(err)
+	}
+	f.Close()
+
+	sparse := &MediaMetadata{Title: "Sidecar Title", Author: "Sidecar Author"}
+	s := NewMediaScanner(nil)
+	merged, err := s.mergeMetadata(epubPath, sparse)
+	if err != nil {
+		t.Fatalf("mergeMetadata() error: %v", err)
+	}
+	if merged.Title != "Sidecar Title" || merged.Author != "Sidecar Author" {
+		t.Errorf("sidecar values overwritten: title=%q author=%q", merged.Title, merged.Author)
+	}
+	if merged.Description != "Embedded description from the book." {
+		t.Errorf("Description = %q, want embedded fill", merged.Description)
+	}
+	if merged.Publisher != "Embedded Publisher" {
+		t.Errorf("Publisher = %q, want embedded fill", merged.Publisher)
+	}
+	if merged.Language != "en" {
+		t.Errorf("Language = %q, want embedded fill", merged.Language)
+	}
+}
+
+// TestMergeMetadataPDFGapFill verifies the same for PDFs: a sparse sidecar
+// keeps its title while author/description/publisher/tags/pagecount fill in
+// from the embedded Info dictionary.
+func TestMergeMetadataPDFGapFill(t *testing.T) {
+	dir := t.TempDir()
+	pdfPath := filepath.Join(dir, "gappy.pdf")
+	if err := os.WriteFile(pdfPath, createTestPDFWithImage(), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	sparse := &MediaMetadata{Title: "Kept Title"}
+	s := NewMediaScanner(nil)
+	merged, err := s.mergeMetadata(pdfPath, sparse)
+	if err != nil {
+		t.Fatalf("mergeMetadata() error: %v", err)
+	}
+
+	checks := []struct {
+		name string
+		got  string
+		want string
+	}{
+		{"Title (sidecar wins)", merged.Title, "Kept Title"},
+		{"Author", merged.Author, "Embedded Author"},
+		{"Description", merged.Description, "Embedded Subject"},
+		{"Publisher", merged.Publisher, "Embedded Producer"},
+	}
+	for _, c := range checks {
+		if c.got != c.want {
+			t.Errorf("%s = %q, want %q", c.name, c.got, c.want)
+		}
+	}
+	if len(merged.Tags) == 0 {
+		t.Error("Tags empty, want keywords from Info dict")
+	}
+	if merged.PageCount != 1 {
+		t.Errorf("PageCount = %d, want 1 from Info dict", merged.PageCount)
+	}
+}

internal/services/media_scanner_opf.go

@@ -0,0 +1,344 @@
+package services
+
+import (
+	"bytes"
+	"encoding/xml"
+	"strconv"
+	"strings"
+)
+
+// Calibre-modeled OPF parsing. The scanner previously scraped OPF content
+// with attribute-order-sensitive regexes; real books serialize attributes in
+// any order (e.g. Pragmatic/Pattinson EPUBs put id before properties and
+// content before name), which silently defeated cover detection. Everything
+// here is parsed with encoding/xml so attribute order and namespace prefix
+// choices are irrelevant.
+
+type opfDCValue struct {
+	ID    string `xml:"id,attr"`
+	Value string `xml:",chardata"`
+}
+
+type opfIdentifier struct {
+	Scheme string `xml:"http://www.idpf.org/2007/opf scheme,attr"`
+	Value  string `xml:",chardata"`
+}
+
+type opfMeta struct {
+	ID       string `xml:"id,attr"`
+	Name     string `xml:"name,attr"`
+	Content  string `xml:"content,attr"`
+	Property string `xml:"property,attr"`
+	Refines  string `xml:"refines,attr"`
+	Value    string `xml:",chardata"`
+}
+
+type opfItem struct {
+	ID         string `xml:"id,attr"`
+	Href       string `xml:"href,attr"`
+	MediaType  string `xml:"media-type,attr"`
+	Properties string `xml:"properties,attr"`
+}
+
+// opfDocument is a structured view of an OPF package document.
+type opfDocument struct {
+	Metadata struct {
+		Titles       []opfDCValue    `xml:"http://purl.org/dc/elements/1.1/ title"`
+		Creators     []string        `xml:"http://purl.org/dc/elements/1.1/ creator"`
+		Subjects     []string        `xml:"http://purl.org/dc/elements/1.1/ subject"`
+		Descriptions []string        `xml:"http://purl.org/dc/elements/1.1/ description"`
+		Publishers   []string        `xml:"http://purl.org/dc/elements/1.1/ publisher"`
+		Dates        []string        `xml:"http://purl.org/dc/elements/1.1/ date"`
+		Languages    []string        `xml:"http://purl.org/dc/elements/1.1/ language"`
+		Identifiers  []opfIdentifier `xml:"http://purl.org/dc/elements/1.1/ identifier"`
+		Contributors []string        `xml:"http://purl.org/dc/elements/1.1/ contributor"`
+		Metas        []opfMeta       `xml:"meta"`
+	} `xml:"metadata"`
+	Manifest struct {
+		Items []opfItem `xml:"item"`
+	} `xml:"manifest"`
+	Spine struct {
+		PageProgressionDirection string `xml:"page-progression-direction,attr"`
+		Itemrefs                 []struct {
+			IDRef string `xml:"idref,attr"`
+		} `xml:"itemref"`
+	} `xml:"spine"`
+	Guide struct {
+		References []struct {
+			Type string `xml:"type,attr"`
+			Href string `xml:"href,attr"`
+		} `xml:"reference"`
+	} `xml:"guide"`
+}
+
+func parseOPFXML(content []byte) (*opfDocument, error) {
+	var doc opfDocument
+	if err := xml.Unmarshal(content, &doc); err != nil {
+		return nil, err
+	}
+	return &doc, nil
+}
+
+// refinesFor maps an element id to its EPUB3 refining metas
+// (those whose refines attribute starts with '#').
+func (d *opfDocument) refinesFor(id string) []opfMeta {
+	var out []opfMeta
+	if id == "" {
+		return out
+	}
+	for _, m := range d.Metadata.Metas {
+		if strings.HasPrefix(m.Refines, "#") && m.Refines[1:] == id {
+			out = append(out, m)
+		}
+	}
+	return out
+}
+
+// refinesProperty returns the value of the first refining meta carrying the
+// given property (e.g. "title-type", "collection-type", "group-position").
+func refinesProperty(metas []opfMeta, property string) (string, bool) {
+	for _, m := range metas {
+		if strings.EqualFold(m.Property, property) {
+			if v := strings.TrimSpace(m.Value); v != "" {
+				return v, true
+			}
+		}
+	}
+	return "", false
+}
+
+// selectTitle ports Calibre's read_title: prefer the dc:title refined as
+// title-type "main"; fall back to the first non-empty title. A distinct
+// subtitle (title-type containing "subtitle"/"sub-title") is joined onto the
+// main title with ": ", exactly as Calibre stores it.
+func (d *opfDocument) selectTitle() string {
+	var first, main, subtitle string
+	for _, t := range d.Metadata.Titles {
+		v := strings.TrimSpace(t.Value)
+		if v == "" {
+			continue
+		}
+		if first == "" {
+			first = v
+		}
+		tt, ok := refinesProperty(d.refinesFor(t.ID), "title-type")
+		if !ok {
+			continue
+		}
+		switch strings.ToLower(tt) {
+		case "main":
+			if main == "" {
+				main = v
+			}
+		default:
+			l := strings.ToLower(tt)
+			if strings.Contains(l, "subtitle") || strings.Contains(l, "sub-title") {
+				if subtitle == "" {
+					subtitle = v
+				}
+			}
+		}
+	}
+	title := main
+	if title == "" {
+		title = first
+	}
+	if subtitle != "" && subtitle != title {
+		title = title + ": " + subtitle
+	}
+	return title
+}
+
+// readSeries ports Calibre's read_series: EPUB3 belongs-to-collection (with a
+// collection-type=series refine and group-position index) first, then the
+// classic calibre:series / calibre:series_index metas.
+func (d *opfDocument) readSeries() (series string, index float64) {
+	for _, m := range d.Metadata.Metas {
+		if !strings.EqualFold(m.Property, "belongs-to-collection") {
+			continue
+		}
+		name := strings.TrimSpace(m.Value)
+		if name == "" {
+			continue
+		}
+		refines := d.refinesFor(m.ID)
+		if ct, ok := refinesProperty(refines, "collection-type"); !ok || !strings.EqualFold(ct, "series") {
+			continue
+		}
+		if gp, ok := refinesProperty(refines, "group-position"); ok {
+			if v, err := strconv.ParseFloat(strings.TrimSpace(gp), 64); err == nil {
+				index = v
+			}
+		}
+		return name, index
+	}
+	for _, m := range d.Metadata.Metas {
+		switch m.Name {
+		case "calibre:series":
+			series = m.Content
+		case "calibre:series_index":
+			if v, err := strconv.ParseFloat(strings.TrimSpace(m.Content), 64); err == nil {
+				index = v
+			}
+		}
+	}
+	return series, index
+}
+
+// pageProgressionDirection returns the OPF spine's reading direction as
+// "rtl" or "ltr", or "" when the file declares none (callers treat that as
+// unknown, not as left-to-right). EPUB2/3 declare this on <spine>; it is
+// what foliate reads client-side, and the DB column feeds clients (and the
+// web reader's fixed-layout override) that need it up front.
+func (d *opfDocument) pageProgressionDirection() string {
+	switch strings.ToLower(strings.TrimSpace(d.Spine.PageProgressionDirection)) {
+	case "rtl", "right-to-left":
+		return "rtl"
+	case "ltr", "left-to-right", "default":
+		return "ltr"
+	default:
+		return ""
+	}
+}
+
+// itemByID returns manifest items with id, href and media-type, keyed by id.
+func (d *opfDocument) itemByID() map[string]opfItem {
+	m := make(map[string]opfItem, len(d.Manifest.Items))
+	for _, it := range d.Manifest.Items {
+		if it.ID != "" && it.Href != "" && it.MediaType != "" {
+			m[it.ID] = it
+		}
+	}
+	return m
+}
+
+// firstSpineItem returns the manifest item for the first spine idref.
+func (d *opfDocument) firstSpineItem() (opfItem, bool) {
+	if len(d.Spine.Itemrefs) == 0 {
+		return opfItem{}, false
+	}
+	item, ok := d.itemByID()[d.Spine.Itemrefs[0].IDRef]
+	return item, ok
+}
+
+// isRasterMedia reports whether a manifest media-type is an image but not an
+// (X)HTML document - Calibre's guard against cover *pages* masquerading as
+// cover images.
+func isRasterMedia(mediaType string) bool {
+	mt := strings.ToLower(strings.TrimSpace(mediaType))
+	if mt == "" {
+		return false
+	}
+	if strings.Contains(mt, "xml") || strings.Contains(mt, "html") {
+		return false
+	}
+	return strings.HasPrefix(mt, "image/")
+}
+
+// findRasterCoverInOPF ports Calibre's read_raster_cover resolution order:
+//  1. manifest item with properties containing "cover-image"
+//  2. <meta name="cover" content="ID"> resolved through the manifest
+//  3. the first spine item being a raster image itself (store manga)
+//
+// Returns the OPF-relative href of the cover image, or "".
+func (d *opfDocument) findRasterCoverInOPF() string {
+	// 1. properties="cover-image" (space-separated property list)
+	for _, it := range d.Manifest.Items {
+		for _, prop := range strings.Fields(it.Properties) {
+			if strings.EqualFold(prop, "cover-image") && isRasterMedia(it.MediaType) {
+				return it.Href
+			}
+		}
+	}
+
+	// 2. meta name="cover" content=<manifest image id>
+	byID := d.itemByID()
+	for _, m := range d.Metadata.Metas {
+		if !strings.EqualFold(m.Name, "cover") {
+			continue
+		}
+		if it, ok := byID[strings.TrimSpace(m.Content)]; ok && isRasterMedia(it.MediaType) {
+			return it.Href
+		}
+	}
+
+	// 3. first spine item is itself an image (jpeg/webp/png per Calibre)
+	if it, ok := d.firstSpineItem(); ok {
+		mt := strings.ToLower(it.MediaType)
+		if mt == "image/jpeg" || mt == "image/webp" || mt == "image/png" {
+			return it.Href
+		}
+	}
+
+	return ""
+}
+
+// coverPageHref returns the OPF-relative href of the cover *page* document to
+// mine for an embedded image: the guide's type="cover" reference when
+// present, otherwise the first spine item (Calibre renders the latter).
+func (d *opfDocument) coverPageHref() string {
+	for _, ref := range d.Guide.References {
+		if strings.EqualFold(ref.Type, "cover") && ref.Href != "" {
+			return ref.Href
+		}
+	}
+	if it, ok := d.firstSpineItem(); ok {
+		if it.Href != "" && !isRasterMedia(it.MediaType) {
+			return it.Href
+		}
+	}
+	return ""
+}
+
+// isISBNLike reports whether a bare identifier value is shaped like an ISBN
+// (digits, optional hyphens/spaces, optional trailing X; 10 or 13
+// significant characters). Guards the scheme-less dc:identifier fallback
+// against URLs and UUIDs sharing the same slot.
+func isISBNLike(v string) bool {
+	digits := 0
+	for i, r := range v {
+		switch {
+		case r >= '0' && r <= '9':
+			digits++
+		case r == '-' || r == ' ':
+			// separator
+		case (r == 'X' || r == 'x') && i == len(v)-1:
+			digits++ // ISBN-10 check character
+		default:
+			return false
+		}
+	}
+	return digits == 10 || digits == 13
+}
+
+// findImageReferenceInPage extracts the first raster image reference from a
+// cover (X)HTML page: <img src="..."> or SVG <image xlink:href="...">.
+// Token-based parsing keeps it tolerant of mixed namespaces and fragments.
+// Returns the reference relative to the page document, or "".
+func findImageReferenceInPage(pageContent []byte) string {
+	decoder := xml.NewDecoder(bytes.NewReader(pageContent))
+	for {
+		tok, err := decoder.Token()
+		if err != nil {
+			return ""
+		}
+		start, ok := tok.(xml.StartElement)
+		if !ok {
+			continue
+		}
+		switch strings.ToLower(start.Name.Local) {
+		case "img":
+			for _, a := range start.Attr {
+				if strings.EqualFold(a.Name.Local, "src") && strings.TrimSpace(a.Value) != "" {
+					return strings.TrimSpace(a.Value)
+				}
+			}
+		case "image":
+			for _, a := range start.Attr {
+				if strings.EqualFold(a.Name.Local, "href") && strings.TrimSpace(a.Value) != "" {
+					return strings.TrimSpace(a.Value)
+				}
+			}
+		}
+	}
+}

internal/services/media_scanner_opf_test.go

@@ -0,0 +1,297 @@
+package services
+
+import (
+	"archive/zip"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// helper to build an EPUB zip from a file map for cover tests
+func writeEPUB(t *testing.T, path string, files map[string]string) {
+	t.Helper()
+	f, err := os.Create(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close()
+	w := zip.NewWriter(f)
+	mimetype, err := w.CreateHeader(&zip.FileHeader{Name: "mimetype", Method: zip.Store})
+	if err != nil {
+		t.Fatal(err)
+	}
+	mimetype.Write([]byte("application/epub+zip"))
+	for name, content := range files {
+		fw, err := w.Create(name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, err := fw.Write([]byte(content)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+const containerXML = `<?xml version="1.0"?><container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container"><rootfiles><rootfile full-path="OEBPS/package.opf" media-type="application/oebps-package+xml"/></rootfiles></container>`
+
+const tinyJPEG = "\xff\xd8\xff\xe0\x00\x10JFIF\x00\x01\x01\x00\x00\x01\x00\x01\x00\x00\xff\xd9"
+
+// TestFindCoverInOPFAttributeOrder guards the regression where attribute
+// order defeated regex scraping: this OPF mirrors Grand Central's "3 Days to
+// Live" serialization (href before id, content before name on the meta tag).
+func TestFindCoverInOPFAttributeOrder(t *testing.T) {
+	opf := `<?xml version="1.0"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="pub-id">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:title>3 Days to Live</dc:title>
+    <meta content="cover-image" name="cover"/>
+  </metadata>
+  <manifest>
+    <item href="images/9781538752760.jpg" id="cover-image" media-type="image/jpeg" properties="cover-image"/>
+  </manifest>
+  <spine/>
+</package>`
+	files := map[string]string{
+		"META-INF/container.xml":         containerXML,
+		"OEBPS/package.opf":              opf,
+		"OEBPS/images/9781538752760.jpg": tinyJPEG,
+	}
+	epubPath := filepath.Join(t.TempDir(), "book.epub")
+	writeEPUB(t, epubPath, files)
+
+	s := NewMediaScanner(nil)
+	coverPath, err := s.extractEPUBCover(epubPath)
+	if err != nil {
+		t.Fatalf("extractEPUBCover() error: %v", err)
+	}
+	if coverPath == "" {
+		t.Fatal("cover not extracted - attribute order still defeats resolution")
+	}
+	if _, err := os.Stat(coverPath); err != nil {
+		t.Fatalf("cover file not written: %v", err)
+	}
+}
+
+// TestFindCoverInOPFCoverPage covers books that declare no raster cover at
+// all: the classic EPUB2/Adobe structure where cover.xhtml wraps the image
+// (here via SVG), reachable through the guide reference or first spine item.
+func TestFindCoverInOPFCoverPage(t *testing.T) {
+	opf := `<?xml version="1.0"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="2.0">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:title>Old Adobe Book</dc:title>
+  </metadata>
+  <manifest>
+    <item id="coverpage" href="text/cover.xhtml" media-type="application/xhtml+xml"/>
+    <item id="coverimg" href="art/cover-wrap.jpg" media-type="image/jpeg"/>
+  </manifest>
+  <spine><itemref idref="coverpage"/></spine>
+  <guide><reference type="cover" href="text/cover.xhtml"/></guide>
+</package>`
+	coverPage := `<?xml version="1.0"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <body>
+    <div><svg xmlns="http://www.w3.org/2000/svg"><image xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../art/cover-wrap.jpg"/></svg></div>
+  </body>
+</html>`
+	files := map[string]string{
+		"META-INF/container.xml":   containerXML,
+		"OEBPS/package.opf":        opf,
+		"OEBPS/text/cover.xhtml":   coverPage,
+		"OEBPS/art/cover-wrap.jpg": tinyJPEG,
+	}
+	epubPath := filepath.Join(t.TempDir(), "adobe.epub")
+	writeEPUB(t, epubPath, files)
+
+	s := NewMediaScanner(nil)
+	coverPath, err := s.extractEPUBCover(epubPath)
+	if err != nil {
+		t.Fatalf("extractEPUBCover() error: %v", err)
+	}
+	if coverPath == "" {
+		t.Fatal("cover-page fallback failed to find SVG-wrapped image")
+	}
+}
+
+// TestFindCoverInOPFImageFirstSpine covers store manga whose first spine
+// item is a raster image itself (Calibre's third resolution step).
+func TestFindCoverInOPFImageFirstSpine(t *testing.T) {
+	opf := `<?xml version="1.0"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:title>Manga Vol 1</dc:title></metadata>
+  <manifest>
+    <item id="p1" href="pages/0001.jpg" media-type="image/jpeg"/>
+  </manifest>
+  <spine><itemref idref="p1"/></spine>
+</package>`
+	files := map[string]string{
+		"META-INF/container.xml": containerXML,
+		"OEBPS/package.opf":      opf,
+		"OEBPS/pages/0001.jpg":   tinyJPEG,
+	}
+	epubPath := filepath.Join(t.TempDir(), "manga.epub")
+	writeEPUB(t, epubPath, files)
+
+	s := NewMediaScanner(nil)
+	coverPath, err := s.extractEPUBCover(epubPath)
+	if err != nil {
+		t.Fatalf("extractEPUBCover() error: %v", err)
+	}
+	if coverPath == "" {
+		t.Fatal("image-first spine cover not detected")
+	}
+}
+
+// TestParseOPFContentTitleTypeAndSeries covers EPUB3 refines-based title
+// selection (main + subtitle joined Calibre-style) and belongs-to-collection
+// series with collection-type and group-position refines.
+func TestParseOPFContentTitleTypeAndSeries(t *testing.T) {
+	opf := `<?xml version="1.0"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="pub-id">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:title id="t1">The Main Title</dc:title>
+    <dc:title id="t2">The Subtitle</dc:title>
+    <meta refines="#t1" property="title-type">main</meta>
+    <meta refines="#t2" property="title-type">subtitle</meta>
+    <dc:subject>Programming</dc:subject>
+    <dc:subject>Algorithms</dc:subject>
+    <dc:identifier>urn:isbn:978-3-16-148410-0</dc:identifier>
+    <meta id="coll1" property="belongs-to-collection">Great Series</meta>
+    <meta refines="#coll1" property="collection-type">series</meta>
+    <meta refines="#coll1" property="group-position">4.5</meta>
+  </metadata>
+</package>`
+	metadata, err := parseOPFContent([]byte(opf))
+	if err != nil {
+		t.Fatalf("parseOPFContent() error: %v", err)
+	}
+	if want := "The Main Title: The Subtitle"; metadata.Title != want {
+		t.Errorf("Title = %q, want %q", metadata.Title, want)
+	}
+	if metadata.Series != "Great Series" || metadata.SeriesNumber != 4 {
+		t.Errorf("Series = %q/%d, want Great Series/4", metadata.Series, metadata.SeriesNumber)
+	}
+	if metadata.ISBN == "" {
+		t.Error("urn:isbn: identifier not extracted")
+	}
+	if metadata.Genre != "Programming" {
+		t.Errorf("Genre = %q, want first subject %q", metadata.Genre, "Programming")
+	}
+	if len(metadata.Tags) != 2 {
+		t.Errorf("Tags = %v, want both subjects", metadata.Tags)
+	}
+}
+
+// TestParseOPFContentSubjectsWithCommas verifies subject headings keep their
+// embedded commas as single tags (Library of Congress style headings).
+func TestParseOPFContentSubjectsWithCommas(t *testing.T) {
+	opf := `<?xml version="1.0"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="2.0">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:title>A Study in Scarlet</dc:title>
+    <dc:subject>Holmes, Sherlock (Fictitious character) -- Fiction</dc:subject>
+  </metadata>
+</package>`
+	metadata, err := parseOPFContent([]byte(opf))
+	if err != nil {
+		t.Fatalf("parseOPFContent() error: %v", err)
+	}
+	if len(metadata.Tags) != 1 {
+		t.Errorf("Tags = %v, want exactly 1 unsplit subject heading", metadata.Tags)
+	}
+}
+
+// TestResolveOPFPath checks URL decoding and posix normalization of
+// OPF-relative hrefs.
+func TestResolveOPFPath(t *testing.T) {
+	tests := []struct {
+		opfPath, href, want string
+	}{
+		{"OEBPS/package.opf", "images/cover.jpg", "OEBPS/images/cover.jpg"},
+		{"package.opf", "cover.jpg", "cover.jpg"},
+		{"OEBPS/package.opf", "../cover.jpg", "cover.jpg"},
+		{"OEBPS/package.opf", "my%20covers/a%20cover.jpg", "OEBPS/my covers/a cover.jpg"},
+	}
+	for _, tt := range tests {
+		if got := resolveOPFPath(tt.opfPath, tt.href); got != tt.want {
+			t.Errorf("resolveOPFPath(%q, %q) = %q, want %q", tt.opfPath, tt.href, got, tt.want)
+		}
+	}
+}
+
+// TestParseOPFContentPageProgressionDirection verifies the EPUB spine's
+// page-progression-direction feeds ReadingDirection, and that an undeclared
+// direction stays empty rather than forcing left-to-right.
+func TestParseOPFContentPageProgressionDirection(t *testing.T) {
+	makeOPF := func(spineAttrs string) string {
+		return `<?xml version="1.0"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:title>Dir Test</dc:title></metadata>
+  <manifest><item id="p1" href="p1.xhtml" media-type="application/xhtml+xml"/></manifest>
+  <spine` + spineAttrs + `><itemref idref="p1"/></spine>
+</package>`
+	}
+	tests := []struct {
+		name       string
+		spineAttrs string
+		want       string
+	}{
+		{"rtl declared lowercase", ` page-progression-direction="rtl"`, "rtl"},
+		{"rtl declared uppercase", ` page-progression-direction="RTL"`, "rtl"},
+		{"ltr declared", ` page-progression-direction="ltr"`, "ltr"},
+		{"undeclared stays empty", ``, ""},
+		{"unknown value stays empty", ` page-progression-direction="sideways"`, ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			metadata, err := parseOPFContent([]byte(makeOPF(tt.spineAttrs)))
+			if err != nil {
+				t.Fatalf("parseOPFContent() error: %v", err)
+			}
+			if metadata.ReadingDirection != tt.want {
+				t.Errorf("ReadingDirection = %q, want %q", metadata.ReadingDirection, tt.want)
+			}
+		})
+	}
+}
+
+// TestMergeMetadataReadingDirectionGapFill verifies the sidecar wins when it
+// declares a direction, while an embedded-only direction fills the blank.
+func TestMergeMetadataReadingDirectionGapFill(t *testing.T) {
+	dir := t.TempDir()
+	epubPath := filepath.Join(dir, "dir.epub")
+	files := map[string]string{
+		"META-INF/container.xml": containerXML,
+		"OEBPS/package.opf": `<?xml version="1.0"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:title>RTL Book</dc:title></metadata>
+  <manifest><item id="p1" href="p1.xhtml" media-type="application/xhtml+xml"/></manifest>
+  <spine page-progression-direction="rtl"><itemref idref="p1"/></spine>
+</package>`,
+		"OEBPS/p1.xhtml": `<html><body><p>hi</p></body></html>`,
+	}
+	writeEPUB(t, epubPath, files)
+
+	s := NewMediaScanner(nil)
+
+	// Sidecar blank -> embedded rtl fills it
+	merged, err := s.mergeMetadata(epubPath, &MediaMetadata{Title: "Sidecar"})
+	if err != nil {
+		t.Fatalf("mergeMetadata() error: %v", err)
+	}
+	if merged.ReadingDirection != "rtl" {
+		t.Errorf("ReadingDirection = %q, want embedded rtl fill", merged.ReadingDirection)
+	}
+
+	// Sidecar ltr wins over embedded rtl
+	merged, err = s.mergeMetadata(epubPath, &MediaMetadata{Title: "Sidecar", ReadingDirection: "ltr"})
+	if err != nil {
+		t.Fatalf("mergeMetadata() error: %v", err)
+	}
+	if merged.ReadingDirection != "ltr" {
+		t.Errorf("ReadingDirection = %q, want sidecar ltr preserved", merged.ReadingDirection)
+	}
+}

templates/admin_archived.templ

@@ -0,0 +1,103 @@
+package templates
+
+templ AdminArchived(user User, items []ArchivedItem, retentionDays int) {
+	<!DOCTYPE html>
+	<html lang="en">
+		<head>
+			<meta charset="UTF-8"/>
+			<title>Archived Items - Bookhoard</title>
+			<script src="/static/htmx.min.js"></script>
+			<link href="/static/style.css" rel="stylesheet"/>
+			<link rel="icon" type="image/svg+xml" href="/static/favicon.svg"/>
+		</head>
+		<body class="theme-{ user.Theme }">
+			@Header(user, "/admin/archived")
+			<main class="p-8">
+				<div class="max-w-5xl">
+					<div class="mb-8">
+						<div class="flex items-center justify-between gap-4 flex-wrap">
+							<div>
+								<div class="flex items-center gap-3 mb-1">
+									<span class="grid place-items-center h-10 w-10 rounded-xl" style="background-color: var(--accent-muted); color: var(--accent);">
+										@Icon("library", "h-5 w-5")
+									</span>
+									<h1 class="text-2xl font-bold tracking-tight" style="color: var(--text-primary)">Archived Items</h1>
+								</div>
+								<p class="text-sm" style="color: var(--text-secondary)">
+									Books hidden because their files are missing from disk. Reading history is
+									kept in case a file returns; moves are detected automatically.
+									if retentionDays > 0 {
+										Archived items are permanently deleted after { retentionDays } days
+										(ARCHIVE_RETENTION_DAYS).
+									} else {
+										Archived items are kept until manually purged (retention disabled).
+									}
+								</p>
+							</div>
+							if len(items) > 0 {
+								<button type="button" onclick="purgeArchivedItems()" class="btn btn-secondary">
+									@Icon("trash", "h-4 w-4")
+									Purge All Archived
+								</button>
+							}
+						</div>
+					</div>
+
+					if len(items) == 0 {
+						<div class="card p-8 text-center">
+							<p style="color: var(--text-secondary)">Nothing is archived or missing. All clear.</p>
+						</div>
+					} else {
+						<div class="card overflow-hidden">
+							<table class="w-full text-sm">
+								<thead>
+									<tr class="border-b text-left" style="border-color: var(--border); color: var(--text-secondary);">
+										<th class="px-4 py-3 font-semibold">Book</th>
+										<th class="px-4 py-3 font-semibold">Library</th>
+										<th class="px-4 py-3 font-semibold">Status</th>
+										<th class="px-4 py-3 font-semibold text-right">Actions</th>
+									</tr>
+								</thead>
+								<tbody>
+									for _, item := range items {
+										<tr class="border-b" style="border-color: color-mix(in srgb, var(--text-primary) 5%, transparent);">
+											<td class="px-4 py-3">
+												<p class="font-medium" style="color: var(--text-primary)">{ item.Title }</p>
+												if item.Author != "" {
+													<p style="color: var(--text-secondary)">{ item.Author }</p>
+												}
+												<p class="font-mono text-xs break-all" style="color: var(--text-secondary)">{ item.FilePath }</p>
+											</td>
+											<td class="px-4 py-3" style="color: var(--text-primary)">{ item.LibraryName }</td>
+											<td class="px-4 py-3" style="color: var(--text-secondary)">{ item.Status }</td>
+											<td class="px-4 py-3 text-right whitespace-nowrap">
+												<button
+													type="button"
+													data-unarchive={ item.ID }
+													class="btn btn-ghost text-xs"
+													title="Restore to libraries now; if the file is still gone the next scan hides it again"
+												>
+													@Icon("refresh", "h-3.5 w-3.5")
+													Restore
+												</button>
+												<button
+													type="button"
+													data-delete-archived={ item.ID }
+													class="btn btn-ghost text-xs"
+													title="Delete this item and its reading history permanently"
+												>
+													@Icon("trash", "h-3.5 w-3.5")
+													Delete
+												</button>
+											</td>
+										</tr>
+									}
+								</tbody>
+							</table>
+						</div>
+					}
+				</div>
+			</main>
+		</body>
+	</html>
+}

templates/admin_archived_templ.go

@@ -0,0 +1,244 @@
+// Code generated by templ - DO NOT EDIT.
+
+// templ: version: v0.3.1020
+package templates
+
+//lint:file-ignore SA4006 This context is only used if a nested component is present.
+
+import "github.com/a-h/templ"
+import templruntime "github.com/a-h/templ/runtime"
+
+func AdminArchived(user User, items []ArchivedItem, retentionDays int) templ.Component {
+	return templruntime.GeneratedTemplate(func(templ_7745c5c3_Input templruntime.GeneratedComponentInput) (templ_7745c5c3_Err error) {
+		templ_7745c5c3_W, ctx := templ_7745c5c3_Input.Writer, templ_7745c5c3_Input.Context
+		if templ_7745c5c3_CtxErr := ctx.Err(); templ_7745c5c3_CtxErr != nil {
+			return templ_7745c5c3_CtxErr
+		}
+		templ_7745c5c3_Buffer, templ_7745c5c3_IsBuffer := templruntime.GetBuffer(templ_7745c5c3_W)
+		if !templ_7745c5c3_IsBuffer {
+			defer func() {
+				templ_7745c5c3_BufErr := templruntime.ReleaseBuffer(templ_7745c5c3_Buffer)
+				if templ_7745c5c3_Err == nil {
+					templ_7745c5c3_Err = templ_7745c5c3_BufErr
+				}
+			}()
+		}
+		ctx = templ.InitializeContext(ctx)
+		templ_7745c5c3_Var1 := templ.GetChildren(ctx)
+		if templ_7745c5c3_Var1 == nil {
+			templ_7745c5c3_Var1 = templ.NopComponent
+		}
+		ctx = templ.ClearChildren(ctx)
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 1, "<!doctype html><html lang=\"en\"><head><meta charset=\"UTF-8\"><title>Archived Items - Bookhoard</title><script src=\"/static/htmx.min.js\"></script><link href=\"/static/style.css\" rel=\"stylesheet\"><link rel=\"icon\" type=\"image/svg+xml\" href=\"/static/favicon.svg\"></head><body class=\"theme-{ user.Theme }\">")
+		if templ_7745c5c3_Err != nil {
+			return templ_7745c5c3_Err
+		}
+		templ_7745c5c3_Err = Header(user, "/admin/archived").Render(ctx, templ_7745c5c3_Buffer)
+		if templ_7745c5c3_Err != nil {
+			return templ_7745c5c3_Err
+		}
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 2, "<main class=\"p-8\"><div class=\"max-w-5xl\"><div class=\"mb-8\"><div class=\"flex items-center justify-between gap-4 flex-wrap\"><div><div class=\"flex items-center gap-3 mb-1\"><span class=\"grid place-items-center h-10 w-10 rounded-xl\" style=\"background-color: var(--accent-muted); color: var(--accent);\">")
+		if templ_7745c5c3_Err != nil {
+			return templ_7745c5c3_Err
+		}
+		templ_7745c5c3_Err = Icon("library", "h-5 w-5").Render(ctx, templ_7745c5c3_Buffer)
+		if templ_7745c5c3_Err != nil {
+			return templ_7745c5c3_Err
+		}
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 3, "</span><h1 class=\"text-2xl font-bold tracking-tight\" style=\"color: var(--text-primary)\">Archived Items</h1></div><p class=\"text-sm\" style=\"color: var(--text-secondary)\">Books hidden because their files are missing from disk. Reading history is kept in case a file returns; moves are detected automatically. ")
+		if templ_7745c5c3_Err != nil {
+			return templ_7745c5c3_Err
+		}
+		if retentionDays > 0 {
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 4, "Archived items are permanently deleted after ")
+			if templ_7745c5c3_Err != nil {
+				return templ_7745c5c3_Err
+			}
+			var templ_7745c5c3_Var2 string
+			templ_7745c5c3_Var2, templ_7745c5c3_Err = templ.JoinStringErrs(retentionDays)
+			if templ_7745c5c3_Err != nil {
+				return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 30, Col: 70}
+			}
+			_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var2))
+			if templ_7745c5c3_Err != nil {
+				return templ_7745c5c3_Err
+			}
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 5, " days (ARCHIVE_RETENTION_DAYS).")
+			if templ_7745c5c3_Err != nil {
+				return templ_7745c5c3_Err
+			}
+		} else {
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 6, "Archived items are kept until manually purged (retention disabled).")
+			if templ_7745c5c3_Err != nil {
+				return templ_7745c5c3_Err
+			}
+		}
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 7, "</p></div>")
+		if templ_7745c5c3_Err != nil {
+			return templ_7745c5c3_Err
+		}
+		if len(items) > 0 {
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 8, "<button type=\"button\" onclick=\"purgeArchivedItems()\" class=\"btn btn-secondary\">")
+			if templ_7745c5c3_Err != nil {
+				return templ_7745c5c3_Err
+			}
+			templ_7745c5c3_Err = Icon("trash", "h-4 w-4").Render(ctx, templ_7745c5c3_Buffer)
+			if templ_7745c5c3_Err != nil {
+				return templ_7745c5c3_Err
+			}
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 9, "Purge All Archived</button>")
+			if templ_7745c5c3_Err != nil {
+				return templ_7745c5c3_Err
+			}
+		}
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 10, "</div></div>")
+		if templ_7745c5c3_Err != nil {
+			return templ_7745c5c3_Err
+		}
+		if len(items) == 0 {
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 11, "<div class=\"card p-8 text-center\"><p style=\"color: var(--text-secondary)\">Nothing is archived or missing. All clear.</p></div>")
+			if templ_7745c5c3_Err != nil {
+				return templ_7745c5c3_Err
+			}
+		} else {
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 12, "<div class=\"card overflow-hidden\"><table class=\"w-full text-sm\"><thead><tr class=\"border-b text-left\" style=\"border-color: var(--border); color: var(--text-secondary);\"><th class=\"px-4 py-3 font-semibold\">Book</th><th class=\"px-4 py-3 font-semibold\">Library</th><th class=\"px-4 py-3 font-semibold\">Status</th><th class=\"px-4 py-3 font-semibold text-right\">Actions</th></tr></thead> <tbody>")
+			if templ_7745c5c3_Err != nil {
+				return templ_7745c5c3_Err
+			}
+			for _, item := range items {
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 13, "<tr class=\"border-b\" style=\"border-color: color-mix(in srgb, var(--text-primary) 5%, transparent);\"><td class=\"px-4 py-3\"><p class=\"font-medium\" style=\"color: var(--text-primary)\">")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var3 string
+				templ_7745c5c3_Var3, templ_7745c5c3_Err = templ.JoinStringErrs(item.Title)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 65, Col: 82}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var3))
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 14, "</p>")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				if item.Author != "" {
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 15, "<p style=\"color: var(--text-secondary)\">")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					var templ_7745c5c3_Var4 string
+					templ_7745c5c3_Var4, templ_7745c5c3_Err = templ.JoinStringErrs(item.Author)
+					if templ_7745c5c3_Err != nil {
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 67, Col: 66}
+					}
+					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var4))
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 16, "</p>")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 17, "<p class=\"font-mono text-xs break-all\" style=\"color: var(--text-secondary)\">")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var5 string
+				templ_7745c5c3_Var5, templ_7745c5c3_Err = templ.JoinStringErrs(item.FilePath)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 69, Col: 103}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var5))
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 18, "</p></td><td class=\"px-4 py-3\" style=\"color: var(--text-primary)\">")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var6 string
+				templ_7745c5c3_Var6, templ_7745c5c3_Err = templ.JoinStringErrs(item.LibraryName)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 71, Col: 86}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var6))
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 19, "</td><td class=\"px-4 py-3\" style=\"color: var(--text-secondary)\">")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var7 string
+				templ_7745c5c3_Var7, templ_7745c5c3_Err = templ.JoinStringErrs(item.Status)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 72, Col: 83}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var7))
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 20, "</td><td class=\"px-4 py-3 text-right whitespace-nowrap\"><button type=\"button\" data-unarchive=\"")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var8 string
+				templ_7745c5c3_Var8, templ_7745c5c3_Err = templ.ResolveAttributeValue(item.ID)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 76, Col: 37}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var8)
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 21, "\" class=\"btn btn-ghost text-xs\" title=\"Restore to libraries now; if the file is still gone the next scan hides it again\">")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = Icon("refresh", "h-3.5 w-3.5").Render(ctx, templ_7745c5c3_Buffer)
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 22, "Restore</button> <button type=\"button\" data-delete-archived=\"")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var9 string
+				templ_7745c5c3_Var9, templ_7745c5c3_Err = templ.ResolveAttributeValue(item.ID)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/admin_archived.templ`, Line: 85, Col: 43}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var9)
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 23, "\" class=\"btn btn-ghost text-xs\" title=\"Delete this item and its reading history permanently\">")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = Icon("trash", "h-3.5 w-3.5").Render(ctx, templ_7745c5c3_Buffer)
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 24, "Delete</button></td></tr>")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+			}
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 25, "</tbody></table></div>")
+			if templ_7745c5c3_Err != nil {
+				return templ_7745c5c3_Err
+			}
+		}
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 26, "</div></main></body></html>")
+		if templ_7745c5c3_Err != nil {
+			return templ_7745c5c3_Err
+		}
+		return nil
+	})
+}
+
+var _ = templruntime.GeneratedTemplate

templates/admin_library.templ

@@ -1,6 +1,6 @@
 package templates
 
-templ AdminLibrary(user User, libraries []LibraryData, users []User) {
+templ AdminLibrary(user User, libraries []LibraryData, users []User, archivedCount int64) {
 	<!DOCTYPE html>
 	<html lang="en">
 		<head>
@@ -34,6 +34,28 @@ templ AdminLibrary(user User, libraries []LibraryData, users []User) {
 						</button>
 						</div>
 					</div>
+					if archivedCount > 0 {
+						<div class="card p-4 mb-6 flex items-center justify-between gap-4 flex-wrap">
+							<div>
+								<p class="font-semibold" style="color: var(--text-primary)">
+									<a href="/admin/archived" class="hover:underline" style="color: var(--text-primary); text-decoration: none;">
+										Archived items: { archivedCount }
+									</a>
+								</p>
+								<p class="text-sm" style="color: var(--text-secondary)">
+									Files missing from disk for two consecutive scans. Reading history is kept
+									unless purged; items return automatically if their files come back.
+								</p>
+							</div>
+							<div class="flex items-center gap-2">
+								<a href="/admin/archived" class="btn btn-secondary">View Archived</a>
+								<button type="button" onclick="purgeArchivedItems()" class="btn btn-secondary">
+									@Icon("trash", "h-4 w-4")
+									Purge Archived Now
+								</button>
+							</div>
+						</div>
+					}
 					<div id="libraries-container">
 						@LibraryList(user, libraries, users)
 					</div>

templates/bookshelf.templ

@@ -149,7 +149,13 @@ templ BookShelf(
 												<option value="">All Books ({ TotalMediaCount(libraries) })</option>
 											}
 										for _, lib := range libraries {
+											if lib.Offline {
 												if lib.ID == currentLibraryID {
+													<option value={ lib.ID } selected>{ lib.Name } ({ lib.MediaCount }) — storage offline</option>
+												} else {
+													<option value={ lib.ID }>{ lib.Name } ({ lib.MediaCount }) — storage offline</option>
+												}
+											} else if lib.ID == currentLibraryID {
 												<option value={ lib.ID } selected>{ lib.Name } ({ lib.MediaCount })</option>
 											} else {
 												<option value={ lib.ID }>{ lib.Name } ({ lib.MediaCount })</option>

templates/bookshelf_templ.go

@@ -203,6 +203,7 @@ func BookShelf(
 				}
 			}
 			for _, lib := range libraries {
+				if lib.Offline {
 					if lib.ID == currentLibraryID {
 						templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 21, "<option value=\"")
 						if templ_7745c5c3_Err != nil {
@@ -211,7 +212,7 @@ func BookShelf(
 						var templ_7745c5c3_Var6 string
 						templ_7745c5c3_Var6, templ_7745c5c3_Err = templ.ResolveAttributeValue(lib.ID)
 						if templ_7745c5c3_Err != nil {
-						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 153, Col: 35}
+							return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 154, Col: 35}
 						}
 						_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var6)
 						if templ_7745c5c3_Err != nil {
@@ -224,7 +225,7 @@ func BookShelf(
 						var templ_7745c5c3_Var7 string
 						templ_7745c5c3_Var7, templ_7745c5c3_Err = templ.JoinStringErrs(lib.Name)
 						if templ_7745c5c3_Err != nil {
-						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 153, Col: 57}
+							return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 154, Col: 57}
 						}
 						_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var7))
 						if templ_7745c5c3_Err != nil {
@@ -237,13 +238,13 @@ func BookShelf(
 						var templ_7745c5c3_Var8 string
 						templ_7745c5c3_Var8, templ_7745c5c3_Err = templ.JoinStringErrs(lib.MediaCount)
 						if templ_7745c5c3_Err != nil {
-						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 153, Col: 77}
+							return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 154, Col: 77}
 						}
 						_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var8))
 						if templ_7745c5c3_Err != nil {
 							return templ_7745c5c3_Err
 						}
-					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 24, ")</option>")
+						templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 24, ") — storage offline</option>")
 						if templ_7745c5c3_Err != nil {
 							return templ_7745c5c3_Err
 						}
@@ -255,7 +256,7 @@ func BookShelf(
 						var templ_7745c5c3_Var9 string
 						templ_7745c5c3_Var9, templ_7745c5c3_Err = templ.ResolveAttributeValue(lib.ID)
 						if templ_7745c5c3_Err != nil {
-						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 155, Col: 35}
+							return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 156, Col: 35}
 						}
 						_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var9)
 						if templ_7745c5c3_Err != nil {
@@ -268,7 +269,7 @@ func BookShelf(
 						var templ_7745c5c3_Var10 string
 						templ_7745c5c3_Var10, templ_7745c5c3_Err = templ.JoinStringErrs(lib.Name)
 						if templ_7745c5c3_Err != nil {
-						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 155, Col: 48}
+							return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 156, Col: 48}
 						}
 						_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var10))
 						if templ_7745c5c3_Err != nil {
@@ -281,20 +282,109 @@ func BookShelf(
 						var templ_7745c5c3_Var11 string
 						templ_7745c5c3_Var11, templ_7745c5c3_Err = templ.JoinStringErrs(lib.MediaCount)
 						if templ_7745c5c3_Err != nil {
-						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 155, Col: 68}
+							return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 156, Col: 68}
 						}
 						_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var11))
 						if templ_7745c5c3_Err != nil {
 							return templ_7745c5c3_Err
 						}
-					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 28, ")</option>")
+						templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 28, ") — storage offline</option>")
+						if templ_7745c5c3_Err != nil {
+							return templ_7745c5c3_Err
+						}
+					}
+				} else if lib.ID == currentLibraryID {
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 29, "<option value=\"")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					var templ_7745c5c3_Var12 string
+					templ_7745c5c3_Var12, templ_7745c5c3_Err = templ.ResolveAttributeValue(lib.ID)
+					if templ_7745c5c3_Err != nil {
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 159, Col: 34}
+					}
+					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var12)
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 30, "\" selected>")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					var templ_7745c5c3_Var13 string
+					templ_7745c5c3_Var13, templ_7745c5c3_Err = templ.JoinStringErrs(lib.Name)
+					if templ_7745c5c3_Err != nil {
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 159, Col: 56}
+					}
+					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var13))
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 31, " (")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					var templ_7745c5c3_Var14 string
+					templ_7745c5c3_Var14, templ_7745c5c3_Err = templ.JoinStringErrs(lib.MediaCount)
+					if templ_7745c5c3_Err != nil {
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 159, Col: 76}
+					}
+					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var14))
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 32, ")</option>")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+				} else {
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 33, "<option value=\"")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					var templ_7745c5c3_Var15 string
+					templ_7745c5c3_Var15, templ_7745c5c3_Err = templ.ResolveAttributeValue(lib.ID)
+					if templ_7745c5c3_Err != nil {
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 161, Col: 34}
+					}
+					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var15)
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 34, "\">")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					var templ_7745c5c3_Var16 string
+					templ_7745c5c3_Var16, templ_7745c5c3_Err = templ.JoinStringErrs(lib.Name)
+					if templ_7745c5c3_Err != nil {
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 161, Col: 47}
+					}
+					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var16))
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 35, " (")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					var templ_7745c5c3_Var17 string
+					templ_7745c5c3_Var17, templ_7745c5c3_Err = templ.JoinStringErrs(lib.MediaCount)
+					if templ_7745c5c3_Err != nil {
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 161, Col: 67}
+					}
+					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var17))
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 36, ")</option>")
 					if templ_7745c5c3_Err != nil {
 						return templ_7745c5c3_Err
 					}
 				}
 			}
 		}
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 29, "</select></div><div><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Author</label> <input type=\"text\" name=\"author_filter\" placeholder=\"Filter by author\" class=\"input\" list=\"author-datalist\" @input.debounce.300ms=\"if($el.value.length >= 2) fetchAuthorValues($el)\"> <datalist id=\"author-datalist\"></datalist></div><div class=\"relative\"><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Tags</label> <input type=\"text\" name=\"tags_filter\" placeholder=\"Filter by tags\" class=\"input\" @input.debounce.300ms=\"if($el.value.length >= 2) fetchTagValues($el)\" @keydown=\"onTagFilterKeydown($event)\" @blur=\"hideTagDropdown()\"><div x-show=\"showTagDropdown\" x-transition x-cloak class=\"absolute z-50 mt-1 w-full rounded-lg shadow-lg max-h-48 overflow-y-auto\" style=\"background-color: var(--bg-primary); border: 1px solid var(--border);\"><template x-for=\"sug in tagSuggestions\" :key=\"sug.value\"><button type=\"button\" class=\"w-full text-left px-3 py-2 text-sm flex justify-between items-center\" :class=\"tagHighlightIndex === tagSuggestions.indexOf(sug) ? 'opacity-80' : ''\" :style=\"tagHighlightIndex === tagSuggestions.indexOf(sug) ? 'background-color: var(--bg-secondary); color: var(--text-primary);' : 'color: var(--text-primary);'\" @click=\"selectTagSuggestion(sug.value)\"><span x-text=\"sug.value\"></span> <span class=\"text-xs\" style=\"color: var(--text-secondary);\" x-text=\"sug.count + ' books'\"></span></button></template></div></div><div><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Series</label> <input type=\"text\" name=\"series_filter\" placeholder=\"Filter by series\" class=\"input\" list=\"series-datalist\" @input.debounce.300ms=\"if($el.value.length >= 2) fetchSeriesValues($el)\"> <datalist id=\"series-datalist\"></datalist></div><div><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Language</label> <input type=\"text\" name=\"language_filter\" placeholder=\"Filter by language\" class=\"input\" list=\"language-datalist\" @input.debounce.300ms=\"if($el.value.length >= 2) fetchLanguageValues($el)\"> <datalist id=\"language-datalist\"></datalist></div><div><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Year Range</label><div class=\"flex gap-2\"><input type=\"number\" name=\"year_min\" placeholder=\"From\" class=\"input\"> <input type=\"number\" name=\"year_max\" placeholder=\"To\" class=\"input\"></div></div><div><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Cover</label> <input type=\"button\" id=\"has-cover-tristate\" class=\"tristate-btn w-full transition-all duration-300 cursor-pointer flex items-center justify-center gap-2 px-4 py-2 rounded-lg border text-sm\" :class=\"{\n\t\t\t\t\t\t\t\t\t\t\t'state-null': hasCoverState === null,\n\t\t\t\t\t\t\t\t\t\t\t'state-true': hasCoverState === true,\n\t\t\t\t\t\t\t\t\t\t\t'state-false': hasCoverState === false\n\t\t\t\t\t\t\t\t\t\t}\" :value=\"hasCoverState === null ? '○ Any cover' : hasCoverState === true ? '✓ Has cover' : '✗ No cover'\" @click=\"cycleHasCover()\"><template x-if=\"hasCoverState !== null\"><input type=\"hidden\" name=\"has_cover\" :value=\"hasCoverState ? 'true' : 'false'\"></template></div></div><div class=\"sticky bottom-0 px-6 py-4 border-t\" style=\"background-color: var(--bg-secondary); border-color: color-mix(in srgb, var(--text-primary) 7%, transparent);\"><button type=\"submit\" @click=\"filtersOpen = false\" class=\"btn btn-primary w-full\">Apply Filters</button></div></div></div></form><div id=\"books-grid\" class=\"grid grid-cols-2 md:grid-cols-4 lg:grid-cols-5 xl:grid-cols-6 gap-4\">")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 37, "</select></div><div><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Author</label> <input type=\"text\" name=\"author_filter\" placeholder=\"Filter by author\" class=\"input\" list=\"author-datalist\" @input.debounce.300ms=\"if($el.value.length >= 2) fetchAuthorValues($el)\"> <datalist id=\"author-datalist\"></datalist></div><div class=\"relative\"><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Tags</label> <input type=\"text\" name=\"tags_filter\" placeholder=\"Filter by tags\" class=\"input\" @input.debounce.300ms=\"if($el.value.length >= 2) fetchTagValues($el)\" @keydown=\"onTagFilterKeydown($event)\" @blur=\"hideTagDropdown()\"><div x-show=\"showTagDropdown\" x-transition x-cloak class=\"absolute z-50 mt-1 w-full rounded-lg shadow-lg max-h-48 overflow-y-auto\" style=\"background-color: var(--bg-primary); border: 1px solid var(--border);\"><template x-for=\"sug in tagSuggestions\" :key=\"sug.value\"><button type=\"button\" class=\"w-full text-left px-3 py-2 text-sm flex justify-between items-center\" :class=\"tagHighlightIndex === tagSuggestions.indexOf(sug) ? 'opacity-80' : ''\" :style=\"tagHighlightIndex === tagSuggestions.indexOf(sug) ? 'background-color: var(--bg-secondary); color: var(--text-primary);' : 'color: var(--text-primary);'\" @click=\"selectTagSuggestion(sug.value)\"><span x-text=\"sug.value\"></span> <span class=\"text-xs\" style=\"color: var(--text-secondary);\" x-text=\"sug.count + ' books'\"></span></button></template></div></div><div><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Series</label> <input type=\"text\" name=\"series_filter\" placeholder=\"Filter by series\" class=\"input\" list=\"series-datalist\" @input.debounce.300ms=\"if($el.value.length >= 2) fetchSeriesValues($el)\"> <datalist id=\"series-datalist\"></datalist></div><div><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Language</label> <input type=\"text\" name=\"language_filter\" placeholder=\"Filter by language\" class=\"input\" list=\"language-datalist\" @input.debounce.300ms=\"if($el.value.length >= 2) fetchLanguageValues($el)\"> <datalist id=\"language-datalist\"></datalist></div><div><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Year Range</label><div class=\"flex gap-2\"><input type=\"number\" name=\"year_min\" placeholder=\"From\" class=\"input\"> <input type=\"number\" name=\"year_max\" placeholder=\"To\" class=\"input\"></div></div><div><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Cover</label> <input type=\"button\" id=\"has-cover-tristate\" class=\"tristate-btn w-full transition-all duration-300 cursor-pointer flex items-center justify-center gap-2 px-4 py-2 rounded-lg border text-sm\" :class=\"{\n\t\t\t\t\t\t\t\t\t\t\t'state-null': hasCoverState === null,\n\t\t\t\t\t\t\t\t\t\t\t'state-true': hasCoverState === true,\n\t\t\t\t\t\t\t\t\t\t\t'state-false': hasCoverState === false\n\t\t\t\t\t\t\t\t\t\t}\" :value=\"hasCoverState === null ? '○ Any cover' : hasCoverState === true ? '✓ Has cover' : '✗ No cover'\" @click=\"cycleHasCover()\"><template x-if=\"hasCoverState !== null\"><input type=\"hidden\" name=\"has_cover\" :value=\"hasCoverState ? 'true' : 'false'\"></template></div></div><div class=\"sticky bottom-0 px-6 py-4 border-t\" style=\"background-color: var(--bg-secondary); border-color: color-mix(in srgb, var(--text-primary) 7%, transparent);\"><button type=\"submit\" @click=\"filtersOpen = false\" class=\"btn btn-primary w-full\">Apply Filters</button></div></div></div></form><div id=\"books-grid\" class=\"grid grid-cols-2 md:grid-cols-4 lg:grid-cols-5 xl:grid-cols-6 gap-4\">")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
@@ -303,53 +393,53 @@ func BookShelf(
 			return templ_7745c5c3_Err
 		}
 		if errorMessage != "" {
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 30, "<div class=\"col-span-full mt-2 p-4 rounded-xl border\" style=\"background-color: color-mix(in srgb, var(--status-danger) 10%, transparent); border-color: var(--status-danger);\"><p style=\"color: var(--text-primary)\">")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 38, "<div class=\"col-span-full mt-2 p-4 rounded-xl border\" style=\"background-color: color-mix(in srgb, var(--status-danger) 10%, transparent); border-color: var(--status-danger);\"><p style=\"color: var(--text-primary)\">")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
-			var templ_7745c5c3_Var12 string
+			var templ_7745c5c3_Var18 string
-			templ_7745c5c3_Var12, templ_7745c5c3_Err = templ.JoinStringErrs(errorMessage)
+			templ_7745c5c3_Var18, templ_7745c5c3_Err = templ.JoinStringErrs(errorMessage)
 			if templ_7745c5c3_Err != nil {
-				return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 269, Col: 59}
+				return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 275, Col: 59}
 			}
-			_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var12))
+			_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var18))
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 31, "</p></div>")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 39, "</p></div>")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
 		}
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 32, "</div><div id=\"pagination\" class=\"mt-6 flex justify-center items-center gap-2\">")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 40, "</div><div id=\"pagination\" class=\"mt-6 flex justify-center items-center gap-2\">")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
 		if count > 0 {
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 33, "<button type=\"button\" class=\"btn btn-secondary disabled:opacity-40\" hx-get=\"")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 41, "<button type=\"button\" class=\"btn btn-secondary disabled:opacity-40\" hx-get=\"")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
-			var templ_7745c5c3_Var13 string
+			var templ_7745c5c3_Var19 string
-			templ_7745c5c3_Var13, templ_7745c5c3_Err = templ.ResolveAttributeValue(fmt.Sprintf("/api/media-items/search?library_id=%s&limit=%d&offset=%d", currentLibraryID, limit, offset-limit))
+			templ_7745c5c3_Var19, templ_7745c5c3_Err = templ.ResolveAttributeValue(fmt.Sprintf("/api/media-items/search?library_id=%s&limit=%d&offset=%d", currentLibraryID, limit, offset-limit))
 			if templ_7745c5c3_Err != nil {
-				return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 278, Col: 126}
+				return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 284, Col: 126}
 			}
-			_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var13)
+			_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var19)
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 34, "\" hx-target=\"#books-grid\" hx-include=\"#filter-form\"")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 42, "\" hx-target=\"#books-grid\" hx-include=\"#filter-form\"")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
 			if offset <= 0 {
-				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 35, " disabled")
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 43, " disabled")
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
 			}
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 36, ">")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 44, ">")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
@@ -357,43 +447,43 @@ func BookShelf(
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 37, "<span>Prev</span></button> <span class=\"px-4 py-2 text-sm\" style=\"color: var(--text-secondary);\">Page ")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 45, "<span>Prev</span></button> <span class=\"px-4 py-2 text-sm\" style=\"color: var(--text-secondary);\">Page ")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
-			var templ_7745c5c3_Var14 string
+			var templ_7745c5c3_Var20 string
-			templ_7745c5c3_Var14, templ_7745c5c3_Err = templ.JoinStringErrs(offset/limit + 1)
+			templ_7745c5c3_Var20, templ_7745c5c3_Err = templ.JoinStringErrs(offset/limit + 1)
 			if templ_7745c5c3_Err != nil {
-				return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 287, Col: 32}
+				return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 293, Col: 32}
 			}
-			_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var14))
+			_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var20))
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 38, "</span> <button type=\"button\" class=\"btn btn-secondary disabled:opacity-40\" hx-get=\"")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 46, "</span> <button type=\"button\" class=\"btn btn-secondary disabled:opacity-40\" hx-get=\"")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
-			var templ_7745c5c3_Var15 string
+			var templ_7745c5c3_Var21 string
-			templ_7745c5c3_Var15, templ_7745c5c3_Err = templ.ResolveAttributeValue(fmt.Sprintf("/api/media-items/search?library_id=%s&limit=%d&offset=%d", currentLibraryID, limit, offset+limit))
+			templ_7745c5c3_Var21, templ_7745c5c3_Err = templ.ResolveAttributeValue(fmt.Sprintf("/api/media-items/search?library_id=%s&limit=%d&offset=%d", currentLibraryID, limit, offset+limit))
 			if templ_7745c5c3_Err != nil {
-				return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 292, Col: 126}
+				return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/bookshelf.templ`, Line: 298, Col: 126}
 			}
-			_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var15)
+			_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var21)
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 39, "\" hx-target=\"#books-grid\" hx-include=\"#filter-form\"")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 47, "\" hx-target=\"#books-grid\" hx-include=\"#filter-form\"")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
 			if offset+limit >= count {
-				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 40, " disabled")
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 48, " disabled")
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
 			}
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 41, "><span>Next</span>")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 49, "><span>Next</span>")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
@@ -401,12 +491,12 @@ func BookShelf(
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 42, "</button>")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 50, "</button>")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
 		}
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 43, "</div></div><div x-show=\"showSaveModal\" @click.self=\"showSaveModal = false\" x-transition x-cloak class=\"fixed inset-0 z-[70] flex items-center justify-center p-4\" style=\"background-color: var(--surface-overlay);\"><div @click.stop class=\"card rounded-2xl p-6 w-full max-w-md\"><div class=\"flex justify-between items-center mb-4\"><h2 class=\"text-xl font-bold\" style=\"color: var(--text-primary)\">Save Filter</h2><button @click=\"showSaveModal = false\" class=\"icon-btn\" aria-label=\"Close\">")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 51, "</div></div><div x-show=\"showSaveModal\" @click.self=\"showSaveModal = false\" x-transition x-cloak class=\"fixed inset-0 z-[70] flex items-center justify-center p-4\" style=\"background-color: var(--surface-overlay);\"><div @click.stop class=\"card rounded-2xl p-6 w-full max-w-md\"><div class=\"flex justify-between items-center mb-4\"><h2 class=\"text-xl font-bold\" style=\"color: var(--text-primary)\">Save Filter</h2><button @click=\"showSaveModal = false\" class=\"icon-btn\" aria-label=\"Close\">")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
@@ -414,7 +504,7 @@ func BookShelf(
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 44, "</button></div><form hx-post=\"/api/saved-filters\" hx-target=\"#saved-filters-list\" hx-swap=\"beforeend\" hx-include=\"#filter-form\" @htmx:afterRequest=\"if(event.detail.xhr.status < 400) { afterFilterSave() }\"><div class=\"mb-4\"><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Filter Name</label> <input type=\"text\" name=\"filter_name\" placeholder=\"My Custom Filter\" class=\"input\" required><div id=\"filter-save-error\" style=\"display: none; color: var(--status-danger); padding: 0.75rem; border-radius: 0.5rem; margin-top: 0.75rem;\"></div><input type=\"hidden\" name=\"resource_type\" value=\"media-items\"></div><div class=\"flex justify-end gap-2\"><button type=\"button\" @click=\"showSaveModal = false\" class=\"btn btn-secondary\">Cancel</button> <button type=\"submit\" class=\"btn btn-primary\">Save</button></div><input type=\"hidden\" name=\"limit\" value=\"50\"> <input type=\"hidden\" name=\"offset\" value=\"0\"></form></div></div></body></html>")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 52, "</button></div><form hx-post=\"/api/saved-filters\" hx-target=\"#saved-filters-list\" hx-swap=\"beforeend\" hx-include=\"#filter-form\" @htmx:afterRequest=\"if(event.detail.xhr.status < 400) { afterFilterSave() }\"><div class=\"mb-4\"><label class=\"block text-xs font-semibold uppercase tracking-wide mb-2\" style=\"color: var(--text-secondary)\">Filter Name</label> <input type=\"text\" name=\"filter_name\" placeholder=\"My Custom Filter\" class=\"input\" required><div id=\"filter-save-error\" style=\"display: none; color: var(--status-danger); padding: 0.75rem; border-radius: 0.5rem; margin-top: 0.75rem;\"></div><input type=\"hidden\" name=\"resource_type\" value=\"media-items\"></div><div class=\"flex justify-end gap-2\"><button type=\"button\" @click=\"showSaveModal = false\" class=\"btn btn-secondary\">Cancel</button> <button type=\"submit\" class=\"btn btn-primary\">Save</button></div><input type=\"hidden\" name=\"limit\" value=\"50\"> <input type=\"hidden\" name=\"offset\" value=\"0\"></form></div></div></body></html>")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}

templates/library_switcher.templ

@@ -15,7 +15,13 @@ templ LibrarySwitcher(libData []LibraryData, currentLibraryID string, actions ..
 				>
 				<option value="">All Libraries ({ TotalMediaCount(libData) })</option>
 				for _, lib := range libData {
+					if lib.Offline {
 						if lib.ID == currentLibraryID {
+							<option value={ lib.ID } selected>{ lib.Name } ({ lib.MediaCount }) — storage offline</option>
+						} else {
+							<option value={ lib.ID }>{ lib.Name } ({ lib.MediaCount }) — storage offline</option>
+						}
+					} else if lib.ID == currentLibraryID {
 						<option value={ lib.ID } selected>{ lib.Name } ({ lib.MediaCount })</option>
 					} else {
 						<option value={ lib.ID }>{ lib.Name } ({ lib.MediaCount })</option>

templates/library_switcher_templ.go

@@ -36,7 +36,7 @@ func LibrarySwitcher(libData []LibraryData, currentLibraryID string, actions ...
 		var templ_7745c5c3_Var2 string
 		templ_7745c5c3_Var2, templ_7745c5c3_Err = templ.JoinStringErrs(TotalMediaCount(libData))
 		if templ_7745c5c3_Err != nil {
-			return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 16, Col: 63}
+			return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 16, Col: 62}
 		}
 		_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var2))
 		if templ_7745c5c3_Err != nil {
@@ -47,6 +47,7 @@ func LibrarySwitcher(libData []LibraryData, currentLibraryID string, actions ...
 			return templ_7745c5c3_Err
 		}
 		for _, lib := range libData {
+			if lib.Offline {
 				if lib.ID == currentLibraryID {
 					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 3, "<option value=\"")
 					if templ_7745c5c3_Err != nil {
@@ -55,7 +56,7 @@ func LibrarySwitcher(libData []LibraryData, currentLibraryID string, actions ...
 					var templ_7745c5c3_Var3 string
 					templ_7745c5c3_Var3, templ_7745c5c3_Err = templ.ResolveAttributeValue(lib.ID)
 					if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 19, Col: 29}
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 20, Col: 29}
 					}
 					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var3)
 					if templ_7745c5c3_Err != nil {
@@ -68,7 +69,7 @@ func LibrarySwitcher(libData []LibraryData, currentLibraryID string, actions ...
 					var templ_7745c5c3_Var4 string
 					templ_7745c5c3_Var4, templ_7745c5c3_Err = templ.JoinStringErrs(lib.Name)
 					if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 19, Col: 51}
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 20, Col: 51}
 					}
 					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var4))
 					if templ_7745c5c3_Err != nil {
@@ -81,13 +82,13 @@ func LibrarySwitcher(libData []LibraryData, currentLibraryID string, actions ...
 					var templ_7745c5c3_Var5 string
 					templ_7745c5c3_Var5, templ_7745c5c3_Err = templ.JoinStringErrs(lib.MediaCount)
 					if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 19, Col: 71}
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 20, Col: 71}
 					}
 					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var5))
 					if templ_7745c5c3_Err != nil {
 						return templ_7745c5c3_Err
 					}
-				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 6, ")</option>")
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 6, ") — storage offline</option>")
 					if templ_7745c5c3_Err != nil {
 						return templ_7745c5c3_Err
 					}
@@ -99,7 +100,7 @@ func LibrarySwitcher(libData []LibraryData, currentLibraryID string, actions ...
 					var templ_7745c5c3_Var6 string
 					templ_7745c5c3_Var6, templ_7745c5c3_Err = templ.ResolveAttributeValue(lib.ID)
 					if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 21, Col: 29}
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 22, Col: 29}
 					}
 					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var6)
 					if templ_7745c5c3_Err != nil {
@@ -112,7 +113,7 @@ func LibrarySwitcher(libData []LibraryData, currentLibraryID string, actions ...
 					var templ_7745c5c3_Var7 string
 					templ_7745c5c3_Var7, templ_7745c5c3_Err = templ.JoinStringErrs(lib.Name)
 					if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 21, Col: 42}
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 22, Col: 42}
 					}
 					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var7))
 					if templ_7745c5c3_Err != nil {
@@ -125,24 +126,113 @@ func LibrarySwitcher(libData []LibraryData, currentLibraryID string, actions ...
 					var templ_7745c5c3_Var8 string
 					templ_7745c5c3_Var8, templ_7745c5c3_Err = templ.JoinStringErrs(lib.MediaCount)
 					if templ_7745c5c3_Err != nil {
-					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 21, Col: 62}
+						return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 22, Col: 62}
 					}
 					_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var8))
 					if templ_7745c5c3_Err != nil {
 						return templ_7745c5c3_Err
 					}
-				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 10, ")</option>")
+					templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 10, ") — storage offline</option>")
+					if templ_7745c5c3_Err != nil {
+						return templ_7745c5c3_Err
+					}
+				}
+			} else if lib.ID == currentLibraryID {
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 11, "<option value=\"")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var9 string
+				templ_7745c5c3_Var9, templ_7745c5c3_Err = templ.ResolveAttributeValue(lib.ID)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 25, Col: 28}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var9)
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 12, "\" selected>")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var10 string
+				templ_7745c5c3_Var10, templ_7745c5c3_Err = templ.JoinStringErrs(lib.Name)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 25, Col: 50}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var10))
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 13, " (")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var11 string
+				templ_7745c5c3_Var11, templ_7745c5c3_Err = templ.JoinStringErrs(lib.MediaCount)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 25, Col: 70}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var11))
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 14, ")</option>")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+			} else {
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 15, "<option value=\"")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var12 string
+				templ_7745c5c3_Var12, templ_7745c5c3_Err = templ.ResolveAttributeValue(lib.ID)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 27, Col: 28}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ_7745c5c3_Var12)
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 16, "\">")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var13 string
+				templ_7745c5c3_Var13, templ_7745c5c3_Err = templ.JoinStringErrs(lib.Name)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 27, Col: 41}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var13))
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 17, " (")
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				var templ_7745c5c3_Var14 string
+				templ_7745c5c3_Var14, templ_7745c5c3_Err = templ.JoinStringErrs(lib.MediaCount)
+				if templ_7745c5c3_Err != nil {
+					return templ.Error{Err: templ_7745c5c3_Err, FileName: `templates/library_switcher.templ`, Line: 27, Col: 61}
+				}
+				_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var14))
+				if templ_7745c5c3_Err != nil {
+					return templ_7745c5c3_Err
+				}
+				templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 18, ")</option>")
 				if templ_7745c5c3_Err != nil {
 					return templ_7745c5c3_Err
 				}
 			}
 		}
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 11, "</select></div>")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 19, "</select></div>")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
 		if len(actions) > 0 {
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 12, "<div class=\"flex items-center gap-2\">")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 20, "<div class=\"flex items-center gap-2\">")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
@@ -152,12 +242,12 @@ func LibrarySwitcher(libData []LibraryData, currentLibraryID string, actions ...
 					return templ_7745c5c3_Err
 				}
 			}
-			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 13, "</div>")
+			templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 21, "</div>")
 			if templ_7745c5c3_Err != nil {
 				return templ_7745c5c3_Err
 			}
 		}
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 14, "</div><div id=\"loading-spinner\" class=\"hidden fixed inset-0 bg-opacity-50 flex items-center justify-center z-50\" style=\"background-color: var(--bg-primary);\"><div class=\"animate-spin rounded-full h-12 w-12 border-b-2\" style=\"border-color: var(--accent);\"></div></div></div>")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 22, "</div><div id=\"loading-spinner\" class=\"hidden fixed inset-0 bg-opacity-50 flex items-center justify-center z-50\" style=\"background-color: var(--bg-primary);\"><div class=\"animate-spin rounded-full h-12 w-12 border-b-2\" style=\"border-color: var(--accent);\"></div></div></div>")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
@@ -181,12 +271,12 @@ func DashboardActions() templ.Component {
 			}()
 		}
 		ctx = templ.InitializeContext(ctx)
-		templ_7745c5c3_Var9 := templ.GetChildren(ctx)
+		templ_7745c5c3_Var15 := templ.GetChildren(ctx)
-		if templ_7745c5c3_Var9 == nil {
+		if templ_7745c5c3_Var15 == nil {
-			templ_7745c5c3_Var9 = templ.NopComponent
+			templ_7745c5c3_Var15 = templ.NopComponent
 		}
 		ctx = templ.ClearChildren(ctx)
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 15, "<button data-action=\"open-dashboard-settings\" class=\"icon-btn\" title=\"Customize Dashboard\">")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 23, "<button data-action=\"open-dashboard-settings\" class=\"icon-btn\" title=\"Customize Dashboard\">")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
@@ -194,7 +284,7 @@ func DashboardActions() templ.Component {
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 16, "</button> <button data-action=\"reload-page\" class=\"icon-btn\" title=\"Refresh\">")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 24, "</button> <button data-action=\"reload-page\" class=\"icon-btn\" title=\"Refresh\">")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
@@ -202,7 +292,7 @@ func DashboardActions() templ.Component {
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 17, "</button>")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 25, "</button>")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}

templates/types.go

@@ -41,12 +41,30 @@ type LibraryData struct {
 	TypeValue   string
 	MediaCount  int64
 	FolderCount int
+	// Offline is true when none of the library's folders exist on disk
+	// (e.g. an unmounted external drive). Contents stay intact and reappear
+	// when the storage returns.
+	Offline bool
 }
 
 type FolderData struct {
 	FolderPath string
 }
 
+// ArchivedItem feeds the admin archived-items page: media hidden from
+// libraries because their files vanished, with their pending fate.
+type ArchivedItem struct {
+	ID           string
+	Title        string
+	Author       string
+	LibraryName  string
+	FilePath     string
+	MissingScans int32
+	ArchivedAt   *time.Time
+	PurgeAt      *time.Time
+	Status       string
+}
+
 type DirEntry struct {
 	Name string
 	Path string

templates/utils.go

@@ -65,6 +65,12 @@ func isUserVisible(userID string, visibility []UserVisibilityData) bool {
 func TotalMediaCount(libs []LibraryData) int64 {
 	var total int64
 	for _, l := range libs {
+		// Unmounted storage contributes nothing visible: an offline
+		// library's holdings stay in the database but out of the UI
+		// until its folders return.
+		if l.Offline {
+			continue
+		}
 		total += l.MediaCount
 	}
 	return total

web/src/admin.ts

@@ -249,6 +249,107 @@ function stopScanStatusPolling(): void {
   }
 }
 
+// Purge all archived items (files missing from disk for 2+ scans). Exposed on
+// window for the library admin page's inline button; reading history is
+// deleted with the rows, so a confirm dialog guards it.
+async function purgeArchivedItems(): Promise<void> {
+  const token = localStorage.getItem("token");
+  if (!token) return;
+
+  if (
+    !window.confirm(
+      "Permanently delete all archived items? Their reading progress, notes, and highlights will be lost.",
+    )
+  ) {
+    return;
+  }
+
+  try {
+    const resp = await fetch("/api/media-items/purge-archived", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({}));
+      throw new Error(err.error || "Failed to purge archived items");
+    }
+    const data = await resp.json();
+    showToast(
+      `Purged ${data.purged} archived item${data.purged === 1 ? "" : "s"}`,
+      "success",
+    );
+    setTimeout(() => window.location.reload(), 700);
+  } catch (e) {
+    showToast(
+      e instanceof Error ? e.message : "Failed to purge archived items",
+      "error",
+    );
+  }
+}
+
+(window as any).purgeArchivedItems = purgeArchivedItems;
+
+// Restore a hidden/archived item to library visibility without waiting for
+// its file to return (POST /api/media-items/:id/unarchive). If the file is
+// still gone the next scan hides it again.
+async function unarchiveItem(id: string): Promise<void> {
+  const token = localStorage.getItem("token");
+  if (!token) return;
+  try {
+    const resp = await fetch(`/api/media-items/${id}/unarchive`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({}));
+      throw new Error(err.error || "Failed to restore item");
+    }
+    showToast("Item restored to libraries", "success");
+    setTimeout(() => window.location.reload(), 500);
+  } catch (e) {
+    showToast(e instanceof Error ? e.message : "Failed to restore item", "error");
+  }
+}
+
+// Permanently delete one archived item and its reading history
+// (DELETE /api/media-items/:id).
+async function deleteArchivedItem(id: string): Promise<void> {
+  const token = localStorage.getItem("token");
+  if (!token) return;
+  if (
+    !window.confirm(
+      "Permanently delete this item? Its reading progress, notes, and highlights will be lost.",
+    )
+  ) {
+    return;
+  }
+  try {
+    const resp = await fetch(`/api/media-items/${id}`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({}));
+      throw new Error(err.error || "Failed to delete item");
+    }
+    showToast("Item deleted", "success");
+    setTimeout(() => window.location.reload(), 500);
+  } catch (e) {
+    showToast(e instanceof Error ? e.message : "Failed to delete item", "error");
+  }
+}
+
+// The archived-items page renders per-row buttons with data attributes
+// (escaping-safe); bind them here. Module scripts run after DOM parse.
+document.querySelectorAll<HTMLElement>("[data-unarchive]").forEach((el) => {
+  el.addEventListener("click", () => unarchiveItem(el.dataset.unarchive || ""));
+});
+document.querySelectorAll<HTMLElement>("[data-delete-archived]").forEach((el) => {
+  el.addEventListener("click", () =>
+    deleteArchivedItem(el.dataset.deleteArchived || ""),
+  );
+});
+
 export {
   hideScanProgress,
   loadWatchStatus,