47 lines
3.6 KiB
Markdown
47 lines
3.6 KiB
Markdown
Guidance for Claude Code working under `userscript/`. See root `CLAUDE.md` for the project-wide architecture diagram, hard constraints, and design system.
|
||
|
||
### Userscript structure (single IIFE, `manga-bookmark.user.js`)
|
||
|
||
1. **Site adapters** — one per host, `detect(location, document)` return page `type` + IDs. Identify type/IDs from **URL regex** (most stable); pull `title`/`cover` from **`og:title`/`og:image` meta tags**, not CSS classes.
|
||
2. **API client** — `apiGet/apiPut/apiDelete` with bearer header; `localStorage` key `bmgr:manga: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. **Retry queue** — every write go through `pushBookmark`/`pushDelete`, so
|
||
failed mutation park in `localStorage` (`bmgr:manga:queue`) and replayed on
|
||
next navigation, reconnect, or `refresh()`. Entries are markers
|
||
(`{key, op, sendStatus, attempts}`), never payloads — body read from
|
||
cache at send time, so one entry per key give ordering and coalescing for
|
||
free. `sendStatus` is **sticky**: while archive pending, later writes to
|
||
that key keep carrying bucket, which stop successful
|
||
in-between write from silently un-archiving series. `refresh()` drains
|
||
before it fetches and overlays anything still pending, so list never
|
||
flaps. 400 drops entry, 401 abort pass and keep queue, and
|
||
transient failures retry to cap of 10. Latest-chapter writes deliberately
|
||
stay out of queue. See
|
||
`docs/superpowers/specs/2026-07-27-offline-retry-queue-design.md`.
|
||
5. **UI** — rendered inside **Shadow DOM** root to isolate from site CSS
|
||
(critical on mobile). Three tabs (All / Favourites / Archived) and row of
|
||
link chips to web UI and both manga sites; `WEB_BASE` sits in CONFIG
|
||
block next to `API_BASE`. FAB is `7 × 44` edge tab whose *hit* area
|
||
widened to `28 × 72` by invisible `#hit` child; `#fab` must keep
|
||
`touch-action: none` and must **not** regain `overflow: hidden`. Since
|
||
`touch-action` resolved at gesture start, strip can't be both
|
||
browser-scrolled and script-dragged, so `makeDraggable` splits by intent: swipe
|
||
from `#hit` scrolls via `window.scrollBy`, hold of `ARM_MS` arms
|
||
reposition drag, visible sliver drags with no hold. See
|
||
`docs/superpowers/specs/2026-07-28-edge-tab-hitbox-design.md`.
|
||
6. **SPA navigation** — Asura is Astro, client-routed on comic/chapter pages: patch `history.pushState`/`replaceState` + listen `popstate`, re-run `detect()` on URL change so auto-update fire without reload. Demonic uses classic reloads (initial `document-idle` run suffice).
|
||
|
||
### Live URL shapes (verified 2026-07-26, may drift — re-check against live pages before trust)
|
||
|
||
- **asurascans.com**: series `/comics/<slug>` (slug carries trailing
|
||
site-wide build-hash suffix, e.g. `-059befe1`, that **rotates on every
|
||
redeploy**), chapter `/comics/<slug>/chapter/<n>`. `seriesId` must strip
|
||
hash (`/-[0-9a-f]{8}$/`, `stripBuildHash` in userscript,
|
||
`asuraBuildHash` in backend); URLs keep full slug — stale-hash
|
||
URLs 302 to current ones. Astro-rendered; chapter links present in raw
|
||
server HTML.
|
||
- **demonicscans.org**: series `/manga/<slug>` (slug may URL-encode punctuation, e.g. `%2527` for `'`), chapter `/title/<slug>/chapter/<n>/<page>` (older `chaptered.php?manga=<id>&chapter=<n>` form still exists as redirect, what series-page chapter-list anchors link through).
|
||
Encodings (incl. triple-encoded punctuation like `%25252D`) identical
|
||
on /manga/ and /title/ pages, so decode-once seriesIds match — verified
|
||
2026-07-28.
|