cloud-reader/docs/frontend/015-epub-bookmarks-notes.md

015 — EPUB bookmarks and notes (physical-book UX)

Status: Implemented
Created: 2026-06-04

Objective

Let users select passage text while reading an EPUB, save a bookmark (with optional thought), list markers in chapter order, and jump back to the exact location. Global view groups markers by book in a Reddit-style thread layout.

Fix: AnnotationsProvider

AnnotationsProvider wraps all routes in App.tsx so /bookmarks-notes and the reader can use useAnnotations().

Data model

Bookmark (annotations app) references books.EBook, not catalog Book:

Field	Purpose
ebook	FK to uploaded ebook
epub_cfi	EPUB CFI anchor
chapter_index	Spine index for sort order
chapter_title	Display label
location_text	Selected passage quote
content	Optional user thought (empty = bookmark only)
page	Legacy display field (chapter_index + 1)

Unique: (user, ebook, epub_cfi).

Default API ordering: chapter_index, epub_cfi.

Legacy Note model remains for old API; new UX uses Bookmark.content only.

Reader flow

sequenceDiagram
  participant User
  participant EpubView
  participant Popover
  participant API
  User->>EpubView: Select text
  EpubView->>Popover: Show near selection
  User->>Popover: Save optional thought
  Popover->>API: POST /annotations/bookmarks/

1. Text selection via epub.js selected event and content mouseup hook.
2. SelectionPopover — floating UI, optional textarea.
3. Toolbar bookmark icon opens BookMarkersPanel (current ebook only).
4. “Go to passage” sets reader location to stored CFI (/read/:id with router state).

Global page (/bookmarks-notes)

MarkerThreadsView:

• Groups markers by ebook (collapsible book rows).
• Within each book: chapter order, passage as blockquote, thought indented below (Reddit-style).
• Optional filter: /bookmarks-notes/:ebookId.

API

• GET /api/annotations/bookmarks/?ebook={id}
• POST /api/annotations/bookmarks/ — body: ebook, epub_cfi, chapter_index, chapter_title, location_text, content

i18n

New keys under annotations.* (EN/ES): saveMarker, thoughtPlaceholder, bookmarkOnly, selectTextHint, goToPassage, inBookPanel, markerCount, etc.

Verification

1. /bookmarks-notes loads without provider error.
2. Select text in reader → popover → save with/without thought.
3. Markers appear in reader panel and global page under correct book, in chapter order.
4. “Go to passage” opens the correct location.

See also 016 — Bookmark reading anchor for preserving reading position while peeking at bookmarks.

Out of scope

• PDF selection
• Multiple replies per passage
• Migrating legacy Note rows into Bookmark