mangaBookmark/plans/2026-07-25-bookmark-list-favorites-design.md

Bookmark list ordering, latest-chapter display, and favorites

Date: 2026-07-25 Status: Approved by user, pending implementation plan

Context

Three requested additions to the Bromite userscript's bookmark panel (userscript/manga-bookmark.user.js) plus one incidental bug found while verifying feasibility live:

1. Bookmark list should show the most-recently-read manga first.
2. Show not just the last chapter read, but the latest chapter available for that manga, if feasible.
3. A favorites mechanism: a second list/tab showing only favorited manga, without removing favorited manga from the normal list.

1. Reorder by latest read (already implemented)

reindex() in manga-bookmark.user.js has sorted state.list by (b.updated_at || 0) descending since the very first commit (f58d113). updated_at is set whenever progress is recorded (bookmarkCurrent, updateToCurrentChapter, setChapterManual). No code change needed here — confirmed by decision: only an actual progress advance should reorder the list (not simply opening/re-reading an old chapter).

The only risk to this existing behavior is introduced by features 2 and 3 below, since both add new fields synced through the same PUT endpoint that currently (per existing CLAUDE.md) has the server set updated_at unconditionally on every upsert. See section 4.

2. Latest available chapter

Feasibility (verified live via Playwright, 2026-07-25)

• Chapter reader pages only expose immediate neighbors. On asurascans.com/comics/dungeon-odyssey-f886a8af/chapter/160, the DOM contains only chapters 159–161 (prev/next nav) — not the full list.
• Series pages list every chapter, newest first by default. On asurascans.com/comics/dungeon-odyssey-f886a8af, the series page's chapter list panel contains one <a href=".../chapter/N">Chapter N ...</a> per chapter (verified: 162 links for a 162-chapter series, first is Chapter 162). This is therefore the only reliable place to learn the true latest chapter number.
• Demonic's series page (demonicscans.org/manga/Dungeon-Odyssey) similarly lists every chapter via chaptered.php?manga=<id>&chapter=<n> links, interleaved with a "first chapter" quick-jump link. Taking max() of all parsed chapter numbers (rather than assuming list order) is used for robustness on this site.

Conclusion: latest-available-chapter data can only be refreshed when the user visits a bookmarked series' series page (not on every chapter open). This is a real, disclosed limitation — not solved by polling, since the backend cannot fetch these sites itself (Cloudflare blocks server-side fetch, per existing CLAUDE.md constraint) and there is no reader-page source for it.

Behavior

• New adapter capability: on detect() returning type: "series" for an already-bookmarked series (state.byKey[key] exists), scan the page for chapter links per the site-specific pattern below and compute the max chapter number + its display label.
  • Asura: a[href*="/chapter/"] where the href matches /chapter/([\d.]+)$/ and the link text matches /Chapter\s+[\d.]+/ (excludes the unrelated "First Chapter" quick-jump button, which lacks that text pattern).
  • Demonic: all a[href] matching /chaptered\.php\?manga=\d+&chapter=([\d.]+)/; take the max parsed chapter number across all matches (list order is not assumed reliable).
• If the computed max differs from the bookmark's stored latest_chapter_num, silently update latest_chapter (label) and latest_chapter_num via the API — but this update must not change updated_at / list order (see section 4).
• Display: each list item's subtitle line becomes e.g. "Read: Chapter 12 · Latest: Chapter 15" when latest is known and differs from last-read; otherwise unchanged ("Chapter 12 · asura" as today). Plain inline text, no separate badge/count UI.

3. Favorites

• New field favorite: bool on the bookmark record, synced through the existing PUT endpoint (chosen over local-only storage so favorites persist across devices/reinstalls, consistent with how the rest of the data syncs).
• Each list item gets a star toggle (☆ / ★) that flips favorite and PUTs the updated bookmark. Toggling must not change updated_at / list order (see section 4).
• The panel gains two tabs above the bookmark list: All and ★ Favorites. Both apply the same sort (section 1). Switching tabs is local UI state (not persisted) defaulting to "All". A favorited manga continues to appear in "All" — tabs only filter which array is rendered, favoriting never removes the bookmark from state.list.

4. Backend change required: conditional updated_at

Current CLAUDE.md / store.go behavior: PUT /bookmarks/{key} always sets updated_at server-side on every upsert. Once latest-chapter-capture and favorite-toggle both PUT through that same endpoint, this would reorder the list on every series-page visit or star click — contradicting the "reorder only on progress advance" decision from section 1.

Change: Store.Upsert sets updated_at = now() only when:

• the bookmark is new (no existing row for that key), or
• last_chapter_num in the incoming payload differs from the currently stored value.

Otherwise the existing stored updated_at is preserved, even though other fields (favorite, latest_chapter, latest_chapter_num, cover, title, etc.) are still updated. This centralizes "what counts as a progress advance" as a single authoritative rule in the backend, applied consistently regardless of which device/browser performed the write.

This is a deliberate deviation from the current CLAUDE.md wording ("server sets updated_at" unconditionally) and needs the doc updated to match.

5. Asura redirect bug (bundled into this work)

Verified live: https://asuracomic.net/comics/dungeon-odyssey-f886a8af returns an HTTP 301 with Location: https://asurascans.com/ (root, no path) — a Cloudflare-edge redirect that discards the path before any JS on asuracomic.net executes. This contradicts the existing code comment ("asuracomic.net currently 301s to asurascans.com", implying path preservation) and means any deep link on asuracomic.net currently lands the user on the asurascans.com homepage with page type "other" — bookmark/progress detection silently does nothing.

There is no client-side fix: the userscript's @match for asuracomic.net/* never gets a chance to run for these URLs, since the redirect happens at the edge before the browser has a document to inject into. Fix is documentation-only: correct the misleading comment in asura.matches()/adapter notes and README to state that asuracomic.net deep links are currently broken, and the user should navigate via asurascans.com links directly. No behavior change to ship.

Data model summary

Bookmark (backend store.go) gains:

field	type	notes
favorite	bool	default false
latest_chapter	string	display label, e.g. "Chapter 162"; empty if never captured
latest_chapter_num	*float64	nullable; null if never captured

SQLite migration: additive ALTER TABLE bookmarks ADD COLUMN ... for each, guarded against "duplicate column" errors so it's safe to run against the already-deployed database.

Testing

• Go: table-driven tests for Store.Upsert's conditional updated_at logic (new bookmark, unchanged progress, changed progress, favorite-only change, latest-chapter-only change).
• Userscript: manual on-device verification (per existing project convention — no JS test harness in this repo). Verify:
  • list reorders only when a chapter is actually advanced, not on plain re-visit or favorite toggle.
  • latest-chapter capture fires on series-page visits and displays correctly for both sites.
  • favorite toggle persists across a panel close/reopen and a refresh() (i.e. round-trips through the backend correctly).
  • favorited manga still appears in "All" tab.