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: capturing latest-available-chapter data requires fetching a series page's HTML (no reader-page source, no JSON API — see below). The backend cannot do this itself (Cloudflare blocks server-side fetch, per existing CLAUDE.md constraint), so it must happen from the userscript, running in the user's real browser session. Section "Background opportunistic refresh" below extends this beyond "only when you open that exact series page."

No stable API exists (checked live, 2026-07-25)

• The series page is server-rendered HTML (Next.js SSR) — network capture during a series-page load shows no _next/data JSON call and no XHR/fetch for chapter data (only unrelated api.asurascans.com calls for announcements/promotions banners). Chapter data is embedded directly in the HTML, not fetched separately.
• No RSS/feed exists: asurascans.com/feed, /rss, /rss.xml all 404.
• Conclusion: HTML scraping (DOM when live on the page, raw-text regex when background-fetched — see below) is the only available data source on either site. There is nothing more "API-like" to poll instead.

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.

Background opportunistic refresh (closer to "live")

Live-page capture above only refreshes a series when the user happens to open that exact series page. To reduce that gap without server-side polling (still blocked by Cloudflare — verified: server-side fetch is a datacenter request with no browser session, this is unchanged and not being revisited), the userscript also does same-origin background checks using the user's own real browser session:

• Same-origin only. fetch() issued from a page on asurascans.com can only safely reach other asurascans.com paths (no CORS trouble, looks like a normal authenticated browser request). It cannot reach demonicscans.org or vice versa. So visiting any page on a site opportunistically refreshes only that site's bookmarks — confirmed live that same-origin fetch() from an already-loaded page succeeds cleanly (tested against asurascans.com/sitemap.xml from a comics/* page).
• Trigger: on every page load, after init()/refresh(), run backgroundRefreshLatest(). It picks bookmarks belonging to the current site that haven't been checked within a throttle window (LATEST_CHECK_THROTTLE_MS, proposed 4 hours), oldest-checked-first, and checks at most LATEST_CHECK_BATCH of them (proposed 1) per page load — so a normal reading session gradually keeps bookmarks fresh without ever bursting requests.
• Freshness tracking is local-only, not synced: a small mangabm:lastchecked localStorage map of { [key]: timestampMs }. It's device-local by nature (each device does its own background checks) and keeping it out of the synced Bookmark record avoids polluting the cross-device schema with a per-device value.
• Fetch + parse: fetch(bookmark.series_url) → res.text() → apply the same regex rule already defined above (Asura: chapter-link href + "Chapter N" text; Demonic: max of all chaptered.php?...chapter= matches) against the raw HTML string instead of the live DOM. No additional parsing logic — this reuses the exact same rule, just fed fetched text instead of document.
• Update path: identical to live-page capture — PUT the bookmark with new latest_chapter/latest_chapter_num if changed, no updated_at bump (section 4).
• Failure handling: a failed/blocked background fetch is silently skipped (no toast, no retry loop) — next eligible page load tries again naturally once the throttle window passes.
• What this buys: instead of "only fresh if you opened that exact series page," bookmarks on a site you're actively reading converge to "checked within the last ~4 hours," which is meaningfully closer to live given frequent reading — without needing server-side scraping that Cloudflare would block anyway. It is still not push/instant; nothing can notify the moment a new chapter is posted without the site itself offering that (it doesn't — no RSS/webhooks, confirmed above).

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.

Userscript-local, not synced: mangabm:lastchecked localStorage key, a { [bookmarkKey]: timestampMs } map used only to throttle background refresh (see section 2).

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.
  • background refresh: check one stale same-site bookmark per page load, skips bookmarks checked within the throttle window, updates silently without reordering the list, and doesn't fire cross-site.
  • 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.