sulthan/mangaBookmark
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

chore: untrack plans and docs/superpowers dirs

Browse Source 
Keep local planning docs out of the repo; add to .gitignore.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Sulthan Zaki
2026-07-26 13:56:34 +07:00
parent ebc7a546c5
commit c601ef54d5
6 changed files with 2 additions and 3252 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+2
View File
@@ -5,3 +5,5 @@
backend/server
.playwright-mcp/
graphify-out/
plans/
docs/superpowers/
docs/superpowers/specs/2026-07-25-web-ui-design.md
-263
View File
@@ -1,263 +0,0 @@
# Web UI Design — browser-accessible bookmark list
Date: 2026-07-25
Branch: `feat/web-ui`
Status: approved
## 1. Problem
The bookmark list is reachable only from inside the userscript, which means it
exists only on pages of asurascans.com and demonicscans.org. There is no way to
open the list on its own — from a desktop, from a phone home screen, or when
neither manga site is loaded.
This adds a website, served by the existing Go backend, that renders the same
list with the same actions.
## 2. Scope
In scope:
- Password-gated website showing all bookmarks, ordered by `updated_at DESC`.
- All / Favourites tabs.
- A "Continue reading" strip of the five most recent series.
- Per-series actions: continue reading, toggle favourite, manually override the
read chapter, delete.
- Client-side title search.
Out of scope:
- A chapter-level reading-event log. The list order already answers "what did I
read last". A `reading_events` table is a separate future spec.
- Any change to `GET /bookmarks`, `PUT /bookmarks/{key}`,
`DELETE /bookmarks/{key}`, or to the userscript. Those stay exactly as they
are, so the website cannot regress phone reading.
- Offline support. The userscript keeps its `localStorage` cache; the website is
server-rendered and requires connectivity.
## 3. Architecture
One binary, one container, one SQLite file. The website is added to the running
service rather than deployed alongside it.
```
Bromite userscript ──bearer──> /bookmarks* ─┐
├─> Store ──> SQLite
Browser (phone/desktop) ──cookie──> / , /ui/*┘
```
New files under `backend/`:
| File | Purpose |
| --- | --- |
| `web.go` | Page and HTML-fragment handlers |
| `session.go` | Cookie signing/verification, login rate limit |
| `templates/*.html` | `go:embed`-ed templates |
| `static/*` | `go:embed`-ed `style.css`, `htmx.min.js`, `filter.js` |
Templates and static assets are embedded, so the image stays a single static
binary on distroless and `CGO_ENABLED=0` still holds.
### 3.1 Routes
| Route | Auth | Response |
| --- | --- | --- |
| `GET /` | session | List page; login page when no valid session |
| `POST /login` | none | Sets cookie, `303` to `/` |
| `POST /logout` | session | Clears cookie, `303` to `/` |
| `GET /static/{path...}` | none | Embedded asset, long-lived cache header |
| `GET /ui/list?tab=all\|fav` | session | List fragment |
| `POST /ui/bookmarks/{key}/favorite` | session | Re-rendered card |
| `POST /ui/bookmarks/{key}/chapter` | session | Re-rendered card |
| `DELETE /ui/bookmarks/{key}` | session | `200` with empty body |
`GET /` returns the login page with status `200` rather than redirecting to a
separate login URL. One page, no redirect loop to reason about.
`/ui/*` returns HTML fragments, not JSON, and is authenticated by cookie. It is
kept separate from `/bookmarks*` deliberately: that API is JSON, authenticated
by bearer token, and consumed by the userscript. Sharing one route for two
representations and two auth schemes would couple the website's needs to the
userscript's contract.
Middleware layering is unchanged at the top: `withCORS` stays outermost.
`/bookmarks*` keeps `withAuth` (bearer). `/` and `/ui/*` are wrapped in a new
`withSession`. Web routes are same-origin, so CORS is a no-op for them.
### 3.2 Store change
`Store` gains one method:
```go
func (s *Store) Get(key string) (Bookmark, bool, error)
```
Every UI mutation is read-modify-write: load the row, change the single field,
call the existing `Upsert`, then render the row `Upsert` returns. This reuses
the conditional-`updated_at` rule rather than reimplementing it — favouriting
does not reorder the list, a chapter override does. Rendering the returned row
(not the request payload) is the same contract `PUT /bookmarks/{key}` already
follows.
Not adding `Get` and instead patching columns directly would duplicate the
`updated_at` decision in a second place. That rule has already caused one bug;
it lives in exactly one function.
## 4. Session authentication
### 4.1 Configuration
New environment variable `WEB_PASSWORD`. When it is empty the web routes are not
registered at all and `/` returns `404`. Fail-closed: a deployment that forgets
the variable exposes nothing.
The password is stored in plaintext in `.env`, alongside `API_TOKEN`. This is a
single-user deployment with no user table, and anyone who can read `.env`
already holds the API token, so hashing it protects nothing that is not already
lost. `.env` is gitignored and the repository is private and self-hosted.
### 4.2 Cookie
Name `mangabm_session`. Value:
```
<expiry_unix_ms> "." base64url(HMAC-SHA256(<expiry_unix_ms>, key))
key = SHA256(API_TOKEN || 0x00 || WEB_PASSWORD || "mangabm-web-session-v1")
```
Stateless: no session table, sessions survive restarts, and rotating either
`API_TOKEN` or `WEB_PASSWORD` invalidates every session at once. Both secrets
are bound in so that changing the password actually logs existing browsers out;
the `0x00` separates the two variable-length secrets so no pair of different
inputs can concatenate to the same string.
Attributes: `HttpOnly`, `SameSite=Lax`, `Path=/`, `Max-Age` 60 days so the phone
stays logged in across long gaps. `Secure` is set when `r.TLS != nil` or
`X-Forwarded-Proto: https`, and omitted otherwise so `http://localhost`
development can still log in.
Verification order is fixed: split on `.`, parse the expiry, reject if it is in
the past, and only then `subtle.ConstantTimeCompare` the HMAC. Comparing before
validating the shape leaks structure through error timing.
The password comparison at login is also constant-time.
### 4.3 CSRF
All mutations are `POST` or `DELETE` and carry a `SameSite=Lax` cookie, which a
cross-site form post does not send. No separate CSRF token.
### 4.4 Login rate limit
In-memory, no persistence. Ten failed attempts within a rolling 20-minute window
for one client IP return `429` with a `Retry-After` header. Entries expire on
their own; there is no permanent ban and no unlock step. A successful login
clears that IP's counter.
Client IP is the **rightmost** entry of `X-Forwarded-For`. Traefik appends the
peer address it observed to whatever the client sent, so the leftmost entry is
attacker-controlled and the rightmost is not. `r.RemoteAddr` is unusable here —
behind Traefik it is always the proxy's container address, which would turn a
per-IP limit into a global one.
Known and accepted limitation: behind carrier-grade NAT the limit is shared with
every other subscriber on the same public address, so a stranger exhausting the
budget can lock the owner out for up to 20 minutes. The window self-heals and
ten attempts is generous for a mistyped password, so this is preferred over
removing the limit.
## 5. Interface
Mobile-first. Dark by default, honouring `prefers-color-scheme`. Tap targets at
least 44px. At viewports 900px and wider the card list becomes a 2–3 column
grid.
### 5.1 Login page
A centered card with a single password field (`type="password"`,
`autocomplete="current-password"`) and a submit button. Failed attempts render
an inline error. A rate-limited attempt renders how long to wait.
### 5.2 List page
```
┌──────────────────────────┐
│ mangaBookmark [logout]│
│ [ search… ] │
│ ( All ) ( Favourites ) │
├──────────────────────────┤
│ Continue reading │
│ [card][card][card] → │
├──────────────────────────┤
│ ┌────┬───────────────┐ │
│ │cvr │ Title ASURA│ │
│ │ │ Ch 45 · NEW 47│ │
│ │ │ [Continue]★✎🗑│ │
│ └────┴───────────────┘ │
└──────────────────────────┘
```
- The main list is ordered `updated_at DESC`. That ordering is the reading
history; no separate history view exists.
- "Continue reading" shows the top five of the same ordering in a horizontally
scrolling strip.
- A `NEW` badge appears when `latest_chapter_num` is present and greater than
`last_chapter_num`.
- **Continue** opens `last_chapter_url` in a new tab; it falls back to
`series_url` when no chapter URL is stored.
- The favourite control is an htmx `POST`; the swapped-in card shows the new
state. The list does not reorder.
- The chapter override expands an inline number input on the card. Submitting
forces `last_chapter` and `last_chapter_num` to the entered value, which does
move `updated_at` and therefore does reorder the list.
- Delete asks for confirmation, then htmx removes the card from the DOM.
- Search filters cards by title in the browser with roughly fifteen lines of
JavaScript. No request is made.
- The empty list renders a short message pointing at the userscript.
### 5.3 Tabs
Switching tabs issues `GET /ui/list?tab=…` and swaps the list container,
pushing the URL so the back button works. Favourites is the same list filtered
to `favorite = true`, in the same order.
## 6. Testing
`session_test.go`:
- A signed cookie round-trips and verifies.
- An expired cookie is rejected.
- A cookie with a tampered HMAC is rejected.
- A cookie with a tampered expiry is rejected.
- A correct password logs in; a wrong one does not.
- Ten failures trip the limiter; the eleventh attempt returns `429`.
- A successful login clears the counter.
- The rightmost `X-Forwarded-For` entry is the one keyed on.
`web_test.go`:
- `GET /` without a cookie returns `200` and the login page.
- `/ui/*` without a cookie returns `401`.
- `/ui/list` with a cookie returns the list fragment; `?tab=fav` returns only
favourites.
- Toggling favourite leaves `updated_at` unchanged.
- A chapter override changes `updated_at`.
- Deleting removes the row.
- With `WEB_PASSWORD` empty, `/` returns `404`.
Templates are parsed once at startup so a broken template fails the process
immediately rather than the first request.
## 7. Deployment
- `.env` and `.env.example` gain `WEB_PASSWORD`.
- `docker-compose.prod.yml` gains a second Traefik router label for
`manga.violetcrown.my.id` pointing at the same service on port 8080. Both
routers share one container; no second service, no second certificate
resolver.
- A DNS `A`/`AAAA` record for `manga.violetcrown.my.id`.
- `DEPLOY.md` gains a section covering the DNS record, the new variable, and
generating a password.
`ALLOWED_ORIGINS` is untouched. The website is same-origin and never triggers
CORS; only the userscript's cross-origin calls do.
plans/2026-07-25-bookmark-implementation-plan.md
-286
View File
@@ -1,286 +0,0 @@
# Implementation plan: bookmark reorder, latest-chapter tracking, favorites
## Context
Design already approved and committed at
`plans/2026-07-25-bookmark-list-favorites-design.md` on branch
`feat/bookmark-list-favorites-latest`. It covers three requested userscript
features plus one incidental bug found while verifying feasibility live via
Playwright:
1. Bookmark list reordered so the most-recently-progressed manga is first.
2. Show the latest *available* chapter for a manga, not just the last one
read — including a background same-origin refresh mechanism to get closer
to "live" without server-side polling (Cloudflare blocks that; confirmed
live, and confirmed no JSON API / RSS exists on either site to poll
instead).
3. A favorites mechanism (star toggle + tabs) that doesn't remove a manga
from the normal list.
4. `asuracomic.net` deep links now 301-redirect straight to the
`asurascans.com` homepage (path discarded) — a Cloudflare-edge redirect
confirmed live, with no client-side fix possible. Doc-only correction.
This plan turns that design into concrete code changes against the actual
current backend (Go/SQLite) and userscript, informed by full reads of
`backend/store.go`, `backend/handlers.go`, `backend/store_test.go`,
`backend/main.go`, and the full 782-line
`userscript/manga-bookmark.user.js`.
## Key design decision surfaced during planning
Today `handlers.go`'s `put()` echoes back the client's decoded request
struct as the API response, not what was actually persisted. Once
`updated_at` is sometimes *not* bumped (this whole feature's core mechanic),
echoing the request struct back would return a **wrong** `updated_at` to the
caller on every no-bump write — silently breaking the ordering guarantee the
entire feature depends on, since the userscript's `syncUpsert`/mutation
helpers adopt whatever the server echoes back (`upsertLocal(saved)`) as the
new source of truth. **`Store.Upsert` must therefore return the row as
actually written (read back inside the same transaction), and `handlers.go`
must respond with that**, not the client's payload. This is a correctness
fix required by the design, not a new decision to re-litigate.
Confirmed via the user: background latest-chapter refresh should fire on
Asura's SPA in-app navigation too (`onNavigate()`), not only true browser
page loads (`init()`) — more refresh opportunities on a client-routed site
that rarely does full reloads, still bounded by the same throttle/batch
limits.
## Phase 1 — Backend (`backend/`), TDD
### 1.1 Tests first — `backend/store_test.go`
Add four tests (all go through the existing `newTestServer(t)` /
`httptest` pattern already used in this file, since there are no direct
`Store`-level unit tests in the current style):
- **`TestUpsertConditionalUpdatedAt`** — table-driven: new bookmark (bumps),
unchanged progress (no bump), changed progress (bumps), favorite-only
change (no bump), latest-chapter-only change (no bump). Assert on the
`updated_at` returned by each PUT response.
- **`TestFavoriteRoundTrip`** — PUT `favorite: true`, GET list, assert it
round-trips.
- **`TestLatestChapterNullable`** — PUT without `latest_chapter_num`, assert
JSON response has `"latest_chapter_num":null`; PUT again with a value,
assert it round-trips.
- **`TestOpenStoreMigratesLegacySchema`** — hand-create the *old* (10-column)
schema in a temp DB file, seed one row, then call `OpenStore` on it and
assert the row survives with the new columns defaulting cleanly
(`favorite=false`, `latest_chapter=""`, `latest_chapter_num=nil`). This is
the safety net for the already-deployed production DB.
Run `cd backend && go test ./...` — expect compile failures (red state is
correct/expected before 1.2).
### 1.2 `backend/store.go`
- **`Bookmark` struct**: add `Favorite bool `json:"favorite"``,
`LatestChapter string `json:"latest_chapter"``,
`LatestChapterNum *float64 `json:"latest_chapter_num"`` (nullable — only
this one needs to be a pointer, per the design doc's data-model table).
- **`schema`**: extend `CREATE TABLE IF NOT EXISTS` with
`favorite INTEGER NOT NULL DEFAULT 0`,
`latest_chapter TEXT NOT NULL DEFAULT ''`, `latest_chapter_num REAL`
(covers fresh installs only).
- **Idempotent migration for the already-deployed DB**: add a
`migrateColumns(db)` helper using `PRAGMA table_info(bookmarks)` to check
each new column's existence before running its `ALTER TABLE ... ADD
COLUMN` (SQLite has no `ADD COLUMN IF NOT EXISTS`). Call it in
`OpenStore` right after the existing `schema` exec succeeds, same
error-wrapping style as today.
- **Shared `scanBookmark` helper**: centralizes converting the `favorite`
`INTEGER` (0/1) to `bool` and the nullable `latest_chapter_num` `REAL` to
`*float64` via `sql.NullFloat64`, used by both `List()` and `Upsert()`'s
read-back.
- **`List()`**: extend the `SELECT` to the new columns, scan via
`scanBookmark`.
- **`Upsert(b Bookmark) (Bookmark, error)`** — signature changes to return
the stored row. Implementation: wrap in `db.Begin()`/`tx.Commit()`
(explicit "read exactly what I just wrote" guarantee rather than relying
on `SetMaxOpenConns(1)` staying 1 forever). The `INSERT ... ON CONFLICT
DO UPDATE SET` gets a `CASE` expression for `updated_at`:
```sql
updated_at = CASE
WHEN bookmarks.last_chapter_num IS NOT excluded.last_chapter_num
THEN excluded.updated_at
ELSE bookmarks.updated_at
END
```
This is valid SQLite upsert syntax (bare column = pre-update row value,
`excluded.col` = proposed new row) and naturally handles "new row" for
free — `ON CONFLICT DO UPDATE` only fires on the update path, so a
genuinely new row goes through the plain `INSERT ... VALUES` and always
gets the fresh `updated_at`. After the exec, `SELECT` the row back inside
the same transaction and return it via `scanBookmark`.
### 1.3 `backend/handlers.go`
In `put()`: keep `b.UpdatedAt = time.Now().UnixMilli()` as a *candidate*
value (update its comment — it's no longer unconditionally authoritative),
then:
```go
stored, err := h.store.Upsert(b)
...
writeJSON(w, http.StatusOK, stored)
```
No other changes — `Favorite`/`LatestChapter`/`LatestChapterNum` already
flow through untouched from the decoded body, which is correct (they're
fully client-set synced fields). `list()`/`delete()` unchanged.
### 1.4 Green + build
```bash
cd backend && go test ./... # all pass, including pre-existing TestBookmarkRoundTrip unmodified
cd backend && CGO_ENABLED=0 go build # static binary still builds
```
## Phase 2 — Userscript (`userscript/manga-bookmark.user.js`)
No JS test harness in this repo — verification is manual (Phase 4).
1. **Config constants** (near `CACHE_KEY`, ~line 24): `LASTCHECKED_KEY =
"mangabm:lastchecked"`, `LATEST_CHECK_THROTTLE_MS = 4 * 60 * 60 * 1000`
(4h), `LATEST_CHECK_BATCH = 1`.
2. **Shared anchor extraction** so the exact same per-site chapter-matching
rule runs against both the live DOM and raw fetched HTML text (no HTML
parser available for the fetch path): `anchorsFromDocument(doc)` (via
`querySelectorAll("a[href]")`) and `anchorsFromHTML(html)` (regex-based
`<a href="...">...</a>` extraction). Add near `meta()` (~line 34).
3. **Per-adapter `latestChapterFromAnchors(anchors)`** added to both `asura`
and `demonic` adapter objects, implementing the regex rules from the
design doc (Asura: href matches `/chapter/([\d.]+)$/` AND text matches
`/Chapter\s+[\d.]+/i`, excluding the "First Chapter" quick-jump button;
Demonic: all `chaptered.php?manga=\d+&chapter=([\d.]+)` matches, take
max — no order assumption). Plus a `computeLatestChapter(site, anchors)`
dispatcher near `keyOf()`.
4. **`mangabm:lastchecked` local helpers**: `loadLastChecked()` /
`saveLastChecked(map)`, parallel to existing `loadCache`/`saveCache`
(~line 154), storing `{ [bookmarkKey]: timestampMs }`. Client-local only,
never synced.
5. **`applyLatestChapterIfChanged(existing, latest)`** (~near `syncUpsert`,
line 295): if `latest.num` differs from the bookmark's stored
`latest_chapter_num`, optimistically update local cache + render, then
`apiPut` with `updated_at: Date.now()` as a *candidate* — the backend
(Phase 1) decides whether to actually apply it, and the client adopts
whatever comes back via `upsertLocal(saved)`, same pattern the rest of
the file already uses. No client-side "don't reorder" logic needed
beyond that — the server is the single source of truth for it. Silent
on failure (no toast), per the design doc.
6. **Live-page capture**: `maybeCaptureLatestOnSeriesPage()` — on a
`type: "series"` page for an already-bookmarked series, scan the live
DOM via `anchorsFromDocument` + `computeLatestChapter`, then
`applyLatestChapterIfChanged`. Hooked into `onNavigate()` (~line 633),
after the existing `maybeAutoUpdate()` call.
7. **Background opportunistic refresh**: `backgroundRefreshLatest()` — get
`currentSite()` (which adapter matches `window.location`), pick
same-site bookmarks not checked within `LATEST_CHECK_THROTTLE_MS`
(oldest-checked-first), fetch+parse at most `LATEST_CHECK_BATCH` of them
via `fetch(bm.series_url).then(r => r.text())` → `anchorsFromHTML` →
`computeLatestChapter` → `applyLatestChapterIfChanged`. Mark each
attempted bookmark's `lastchecked` timestamp regardless of success/failure
(advances the throttle window either way, avoiding hammering a
consistently-failing fetch). Silent on failure.
**Hook into both `init()` and `onNavigate()`** (per user's confirmed
preference — more refresh opportunities on Asura's SPA navigation, same
throttle/batch caps prevent request bursts either way).
8. **`toggleFavorite(key)`** (~near `setChapterManual`, line 293): flips
`favorite`, optimistic update, `apiPut` with `Date.now()` candidate
timestamp (again, backend decides), toast on success/failure (consistent
with other explicit user-initiated actions like bookmark/remove).
9. **Tabs**: new module state `let activeTab = "all";` (~near `panelOpen`,
line 374; not persisted, defaults to "all"). Wire click handlers in
`buildUI()` for new `#tabAll`/`#tabFav` elements. In `render()` (~line
568), toggle each tab's `.active` class and filter which array feeds the
list-building loop (`activeTab === "favorites" ? state.list.filter(b =>
b.favorite) : state.list`) — `state.list` itself is never mutated/filtered,
so a favorited manga always still appears in "All".
10. **`renderItem(b)`** (~line 579): add a star toggle button (☆/★,
`onclick: () => toggleFavorite(b.key)`) alongside the existing
Continue/Edit/Remove buttons, and change the subtitle line to
`"Read: " + last_chapter + " · Latest: " + latest_chapter` when
`latest_chapter_num` is known and strictly greater than
`last_chapter_num` (avoids showing "Latest: Chapter 12" next to "Read:
Chapter 12" when they're numerically equal); otherwise keep today's
`"<last_chapter> · <site>"` text.
11. **`TEMPLATE`** (~line 679): insert a tabs bar
(`<div id="tabs"><button id="tabAll" class="tab active">All</button>
<button id="tabFav" class="tab">★ Favorites</button></div>`) between
`#context` and `#list`.
12. **`CSS`** (~near `.ctx-sub`/`.btn.danger`): add `.tab`/`.tab.active` and
`.btn.star`/`.btn.star.active` rules following the existing dark-theme
`.btn` modifier convention (`.btn.primary`, `.btn.small`, `.btn.danger`).
13. **Fix the misleading redirect comment** (line 41, in the `asura`
adapter object): replace "asuracomic.net currently 301s to
asurascans.com; match both." with an accurate note that the redirect
now discards the path (goes straight to the asurascans.com root),
happens at the Cloudflare edge before any JS runs, so no client-side
fix is possible, and the user should navigate via asurascans.com links
directly. No change to the `matches()` regex itself.
14. **`@version`**: bump `1.1.0` → `1.2.0`.
## Phase 3 — Documentation
- **`CLAUDE.md`**: update the `PUT /bookmarks/{key}` endpoint description
(currently "upsert, server sets updated_at") to describe the new
conditional rule, referencing
`plans/2026-07-25-bookmark-list-favorites-design.md` §4.
- **`README.md`**: update the matching endpoint-table row, and correct the
"Adapter reference" section's Asura row to note `asuracomic.net` deep
links currently 301 to the asurascans.com root (broken/path discarded) —
use `asurascans.com` links directly. While touching this, also fix
`CLAUDE.md`'s intro line ("asuracomic.net (formerly asurascans.com)"),
which has the relationship backwards and is inconsistent with README's
own phrasing ("asurascans.com (a.k.a. asuracomic.net)") — bundle this
small adjacent correction in since it's directly related to the same
finding.
## Verification
**Backend (automated):**
```bash
cd backend && go test ./...
cd backend && CGO_ENABLED=0 go build
```
**Backend (manual smoke test, extends the existing curl convention in
CLAUDE.md/README.md):** PUT a new bookmark, then PUT again changing only
`favorite`, then only `latest_chapter*`, then a real `last_chapter_num`
advance — confirm via `jq .updated_at` that only the first and last calls
change `updated_at`.
**Userscript (manual — no JS test harness exists in this repo, matching
existing project convention):**
- List reorders only on a genuine progress advance, not on plain re-visit,
favorite toggle, or latest-chapter capture.
- Latest-chapter capture fires when visiting a bookmarked series page on
both sites and displays the "Read: X · Latest: Y" subtitle correctly.
- Background refresh: check `localStorage['mangabm:lastchecked']` in
devtools to confirm throttling behavior; confirm via the Network tab that
it never fires a cross-site request (only same-origin as the currently
loaded site).
- Favorite toggle persists across a panel close/reopen and a `refresh()`
round-trip through the backend; favorited manga still shows in "All".
- Fastest iteration path: desktop Tampermonkey/Violentmonkey first (script
stays `GM_*`-free), then confirm on Bromite per existing project
convention.
## Critical files
- `backend/store.go`
- `backend/handlers.go`
- `backend/store_test.go`
- `userscript/manga-bookmark.user.js`
- `CLAUDE.md`
- `README.md`
plans/2026-07-25-bookmark-list-favorites-design.md
-231
View File
@@ -1,231 +0,0 @@
# 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.
plans/2026-07-25-web-ui-implementation-plan.md
-2330
View File
File diff suppressed because it is too large Load Diff
plans/mangaBookmark.md
-142
View File
@@ -1,142 +0,0 @@
# Manga Bookmark — Userscript + Self-Hosted Sync Backend
## Context
The user reads manga on **asurascans.com** (now serves from `asuracomic.net`) and **demonicscans.org**, on a **mobile browser (Bromite)**. They want to bookmark a series and auto-record the latest chapter they've read, with a UI reachable while those sites are open on the phone. Progress must sync across devices, so it lives in a backend on the user's own server.
### Hard constraints (drive the whole design)
Bromite uses Chromium's native userscript engine — **not** Tampermonkey. Per Bromite's wiki / Chromium docs:
- **No `GM_setValue` / `GM_getValue`** → persistence must use page `localStorage`.
- **No `GM_registerMenuCommand`** → UI must be injected on-page (floating button + panel).
- **`GM_xmlhttpRequest` is same-origin only** → cross-origin calls use plain `fetch()`, which works only against a **CORS-enabled** backend.
- Userscripts run in an **isolated world** → the manga site's JS cannot read our embedded API token (safe to embed).
- `asurascans.com` and `demonicscans.org` are **separate origins** with **separate `localStorage`** → the only way to unify bookmarks across both sites is a **shared remote store**. Cloud sync is therefore required, not a nice-to-have.
- The manga sites are `https://`, so the backend **must be HTTPS** (mixed-content block otherwise). User already runs a reverse proxy + domain, so a subdomain (e.g. `manga-api.<domain>`) fronts the service.
### Decisions locked with user
- Backend: **self-hosted, Go** (resource-friendly), Docker Compose, behind existing reverse proxy (TLS handled there).
- Scope: **track read progress only** — no "new chapters available" detection (YAGNI for v1).
- Record last-read: **auto on chapter open + manual override** in the panel.
- UI: **floating button + slide-in panel**.
---
## Architecture
```
Bromite (mobile)
userscript (isolated world, per-site adapters)
localStorage cache <--> fetch() over HTTPS
|
reverse proxy (TLS, CORS origin)
|
Go service (net/http) -> SQLite file (volume)
```
Two deliverables in this repo:
```
mangaBookmark/
backend/
main.go # server bootstrap, config from env, router
handlers.go # GET/PUT/DELETE /bookmarks, /healthz
store.go # SQLite open + queries (modernc.org/sqlite, CGO_ENABLED=0)
middleware.go # bearer-token auth + CORS/preflight
store_test.go # handler + store tests (httptest + temp sqlite)
go.mod
Dockerfile # multi-stage: golang:alpine build -> scratch/distroless
docker-compose.yml # service + named volume for the sqlite file
userscript/
manga-bookmark.user.js
README.md # deploy steps + Bromite install steps + config
```
---
## Backend (Go)
**Stack:** stdlib `net/http` (no framework needed for 3 routes) + `modernc.org/sqlite` (pure Go → static binary, `scratch` image). Rust/axum + `rusqlite` is a drop-in alternative if preferred later.
**Data model** — one table, `key` unique across both sites:
```sql
CREATE TABLE IF NOT EXISTS bookmarks (
key TEXT PRIMARY KEY, -- "<site>:<series_id>"
site TEXT NOT NULL, -- "asura" | "demonic"
series_id TEXT NOT NULL,
title TEXT,
series_url TEXT,
cover TEXT,
last_chapter TEXT, -- label as shown, e.g. "Chapter 123"
last_chapter_num REAL, -- parsed for max() comparison
last_chapter_url TEXT,
updated_at INTEGER NOT NULL -- unix ms
);
```
**Endpoints** (JSON):
- `GET /bookmarks` → array of all bookmarks (single-user store).
- `PUT /bookmarks/{key}` → upsert one series (body = bookmark object). Server sets `updated_at`.
- `DELETE /bookmarks/{key}` → remove one.
- `GET /healthz` → `200 ok` (no auth).
**Middleware:**
- **Auth:** require `Authorization: Bearer <API_TOKEN>` (env) on `/bookmarks*`; 401 otherwise. Constant-time compare.
- **CORS:** reflect `Origin` when it's in `ALLOWED_ORIGINS` (env, comma list: `https://asuracomic.net,https://asurascans.com,https://demonicscans.org`). Allow methods `GET,PUT,DELETE,OPTIONS`, headers `Authorization,Content-Type`. Answer preflight `OPTIONS` with `204`.
**Config via env:** `API_TOKEN`, `ALLOWED_ORIGINS`, `DB_PATH` (default `/data/bookmarks.db`), `PORT` (default `8080`).
**Dockerfile:** multi-stage — `golang:1.23-alpine` build with `CGO_ENABLED=0 go build`, final stage `gcr.io/distroless/static` (or `scratch`) copying the binary; `/data` volume for the SQLite file. (See `multi-stage-dockerfile` skill.)
**docker-compose.yml:** one service, named volume mounted at `/data`, env vars, `restart: unless-stopped`. Attach to the existing reverse-proxy network (or expose a local port the proxy targets) — the proxy terminates TLS and routes `manga-api.<domain>` → service `:8080`. (See `docker-compose-orchestration` skill.)
---
## Userscript (`manga-bookmark.user.js`)
Single Bromite-compatible file. **No `GM_*` calls anywhere** (so it also runs in desktop Tampermonkey/Violentmonkey for faster iteration). Wrapped in an IIFE.
**Metadata header:** `@match https://asuracomic.net/*`, `https://asurascans.com/*`, `https://demonicscans.org/*`; `@run-at document-idle`; `@name`, `@version`.
**Config block (top of file, user fills in):**
```js
const API_BASE = "https://manga-api.<domain>";
const API_TOKEN = "<paste token>";
```
**Modules inside the IIFE:**
1. **Site adapters** — one per host, each exposing `detect(location, document)` → `{ type: 'series'|'chapter'|'other', site, seriesId, title, cover, seriesUrl, chapterLabel, chapterNum, chapterUrl }`.
- Identify page **type + IDs from URL regex** (most stable); pull `title`/`cover` from **`og:title` / `og:image` meta tags** (present and stable on both sites, avoids brittle CSS classes).
- Asura: series `…/series/<slug>-<id>`, chapter `…/series/<slug>-<id>/chapter/<n>` → `seriesId = <slug>-<id>`, `chapterNum = n`.
- Demonic: series `…/manga/<slug>`, chapter reader `…/title/<id>/<chapterId>` (exact reader path to be confirmed against live DOM).
- **URL patterns + selectors get verified against live pages during implementation** (Cloudflare blocks server-side fetch; confirm via Playwright MCP or on-device devtools before finalizing).
2. **API client** — `apiGet()`, `apiPut(key, obj)`, `apiDelete(key)` via `fetch` with the bearer header. `localStorage` key `mangabm:cache` holds the last-known bookmark list for instant render + offline fallback.
3. **Progress logic** — on a chapter page of a **bookmarked** series, auto-upsert `last_chapter` when `chapterNum >= stored last_chapter_num` (so re-reading old chapters doesn't regress progress; unparseable → set current). Manual override in the panel forces any value. Bookmarking a new series is available from both series and chapter pages.
4. **Floating UI** — rendered inside a **Shadow DOM** root (isolates from site CSS; important on mobile). Fixed circular button bottom-right (respects safe-area insets, high `z-index`); tap toggles a slide-in panel:
- Header: context of current page — "+ Bookmark this" if unbookmarked, else current progress + "Update to this chapter".
- List: bookmarks sorted by `updated_at` desc — title, last chapter, **Continue** link (→ `last_chapter_url` or `series_url`), edit-chapter input, remove.
- Toasts for sync success/failure.
5. **SPA navigation** — Asura is a Next.js client-routed app (no full reload on chapter change). Patch `history.pushState`/`replaceState` + listen for `popstate`, re-run `detect()` on URL change so auto-update fires without reload. Demonic (classic reloads) works via the initial `document-idle` run.
**Sync strategy:** last-write-wins (single user). On load: `apiGet()` → render → cache. On mutation: optimistic cache+UI update, then `PUT`/`DELETE`; on failure show a toast, keep local, retry on next load.
---
## Verification
**Backend**
- `go test ./...` — auth (401 without/with bad token), CORS preflight headers + origin reflection, upsert→get→delete round-trip against a temp SQLite file.
- Local smoke: `docker compose up`, then `curl` `GET/PUT/DELETE` with `Authorization` header; confirm `OPTIONS` preflight returns the CORS headers.
- Deployed: hit `https://manga-api.<domain>/healthz`; confirm valid TLS (no mixed-content) and preflight from a real site origin.
**Userscript**
- Confirm adapter URL regex + `og:` extraction on live Asura + Demonic pages (Playwright MCP or on-device devtools) before finalizing selectors.
- Desktop dry-run in Tampermonkey/Violentmonkey (same file, no GM APIs): bookmark a series, open a chapter, verify panel updates and `curl GET /bookmarks` on the server reflects it.
- On Bromite: install per README, repeat the flow on both sites; verify auto-update on chapter open, manual override, Continue link, and cross-site unified list (bookmark on Asura shows when panel opened on Demonic).
**Open items to confirm during build:** exact Demonic reader URL path + chapter-number source; Asura's live series/chapter path (post-`asuracomic.net` migration); Bromite's current userscript-install steps (documented in README, verified on-device).