Revert "fix(bookmarks): upsert on title conflict so position upgrades don't 500"

This reverts commit 27b3dcb69f.

database/schema/schema.sql

@@ -335,8 +335,8 @@ CREATE TABLE IF NOT EXISTS media_highlights (
     media_item_id UUID NOT NULL REFERENCES media_items(id) ON DELETE CASCADE,
     user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
     selection_text TEXT NOT NULL,
-    start_position VARCHAR(100), -- position (page:offset or CFI) where highlight starts
+    start_position TEXT, -- position (page:offset, CFI, or locator JSON) where highlight starts
-    end_position VARCHAR(100),   -- position (page:offset or CFI) where highlight ends
+    end_position TEXT,   -- position (page:offset, CFI, or locator JSON) where highlight ends
     color VARCHAR(7) DEFAULT '#ffff00', -- hex color code for highlight
     note_id UUID REFERENCES media_notes(id) ON DELETE SET NULL, -- optional associated note
     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
@@ -1364,6 +1364,13 @@ ALTER TABLE media_highlights ADD COLUMN IF NOT EXISTS note_text TEXT;
 ALTER TABLE media_highlights ADD COLUMN IF NOT EXISTS deleted BOOLEAN DEFAULT FALSE;
 ALTER TABLE media_highlights ADD COLUMN IF NOT EXISTS deleted_at TIMESTAMPTZ;
 
+-- Widen position columns for existing databases: the API handlers
+-- validate up to 1000 characters (full Readium locators, KOReader CRE
+-- xpointers) but VARCHAR(100) rejected anything longer at the database
+-- layer. VARCHAR -> TEXT is a metadata-only change, safe to re-run.
+ALTER TABLE media_highlights ALTER COLUMN start_position TYPE TEXT;
+ALTER TABLE media_highlights ALTER COLUMN end_position TYPE TEXT;
+
 ALTER TABLE media_notes ADD COLUMN IF NOT EXISTS dedup_key VARCHAR(40);
 ALTER TABLE media_notes ADD COLUMN IF NOT EXISTS last_modified_at TIMESTAMPTZ;
 ALTER TABLE media_notes ADD COLUMN IF NOT EXISTS last_modified_source VARCHAR(30);

docs/developer/android-app.md

@@ -96,6 +96,18 @@ Planned reading features:
 - Zoom and pan; aggressive preloading of adjacent pages
 - Webtoon / continuous vertical mode: post-v1
 
+### Reader settings parity with the web reader
+
+The web reader (`web/src/reader/`) is the reference implementation for reading ergonomics — its font selection, reading themes, and highlight system are considered well-designed; only its desktop-oriented presentation is being replaced on mobile. The Android reader should reuse the same settings model (stored in the `reader_settings` table and synced via the settings endpoint) rather than inventing a parallel one:
+
+- **Fonts**: the same roster of variable fonts, self-hosted under `/static/fonts/` — Literata (default), Crimson Pro, Source Serif 4, EB Garamond, Libertinus Serif, Noto Serif, Charis SIL, IBM Plex Serif (`FONT_MAP` in `web/src/reader/reader.ts`)
+- **Typography**: `font_size` (default 18), `line_height` (1.6), `margin_width`, `double_page_spread`
+- **Themes**: `chrome_theme` (default `tokyo-night`) for app chrome vs `reading_theme`/`reading_mode` for the page surface, plus the fx stack (`fx_brightness`, `fx_contrast`, `fx_invert`)
+- **Navigation**: `tap_zones_enabled` + `tap_zone_size`, `reading_direction`, `progress_mode`
+- **Highlights**: per-annotation color (default `#ffd54f`), matching the web palette
+
+Settings chosen on one device should follow the user everywhere — mobile changes write back through the same sync.
+
 ---
 
 ## 🍎 iOS Posture

docs/developer/api/api-reference.md

@@ -89,7 +89,7 @@ See [Media Item Operations](media-items/)
 - GET /api/media-items/:id - Get media item details
 - POST /api/media-items/bulk-delete - Bulk delete media items
 - POST /api/media-items/bulk-update - Bulk update media items (tags/contributors with normalization)
-- GET /api/media-items/:uuid/download - Download media item file
+- GET /uploads/library-{library_id}/{file_path} - Download book file / cover (JWT; see [Download Media Item](media-items/download_media_item.md))
 - POST /api/media-items/:id/rating - Create rating
 - GET /api/media-items/:id/rating - Get rating
 - PUT /api/media-items/:id/rating - Update rating

docs/developer/api/media-items/download_media_item.md

@@ -2,15 +2,19 @@
 
 Download a media item file (EPUB, PDF, etc.) from the Bookhoard server.
 
-**Endpoint**: `GET /api/media-items/:uuid/download`
+Book files are served by the authenticated file route, the same one the web reader uses. Build the URL from the media item's `library_id` and relative `file_path` (both returned by the media item list/get endpoints):
-**Auth**: None (public endpoint for Kobo devices)
+
-**Content-Type**: Binary file download
+**Endpoint**: `GET /uploads/library-{library_id}/{file_path}`
+**Auth**: Required (JWT - Bearer header or session cookie)
+
+The `file_path` segments are URL-escaped individually; slashes are preserved. `cover_image_path` uses the same route.
 
 ## Path Parameters
 
-| Parameter | Type   | Required | Description     |
+| Parameter   | Type   | Required | Description                          |
-| --------- | ------ | -------- | --------------- |
+| ----------- | ------ | -------- | ------------------------------------ |
-| uuid      | string | Yes      | Media item UUID |
+| library_id  | string | Yes      | Library UUID (the item's library)    |
+| file_path   | string | Yes      | The item's relative `file_path`      |
 
 ## Response
 
@@ -18,25 +22,27 @@ Download a media item file (EPUB, PDF, etc.) from the Bookhoard server.
 
 **Response Headers**:
 
-- `Content-Type`: `application/epub+zip`, `application/pdf`, or appropriate MIME type
+- `Content-Type`: MIME type by file extension (`application/epub+zip`, `application/pdf`, …; `application/octet-stream` fallback)
-- `Content-Disposition`: `attachment; filename="filename.epub"`
+- `Cache-Control`: `public, max-age=86400`
 
 ## Error Responses
 
-| Code | Description                       |
+| Code | Description                 |
-| ---- | --------------------------------- |
+| ---- | --------------------------- |
-| 404  | Media item not found              |
+| 400  | Invalid library ID or path  |
-| 500  | Server error during file download |
+| 401  | Missing/invalid token       |
+| 404  | File not found on disk      |
 
 ## Example
 
 ```bash
-curl -O http://localhost:8765/api/media-items/550e8400-e29b-41d4-a716-446655440000/download
+curl -O -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:8765/uploads/library/550e8400-.../books/1984.epub"
 ```
 
+(URL shape: `/uploads/library-{uuid}/{escaped-relative-path}`.)
+
 ## Notes
 
-- **Public endpoint**: No authentication required for Kobo device downloads
+- **Do not rely on `GET /api/media-items/:id/download`** — it appears in older docs but is **not registered**; `MediaHandler.DownloadBook` exists as dead code. Use the file route above.
-- **File format**: Returns the original file format (EPUB, PDF, etc.)
+- OPDS-capable devices may alternatively use the device-authenticated `GET /opds/devices/{deviceId}/download/{bookId}`, which supports on-the-fly format conversion (epub, kepub, pdf, cbz).
-- **Kobo integration**: Designed for direct downloads from Kobo e-readers
-- **Cover images**: Use `/api/media-items/:uuid/cover` for cover images

internal/handlers/media.go

@@ -11,7 +11,6 @@ import (
 	"fmt"
 	"io"
 	"log"
-	"mime"
 	"mime/multipart"
 	"net/http"
 	"net/url"
@@ -191,55 +190,6 @@ func (mh *MediaHandler) SetAnnotationService(svc *wsync.AnnotationService) {
 	mh.annotationSvc = svc
 }
 
-func (h *MediaHandler) DownloadBook(c *echo.Context) error {
-	bookUUID, err := uuid.Parse(c.Param("uuid"))
-	if err != nil {
-		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid book UUID"})
-	}
-
-	pgBookUUID := pgtype.UUID{Bytes: bookUUID, Valid: true}
-
-	mediaItem, err := h.db.GetMediaItem(c.Request().Context(), pgBookUUID)
-	if err != nil {
-		return c.JSON(http.StatusNotFound, map[string]string{"error": "book not found"})
-	}
-
-	// Resolve relative path to absolute filesystem path
-	fullPath, err := h.getFullFilePath(c.Request().Context(), mediaItem.LibraryID, mediaItem.FilePath)
-	if err != nil {
-		return c.JSON(http.StatusNotFound, map[string]string{"error": "book file not found on disk"})
-	}
-
-	if _, err := os.Stat(fullPath); os.IsNotExist(err) {
-		return c.JSON(http.StatusNotFound, map[string]string{"error": "book file not found on disk"})
-	}
-
-	file, err := os.Open(fullPath)
-	if err != nil {
-		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to open book file"})
-	}
-	defer file.Close()
-
-	mimeType := mediaItem.MimeType.String
-	if !mediaItem.MimeType.Valid || mimeType == "" {
-		mimeType = mime.TypeByExtension(filepath.Ext(mediaItem.FilePath))
-	}
-
-	c.Response().Header().Set("Content-Type", mimeType)
-	c.Response().Header().Set("Content-Disposition", "attachment; filename=\""+filepath.Base(mediaItem.FilePath)+"\"")
-
-	if mediaItem.FileSize.Valid && mediaItem.FileSize.Int64 > 0 {
-		c.Response().Header().Set("Content-Length", strconv.FormatInt(mediaItem.FileSize.Int64, 10))
-	}
-
-	_, err = io.Copy(c.Response(), file)
-	if err != nil {
-		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to stream file"})
-	}
-
-	return nil
-}
-
 // ExecuteSearch performs search and returns results with count
 // Public wrapper for shared search logic used by both JSON and HTML endpoints
 func (h *MediaHandler) ExecuteSearch(ctx context.Context, params services.SearchParams) ([]database.SearchMediaItemsUnifiedRow, int, error) {
@@ -2073,30 +2023,86 @@ func (mh *MediaHandler) getFullFilePath(ctx context.Context, libraryID pgtype.UU
 	return mh.libraryService.ResolveMediaPath(ctx, libraryID, relativePath)
 }
 
-// ServeFile serves files (covers or books) via /uploads/library-{id}/path
+// ServeFile serves stored library files (covers and books).
-// Requires JWT authentication
+//
+// Two URL forms funnel into this handler:
+//
+//	/uploads/library-{libraryID}/{relativePath}   (covers, reader files)
+//	/api/media-items/{mediaItemID}/download       (explicit book download)
+//
+// Both require JWT authentication and that the authenticated user can see
+// the library owning the file - library visibility is the permission gate.
 func (mh *MediaHandler) ServeFile(c *echo.Context) error {
-	// URL format: /uploads/library-{libraryID}/{relativePath}
+	var libraryUUID pgtype.UUID
-	// Get library ID directly from route parameter
+	var relativePath string
-	libraryIDStr := c.Param("id")
-	libraryUUID, err := uuid.Parse(libraryIDStr)
-	if err != nil {
-		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid library ID"})
-	}
 
-	// Get remaining path from URL
 	rawPath := c.Param("*")
-	relativePath, err := url.QueryUnescape(rawPath)
+	if rawPath != "" {
-	if err != nil {
+		// Path form: /uploads/library-{libraryID}/{relativePath}
-		relativePath = rawPath
+		libraryIDStr := c.Param("id")
+		parsed, err := uuid.Parse(libraryIDStr)
+		if err != nil {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid library ID"})
+		}
+		libraryUUID = pgtype.UUID{Bytes: parsed, Valid: true}
+
+		relativePath, err = url.QueryUnescape(rawPath)
+		if err != nil {
+			relativePath = rawPath
+		}
+
+		if relativePath == "" {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid path"})
+		}
+	} else {
+		// Item form: /api/media-items/{mediaItemID}/download
+		itemUUID, err := uuid.Parse(c.Param("id"))
+		if err != nil {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid media item ID"})
+		}
+
+		mediaItem, err := mh.db.GetMediaItem(c.Request().Context(), pgtype.UUID{Bytes: itemUUID, Valid: true})
+		if err != nil {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": "book not found"})
+		}
+
+		if !mediaItem.LibraryID.Valid || mediaItem.FilePath == "" {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": "book file not found"})
+		}
+
+		libraryUUID = mediaItem.LibraryID
+		relativePath = mediaItem.FilePath
+
+		// Explicit download endpoint: suggest saving instead of inline display.
+		filename := strings.Map(func(r rune) rune {
+			if r == '"' || r == '\\' || r == '/' {
+				return -1
+			}
+			return r
+		}, filepath.Base(relativePath))
+		c.Response().Header().Set("Content-Disposition", `attachment; filename="`+filename+`"`)
 	}
 
-	if relativePath == "" {
+	// Library visibility gate: the library is what grants permission to
-		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid path"})
+	// see and download media.
+	user := c.Get("user").(database.Users)
+	visibleLibraries, err := mh.libraryService.GetUserVisibleLibraries(c.Request().Context(), user.ID)
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to check library access"})
+	}
+	libraryVisible := false
+	for _, lib := range visibleLibraries {
+		if lib.ID.Valid && lib.ID.Bytes == libraryUUID.Bytes {
+			libraryVisible = true
+			break
+		}
+	}
+	if !libraryVisible {
+		return c.JSON(http.StatusForbidden, map[string]string{"error": "library not accessible"})
 	}
 
 	// Resolve using service
-	fullPath, err := mh.getFullFilePath(c.Request().Context(), pgtype.UUID{Bytes: libraryUUID, Valid: true}, relativePath)
+	fullPath, err := mh.getFullFilePath(c.Request().Context(), libraryUUID, relativePath)
 	if err != nil {
 		return c.JSON(http.StatusNotFound, map[string]string{"error": "file not found"})
 	}

internal/router/media.go

@@ -15,6 +15,9 @@ func registerMediaRoutes(cfg *Config) {
 	// Media item routes (all authenticated users)
 	protected.GET("/media-items", cfg.MediaHandler.ListMediaItems)
 	protected.GET("/media-items/:id", cfg.MediaHandler.GetMediaItem)
+	// Book download endpoint - same ServeFile flow as /uploads/library-:id/*
+	// (JWT + library-visibility gated), addressed by media item ID.
+	protected.GET("/media-items/:id/download", cfg.MediaHandler.ServeFile)
 
 	// Media rating routes (all authenticated users)
 	protected.POST("/media-items/:id/rating", cfg.MediaHandler.CreateMediaRating)