sulthan/mangaBookmark
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0a79e5f3d7af624caf7f8e081532878561114121
mangaBookmark/userscript/AGENTS.md
T
sulthan e2c054e7ce Covers render in the userscript panel, from a public route (#60) (#69) 
Closes #60.

Spec: #55. Originating bug: #47. Architecture: `docs/adr/0007-backend-hosts-cover-bytes.md`. Neither #47 nor #55 is closed from here.

## What this branch does

The panel now renders Covers from the deployment's own origin, and both userscripts stop having an opinion about where a Cover lives.

**The public route was already in place.** `GET /covers/{address}` landed with #59 (`92eba07`) and is registered on the bare mux, outside `httpmw.Auth` and outside the web UI's Discord session — `backend/main.go:210-214`, handler `backend/internal/api/handlers.go:142-158`. It reads no cookie and no header, answers `404` for an address that was never stored (and for a row whose file has gone missing — recorded-but-gone is not-found, never a fabricated body), refuses anything that is not `^[0-9a-f]{64}$` *before* the value becomes a path, and sets `Cache-Control: public, max-age=604800, immutable`. Those four properties are asserted by `backend/cover_test.go:231-278`. This branch re-verified them rather than re-implementing them; the only backend line it touches is a comment.

**Both userscripts lose cover scraping entirely.** Every adapter's `cover:` field is gone, along with the two helpers that fed them: the manga script's `coverFromPage()` (the `img[alt]` DOM scan comix needed, because comix publishes no `og:image`) and the novel script's `metaName()` plus the now-callerless module-level `meta()`. Nothing under `userscript/` reads `og:image`, `meta[name=image]`, or `img[alt]` any more.

**Nothing sends a cover either.** `delete body.cover` sits in `apiPut` — `manga-bookmark.user.js:486`, `novel-bookmark.user.js:275` — which is the single chokepoint every write passes through (`pushBookmark`, the retry-queue flush, `toggleFavorite`, `toggleArchive`). It operates on the `Object.assign` copy, so the in-memory row keeps the cover it renders with. This matters beyond tidiness: a Reader upgrading from an older copy has `localStorage` rows carrying third-party scraped URLs, and without the strip those would ride back up on the next write. The handler discards the field regardless (`handlers.go:53-59`) — it is permanently inert, not pending removal.

**Failed loads get the designed empty state, not the broken-image glyph.** `onerror: (e) => e.target.replaceWith(el("div", { class: "cover ph" }))` on the cover `<img>` in both card renderers (`manga:1380-1390`, `novel:1134-1144`). The replacement is byte-identical to the existing no-cover branch on the very next line, so it picks up the `.cover.ph` styling already in the panel CSS — no new tokens, no new rule. `el()` routes any `on*` prop through `addEventListener`, so this is a listener, not an inline attribute string, and the swap is a `createElement` + DOM call with no markup parsing anywhere near it. This is the half of #47 that was visible on kagane.

**The deleted scraping's tests went with it**: the two comix cover cases, the `pageImages` and `namedMetas` fixtures, the `img[alt]` and `meta[name=...]` stub branches, the now-dead `querySelectorAll` stub member, and every stale `og:image` fixture and `p.cover` assertion across both suites. The export lists needed no change and that was checked, not assumed — `coverFromPage` and `metaName` were module-private on `origin/main` and no cover symbol ever appeared in `module.exports`.

Docs that described the deleted behaviour were corrected in the same breath, because leaving them would instruct the next agent to put the scraping back: `userscript/AGENTS.md` (adapter contract + the per-site notes for comix, kagane and novelfull), the README's adapter reference, and the userscript testing skill's stub table.

## Verification

- `go test -count=1 ./...` — green across all nine packages (`backend` 29.8s, `latest`, `store`, `session`, `token`, `userscript`, `web`).
- `node --check` clean on both userscripts; `node --test` on both logic suites — 46 tests, 46 pass.
- `gofmt -l` clean; `go build ./...` clean.
- The `onerror` swap is DOM behaviour and deliberately has no coverage in the Node harness — that harness stubs a browser precisely so it never needs a DOM, and #60 says not to invent coverage for it. It was instead exercised for real: the `el()` helper and the exact render expression were loaded into a headless Chromium with a deliberately unloadable `src`, and the resulting DOM was `<div class="cover ph"></div>`. Ad hoc, not committed.
- **Not done, needs you:** the on-device criterion — a comix Series bookmarked mid-chapter showing its Cover in the panel. That needs a real install against the deployment and is the one box left unticked on #60.

## Reviewed

Both `/code-review` axes ran against `cc0fa92`. Spec found no missed requirement and no scope creep; standards found the diff clean on the four areas it scrutinised (the `delete body.cover` placement, the `onerror` handler's DOM safety, comment quality, dead-code removal). Their combined findings — the dead `querySelectorAll` stub, the stale README and skill text, and the handler comment whose premise this change invalidates — are fixed in `8b58019`.

## Out of scope, deliberately

The kagane-specific cover proxy still exists and still carries its session gate (#63 deletes it). The poll's blank-Cover fill (#61) and browser-backed Sites joining the pipeline (#62) are untouched.

Reviewed-on: #69
Co-authored-by: Sulthan Zaki <sultankiki05@gmail.com>
Co-committed-by: Sulthan Zaki <sultankiki05@gmail.com>
2026-08-10 08:52:57 +07:00

6.3 KiB
Raw Blame History

Guidance for OpenCode (and Claude Code) working under userscript/. See root AGENTS.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 from og:title (or the page heading where a site ships no og: tags), not CSS classes. No adapter reads a cover: the backend acquires, stores and serves every Cover from its own origin (ADR-0007), the wire's cover is already an address on our origin, and apiPut strips any cover off an outgoing body.
  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.
  • comix.to: series /title/<id>-<slug>, chapter /title/<id>-<slug>/<uploadId>-chapter-<n>. Only the leading <id> is identity — the slug re-renders when a series is renamed (comixSeriesId). An SPA that never rewrites og:title: the server-rendered head keeps whatever document loaded first, so on a cold load og:title is the homepage's "Comix — Read Comics online for free" and after an in-page hop it is the previous series' name. document.title is the one thing client routing does update, so titles come from there, with the chapter page's " · Ch.<n>" tail stripped. It publishes no og:image either, which is one of the reasons cover acquisition moved to the backend.
  • kagane.to: series /series/<uuid>, reader /series/<uuid>/reader/<bookUuid>. Reader URLs carry no chapter number, so the number comes out of og:title. Two shapes exist: "<Series> - Chapter <n>[ - Episode <n>]" and, for volume-numbered series, "<Series> - Volume <v> Chapter <n>" with no episode name — both must yield a bare series title, or the volume tail lands in the bookmark's title. Its covers are challenge- and CORP-protected, so nothing outside kagane.to can load one directly; the panel renders the backend's own cover address like every other Site. Behind a Cloudflare JS challenge, so the backend polls it through the headless browser.
  • novelfull.com (novel script): series /<slug>.html, chapter /<slug>/chapter-<n>[-<title-slug>].html. No og:* tags at all — title from h3.title (series) or a.truyen-title (chapter); the script reads no cover. Behind a Cloudflare JS challenge no TLS fingerprint clears, so the backend polls it through the headless browser.
  • lightnovelworld.net (novel script): series /novel/<slug>/, chapter /<slug>-chapter-<n>/ — flat, at the site root. h1.entry-title is the clean title on a series page and <Title> Chapter <n> on a chapter page. Its series page lists every chapter with an absolute href, so the backend polls it with the plain TLS client.

Second script: novel-bookmark.user.js

A copy of the manga script with two adapters, LIBRARY = "novel" and STORE_PREFIX = "bmgr:novel:". No migration loop (this script has no previous installation to carry keys over from). Installed alongside the manga script; both write to the same backend with the same LIBRARY column discriminating them.

Reference in New Issue View Git Blame Copy Permalink