mangaBookmark/CONTEXT.md

# Bookmark Manager

Read-progress tracker for serialised fiction. A reader browses third-party manga and
novel sites; userscripts capture where they got to and sync it to a self-hosted backend,
so progress survives across sites and devices.

## Language

**Series**:
One ongoing work — a manga or a novel — as published by a Site. Identified by the canonical
slug the Site itself publishes for it, never by its title and never by a Chapter Slug. A
Series exists once and is shared by every Reader who bookmarks it; it owns the facts that
are true regardless of who is reading — title, cover, Latest Chapter. A Reader cannot
change them; they describe the Series, not anyone's relationship to it.
_Avoid_: manga, title, book, comic

**Site**:
One third-party source a Series is published on. A Series on two Sites is two Series.
_Avoid_: source, host, provider, domain

**Chapter Slug**:
A slug a Site builds its chapter addresses from. Not an identity: one Series may have
several, any of them may differ from the slug that identifies the Series, and none is
computable from another. Only the Site's own links say which ones a Series uses, so a
Chapter Slug is always discovered, never derived.
_Avoid_: series slug, url slug, permalink, chapter path

**Cover**:
The image that stands for a Series wherever it is listed. A fact about the Series like
its title — one Cover per Series, shared by every Reader, never per-Reader. Defined by
what a Reader's browser can display, not by where the Site keeps the picture: an address
no client can load is not a Cover, it is a missing one.
_Avoid_: thumbnail, poster, image URL, artwork

**Reader**:
A person with their own Progress. Exactly one per set of credentials, so there is no
separate "account" concept to model — the credential belongs to the Reader.
_Avoid_: user, account, member, subscriber

**Bookmark**:
One Reader's tracked relationship with one Series, holding only what differs between
Readers: Progress, Favourite, Lifecycle bucket. Facts about the Series itself belong
to the Series, not here.
_Avoid_: entry, item, record, subscription

**Library**:
One of the two halves of the collection — manga or novel — selected by a Bookmark's
`kind`. The web UI and the userscripts each address exactly one Library at a time.
Not a per-person concept: "everything one person has bookmarked" is a different idea
and must not be called a Library.
_Avoid_: section, tab, category

**Progress**:
The furthest chapter a reader has actually read in a Series. Only a change in Progress
is real activity, so only Progress reorders the list.
_Avoid_: position, bookmark (the noun is taken), last read

**Latest Chapter**:
The highest-numbered chapter a Site has published for a Series. The number is what
ranks it, never a date and never the Site's own "newest chapter" banner — where a Site
disagrees with itself, its list of chapters is the record and its summary of that list
is not. Established by a Poll and, between Polls, by a Sighting. Distinct from Progress
in every way that matters: it is a fact about the Site, not about the reader, and it
must never reorder the list.
_Avoid_: newest, current chapter, update

**Poll**:
The backend's own check of a Site for a Series's Latest Chapter, made without the
Reader present. Performed once per Series no matter how many Readers bookmarked it —
a Poll is work done on behalf of the Series, never on behalf of a Reader.
_Avoid_: scrape, refresh, check, sync

**Poll Lane**:
One Site's own stream of Polls, carrying the pace at which that Site is willing to be
asked. Every Site has exactly one and no Lane can slow, block or borrow from another's;
a Reader never has one and never influences one.
_Avoid_: worker, queue, scheduler, batch, wave

**Sighting**:
What a Reader's browser happened to see of a Series's Latest Chapter while that Reader
was on the page. It reports the same fact as a Poll but carries none of its authority:
a Poll always overrules it, and only a Sighting on a Series no Reader else holds may
defer one. A Sighting a later Poll contradicts downwards is a false Sighting, and
enough of those cost the Reader the right to defer at all.
_Avoid_: client report, user poll, observation, claim

**Acquisition**:
The single read of a Series page made the moment the Series first exists, giving it
both its Latest Chapter and its Cover without waiting for the Lane's pace. Distinct
from a Poll in the two ways that matter: a Reader is present — it is triggered by
their first Bookmark of that Series — and it is the only read that establishes a
Cover rather than refreshing facts. It happens once in a Series's life; every later
read of the same page is a Poll.
_Avoid_: initial poll, first fetch, prefetch, warm-up

**New Chapter**:
The state where Latest Chapter is ahead of Progress. The single condition the ember
accent is permitted to signal.
_Avoid_: unread, update available

**Lifecycle bucket**:
Which of three mutually exclusive states a Bookmark sits in — reading, archived, or
finished. A Bookmark is in exactly one. Orthogonal to being a favourite.
_Avoid_: state, status (as a domain word), list

**Favourite**:
A reader's manual pin on a Bookmark. Orthogonal to the Lifecycle bucket, and never a
reason to reorder the list.
_Avoid_: starred, pinned, priority