From b35a89d6a1aeaf2ce26739c7bb5dd49e4424644a Mon Sep 17 00:00:00 2001 From: Sulthan Zaki Date: Sun, 26 Jul 2026 14:38:45 +0700 Subject: [PATCH] docs: correct manga-site adapter details and Cloudflare assumptions asurascans.com moved to Astro with /comics/ paths (was documented as Next.js /series/). 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 --- CLAUDE.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9405fd0..3e6cf8a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 carries a trailing hash-like suffix, e.g. `-f886a8af`), chapter `/comics//chapter/`. Astro-rendered; chapter links are present in raw server HTML (no client-side-only render blocking a server fetch). +- **demonicscans.org**: series `/manga/` (slug may URL-encode punctuation, e.g. `%2527` for `'`), chapter `/title//chapter//` (the older `chaptered.php?manga=&chapter=` form still exists as a redirect and is what series-page chapter-list anchors link through). ## Commands (once code exists)