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

docs: correct manga-site adapter details and Cloudflare assumptions

Browse Source 
asurascans.com moved to Astro with /comics/<slug> paths (was documented
as Next.js /series/<id>). Also replace the untested "CGNAT gets
challenge-paged" claim with live-verified results: curl passes clean
from both the dev machine and VPS as of 2026-07-26, so Cloudflare's
block is IP-reputation-based and time-varying, not a fixed property of
either machine.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Sulthan Zaki
2026-07-26 14:38:45 +07:00
parent c601ef54d5
commit b35a89d6a1
1 changed files with 8 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+8 -3
View File
@@ -8,7 +8,7 @@ Greenfield. Only `plans/mangaBookmark.md` exists — no code yet. That plan is t
## What this is
A manga read-progress tracker for a user reading on **asurascans.com** (the current domain; asuracomic.net is the older one) and **demonicscans.org** from **Bromite** (mobile Chromium). A userscript injects on-page UI (floating button + slide-in panel) and syncs progress to a self-hosted Go backend so bookmarks unify across both sites and across devices.
A manga read-progress tracker for a user reading on **asurascans.com** (the current domain; asuracomic.net 301s here) and **demonicscans.org** from **Bromite** (mobile Chromium). A userscript injects on-page UI (floating button + slide-in panel) and syncs progress to a self-hosted Go backend so bookmarks unify across both sites and across devices.
## Hard constraints (these drive the design — do not violate)
@@ -17,7 +17,7 @@ Bromite uses Chromium's **native** userscript engine, not Tampermonkey:
- Cross-origin `fetch()` works **only** against a CORS-enabled backend. Manga sites are `https://`, so backend **must be HTTPS** (mixed-content block otherwise).
- Asura and Demonic are **separate origins with separate `localStorage`** — a shared remote store is the only way to unify bookmarks. Cloud sync is required, not optional.
- Userscript runs in an **isolated world**, so the embedded API token is safe from the site's JS.
- Cloudflare blocks server-side fetch of the manga sites — **verify URL regex + `og:` selectors against live pages** (Playwright MCP or on-device devtools) before finalizing adapters, not by curling.
- Cloudflare's block on fetching the manga sites is **IP-reputation-based, not universal — and not reliably reproducible.** Verified 2026-07-26: plain `curl` from both the CGNAT dev machine *and* the deployed VPS got clean 200s with real HTML on both asurascans.com and demonicscans.org (homepage, series, chapter pages) — no interactive Turnstile challenge from either IP at test time. This contradicts an earlier, untested assumption that the CGNAT dev IP would be blocked; it was not, at least on this date. Treat "does curl work right now" as a live, time-varying fact to re-check, not a fixed property of a given machine — Cloudflare's bot scoring can flip a previously-clean IP without notice. Any backend fetcher still needs a graceful-degrade path for when it does get challenged, and adapters should be **verified against live pages** (Playwright MCP, on-device devtools, or a direct probe) before finalizing, not assumed from a single earlier test.
## Architecture
@@ -47,7 +47,12 @@ Bromite userscript (isolated world, per-site adapters, localStorage cache)
2. **API client** — `apiGet/apiPut/apiDelete` with bearer header; `localStorage` key `mangabm:cache` for instant render + offline fallback.
3. **Progress logic** — auto-upsert `last_chapter` only when `chapterNum >= stored last_chapter_num` (re-reading old chapters must not regress progress; unparseable -> set current). Manual panel override forces any value.
4. **UI** — rendered inside a **Shadow DOM** root to isolate from site CSS (critical on mobile).
5. **SPA navigation** — Asura is Next.js client-routed: patch `history.pushState`/`replaceState` + listen `popstate`, re-run `detect()` on URL change so auto-update fires without reload. Demonic uses classic reloads (initial `document-idle` run suffices).
5. **SPA navigation** — Asura is Astro, client-routed on the comic/chapter pages: patch `history.pushState`/`replaceState` + listen `popstate`, re-run `detect()` on URL change so auto-update fires without reload. Demonic uses classic reloads (initial `document-idle` run suffices).
### Live URL shapes (verified 2026-07-26, may drift — re-check against live pages before trusting)
- **asurascans.com**: series `/comics/<slug>` (slug carries a trailing hash-like suffix, e.g. `-f886a8af`), chapter `/comics/<slug>/chapter/<n>`. Astro-rendered; chapter links are present in raw server HTML (no client-side-only render blocking a server fetch).
- **demonicscans.org**: series `/manga/<slug>` (slug may URL-encode punctuation, e.g. `%2527` for `'`), chapter `/title/<slug>/chapter/<n>/<page>` (the older `chaptered.php?manga=<id>&chapter=<n>` form still exists as a redirect and is what series-page chapter-list anchors link through).
## Commands (once code exists)