Reader settings per login session

Each sign-in keeps its own reader mode, zoom, page tone and skipping once
it changes one; sessions that never changed follow the latest set, and a
new sign-in starts from the session used last. Settings -> Reading shows
every session's state, lets a session follow the latest again or become
the latest, and turns the feature off for one shared set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.dockerignore

@@ -10,6 +10,8 @@
 !backup.js
 !reading-analytics.js
 !reading-access.js
+!moments.js
+!reader-sessions.js
 !public/
 !public/**
 !greatest/
@@ -22,6 +24,8 @@
 !scraper/**
 !peering/
 !peering/**
+!perf/
+!perf/**
 !tools/
 !tools/**
 scraper/.cache/**

.env.example

@@ -20,6 +20,10 @@ READING_TIMEZONE=UTC
 READING_QUIZ_UNLOCK_MINUTES=60
 # Optional deployment-managed JSON file under DATA_PATH, e.g. /data/reading-quiz.json.
 # READING_QUIZ_CATALOG_PATH=/data/reading-quiz.json
+# Read an opened chapter into the OS cache ahead of the browser (1 = on, the default); see docs/performance.md.
+# READ_AHEAD=1
+# Performance trace from the start (also switchable at runtime: touch DATA_PATH/perf/trace.on).
+# PERF_TRACE=0
 PROXY_NETWORK=mangacircus-edge
 # Extra Compose files, ':'-separated (docs/deployment.md), e.g. HTTPS with the bundled Caddy:
 # COMPOSE_FILE=docker-compose.yml:deploy/compose.https.yml

AGENTS.md

@@ -12,6 +12,7 @@ Guide for contributors and coding agents. Users who only want to run it: [docs/d
 | `scraper/` | Download queue daemon (`service.js`, `daemon.js`), source adapters and parsers, the publisher that writes the library, metadata lookups |
 | `peering/` | Optional server-to-server sharing (gateway, client, adapter) |
 | `runtime/` | In-container supervisor and configuration |
+| `perf/` | Switchable performance trace and chapter read-ahead ([docs/performance.md](docs/performance.md)) |
 | `discovery/`, `greatest/` | Discovery Scout and the Greatest of All Time dashboard |
 | `tools/` | Demo library, health checks, maintenance tools (dry run by default), UI and Compose test drivers |
 | `deploy/` | `circus.sh` operations helper, HTTPS with Caddy |

Dockerfile

@@ -3,7 +3,7 @@ RUN apk add --no-cache tzdata openssl
 WORKDIR /app
 ARG VCS_REF=development
 LABEL org.opencontainers.image.title="MangaCircus" org.opencontainers.image.revision=$VCS_REF
-COPY package.json server.js library.js reading-direction.js chapter-identity.js chapter-dates.js reading-analytics.js reading-access.js catalog.js backup.js ./
+COPY package.json server.js library.js reading-direction.js chapter-identity.js chapter-dates.js reading-analytics.js reading-access.js catalog.js backup.js moments.js reader-sessions.js ./
 COPY public ./public
 COPY greatest ./greatest
 COPY discovery ./discovery
@@ -11,6 +11,7 @@ COPY tools ./tools
 COPY scraper ./scraper
 COPY peering ./peering
 COPY runtime ./runtime
+COPY perf ./perf
 RUN mkdir -p /library /data && chown node:node /data /library
 ENV PORT=8080 LIBRARY=/library DATA=/data TZ=UTC
 EXPOSE 8080

README.md

@@ -50,6 +50,10 @@ Settings has **User** and **Admin** menu groups. User sections cover Reading, Re
 Notifications and Account. Admin sections cover Scraper, Server & library, Users & access, Collections &
 metadata and Service health. Only admins see administration ([settings navigation](docs/settings-navigation.md)).
 
+Reader settings (mode, zoom, page tone, skipping) are kept per sign-in: each device or browser keeps its own once you
+change one there, and a new sign-in starts from the one you used last. **Settings → Reading → Reader settings per
+session** shows every session's state and turns this off for one shared set ([details](docs/architecture.md#67-reader-settings-per-session)).
+
 ### Settings (environment variables)
 
 These configure the reader process. In Docker most are set for you by `docker-compose.yml`; the variables
@@ -63,6 +67,8 @@ you put in `.env` are listed in [docs/deployment.md](docs/deployment.md#4-config
 | `SIGNUP`        | `closed`    | `open` lets anyone create an account. Otherwise the admin adds users under Settings |
 | `SCAN_INTERVAL` | `10`        | Minutes between shallow library change checks (`0` disables this timer) |
 | `FULL_SCAN_INTERVAL` | `1440` | Minutes between full library reconciliations (`0` disables this timer) |
+| `READ_AHEAD` | `1` | Read an opened chapter's pages (then the next chapter's) into the OS cache ahead of the browser; `0` = off ([docs/performance.md](docs/performance.md)) |
+| `PERF_TRACE` | `0` | `1` = performance trace from the start; it can also be switched at runtime with the file `DATA/perf/trace.on` ([docs/performance.md](docs/performance.md)) |
 | `SCAN_CONCURRENCY` | `8` | Chapter folders and images probed at once by an uncached scan (1–64); higher helps on network storage |
 | `COOKIE_SECURE` | –           | `1` marks the login cookie `Secure` (use it when you serve over HTTPS) |
 | `SCRAPER_URL`   | `http://127.0.0.1:8091` | Private scraper daemon URL |
@@ -142,6 +148,7 @@ completeness.
 - **Flow page gap:** Settings → Reading lets each user keep the normal separator between Flow pages or remove it for continuous webtoon artwork and text that crosses image edges.
 - **Page tone:** the reader's **Tone** button cycles Original → Inverted → Sepia → Dim → Extra dim in Flow, Page and Book. It changes only the artwork, never the controls or site theme. The choice is saved per user; it can also be selected in Settings → User → Reading.
 - **Active Reading Clock:** opt in under Settings → User → Reading time & privacy. No scrolling-speed limit; a visit counts at 60% viewed-page coverage and saves on exit. Pauses in the background or after 30 seconds without reader activity. Tap the clock for this visit's time, coverage, qualification and loading wait.
+- **Continue where you left off:** the first line of the library content (below the search, filters and tags) is one row of the five manga you read most recently and have not finished (same tiles as the grid; they stay in the grid too). It hides while a search is typed, a status filter is set, or the library is sorted by *Recently read*; tags and collection grouping do not affect it. Turn it off under Settings → User → Reading → *Library page*.
 - **Your Reading Story:** private active-time summaries appear on the library and manga pages when history exists. Chapter rows show the last timed read (60%-coverage visit), rereads remain visible as lifetime time, and Settings lets each user hide, export, or delete their own history. No leaderboards or speed ranking are used.
 - **Tap / click zones:**
   - Tapping **beside the pages** always shows or hides the controls.
@@ -149,8 +156,9 @@ completeness.
   - In Flow: the bottom part of the screen goes forward, the top part goes back.
   - The middle of the page also toggles the controls (useful when a zoomed page fills the screen).
   - A horizontal swipe also turns pages on touch screens.
-  - Keys: arrows, Space / PageDown, `m` = controls, `f` = fullscreen.
-- **Controls stay out of the way:** they hide as soon as you turn a page or scroll, and come back only with a tap (middle of the page or beside it). Scrolling up never brings them back. The first time they hide, a short hint says so.
+  - Keys: arrows, Space / PageDown, `i` = controls, `m` = save a moment, `f` = fullscreen, `?` = all shortcuts (also under Settings → User → Keyboard shortcuts).
+- **Moments:** the bookmark button in the top bar (or `m`) saves the page you are on (in Book mode the spread) as a moment. A picture that runs over several pages can take up to four: *+ Previous page* / *+ Next page* add them, stacked in Flow and side by side in Page and Book. Drag over the preview to keep only a region (pages it doesn't touch are left out), and pick exactly one category: Twist, Hot, Awesome, Cute, Funny or Feels, plus an optional note. The button is filled on pages that already have one. Each manga page shows *Your moments* as a strip of crops, sorted by story or by when you saved them; click one to step through them, see the full page, edit, delete or jump into the reader at that page. Moments are private to each user.
+- **Controls stay out of the way:** they hide as soon as you turn a page or scroll, and come back only with a tap (middle of the page or beside it) or `i`. Scrolling up never brings them back. The first time they hide, a short hint says so.
 - **Controls:** the top bar has a chapter picker with every chapter of the manga, grouped by book, with ✓ for read ones. The bottom bar has the page slider, the mode switch, Shift, zoom, the version picker and previous/next chapter.
 - **Loading:** the next pages (next 3 in Page mode, next 2 spreads in Book mode) are downloaded and decoded in advance, so page turns don't flash. A page that still isn't there shows a spinner. On phones, "Add to home screen" opens the app without browser bars, and the ⛶ button (where supported) goes fullscreen.
 - **Progress** is saved per user and chapter version: the last page, whether the chapter is done, and book-mode shifts. The manga page offers *Continue*. Tap a chapter's status to mark it read/unread.

docker-compose.yml

@@ -60,6 +60,9 @@ services:
       SCRAPER_TOKEN_FILE: /run/secrets/scraper_token
       DISCOVERY_HARVEST_AT: ${DISCOVERY_HARVEST_AT:-03:30}
       DISCOVERY_ANILIST_URL: ${DISCOVERY_ANILIST_URL:-}
+      GREATEST_COVER_WARM: ${GREATEST_COVER_WARM:-1}
+      READ_AHEAD: ${READ_AHEAD:-1}
+      PERF_TRACE: ${PERF_TRACE:-0}
     networks: [backend, egress]
     healthcheck:
       test: [CMD, node, tools/healthcheck.js, reader]

docs/architecture.md

@@ -128,12 +128,16 @@ This keeps ids human-readable and derivable without a database. The price: renam
         "flowPageGap": true,            // show the 8 px separator between pages in Flow
         "readingClock": false,           // opt in to credible per-chapter active-time tracking
         "readingStory": true,            // show private retrospective summaries when history exists
+        "continueRow": true,             // library: "Continue where you left off" row at the top
         "zoom": { "flow": 1, "page": 1.5, "book": 1, "strip": 0.8 },   // page zoom per mode
-        "webhook": ""
-      }
+        "webhook": "",
+        "readerPerSession": true        // reader settings per login session (section 6.7)
+      },
+      "readerFrom": "3f9c…"            // public id of the session the latest reader settings came from
     }
   },
-  "sessions":  { "<sha256 of token>": { "u": "admin", "t": 1790796794000 } },
+  "sessions":  { "<sha256 of token>": { "u": "admin", "t": 1790796794000, "seen": 1790796794000,
+                  "agent": "<User-Agent>", "reader": { …locked reader settings, only after a change… } } },
   "progress":  { "admin": { "Moon Garden": { "1/2": {
                   "v": "c0002 Roots [MangaDex]",  // version read
                   "p": 4, "n": 14,                // page index in that version (all pages), page count
@@ -150,6 +154,11 @@ This keeps ids human-readable and derivable without a database. The price: renam
   "follows":   { "admin": { "Moon Garden": true } },
   "notes":     { "admin": [ { "id": "a1b2c3d4e5f6", "t": 1790797300000, "m": "Moon Garden", "c": "2/6",
                               "text": "Moon Garden · Ch. 6: Frost", "read": false } ] },
+  "moments":   { "admin": [ { "id": "9f1c2b3a4d5e", "m": "Moon Garden", "c": "1/2", "v": "c0002 Roots [MangaDex]",
+                              "i": [4], "f": ["0005.png"], "sha": ["<sha256 of the file>"],   // 1–4 pages in displayed order
+                              "layout": "row",                                                // "row" side by side (Page/Book), "column" stacked (Flow)
+                              "region": { "x": 0.1, "y": 0.5, "w": 0.5, "h": 0.25 },          // fractions of the pages put together; null = all
+                              "cat": "awesome", "note": "", "t": 1790797400000 } ] },
   "votes":     { "Moon Garden": { "1/2": { "c0002 Roots [Official]": { "admin": 1, "reader": -1 } } } },
   "known":     { "Moon Garden": ["1/1", "1/2", "1/2.5", "..."] }   // every chapter id ever seen (append-only)
 }
@@ -171,7 +180,7 @@ This keeps ids human-readable and derivable without a database. The price: renam
 
 | Path | Handling |
 |------|----------|
-| `/api/*` | `routes["<METHOD> <path>"]`. Handlers get `{ u, b, q, req, res }` and return an object, which is sent as JSON. Throwing `HttpError(code, message, extra)` sends `{ error, ...extra }` with that status (for example `nextAllowedAt` on a discovery `429`) |
+| `/api/*` | `routes["<METHOD> <path>"]`. Handlers get `{ u, b, q, req, res, sess, sk }` (`sess` = the login session record, `sk` its key) and return an object, which is sent as JSON. Throwing `HttpError(code, message, extra)` sends `{ error, ...extra }` with that status (for example `nextAllowedAt` on a discovery `429`) |
 | `/lib/*` | Image files from `LIBRARY`. Requires a session, allows image extensions only, and the path must resolve inside `LIBRARY`. `ETag` + `private, max-age=86400` |
 | everything else | Static files from `public/` (`/` → `index.html`). `ETag` + `no-cache` |
 
@@ -188,7 +197,9 @@ All requests and responses are JSON. POSTs require `Content-Type: application/js
 | `POST /api/login` `{name, password}` | public | Starts a session (cookie `sid`) |
 | `POST /api/logout` | user | Ends the session |
 | `GET /api/me` | user | Name, admin flag, settings, unread count |
-| `POST /api/settings` `{…partial}` | user | Validated update of the settings keys above |
+| `POST /api/settings` `{…partial}` | user | Validated update of the settings keys above; reader keys go to the current session (6.7) |
+| `GET /api/reader-sessions` | user | `{ enabled, current, latestFrom, latest, sessions: [{ id, device, created, seen, current, locked, reader }] }` |
+| `POST /api/reader-sessions` `{id, action}` | user | `follow`: the session drops its own reader settings and follows the latest; `latest`: its settings become the latest |
 | `POST /api/password` `{old, new}` | user | Change password |
 | `GET /api/library` | user | Manga list with covers, counts, the user's read count, unread notifications, last read, and optional personal Reading Story aggregates |
 | `GET /api/manga?m=` | user | Manga details, books, chapters with ranked versions, progress, optional chapter-time summaries, and `continue` target |
@@ -200,13 +211,18 @@ All requests and responses are JSON. POSTs require `Content-Type: application/js
 | `POST /api/unread` `{m, c}` | user | Forget progress for a chapter |
 | `POST /api/vote` `{m, c, v, value: 1\|-1\|0}` | user | Vote a version; returns the re-ranked versions |
 | `POST /api/follow` `{m, on}` | user | Follow a manga for notifications |
+| `GET /api/moments?m=` | user | The caller's moments of that manga in story order: category, note, region, chapter, `order`, page images, `missing` when a page file is gone. `/api/chapter` also lists the caller's moments on the opened version |
+| `POST /api/moments` `{m, c, v, pages, layout, region, cat, note}` | user | Save a moment: `pages` are 1–4 distinct indexes in displayed order, `layout` `row` (default) or `column`, `cat` one of `twist hot awesome cute funny feels` (required), `region` fractions of the pages put together, or null |
+| `POST /api/moments/update` `{id, cat?, region?, note?}` · `POST /api/moments/delete` `{id}` | user | Edit or delete one of the caller's own moments (another user's id is `404`) |
 | `GET /api/notifications` · `POST /api/notifications/read` `{id \| all}` | user | Notification list and read state |
+| `POST /api/perf` `{page, events: […]}` | user | Browser timings for the performance trace; ignored with `{on: false}` while the trace is off. `/api/chapter` returns `perf: true` while it is on ([performance.md](performance.md)) |
 | `GET /api/admin` | admin | Users, last scan result, library path |
 | `POST /api/admin/rescan` `{full}` | admin | Scan now, and wait for the result |
 | `POST /api/admin/user` `{name, password, admin}` | admin | Create a user or reset a password |
 | `POST /api/admin/user/role` `{name, admin}` | admin | Grant or revoke admin rights; keeps the password and sessions. Revoking your own rights is refused, so one admin always remains |
 | `POST /api/admin/user/delete` `{name}` | admin | Delete a user and their data |
 | `GET /api/admin/backup` · `POST /api/admin/backup` `{command:"settings"\|"run"}` | admin | Built-in backup status, schedule/retention, "back up now" ([backup.md](backup.md)) |
+| `GET /api/greatest-cover?id=<entry>&v=<version>` | user | The Greatest entry's cover from `data/greatest-covers/` (`greatest/covers.js`), cached by the browser for a year; `v` changes with the catalog URL. A `302` to the catalog URL until the copy exists. `/api/greatest` lists this URL as `cover` for titles not in the library |
 | `GET /api/discovery` | user | The caller's discovery feed, settings, feedback and `refresh: { state: idle\|queued\|running, position?, nextAllowedAt?, blockedReason? }` (§6.6) |
 | `POST /api/discovery/feedback` `{candidateId, value}` | user | The caller's choice for a candidate; requires opt-in |
 | `POST /api/discovery/refresh` | user | Queue a per-user AniList harvest for the caller (opt-in required, else `403`). `{ harvestId, position }`; `409` while one is queued or running for the caller; `429 { nextAllowedAt }` within an hour of the last accepted refresh; `503 { blockedReason }` after AniList pushed back, until a nightly or admin harvest |
@@ -258,6 +274,22 @@ The reader alone talks to AniList for discovery ([discovery.md](discovery.md)).
   (all reasons, strongest first) next to `reason`; seed evidence carries `fetchedAt`.
 - `DISCOVERY_ANILIST_URL` overrides the AniList endpoint (tests point it at a local fixture server).
 
+### 6.7 Reader settings per session
+
+The reader keys (`startMode`, `lastMode`, `adapt`, `skipExtras`, `skipCovers`, `flowPageGap`, `pageTone`, `zoom`)
+can differ per login session, so a phone and a desktop keep their own mode and zoom (`reader-sessions.js`):
+
+- `user.settings` holds the **latest** reader set. A session without its own set follows it.
+- The first reader change in a session copies the latest set into `session.reader` with the change applied: the session
+  is now **locked** and keeps that set whatever other sessions do. The change also becomes the latest set.
+- Loading a page (`GET /api/me`) from a locked session makes its set the latest again, so a new sign-in starts from the
+  session used last. A new sign-in has no set of its own until it changes something.
+- Other settings (Reading Story, dates, discovery, webhook, …) stay per user.
+- `readerPerSession: false` (Settings → Reading) brings back one shared set: changes go to `user.settings` and apply to
+  every session. Locked sets are kept and apply again when the switch is turned back on.
+
+Settings → Reading → *Reader settings per session* lists the user's sessions (device from the User-Agent, sign-in and last
+activity, own or following) with "Follow latest again" and "Use for new sessions".
 ## 7. Frontend
 
 ### 7.1 Pages
@@ -321,12 +353,12 @@ mode       = adapt && intended ∉ compatible ? compatible[0] : intended
 | Horizontal swipe ≥ 50 px within 800 ms (paged, not zoomed in) | Previous/next |
 | Ctrl + wheel, touchpad pinch, Safari gesture events, two-finger pinch | Continuous page zoom 20–600 %, snapping to 100 % within ±1 %, anchored at the pointer or finger midpoint. Browser zoom is suppressed only over the pages |
 | Mouse drag (moved ≥ 6 px) | Pan; the following click is swallowed. Hand cursor when the content is larger than the screen |
-| Keys | Arrows follow the direction; Space/PageDown/PageUp (paged); `+` and `-` zoom in 5-percentage-point steps, `0` fits at 100 %; `m`/Esc bars; `f` fullscreen |
+| Keys | Dispatched through `READER_KEYS` in `public/keys.js`, which also feeds Settings → Keyboard shortcuts and the reader's `?` list. Arrows follow the direction; Space/PageDown/PageUp (paged); `+` and `-` zoom in 5-percentage-point steps, `0` fits at 100 %; `m` saves a moment; `i`/Esc bars; `f` fullscreen; `?` shortcuts |
 
 **Bars:**
 - Shown on open.
 - Hidden on the first page turn or after 100 px of scrolling. The first automatic hide (per device, once for Flow and once for Page/Book) shows a hint on how to get them back.
-- **Never shown by scrolling**, only by a tap beside the pages or in the middle of a page (or `m`). Showing them stops a running smooth scroll, so it can't hide them again right away.
+- **Never shown by scrolling**, only by a tap beside the pages or in the middle of a page (or `i`). Showing them stops a running smooth scroll, so it can't hide them again right away.
 - The top bar has the chapter picker (every chapter, grouped by book, ✓ = read).
 
 **Loading:**
@@ -350,6 +382,8 @@ mode       = adapt && intended ∉ compatible ? compatible[0] : intended
 - Pulses are sent at most every 10 seconds and on pause/page exit. The server validates the manga/chapter/version and page indices, de-duplicates `(session, seq)`, clamps time to server-observed intervals and stores compact page ranges separately from ordinary progress.
 - The bottom toolbar chip shows active time and the current state; its panel adds pass time, verified pages, predominant input and loading wait.
 
+**Moments** (`public/moments.js`): the top bar's bookmark button (or `m`) opens a sheet for the page(s) on screen: in Flow the page at the reading line, in Book the spread. "+ Previous page" / "+ Next page" add neighbours (up to four pages) for a picture that runs over several pages: stacked in Flow (`column`), side by side in Page and Book (`row`, right to left for `rtl`). A rectangle dragged over the preview keeps only that region, and pages it does not touch are left out. Exactly one category is required. The button is filled when the page already has a moment. The manga page shows the user's moments as a strip of crops (sort by story or by date saved, category filters from five moments), with a viewer to step through them, edit, delete or open the reader at `read.html?…&p=<page index>`. Crops position the full page images inside a clipping box; nothing is generated on the server.
+
 **Zoom persistence:** per mode key (`flow`, `page`, `book`, `strip`), saved 800 ms after the last change.
 
 ## 8. Deployment
@@ -388,6 +422,7 @@ docker compose up -d --build
 | User data | `db.json` is rewritten as a whole, at most about twice per second while people read. Comfortable up to a few MB (a household or small group, thousands of chapters read) |
 | Concurrency | One process, one writer. No clustering or horizontal scaling by design |
 | Images | Served as stored. No resizing or thumbnails, so large covers make the library page heavy |
+| Slow storage | Opening a chapter reads its pages (then the next chapter's) into the OS cache, two at a time (`READ_AHEAD`). Where the time goes: [performance.md](performance.md) |
 
 ## 10. Design decisions
 

docs/deployment.md

@@ -21,7 +21,7 @@ Data on the host, all bind mounts (no named volumes):
 | Path (`.env`) | Contents | Back up? |
 |---|---|---|
 | `LIBRARY_PATH` | The manga: `Manga/Book/Chapter/images` ([library-format.md](library-format.md)) | Yes, it is your collection |
-| `DATA_PATH` | `db.json` (users, progress, votes), catalog, discovery feeds, library index cache | Yes (built-in backup, section 8). `discovery-cache/` inside it is safe to delete and may be left out of backups: the next harvest rebuilds it |
+| `DATA_PATH` | `db.json` (users, progress, votes), catalog, discovery feeds, library index cache | Yes (built-in backup, section 8). `discovery-cache/` inside it is safe to delete and may be left out of backups: the next harvest rebuilds it. The same holds for `greatest-covers/` (local copies of the Greatest catalog's cover images, fetched again after the next start) |
 | `SCRAPER_DATA_PATH` | Queue, settings, source ledger, metadata cache | Included in the built-in backup |
 | `BACKUP_PATH` | Built-in backup archives | Keep it on another disk or NAS |
 | `SCRAPER_TOKEN_PATH` | Shared secret between reader and scraper | Regenerate if lost |
@@ -71,6 +71,7 @@ demo manga in an empty library after the build in section 5:
 | `READING_WINDOWS_JSON`, `READING_TIMEZONE`, `READING_QUIZ_*` | off | Optional server-enforced reading hours ([reading-limiter.md](reading-limiter.md)) |
 | `DISCOVERY_HARVEST_AT` | `03:30` | Daily time (`HH:MM`) of the nightly Discover harvest from AniList, in the container's local time zone (`TZ`). Only users who opted in are harvested; the admin can change the time or switch it off on the Discover page ([discovery.md](discovery.md)) |
 | `DISCOVERY_ANILIST_URL` | AniList's public API | Tests only: points the discovery harvest at a fixture server. Leave unset in production |
+| `GREATEST_COVER_WARM` | `1` | `0` stops the reader from downloading the Greatest catalog's covers (about 100 images, one per second, 10 s after start and once a day for missing ones). Tests and offline installs set `0`; the page then loads covers from the catalog's own URLs |
 | `APP_IMAGE`, `VCS_REF` | `mangacircus:local`, `development` | Image to run; set a pinned registry image to deploy prebuilt releases (section 7) |
 | `COMPOSE_FILE` | `docker-compose.yml` | Extra Compose files, `:`-separated (e.g. `docker-compose.yml:deploy/compose.https.yml`) |
 | `MANGACIRCUS_DOMAIN` | – | Host name for `deploy/compose.https.yml` |

docs/greatest.md

@@ -23,7 +23,7 @@ Within each cohort, **Rank by my vote** sorts flame → good → neutral → sku
 
 The one-time seed is curated from the research document. All 106 catalog entries now have a cover URL. Most were matched to public AniList manga metadata; the five initial gaps were checked individually. Phoenix (1954) and Nausicaä use matching AniList records; Kitarō uses Drawn & Quarterly's Kitaro edition, Someone Hertz uses Shonen Jump's first-volume cover, and Hitoner uses Shueisha's 2026 first-volume cover. Hitoner's AniList 2024 entry represents an earlier work, so it was **not** used for the 2026 series. The five added URLs returned image content on 2026-10-09, but remote hosts can change them; the UI still shows a title-letter fallback if an image fails.
 
-`node tools/enrich-greatest-catalog.js` is an **optional manual** public-AniList metadata refresh, paced at one request every 1.5 seconds. It only accepts matching manga title and **original serialization year**, leaving uncertain results untouched rather than using a sequel or remake cover. The dashboard makes **no metadata calls when loading**; only an admin pressing **Search MangaDex** triggers a bounded lookup. Browser covers are lazy-loaded from their listed source; local library covers take precedence.
+`node tools/enrich-greatest-catalog.js` is an **optional manual** public-AniList metadata refresh, paced at one request every 1.5 seconds. It only accepts matching manga title and **original serialization year**, leaving uncertain results untouched rather than using a sequel or remake cover. The dashboard makes **no metadata calls when loading**; only an admin pressing **Search MangaDex** triggers a bounded lookup. Local library covers take precedence. For the rest, the reader keeps its own copy of each catalog cover in `data/greatest-covers/` (`greatest/covers.js`): it downloads missing ones one at a time, about one a second, 10 seconds after start and once a day, stops on HTTP 401/403/429, and accepts only JPEG/PNG/WebP/GIF/AVIF images up to 2 MB from the catalog's own HTTPS URLs. The page loads covers from `/api/greatest-cover`, which the browser caches for a year; until a copy exists that route redirects to the catalog URL. Hotlinking about 100 covers per page load made the image CDN drop some of them at random. `GREATEST_COVER_WARM=0` switches the downloads off.
 
 Public catalog chapter counts are often absent; the UI says “Chapters unknown” rather than inventing one. For owned titles, the local library count wins. Status comes from AniList's releasing/finished flag or local library metadata, and may be unknown. Official source links may be publisher editions, chapter services, or an award/info lead; they do not imply all chapters are available in every country. No unverified hoster coverage is claimed.
 

docs/performance.md

@@ -0,0 +1,78 @@
+# Performance trace, load test and read-ahead
+
+When pages load slowly, the trace shows where the time goes: the storage (a NAS, a disk waking up), the
+reader process (CPU, event loop), library scans running at the same time, or the network to the browser.
+
+## Switching the trace on and off
+
+No restart is needed. The reader checks for a flag file every 5 seconds:
+
+```bash
+touch "$DATA/perf/trace.on"     # on   (Docker: the data folder mounted at /data)
+rm "$DATA/perf/trace.on"        # off
+```
+
+`PERF_TRACE=1` in the environment keeps it on from the start. While it is off, the reader does no extra work.
+
+The trace goes to `DATA/perf/trace-YYYY-MM-DD.jsonl` (UTC days), one JSON object per line. Files older than
+14 days are deleted; one day stops growing at 256 MB. The file contains request paths (manga and chapter
+names) and user names, so treat it like the rest of `DATA`.
+
+## What is recorded
+
+Every line has `t` (server time, ms since the epoch) and `k` (kind):
+
+| `k` | Fields | Meaning |
+|---|---|---|
+| `req` | `m`, `path`, `status`, `ms`, `bytes`, `conn`, `aborted`; for files `stat`, `open`, `first`, `readEnd`, `disk`, `netWait`; for pages also `access` | One HTTP request. Phase fields are ms since the request arrived: `stat` file lookup done, `open` file opened, `first` first chunk read, `readEnd` last chunk read. `disk` = time spent waiting for the storage, `netWait` = time the file stream was paused because the client did not take data fast enough. `conn` > 1 means a reused keep-alive connection |
+| `client` | `e`: `hello`, `res`, `view`, `stall` | Reported by the reader page while the trace is on (`public/perf.js`). `res`: the browser's resource timing of a page image (`queue`, `dns`, `connect`, `ttfb`, `download`, `total`, `size`, `server` = the reader's `stat` time, `cached`). `view`: a page turn in page/book mode, `wait` until the new page was decoded and painted, `preloaded`. `stall`: flow mode, a page on screen before its image, `wait` until it loaded. `hello`: browser, viewport, connection type |
+| `nas` | `statMs`, `firstMs`, `ms`, `bytes` or `error` | Every `PERF_NAS_PROBE_SECONDS` (60) one random library page is read. Out of a large library it is almost never cached, so this is the storage's cold latency over time; seconds after a quiet period mean disks were in standby |
+| `loop` | `lagP50`, `lagP99`, `lagMax`, `cpu`, `rss`, `heap` | Every 5 s: event-loop delay (ms), CPU % of one core, memory (MB) |
+| `scan` | `mode`, `ms`, `changed` | Library scans (change checks every `SCAN_INTERVAL`, full reconciliations) |
+| `ahead` | `tag`, `files`, `done`, `skipped`, `bytes`, `ms`, `replaced` | A read-ahead batch (below) |
+| `scraper` | `endpoint`, `ms`, `status`/`error` | Calls from the reader to the scraper daemon |
+| `trace` | `on` | The trace was switched on or off |
+
+## Reading the result
+
+```bash
+node tools/perf-report.js "$DATA/perf"                          # all days
+node tools/perf-report.js "$DATA/perf" --since 2026-10-29T18:00Z --slow 300
+docker compose exec reader node tools/perf-report.js /data/perf  # inside the container
+```
+
+The report starts with a verdict (which phase dominates the slow loads), then percentiles for the server's
+phases, the browser's timings, page turns, flow stalls, the storage probe, the event loop, scans, read-ahead
+and the API routes. `--json` prints the same numbers for scripts and agents.
+
+How to read it:
+
+- **Slow `firstRead` / `readRest`, slow `nas` probes**: the storage is slow. Probes of several seconds after
+  minutes without reads point at disk standby (on a Synology: *Control Panel → Hardware & Power → HDD
+  Hibernation*).
+- **Slow `stat`**: metadata lookups on the storage are slow (often during a scan, see `scan`).
+- **High `netWait`, or browser `download` much longer than the server's `ms`**: the network between server
+  and browser (Wi-Fi, VPN, a proxy).
+- **Browser `queue`**: the browser waited for a free connection (too many parallel requests).
+- **High `lagMax`**: the reader process was busy and could not answer.
+
+## Load test
+
+`tools/perf-bench.js` simulates readers paging through random chapters with a think time and a small
+look-ahead, and reports how long a reader looked at an empty page (`wait`), time to first byte and total
+per page. It only reads (no progress is written). Use a separate account:
+
+```bash
+BENCH_PASSWORD=… node tools/perf-bench.js --url http://server:8080 --user bench --password-env BENCH_PASSWORD \
+  --readers 4 --chapters 3 --pages 40 --think 400 --ahead 2
+```
+
+Run it with the trace on to see the server's side of the same requests.
+
+## Read-ahead
+
+`READ_AHEAD=1` (default): when a chapter is opened, the reader reads its pages once in page order, starting
+at the saved page, two at a time, and then the next chapter's. The data is thrown away; the OS page cache
+keeps it, so the browser's requests are answered from memory instead of the storage. Opening another
+chapter replaces whatever is still queued. `READ_AHEAD=0` turns it off (useful on a local SSD, or to compare
+with the trace).

docs/scraper-service.md

@@ -199,7 +199,8 @@ All responses are JSON. When `SCRAPER_TOKEN` is set, send
 | Method | Path | Body / result |
 |---|---|---|
 | `GET` | `/health` | Basic liveness |
-| `GET` | `/api/state` | Queue, all active source checkpoints, settings, errors, history, adapters |
+| `GET` | `/api/state` | Queue, all active source checkpoints, settings, errors, history, adapters. The library summary in it is rebuilt in the background after a publish, or when it is 15 minutes old (the walk reads every `chapter.json`) |
+| `GET` | `/api/revision` | `{ publishedRevision, status, paused }` only; the reader polls this every 15 s |
 | `POST` | `/api/queue` | `{url,title?,metadataSearch?,scope?,existingPolicy?,libraryMangaId?,inspect?}` |
 | `POST` | `/api/queue/remove` | `{id}`; active downloads cannot be removed |
 | `POST` | `/api/queue/clear-completed` | `{source?}`; remove inactive successful download job rows only; preserve library, history, checkpoints and other statuses |

greatest/covers.js

@@ -0,0 +1,73 @@
+'use strict';
+
+// Local copies of the Greatest catalog's cover images. Hotlinking ~100 covers per page
+// load makes the image CDN drop some of them at random; one polite download each fixes that.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const TYPES = { 'image/jpeg': '.jpg', 'image/png': '.png', 'image/webp': '.webp', 'image/gif': '.gif', 'image/avif': '.avif' };
+const EXTENSIONS = new Set(Object.values(TYPES));
+const USER_AGENT = 'MangaCircus-Greatest/1.0';
+
+class GreatestCovers {
+  constructor(dir, { fetchImpl = fetch, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
+    delayMs = 1000, maxBytes = 2 * 1024 * 1024, timeoutMs = 20000 } = {}) {
+    this.dir = path.resolve(dir);
+    Object.assign(this, { fetchImpl, sleep, delayMs, maxBytes, timeoutMs });
+    this.files = new Map(); // key -> file name
+    try {
+      for (const name of fs.readdirSync(this.dir)) {
+        const ext = path.extname(name);
+        if (EXTENSIONS.has(ext)) this.files.set(path.basename(name, ext), name);
+      }
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  // A hash of the URL names the file, so a changed catalog URL is fetched again.
+  version(url) { return crypto.createHash('sha256').update(String(url)).digest('hex').slice(0, 16); }
+  file(url) {
+    const name = url ? this.files.get(this.version(url)) : null;
+    return name ? path.join(this.dir, name) : null;
+  }
+  // Sequential, paced, and stops on 403/429 like every other outbound client here.
+  async warm(urls) {
+    const result = { fetched: 0, skipped: 0, failed: 0, stopped: null };
+    let requested = false;
+    for (const url of new Set(urls.filter(url => /^https:\/\/\S+$/i.test(String(url || ''))))) {
+      if (this.file(url)) { result.skipped++; continue; }
+      if (requested) await this.sleep(this.delayMs);
+      requested = true;
+      try {
+        await this.download(url);
+        result.fetched++;
+      } catch (error) {
+        if (error.stop) { result.stopped = error.message; break; }
+        result.failed++;
+      }
+    }
+    // Duplicates and repeats of stored covers count as skipped.
+    result.skipped += urls.filter(Boolean).length - new Set(urls.filter(Boolean)).size;
+    return result;
+  }
+  async download(url) {
+    const response = await this.fetchImpl(url, { headers: { 'user-agent': USER_AGENT },
+      signal: AbortSignal.timeout(this.timeoutMs) });
+    if ([401, 403, 429].includes(response.status)) throw Object.assign(new Error(`HTTP ${response.status}`), { stop: true });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const ext = TYPES[String(response.headers.get('content-type') || '').split(';')[0].trim().toLowerCase()];
+    if (!ext) throw new Error('Not an image');
+    if (Number(response.headers.get('content-length')) > this.maxBytes) throw new Error('Image too large');
+    const body = Buffer.from(await response.arrayBuffer());
+    if (!body.length || body.length > this.maxBytes) throw new Error('Image too large or empty');
+    const key = this.version(url), name = key + ext;
+    fs.mkdirSync(this.dir, { recursive: true });
+    const temp = path.join(this.dir, `.${key}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+    try {
+      fs.writeFileSync(temp, body);
+      fs.renameSync(temp, path.join(this.dir, name));
+    } finally { fs.rmSync(temp, { force: true }); }
+    this.files.set(key, name);
+  }
+}
+
+module.exports = { GreatestCovers };

moments.js

@@ -0,0 +1,77 @@
+'use strict';
+/*
+ * Moments: a page, or a region across up to four neighbouring pages, that a reader saved with exactly one category.
+ * `layout` says how those pages sit together: side by side ("row", Page and Book mode) or stacked ("column", Flow).
+ * Stored per user in db.moments[user] as a list. A moment points at its pages by version folder and file
+ * name (plus the file's SHA-256 for a later relocation), so a re-scan that shifts page numbers never makes it
+ * point at the wrong picture: a file that is gone shows as "page moved" instead.
+ */
+const CATEGORIES = ['twist', 'hot', 'awesome', 'cute', 'funny', 'feels'];
+const NOTE_MAX = 200, MAX_PER_USER = 5000, MAX_PAGES = 4, LAYOUTS = ['row', 'column'];
+
+class MomentError extends Error { constructor(msg) { super(msg); this.code = 400; } }
+const fail = msg => { throw new MomentError(msg); };
+
+const clamp01 = x => Math.min(1, Math.max(0, x));
+// A region is a rectangle in fractions (0–1) of the displayed page, or of all its pages put together in `layout`.
+// Nothing or a rectangle covering (almost) everything means the whole page.
+function cleanRegion(r) {
+  if (r == null) return null;
+  const n = ['x', 'y', 'w', 'h'].map(k => Number(r[k]));
+  if (n.some(v => !Number.isFinite(v))) fail('Invalid region.');
+  const x = clamp01(n[0]), y = clamp01(n[1]), w = clamp01(Math.min(n[2], 1 - x)), h = clamp01(Math.min(n[3], 1 - y));
+  if (w < 0.01 || h < 0.01) fail('The selected region is too small.');
+  if (w > 0.995 && h > 0.995) return null;
+  const round = v => Math.round(v * 1e4) / 1e4;
+  return { x: round(x), y: round(y), w: round(w), h: round(h) };
+}
+function cleanCategory(cat) {
+  return CATEGORIES.includes(cat) ? cat : fail('Pick one category: ' + CATEGORIES.join(', ') + '.');
+}
+const cleanNote = note => String(note == null ? '' : note).replace(/\s+/g, ' ').trim().slice(0, NOTE_MAX);
+
+// Page indexes (into the version's full page list) in displayed order: left to right, or top to bottom.
+function cleanPages(pages, version) {
+  if (!Array.isArray(pages) || pages.length < 1 || pages.length > MAX_PAGES) fail(`A moment covers 1 to ${MAX_PAGES} pages.`);
+  const out = pages.map(Number);
+  if (out.some(i => !Number.isInteger(i) || i < 0 || i >= version.pages.length)) fail('Page not found.');
+  if (new Set(out).size !== out.length) fail('A page appears twice.');
+  return out;
+}
+const cleanLayout = layout => (layout == null ? 'row' : LAYOUTS.includes(layout) ? layout : fail('Invalid page layout.'));
+
+// Where a stored moment's pages are now. Returns null when the chapter, the version or a page file is gone.
+function locate(moment, manga) {
+  const chapter = manga && manga.chapterById.get(moment.c), version = chapter && chapter.versions.find(v => v.id === moment.v);
+  if (!version) return null;
+  const pages = moment.f.map((file, k) => {
+    const at = moment.i[k];
+    return version.pages[at] && version.pages[at].f === file ? at : version.pages.findIndex(p => p.f === file);
+  });
+  return pages.every(i => i >= 0) ? { chapter, version, pages } : null;
+}
+
+// The browser's view of a moment. `url` turns a library-relative path into an image URL.
+function view(moment, manga, url) {
+  const at = locate(moment, manga);
+  const chapter = at ? at.chapter : manga && manga.chapterById.get(moment.c);
+  return {
+    id: moment.id, c: moment.c, v: moment.v, cat: moment.cat, note: moment.note || '', t: moment.t, region: moment.region || null,
+    layout: moment.layout || 'row',
+    chapter: chapter ? { label: chapter.label, title: chapter.title, book: chapter.book } : { label: moment.c, title: '', book: '' },
+    // Story order: chapter position in the manga, then page, then how far down the page the region starts.
+    order: [chapter ? manga.chapters.indexOf(chapter) : 1e9, at ? Math.min(...at.pages) : moment.i[0], moment.region ? moment.region.y : 0],
+    missing: !at,
+    pages: at ? at.pages.map(i => {
+      const p = at.version.pages[i];
+      return { i, u: url(at.version.rel + '/' + p.f), w: p.w, h: p.h, r: p.r || 0 };
+    }) : [],
+  };
+}
+
+function storyCompare(a, b) {
+  for (let k = 0; k < 3; k++) if (a.order[k] !== b.order[k]) return a.order[k] - b.order[k];
+  return a.t - b.t;
+}
+
+module.exports = { CATEGORIES, NOTE_MAX, MAX_PER_USER, MAX_PAGES, MomentError, cleanRegion, cleanCategory, cleanNote, cleanPages, cleanLayout, locate, view, storyCompare };

perf/read-ahead.js

@@ -0,0 +1,78 @@
+'use strict';
+/*
+ * Read-ahead for network libraries: when a chapter is opened, its pages (then the next chapter's) are read
+ * once in page order, a few at a time, so the OS page cache holds them before the browser asks. On a NAS
+ * with spinning disks a cold page costs 10-100 ms (seconds while a disk wakes up); a cached one well under
+ * 5 ms. The data is discarded; only the cache effect matters.
+ *
+ * One queue per reader (`key`, the user): opening another chapter replaces that reader's queue only, and
+ * the queues take turns so two people reading at once both get their pages ahead.
+ */
+const fs = require('fs');
+
+class ReadAhead {
+  constructor({ concurrency = 2, remember = 4000, onBatch = () => {} } = {}) {
+    this.concurrency = concurrency; this.remember = remember; this.onBatch = onBatch;
+    this.batches = new Map(); this.turn = []; this.active = 0; this.recent = new Map(); this.buffers = [];
+  }
+
+  // `files` in reading order; `tag` names the batch in the trace.
+  warm(files, tag, key = '') {
+    const old = this.batches.get(key);
+    if (old) this.finish(key, old, true);
+    const queue = files.filter(f => !this.recent.has(f));
+    const batch = { tag, queue, files: queue.length, skipped: files.length - queue.length, bytes: 0, done: 0, active: 0, t0: performance.now() };
+    this.batches.set(key, batch);
+    if (!this.turn.includes(key)) this.turn.unshift(key); // a fresh request goes next
+    if (!queue.length) this.finish(key, batch, false);
+    this.pump();
+  }
+  // Runs after the reader's current batch (e.g. the next chapter) unless a newer warm() replaces it first.
+  then(files, tag, key = '') {
+    const batch = this.batches.get(key);
+    if (!batch) this.warm(files, tag, key); else batch.next = () => this.warm(files, tag, key);
+  }
+
+  pump() {
+    while (this.active < this.concurrency) {
+      const key = this.turn.find(k => this.batches.get(k)?.queue.length);
+      if (key === undefined) return;
+      this.turn.push(...this.turn.splice(this.turn.indexOf(key), 1)); // round robin between readers
+      const batch = this.batches.get(key), file = batch.queue.shift();
+      this.active++; batch.active++;
+      this.readFile(file).then(bytes => { this.note(file); batch.bytes += bytes; batch.done++; }, () => {}).finally(() => {
+        this.active--; batch.active--;
+        if (this.batches.get(key) === batch && !batch.queue.length && !batch.active) this.finish(key, batch, false);
+        this.pump();
+      });
+    }
+  }
+  finish(key, b, replaced) {
+    if (this.batches.get(key) === b) this.batches.delete(key);
+    if (!this.batches.has(key)) this.turn = this.turn.filter(k => k !== key);
+    b.queue = [];
+    this.onBatch({ tag: b.tag, files: b.files, done: b.done, skipped: b.skipped, bytes: b.bytes,
+      ms: Math.round(performance.now() - b.t0), replaced });
+    if (!replaced && b.next) b.next();
+  }
+  note(file) {
+    this.recent.delete(file); this.recent.set(file, 1);
+    while (this.recent.size > this.remember) this.recent.delete(this.recent.keys().next().value);
+  }
+
+  async readFile(file) {
+    const buf = this.buffers.pop() || Buffer.allocUnsafe(256 * 1024);
+    const fh = await fs.promises.open(file, 'r');
+    let total = 0;
+    try {
+      for (;;) {
+        const { bytesRead } = await fh.read(buf, 0, buf.length, total);
+        if (!bytesRead) break;
+        total += bytesRead;
+      }
+    } finally { await fh.close(); this.buffers.push(buf); }
+    return total;
+  }
+}
+
+module.exports = { ReadAhead };

perf/trace.js

@@ -0,0 +1,173 @@
+'use strict';
+/*
+ * Switchable performance trace: one JSON object per line in DATA/perf/trace-YYYY-MM-DD.jsonl.
+ *
+ * On while PERF_TRACE=1 or while the file DATA/perf/trace.on exists (checked every few seconds, so it can be
+ * switched on a running server with `touch` / `rm`). Off, every call is a cheap no-op.
+ *
+ * Event kinds (field `k`): `req` one HTTP request with its phases, `client` timings the reader page reports,
+ * `loop` event-loop lag / CPU / memory every SAMPLE_MS, `nas` a periodic read of one uncached library page,
+ * `scan` library scans, `scraper` calls to the scraper daemon, `ahead` read-ahead batches, `trace` on/off.
+ * The format and the report tool: docs/performance.md, tools/perf-report.js.
+ */
+const fs = require('fs'), path = require('path'), { monitorEventLoopDelay } = require('perf_hooks');
+
+const CHECK_MS = 5000, FLUSH_MS = 1000, SAMPLE_MS = 5000;
+const MAX_DAY_BYTES = 256 * 1024 * 1024; // a runaway trace never fills the data disk
+const KEEP_DAYS = 14;
+
+class Tracer {
+  constructor({ dir, env = process.env, now = Date.now } = {}) {
+    this.dir = dir; this.now = now;
+    this.forced = env.PERF_TRACE === '1';
+    this.flag = path.join(dir, 'trace.on');
+    this.on = false; this.buf = []; this.day = ''; this.dayBytes = 0; this.dropped = 0;
+    this.timers = []; this.probe = null; this.probeMs = Math.max(10, +env.PERF_NAS_PROBE_SECONDS || 60) * 1000;
+  }
+
+  start() {
+    this.check();
+    this.timers.push(setInterval(() => this.check(), CHECK_MS).unref());
+    this.timers.push(setInterval(() => this.flush(), FLUSH_MS).unref());
+    return this;
+  }
+  stop() { for (const t of this.timers) clearInterval(t); this.timers = []; this.setOn(false); this.flush(); }
+
+  check() {
+    let on = this.forced;
+    if (!on) try { fs.accessSync(this.flag); on = true; } catch { /* off */ }
+    this.setOn(on);
+  }
+  setOn(on) {
+    if (on === this.on) return;
+    if (on) {
+      this.on = true;
+      this.log({ k: 'trace', on: true, pid: process.pid, node: process.version });
+      this.startSampler();
+    } else {
+      this.log({ k: 'trace', on: false });
+      this.on = false;
+      this.stopSampler();
+    }
+  }
+
+  log(event) {
+    if (!this.on) return;
+    this.buf.push(JSON.stringify({ t: this.now(), ...event }));
+    if (this.buf.length >= 500) this.flush();
+  }
+
+  flush() {
+    if (!this.buf.length) return;
+    const lines = this.buf.join('\n') + '\n'; this.buf = [];
+    const day = new Date(this.now()).toISOString().slice(0, 10);
+    try {
+      if (day !== this.day) { this.day = day; this.dayBytes = 0; fs.mkdirSync(this.dir, { recursive: true }); this.prune(); }
+      if (this.dayBytes + lines.length > MAX_DAY_BYTES) { this.dropped += lines.length; return; }
+      fs.appendFileSync(path.join(this.dir, `trace-${day}.jsonl`), lines);
+      this.dayBytes += lines.length;
+    } catch (error) { console.warn('[perf] trace write failed:', error.message); }
+  }
+  prune() {
+    const cutoff = new Date(this.now() - KEEP_DAYS * 864e5).toISOString().slice(0, 10);
+    for (const name of fs.readdirSync(this.dir)) {
+      const m = /^trace-(\d{4}-\d\d-\d\d)\.jsonl$/.exec(name);
+      if (m && m[1] < cutoff) fs.rmSync(path.join(this.dir, name), { force: true });
+    }
+  }
+
+  // Event-loop delay shows whether the reader itself (CPU, sync work) holds requests back.
+  startSampler() {
+    const h = monitorEventLoopDelay({ resolution: 10 }); h.enable();
+    let cpu = process.cpuUsage(), at = process.hrtime.bigint();
+    this.sampler = { h, timer: setInterval(() => {
+      const nowCpu = process.cpuUsage(), nowAt = process.hrtime.bigint(), wall = Number(nowAt - at) / 1000;
+      const mem = process.memoryUsage();
+      this.log({ k: 'loop', lagP50: ms(h.percentile(50)), lagP99: ms(h.percentile(99)), lagMax: ms(h.max),
+        cpu: round(((nowCpu.user - cpu.user) + (nowCpu.system - cpu.system)) / wall * 100), rss: mb(mem.rss), heap: mb(mem.heapUsed) });
+      h.reset(); cpu = nowCpu; at = nowAt;
+    }, SAMPLE_MS).unref() };
+    this.startProbe();
+  }
+  stopSampler() {
+    if (this.sampler) { clearInterval(this.sampler.timer); this.sampler.h.disable(); this.sampler = null; }
+    if (this.probe) { clearInterval(this.probe); this.probe = null; }
+  }
+
+  // NAS probe: read one random library page now and then. A page picked at random out of a large library is
+  // almost never in the OS cache, so this measures the storage itself (and shows disks waking from standby).
+  setProbeSource(pick) { this.pick = pick; if (this.on) this.startProbe(); }
+  startProbe() {
+    if (this.probe || !this.pick) return;
+    const run = () => this.probeOnce().catch(() => {});
+    this.probe = setInterval(run, this.probeMs).unref();
+    setTimeout(run, 1000).unref();
+  }
+  async probeOnce() {
+    const file = this.pick && this.pick();
+    if (!file) return;
+    const t0 = performance.now();
+    let st, bytes = 0, firstMs = null, error = null;
+    try {
+      st = await fs.promises.stat(file);
+      const statMs = performance.now() - t0;
+      const fh = await fs.promises.open(file, 'r');
+      try {
+        const chunk = Buffer.allocUnsafe(256 * 1024);
+        for (;;) {
+          const { bytesRead } = await fh.read(chunk, 0, chunk.length, bytes);
+          if (firstMs === null) firstMs = performance.now() - t0;
+          if (!bytesRead) break;
+          bytes += bytesRead;
+        }
+      } finally { await fh.close(); }
+      this.log({ k: 'nas', statMs: round(statMs), firstMs: round(firstMs), ms: round(performance.now() - t0), bytes });
+    } catch (e) { error = e.code || e.message; this.log({ k: 'nas', ms: round(performance.now() - t0), error }); }
+  }
+}
+
+// Wraps one HTTP request: `mark(name)` stores the time since the request arrived, `set` adds fields, and the
+// event is written when the response is done (or the client went away). Off, returns a shared no-op.
+const NOOP = { mark() {}, set() {}, stream() {}, elapsed: () => 0, on: false };
+function requestTrace(tracer, req, res) {
+  if (!tracer.on) return NOOP;
+  const t0 = performance.now(), ev = { k: 'req', m: req.method, path: req.url.split('?')[0].slice(0, 300) };
+  const trace = {
+    on: true,
+    mark(name) { ev[name] = round(performance.now() - t0); },
+    elapsed: () => round(performance.now() - t0),
+    set(fields) { Object.assign(ev, fields); },
+    // Splits a file stream's time into waiting for the disk and waiting for the client (TCP backpressure):
+    // pipe() pauses the file stream while the socket buffer is full and resumes it on 'drain'.
+    stream(src) {
+      let pausedAt = 0, waitNet = 0;
+      src.on('open', () => trace.mark('open'));
+      src.once('data', () => trace.mark('first'));
+      src.on('data', chunk => { ev.bytes = (ev.bytes || 0) + chunk.length; });
+      src.on('pause', () => { pausedAt = performance.now(); });
+      src.on('resume', () => { if (pausedAt) { waitNet += performance.now() - pausedAt; pausedAt = 0; } });
+      src.on('end', () => {
+        trace.mark('readEnd');
+        ev.netWait = round(waitNet);
+        ev.disk = round(Math.max(0, ev.readEnd - (ev.open || 0) - waitNet));
+      });
+    },
+  };
+  let done = false;
+  const finish = aborted => {
+    if (done) return; done = true;
+    ev.ms = round(performance.now() - t0); ev.status = res.statusCode;
+    if (aborted) ev.aborted = true;
+    ev.conn = req.socket._perfRequests = (req.socket._perfRequests || 0) + 1; // >1: keep-alive reuse
+    tracer.log(ev);
+  };
+  res.on('finish', () => finish(false));
+  res.on('close', () => finish(!res.writableFinished));
+  return trace;
+}
+
+const round = v => (v == null || Number.isNaN(v) ? null : Math.round(v * 10) / 10);
+const ms = ns => round(ns / 1e6);
+const mb = b => Math.round(b / 1048576);
+
+module.exports = { Tracer, requestTrace };

public/app.css

@@ -94,7 +94,18 @@ main { max-width: 1200px; margin: 0 auto; padding: 16px; }
 .prog i { display: block; height: 100%; background: var(--accent); }
 .badge { position: absolute; top: 7px; right: 7px; background: var(--accent); color: #fff; font-size: 12px; font-weight: 700; padding: 2px 8px; border-radius: 10px; }
 .empty { text-align: center; padding: 60px 10px; }
+/* One fixed row; tiles sized like a six-column .grid, extra tiles scroll sideways instead of wrapping. */
+.continue-row { margin-bottom: 20px; padding-bottom: 16px; border-bottom: 1px solid var(--line); }
+.continue-banner {
+  display: inline-flex; gap: 6px; align-items: center; margin-bottom: 9px; padding: 2px 9px; border-radius: 10px;
+  background: color-mix(in srgb, var(--accent) 22%, var(--card)); color: #ffd8de; font-size: 12px; font-weight: 650;
+}
+.continue-tiles {
+  display: grid; grid-auto-flow: column; grid-auto-columns: max(140px, calc((100% - 80px) / 6)); gap: 16px;
+  overflow-x: auto; padding-bottom: 4px; scrollbar-width: thin;
+}
 @media (max-width: 560px) {
+  .continue-tiles { grid-auto-columns: calc((100% - 12px) / 2); gap: 12px; }
   main { padding: 12px; }
   .toolbar { flex-wrap: wrap; }
   .toolbar input { flex-basis: 100%; }
@@ -376,6 +387,8 @@ main { max-width: 1200px; margin: 0 auto; padding: 16px; }
 .login input { width: 100%; }
 .saved { color: #7fd3a0; font-size: 13px; }
 .reading-data { margin-top: 16px; padding-top: 12px; border-top: 1px solid var(--line); }
+.reader-sessions { list-style: none; margin: 12px 0 0; padding: 0; }
+.reader-sessions li { display: grid; gap: 4px; padding: 10px 0; border-top: 1px solid var(--line); overflow-wrap: anywhere; }
 .reading-data > summary { cursor: pointer; font-weight: 600; }
 .reading-danger { margin-top: 14px; padding-top: 12px; border-top: 1px solid var(--line); }
 .reading-danger p { margin: 3px 0 8px; }
@@ -491,3 +504,66 @@ body.nobars #bot { transform: translateY(100%); opacity: 0; pointer-events: none
   .seg button { padding: 7px 10px; } #bot .btn { padding: 6px 10px; } .wide-only { display: none; }
   .clock-panel { bottom: calc(124px + env(safe-area-inset-bottom)); }
 }
+
+/* ---------------- moments (BL-0055) ---------------- */
+.moment-btn.on { color: var(--accent); border-color: var(--accent); }
+.moment-btn.on svg path:first-child { fill: currentColor; }
+.moment-dialog { width: min(640px, calc(100vw - 16px)); max-height: calc(100vh - 16px); overflow: auto; color: var(--fg); background: var(--bg);
+  border: 1px solid var(--line); border-radius: 12px; padding: 16px; }
+.moment-dialog::backdrop { background: #000c; }
+.moment-dialog h2 { margin: 0; font-size: 18px; }
+.moment-head { display: flex; align-items: center; gap: 10px; margin-bottom: 8px; }
+.moment-head > :first-child { flex: 1; min-width: 0; }
+.moment-context { font-weight: 600; }
+.moment-preview-wrap { display: flex; justify-content: center; margin: 12px 0 8px; }
+.moment-preview { position: relative; line-height: 0; }
+.moment-composite { position: relative; }
+.moment-page { position: absolute; top: 0; overflow: hidden; background: #19191c; }
+.moment-page img { display: block; width: 100%; height: 100%; -webkit-user-drag: none; user-select: none; }
+.region-layer { position: absolute; inset: 0; cursor: crosshair; touch-action: none; overflow: hidden; }
+.region-box { position: absolute; border: 2px solid #fff; outline: 1px solid #0008; box-shadow: 0 0 0 9999px #0009; pointer-events: none; }
+.moment-region-row { display: flex; align-items: center; justify-content: space-between; gap: 10px; min-height: 32px; }
+.moment-chips { display: flex; flex-wrap: wrap; gap: 8px; margin: 12px 0; }
+.moment-chip { display: inline-flex; align-items: center; gap: 6px; padding: 6px 12px; border-radius: 18px; border: 1px solid var(--line);
+  background: var(--card); color: var(--fg); font: inherit; cursor: pointer; }
+.moment-chip:hover { background: var(--card2); }
+.moment-chip[aria-checked="true"] { border-color: var(--cat); background: color-mix(in srgb, var(--cat) 22%, var(--card)); box-shadow: 0 0 0 1px var(--cat); }
+.moment-dialog input[type=text] { width: 100%; }
+.moment-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-top: 12px; }
+.moment-dialog .btn[disabled] { opacity: .45; pointer-events: none; }
+.moment-crop { position: relative; overflow: hidden; border-radius: 6px; background: #19191c; flex: none; }
+.moment-crop.missing { display: flex; align-items: center; justify-content: center; color: var(--muted); font-size: 13px; line-height: 1.2; text-align: center; }
+.moment-viewer { width: auto; max-width: calc(100vw - 16px); }
+.moment-viewer-body { display: flex; align-items: center; justify-content: center; gap: 8px; }
+.moment-viewer-stage { display: flex; justify-content: center; touch-action: pan-y; user-select: none; }
+.moment-viewer-info { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 12px; }
+.moment-tag { display: inline-flex; align-items: center; gap: 5px; padding: 2px 10px; border-radius: 12px; font-size: 13px;
+  border: 1px solid var(--cat); background: color-mix(in srgb, var(--cat) 18%, var(--card)); }
+.moment-note { flex-basis: 100%; color: var(--muted); font-style: italic; }
+.moment-nav { font-size: 22px; min-width: 40px; }
+@media (max-width: 600px) {
+  .moment-viewer-body { position: relative; }
+  .moment-nav { position: absolute; z-index: 1; background: #000a; }
+  .moment-nav.prev { left: 2px; } .moment-nav.next { right: 2px; }
+}
+.moments-card { max-width: none; }
+.moments-head { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; margin-bottom: 8px; }
+.moments-card h2 { margin: 0; }
+.moment-filters { display: flex; gap: 7px; overflow-x: auto; padding-bottom: 6px; }
+.moment-filter { display: inline-flex; align-items: center; gap: 5px; }
+.moment-strip { display: flex; gap: 10px; overflow-x: auto; padding: 4px 2px 10px; scrollbar-width: thin; }
+.moment-thumb { position: relative; flex: none; display: flex; flex-direction: column; gap: 4px; padding: 0; border: 0; background: none;
+  color: var(--fg); font: inherit; cursor: pointer; text-align: left; }
+.moment-thumb .moment-crop { transition: transform .15s; }
+.moment-thumb:hover .moment-crop, .moment-thumb:focus-visible .moment-crop { transform: scale(1.03); }
+.moment-thumb-cat { position: absolute; top: 5px; left: 5px; display: flex; padding: 3px; border-radius: 50%; background: #000b; }
+.moment-thumb-label { font-size: 12px; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 200px; }
+.key-group h3 { margin: 4px 0 8px; font-size: 15px; }
+.key-group + .key-group { margin-top: 16px; }
+.key-table { border-collapse: collapse; width: 100%; }
+.key-table td { padding: 5px 8px; border-top: 1px solid var(--line); vertical-align: top; }
+.key-table td:first-child { width: 1%; white-space: nowrap; }
+kbd { display: inline-block; min-width: 24px; padding: 1px 7px; border: 1px solid var(--line); border-bottom-width: 2px; border-radius: 5px;
+  background: var(--card2); font: 13px/1.5 ui-monospace, monospace; text-align: center; }
+@media (max-width: 480px) { .moment-dialog { padding: 12px; } .moment-actions .moment-hint { flex-basis: 100%; } .moment-actions .moment-hint:empty { display: none; } }
+.moment-extend { display: flex; flex-wrap: wrap; justify-content: center; gap: 8px; margin-bottom: 8px; }

public/greatest.js

@@ -65,8 +65,10 @@
 
   function cover(item) {
     const box = h('span', { class: 'greatest-cover' }, h('span', { class: 'greatest-cover-fallback', 'aria-hidden': 'true' }, item.title.slice(0, 1)));
-    if (item.cover && safeHref(item.cover)) {
-      const image = h('img', { src: item.cover, alt: '', loading: 'lazy' });
+    // Covers come from the server (cached catalog covers, owned library covers) as relative URLs.
+    const src = /^(api\/greatest-cover\?|lib\/)/.test(item.cover || '') ? item.cover : safeHref(item.cover);
+    if (src) {
+      const image = h('img', { src, alt: '', loading: 'lazy' });
       image.onerror = () => image.remove();
       box.append(image);
     }

public/keys.js

@@ -0,0 +1,35 @@
+'use strict';
+/*
+ * Keyboard shortcuts. The reader dispatches keys through READER_KEYS, and Settings and the reader's "?" list
+ * are drawn from the same tables, so the documentation cannot drift from what the keys do.
+ */
+const READER_KEYS = [
+  { keys: ['ArrowLeft', 'ArrowRight'], label: '← →', action: 'turn', text: 'Previous / next page, following the reading direction' },
+  { keys: [' ', 'PageDown'], label: 'Space · Page Down', action: 'forward', text: 'Next page (Shift + Space: previous) · Page and Book mode' },
+  { keys: ['PageUp'], label: 'Page Up', action: 'back', text: 'Previous page · Page and Book mode' },
+  { keys: ['+', '='], label: '+', action: 'zoomIn', text: 'Zoom in 5 %' },
+  { keys: ['-'], label: '−', action: 'zoomOut', text: 'Zoom out 5 %' },
+  { keys: ['0'], label: '0', action: 'zoomFit', text: 'Fit the screen (100 %)' },
+  { keys: ['m', 'M'], label: 'M', action: 'moment', text: 'Save a moment of the page you are on' },
+  { keys: ['i', 'I'], label: 'I', action: 'bars', text: 'Show or hide the controls' },
+  { keys: ['Escape'], label: 'Esc', action: 'bars', text: 'Show or hide the controls (closes an open dialog first)' },
+  { keys: ['f', 'F'], label: 'F', action: 'fullscreen', text: 'Fullscreen' },
+  { keys: ['?'], label: '?', action: 'help', text: 'Show these shortcuts' },
+];
+const MOMENT_VIEWER_KEYS = [
+  { keys: ['ArrowLeft', 'ArrowRight'], label: '← →', action: 'step', text: 'Previous / next moment' },
+  { keys: ['Escape'], label: 'Esc', action: 'close', text: 'Close the viewer' },
+];
+const KEY_GROUPS = [
+  { title: 'Reader', keys: READER_KEYS },
+  { title: 'Moments viewer (manga page)', keys: MOMENT_VIEWER_KEYS },
+];
+const keyAction = (table, key) => (table.find(entry => entry.keys.includes(key)) || {}).action || null;
+
+function keyTable(groups = KEY_GROUPS) {
+  return groups.map(group => h('section', { class: 'key-group' }, h('h3', {}, group.title),
+    h('table', { class: 'key-table' }, h('tbody', {}, group.keys.map(entry =>
+      h('tr', {}, h('td', {}, h('kbd', {}, entry.label)), h('td', {}, entry.text)))))));
+}
+
+if (typeof module !== 'undefined') module.exports = { READER_KEYS, MOMENT_VIEWER_KEYS, KEY_GROUPS, keyAction };

public/library.js

@@ -55,6 +55,12 @@
     h('option', { value: 'grouped' }, 'Group collections'), h('option', { value: 'expanded' }, 'Expand collections'), h('option', { value: 'individual' }, 'Individual manga'));
   grouping.value = ['grouped', 'expanded', 'individual'].includes(store.get('grouping')) ? store.get('grouping') : 'grouped';
   grouping.onchange = render;
+  // Started but unfinished manga, most recently read first; the same manga still appear in the grid.
+  const continueItems = data.mangas.filter(m => m.lastRead && m.read < m.chapters)
+    .sort((a, b) => b.lastRead - a.lastRead).slice(0, 5);
+  const continueRow = h('section', { class: 'continue-row', 'aria-label': 'Continue where you left off', hidden: true },
+    h('div', { class: 'continue-banner' }, h('span', { 'aria-hidden': 'true' }, '▶'), 'Continue where you left off'),
+    h('div', { class: 'continue-tiles' }, continueItems.map(m => tile(m))));
   if (storyAvailable) {
     const most = data.mangas.find(manga => manga.id === data.reading.mostTimeMangaId);
     const latest = data.mangas.find(manga => manga.id === data.reading.lastMangaId);
@@ -76,7 +82,7 @@
         h('div', { class: 'filter-heading' }, h('b', {}, 'Tags'), h('span', { class: 'muted small' }, 'Manga must match every selected tag')),
         tagBar) : null,
       resultCount),
-    grid);
+    continueRow, grid);
 
   function syncTags() {
     store.set('tags', JSON.stringify([...selectedTags]));
@@ -95,8 +101,24 @@
     return direction * (at - bt) || a.title.localeCompare(b.title);
   }
 
+  function tile(m) {
+    const cover = m.isCollection && m.coverMode === 'mosaic' && m.covers.length
+      ? h('div', { class: 'cv collection-mosaic' }, m.covers.map(src => h('img', { loading: 'lazy', src, alt: '' })))
+      : h('div', { class: 'cv' }, m.cover ? h('img', { loading: 'lazy', src: m.cover, alt: '' }) : null);
+    return h('a', { class: 'tile', href: m.isCollection ? 'collection.html?' + qsa({ id: m.id }) : mangaUrl(m.id) },
+      cover, m.isCollection ? h('span', { class: 'collection-count' }, `${m.members.length} manga`) : null,
+      m.unread ? h('span', { class: 'badge' }, m.unread + ' new') : null,
+      h('div', { class: 't' }, m.title),
+      h('div', { class: 's' }, [m.firstRelease, m.status, m.read ? `${m.read} / ${m.chapters} read` : `${m.chapters} chapters`].filter(Boolean).join(' · ')),
+      m.read ? h('div', { class: 'prog' }, h('i', { style: `width:${Math.round((100 * m.read) / Math.max(1, m.chapters))}%` })) : null);
+  }
+
   function render() {
     store.set('filter', filter.value); store.set('sort', sort.value); store.set('status', status.value); store.set('grouping', grouping.value);
+    // Only on the plain overview: a search or status filter means the reader is looking for something else,
+    // and "Recently read" already puts these first. Tags and grouping keep it.
+    continueRow.hidden = !me.settings.continueRow || !continueItems.length || sort.value === 'read'
+      || !!filter.value.trim() || !!status.value;
     const q = filter.value.trim().toLowerCase();
     const groups = (data.collections || []).filter(c => c.grouped);
     const membership = new Set(groups.flatMap(c => c.members.map(m => m.id)));
@@ -125,17 +147,6 @@
     }
     resultCount.textContent = `${list.length} results · ${data.mangas.length} manga in the library`;
     grid.textContent = '';
-    const tile = m => {
-      const cover = m.isCollection && m.coverMode === 'mosaic' && m.covers.length
-        ? h('div', { class: 'cv collection-mosaic' }, m.covers.map(src => h('img', { loading: 'lazy', src, alt: '' })))
-        : h('div', { class: 'cv' }, m.cover ? h('img', { loading: 'lazy', src: m.cover, alt: '' }) : null);
-      return h('a', { class: 'tile', href: m.isCollection ? 'collection.html?' + qsa({ id: m.id }) : mangaUrl(m.id) },
-        cover, m.isCollection ? h('span', { class: 'collection-count' }, `${m.members.length} manga`) : null,
-        m.unread ? h('span', { class: 'badge' }, m.unread + ' new') : null,
-        h('div', { class: 't' }, m.title),
-        h('div', { class: 's' }, [m.firstRelease, m.status, m.read ? `${m.read} / ${m.chapters} read` : `${m.chapters} chapters`].filter(Boolean).join(' · ')),
-        m.read ? h('div', { class: 'prog' }, h('i', { style: `width:${Math.round((100 * m.read) / Math.max(1, m.chapters))}%` })) : null);
-    };
     if (grouping.value === 'expanded') {
       const visible = new Set(list.map(m => m.id));
       for (const c of groups) {

public/manga.html

@@ -9,6 +9,8 @@
 <link rel="manifest" href="manifest.webmanifest">
 <meta name="theme-color" content="#121214">
 <script src="common.js" defer></script>
+<script src="keys.js" defer></script>
+<script src="moments.js" defer></script>
 <script src="manga.js" defer></script>
 </head>
 <body>

public/manga.js

@@ -164,6 +164,7 @@
   main.append(h('details', { class: 'metadata card', open: metadataOpen },
     h('summary', { class: 'metadata-summary' }, h('h2', {}, 'Metadata')),
     metadata, rawMeta));
+  main.append(momentsGallery());
 
   const volumeButtons = new Map();
   const volumeBar = h('div', { class: 'volume-filter', 'aria-label': 'Filter chapters by volume' });
@@ -316,6 +317,54 @@
     return { text: `◷ ${readingDuration(active, true)}`, title: `${readingDuration(active)} active; current pass in progress` };
   }
 
+  // Your moments (BL-0055): hidden until there is at least one. Only the user's own are ever returned.
+  function momentsGallery() {
+    const sortKey = `moments-sort.${me.name}`;
+    let list = [], sort = store.get(sortKey) === 'recent' ? 'recent' : 'story', filter = null;
+    const section = h('section', { class: 'card moments-card', hidden: true });
+    const count = h('span', { class: 'muted small' });
+    const sortButtons = ['story', 'recent'].map(key => h('button', { type: 'button', 'data-sort': key,
+      onclick: () => { sort = key; store.set(sortKey, key); draw(); } }, key === 'story' ? 'Story' : 'Recent'));
+    const filters = h('div', { class: 'moment-filters', role: 'group', 'aria-label': 'Filter moments by category' });
+    const strip = h('div', { class: 'moment-strip' });
+    section.append(h('div', { class: 'moments-head' }, h('h2', {}, 'Your moments'), count, h('div', { class: 'grow' }),
+      h('div', { class: 'seg', role: 'group', 'aria-label': 'Sort moments' }, sortButtons)), filters, strip);
+    const shown = () => {
+      const items = list.filter(m => !filter || m.cat === filter);
+      return sort === 'recent' ? items.sort((a, b) => b.t - a.t) : items.sort((a, b) => {
+        for (let k = 0; k < 3; k++) if (a.order[k] !== b.order[k]) return a.order[k] - b.order[k];
+        return a.t - b.t;
+      });
+    };
+    function draw() {
+      section.hidden = !list.length;
+      count.textContent = `${list.length} saved`;
+      for (const b of sortButtons) b.classList.toggle('on', b.dataset.sort === sort);
+      // Category filters only help once there are a few moments in more than one category.
+      const cats = MOMENT_CATS.filter(c => list.some(m => m.cat === c.id));
+      if (filter && !cats.some(c => c.id === filter)) filter = null;
+      filters.hidden = list.length < 5 || cats.length < 2;
+      filters.replaceChildren(...cats.map(c => h('button', { type: 'button', class: 'filter-chip moment-filter' + (filter === c.id ? ' on' : ''),
+        'aria-pressed': String(filter === c.id), onclick: () => { filter = filter === c.id ? null : c.id; draw(); } },
+      momentIcon(c.id, 14), `${c.label} ${list.filter(m => m.cat === c.id).length}`)));
+      const items = shown();
+      strip.replaceChildren(...items.map((m, k) => h('button', { type: 'button', class: 'moment-thumb', title: `${momentCat(m.cat).label} · ${m.chapter.label} · ${m.missing ? 'page moved' : momentPageLabel(m.pages)}${m.note ? '\n' + m.note : ''}`,
+        onclick: () => momentViewer({ mangaId: M.id, mangaTitle: M.title, list: items, index: k, onChange: changed }) },
+      momentCrop(m.pages, m.region, 200, 120, m.layout),
+      h('span', { class: 'moment-thumb-cat' }, momentIcon(m.cat, 14)),
+      h('span', { class: 'moment-thumb-label' }, `${m.chapter.label} · ${m.missing ? 'moved' : momentPageLabel(m.pages)}`))));
+    }
+    // The viewer edits its (sorted, filtered) copy; fold the changes back into the full list.
+    function changed(items) {
+      const byId = new Map(items.map(m => [m.id, m]));
+      const visible = new Set(shown().map(m => m.id));
+      list = list.filter(m => !visible.has(m.id) || byId.has(m.id)).map(m => byId.get(m.id) || m);
+      draw();
+    }
+    api('api/moments?' + qsa({ m: M.id })).then(data => { list = data.moments; draw(); }).catch(() => {});
+    return section;
+  }
+
   drawVolumeFilter();
   drawChapters();
 })();

public/moments.js

@@ -0,0 +1,302 @@
+'use strict';
+/*
+ * Moments (BL-0055): a page, or a region of one or two facing pages, saved with exactly one category.
+ * Shared by the reader (save sheet) and the manga page (gallery and viewer). Crops are drawn by positioning the
+ * full page images inside a clipping box, so no thumbnails are generated on the server.
+ */
+const MOMENT_CATS = [
+  { id: 'twist', label: 'Twist', color: '#a29bf2', svg: '<path d="M12 1.5L13.8 4.6L17.3 3.2L17.4 6.8L21 7.6L19.2 10.8L22 13.2L18.8 14.9L19.6 18.5L16 18.2L14.6 21.6L12 19.2L9.4 21.6L8 18.2L4.4 18.5L5.2 14.9L2 13.2L4.8 10.8L3 7.6L6.6 6.8L6.7 3.2L10.2 4.6Z"/><path d="M9.3 8.3v4.4"/><path d="M12.6 9.2a1.9 1.9 0 1 1 2.6 1.8c-.6.3-.8.7-.8 1.5"/><circle cx="9.3" cy="15.3" r=".5" fill="currentColor"/><circle cx="14.4" cy="15.3" r=".5" fill="currentColor"/>' },
+  { id: 'hot', label: 'Hot', color: '#f0845c', svg: '<path d="M12 2.5c.5 3 3 4.5 4.5 7a6.5 6.5 0 1 1-11 1.5c.8 1.2 1.8 1.8 2.8 1.8C7.5 9 9.5 5.5 12 2.5z"/><path d="M12 21a3 3 0 0 1-3-3c0-1.8 1.5-3 3-5c1.5 2 3 3.2 3 5a3 3 0 0 1-3 3z"/><path d="M19.5 3l-1 1.6M21.5 5.5l-1.6.8"/>' },
+  { id: 'awesome', label: 'Awesome', color: '#f2b443', svg: '<path d="M12 5.5L13.5 10.5L18.5 12L13.5 13.5L12 18.5L10.5 13.5L5.5 12L10.5 10.5Z"/><path d="M3 3l2.6 2.6M21 3l-2.6 2.6M3 21l2.6-2.6M21 21l-2.6-2.6M12 1.5v1.8M12 20.7v1.8M1.5 12h1.8M20.7 12h1.8"/>' },
+  { id: 'cute', label: 'Cute', color: '#f07aa5', svg: '<path d="M11 21.5s-7-4.4-7-9.5a4 4 0 0 1 7-2.6a4 4 0 0 1 7 2.6c0 5.1-7 9.5-7 9.5z"/><path d="M8 13.5l1 1M13 13.5l1 1"/><path d="M19.5 2v4M17.5 4h4"/><path d="M4 3.5v2.4M2.8 4.7h2.4"/>' },
+  { id: 'funny', label: 'Funny', color: '#4fcfa0', svg: '<circle cx="11" cy="13" r="8"/><path d="M6.8 11.6l1.6-1.6l1.6 1.6M12 11.6l1.6-1.6l1.6 1.6"/><path d="M7.3 14.5h7.4a3.7 3.7 0 0 1-7.4 0z"/><path d="M20.2 2.5c-1 1.6-1.6 2.6-1.6 3.4a1.6 1.6 0 0 0 3.2 0c0-.8-.6-1.8-1.6-3.4z"/>' },
+  { id: 'feels', label: 'Feels', color: '#6aa8ec', svg: '<path d="M2.5 10c2.5-4 6-5.5 9.5-5.5S19 6 21.5 10"/><path d="M5 11.5a7 7 0 0 0 14 0"/><circle cx="12" cy="11" r="4"/><circle cx="13.5" cy="9.5" r="1" fill="currentColor"/><path d="M18 16.5c-1 1.5-1.5 2.4-1.5 3.1a1.5 1.5 0 0 0 3 0c0-.7-.5-1.6-1.5-3.1z"/>' },
+];
+const momentCat = id => MOMENT_CATS.find(c => c.id === id) || MOMENT_CATS[0];
+function momentIcon(id, size = 18) {
+  const el = icon(`<svg viewBox="0 0 24 24" width="${size}" height="${size}" fill="none" stroke="currentColor" stroke-width="${size < 20 ? 2 : 1.6}" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${momentCat(id).svg}</svg>`);
+  el.style.color = momentCat(id).color;
+  return el;
+}
+const momentPageLabel = pages => {
+  const ns = pages.map(p => p.i + 1).sort((a, b) => a - b);
+  return 'p. ' + (ns.length > 1 ? ns[0] + '–' + ns[ns.length - 1] : ns[0]);
+};
+
+// Displayed size after rotation, as in the reader.
+const shapeOf = p => {
+  const turned = (p.r || 0) % 180, w = (turned ? p.h : p.w) || 1000, hh = (turned ? p.w : p.h) || 1414;
+  return { ...p, a: w / hh };
+};
+const FULL = { x: 0, y: 0, w: 1, h: 1 };
+
+// Each page's box in units: side by side ("row", Page/Book) pages share a height of 1,
+// stacked ("column", Flow) pages share a width of 1.
+function arrange(pages, layout) {
+  const column = layout === 'column';
+  let at = 0;
+  const boxes = pages.map(shapeOf).map((p, k) => {
+    const b = column ? { k, p, x: 0, y: at, w: 1, h: 1 / p.a } : { k, p, x: at, y: 0, w: p.a, h: 1 };
+    at += column ? b.h : b.w;
+    return b;
+  });
+  return { boxes, w: column ? 1 : at, h: column ? at : 1 };
+}
+
+// The pages put together at `scale` px per unit.
+function composite(pages, layout, scale) {
+  const { boxes, w, h: hh } = arrange(pages, layout), el = h('div', { class: 'moment-composite' });
+  for (const b of boxes) {
+    const W = b.w * scale, H = b.h * scale, r = b.p.r || 0;
+    const img = h('img', { src: b.p.u, alt: '', draggable: 'false', decoding: 'async', loading: 'lazy' });
+    if (r) img.style.cssText = `position:absolute;left:50%;top:50%;max-width:none;width:${r % 180 ? H : W}px;height:${r % 180 ? W : H}px;transform:translate(-50%,-50%) rotate(${r}deg)`;
+    el.append(h('div', { class: 'moment-page', style: `left:${b.x * scale}px;top:${b.y * scale}px;width:${W}px;height:${H}px` }, img));
+  }
+  el.style.width = w * scale + 'px';
+  el.style.height = hh * scale + 'px';
+  return el;
+}
+
+// A box of at most maxW × maxH showing `region` (or everything) of the pages.
+function momentCrop(pages, region, maxW, maxH, layout = 'row') {
+  if (!pages.length) return h('div', { class: 'moment-crop missing', style: `width:${Math.round(maxH * 0.7)}px;height:${maxH}px` }, 'Page moved');
+  const r = region || FULL, { w: TW, h: TH } = arrange(pages, layout), aspect = (r.w * TW) / (r.h * TH);
+  const boxW = Math.min(maxW, maxH * aspect), boxH = boxW / aspect, scale = boxW / (r.w * TW);
+  const inner = composite(pages, layout, scale);
+  inner.style.transform = `translate(${-r.x * TW * scale}px, ${-r.y * TH * scale}px)`;
+  return h('div', { class: 'moment-crop', style: `width:${Math.round(boxW)}px;height:${Math.round(boxH)}px` }, inner);
+}
+
+// Drag a rectangle over `target` (position: relative). Coordinates are fractions of the target box.
+function regionPicker(target, initial, onChange) {
+  let region = initial || null, start = null;
+  const box = h('div', { class: 'region-box', hidden: true });
+  const layer = h('div', { class: 'region-layer' }, box);
+  const draw = () => {
+    box.hidden = !region;
+    if (region) Object.assign(box.style, { left: region.x * 100 + '%', top: region.y * 100 + '%', width: region.w * 100 + '%', height: region.h * 100 + '%' });
+    layer.classList.toggle('has-region', !!region);
+  };
+  const at = e => {
+    const rect = layer.getBoundingClientRect();
+    return { x: Math.min(1, Math.max(0, (e.clientX - rect.left) / rect.width)), y: Math.min(1, Math.max(0, (e.clientY - rect.top) / rect.height)) };
+  };
+  layer.addEventListener('pointerdown', e => { e.preventDefault(); layer.setPointerCapture(e.pointerId); start = at(e); });
+  layer.addEventListener('pointermove', e => {
+    if (!start) return;
+    const p = at(e);
+    region = { x: Math.min(start.x, p.x), y: Math.min(start.y, p.y), w: Math.abs(p.x - start.x), h: Math.abs(p.y - start.y) };
+    draw();
+  });
+  const end = () => {
+    if (!start) return;
+    start = null;
+    if (region && (region.w < 0.03 || region.h < 0.03)) region = null; // a tap, not a selection
+    draw();
+    onChange(region);
+  };
+  layer.addEventListener('pointerup', end);
+  layer.addEventListener('pointercancel', end);
+  target.append(layer);
+  draw();
+  return { get: () => region, clear() { region = null; draw(); onChange(null); } };
+}
+
+// Pages the region does not touch are dropped and the region is mapped onto the pages that remain,
+// so a selection inside one page of a spread or a stack saves that page alone.
+function trimPages(pages, region, layout = 'row') {
+  if (pages.length < 2 || !region) return { pages, region };
+  const column = layout === 'column', { boxes, w: TW, h: TH } = arrange(pages, layout), total = column ? TH : TW;
+  const from = (column ? region.y : region.x) * total, to = from + (column ? region.h : region.w) * total, eps = 0.002 * total;
+  const startOf = b => (column ? b.y : b.x), endOf = b => startOf(b) + (column ? b.h : b.w);
+  const keep = boxes.filter(b => endOf(b) > from + eps && startOf(b) < to - eps);
+  if (!keep.length || keep.length === boxes.length) return { pages, region };
+  const s0 = startOf(keep[0]), len = endOf(keep[keep.length - 1]) - s0;
+  const a = Math.max(0, (from - s0) / len), b = Math.min(1, (to - s0) / len);
+  return { pages: keep.map(x => pages[x.k]), region: column ? { ...region, y: a, h: b - a } : { ...region, x: a, w: b - a } };
+}
+
+// `dialog.done()` closes and cleans up at once. The "close" event (Esc) does the same, but it is a queued task
+// that a backgrounded page may run late, so the app never waits for it.
+function openDialog(className, onClose) {
+  const dialog = h('dialog', { class: 'moment-dialog ' + className });
+  let finished = false;
+  dialog.done = () => {
+    if (finished) return;
+    finished = true;
+    if (dialog.open) dialog.close();
+    dialog.remove();
+    if (onClose) onClose();
+  };
+  dialog.addEventListener('close', dialog.done);
+  dialog.addEventListener('click', e => { if (e.target === dialog) dialog.done(); }); // click on the backdrop
+  document.body.append(dialog);
+  return dialog;
+}
+
+/*
+ * The save / edit sheet. `context` [manga title, chapter text]; `initial` {region, cat, note}.
+ * Pages come either fixed (`pages` in displayed order, for an edit) or from `sequence` (pages in reading order)
+ * with the shown `range` [first, last], which "+ Previous page" / "+ Next page" widen up to four pages.
+ * `layout` "row" puts them side by side (right to left when `rtl`), "column" stacks them as in Flow.
+ * `save({pages, layout, region, cat, note})` returns a promise. Resolves with its result, or null when cancelled.
+ */
+function momentSheet({ heading, context, pages: fixed, sequence, range, layout = 'row', rtl = false, initial = {}, save }) {
+  return new Promise(resolve => {
+    let result = null, cat = initial.cat || null, region = initial.region || null, picker = null;
+    let [lo, hi] = range || [0, 0];
+    const start = [lo, hi], MAX = 4;
+    const dialog = openDialog('moment-sheet', () => resolve(result));
+    const pagesNow = () => {
+      if (fixed) return fixed;
+      const run = sequence.slice(lo, hi + 1);
+      return layout === 'row' && rtl ? run.reverse() : run;
+    };
+    const wrap = h('div', { class: 'moment-preview-wrap' });
+    const where = h('div', { class: 'muted small' });
+    const whole = h('button', { class: 'btn small', type: 'button', hidden: true, onclick: () => picker.clear() }, 'Whole selection');
+    const help = h('span', { class: 'muted small' });
+    const earlier = h('button', { class: 'btn small', type: 'button', onclick: () => { lo--; drawPreview(); } }, '+ Previous page');
+    const later = h('button', { class: 'btn small', type: 'button', onclick: () => { hi++; drawPreview(); } }, '+ Next page');
+    const reset = h('button', { class: 'btn small', type: 'button', onclick: () => { [lo, hi] = start; drawPreview(); } }, 'Reset pages');
+    const extend = h('div', { class: 'moment-extend', hidden: !sequence },
+      layout === 'row' && rtl ? [later, reset, earlier] : [earlier, reset, later]);
+    // Changing the pages changes the geometry, so a selection starts over.
+    function drawPreview() {
+      const pages = pagesNow(), { w: TW, h: TH } = arrange(pages, layout);
+      const maxW = Math.min(560, innerWidth - 48);
+      const maxH = Math.min(innerHeight * (layout === 'column' ? 0.62 : innerWidth < 600 ? 0.42 : 0.5), layout === 'column' ? 900 : 520);
+      const preview = h('div', { class: 'moment-preview' }, composite(pages, layout, Math.min(maxW / TW, maxH / TH)));
+      if (picker) region = null;
+      picker = regionPicker(preview, region, r => { region = r; whole.hidden = !r; });
+      whole.hidden = !region;
+      wrap.replaceChildren(preview);
+      where.textContent = `${context[1]} · ${momentPageLabel(pages)}`;
+      help.textContent = 'Drag over the picture to keep just a part; pages it does not touch are left out. Without a selection everything shown is saved.';
+      if (sequence) {
+        const count = hi - lo + 1;
+        earlier.disabled = lo === 0 || count >= MAX;
+        later.disabled = hi === sequence.length - 1 || count >= MAX;
+        reset.hidden = lo === start[0] && hi === start[1];
+      }
+    }
+    const hint = h('span', { class: 'muted small moment-hint' });
+    const saveBtn = h('button', { class: 'btn primary', type: 'submit' }, 'Save moment');
+    const chips = MOMENT_CATS.map(c => {
+      const chip = h('button', { class: 'moment-chip', type: 'button', role: 'radio', 'data-cat': c.id, style: `--cat:${c.color}` }, momentIcon(c.id, 18), c.label);
+      chip.onclick = () => { cat = c.id; drawChips(); };
+      return chip;
+    });
+    const drawChips = () => {
+      for (const chip of chips) chip.setAttribute('aria-checked', String(chip.dataset.cat === cat));
+      saveBtn.disabled = !cat;
+      hint.textContent = cat ? '' : 'Pick a category to save';
+    };
+    const note = h('input', { type: 'text', maxlength: '200', placeholder: 'Optional note', 'aria-label': 'Note', value: initial.note || '' });
+    const error = h('p', { class: 'error small', hidden: true });
+    const form = h('form', { method: 'dialog' },
+      h('div', { class: 'moment-head' }, h('h2', {}, heading),
+        h('button', { class: 'btn icon', type: 'button', 'aria-label': 'Close', onclick: () => dialog.done() }, '×')),
+      h('div', { class: 'moment-context' }, context[0]), where,
+      wrap, extend,
+      h('div', { class: 'moment-region-row' }, help, whole),
+      h('div', { class: 'moment-chips', role: 'radiogroup', 'aria-label': 'Category' }, chips),
+      note, error,
+      h('div', { class: 'moment-actions' }, hint, h('div', { class: 'grow' }),
+        h('button', { class: 'btn', type: 'button', onclick: () => dialog.done() }, 'Cancel'), saveBtn));
+    form.addEventListener('submit', async e => {
+      e.preventDefault();
+      if (!cat) return;
+      saveBtn.disabled = true; error.hidden = true;
+      try {
+        const kept = fixed ? { pages: fixed, region } : trimPages(pagesNow(), region, layout);
+        result = await save({ pages: kept.pages, layout, region: kept.region, cat, note: note.value });
+        dialog.done();
+      } catch (err) { error.textContent = err.message; error.hidden = false; saveBtn.disabled = false; }
+    });
+    dialog.append(form);
+    drawPreview();
+    drawChips();
+    dialog.showModal();
+  });
+}
+
+const momentReadUrl = (mangaId, m) => 'read.html?' + qsa({ m: mangaId, c: m.c, v: m.v, p: m.pages.length ? Math.min(...m.pages.map(p => p.i)) : null });
+
+/*
+ * The large viewer: `list` of moment views, starting at `index`. `onChange(list)` after an edit or a delete.
+ */
+function momentViewer({ mangaId, mangaTitle, list, index, onChange }) {
+  let k = index, full = false;
+  const dialog = openDialog('moment-viewer', () => removeEventListener('resize', draw));
+  const stage = h('div', { class: 'moment-viewer-stage' });
+  const info = h('div', { class: 'moment-viewer-info' });
+  const prevBtn = h('button', { class: 'btn icon moment-nav prev', type: 'button', 'aria-label': 'Previous moment', onclick: () => step(-1) }, '‹');
+  const nextBtn = h('button', { class: 'btn icon moment-nav next', type: 'button', 'aria-label': 'Next moment', onclick: () => step(1) }, '›');
+  const counter = h('span', { class: 'muted small' });
+  const fullBtn = h('button', { class: 'btn small', type: 'button', onclick: () => { full = !full; draw(); } });
+  const readLink = h('a', { class: 'btn primary small' }, 'Open in reader');
+  const actions = h('div', { class: 'moment-actions' }, fullBtn,
+    h('button', { class: 'btn small', type: 'button', onclick: edit }, 'Edit'),
+    h('button', { class: 'btn small danger', type: 'button', onclick: remove }, 'Delete'),
+    h('div', { class: 'grow' }), readLink);
+  dialog.append(
+    h('div', { class: 'moment-head' }, info, counter, h('button', { class: 'btn icon', type: 'button', 'aria-label': 'Close', onclick: () => dialog.done() }, '×')),
+    h('div', { class: 'moment-viewer-body' }, prevBtn, stage, nextBtn), actions);
+
+  function step(d) {
+    if (!list.length) return;
+    k = (k + d + list.length) % list.length; full = false; draw();
+  }
+  function draw() {
+    if (!list.length) return dialog.done();
+    const m = list[k], c = momentCat(m.cat);
+    const maxW = Math.min(1100, innerWidth - (innerWidth < 600 ? 32 : 140)), maxH = innerHeight - (innerWidth < 600 ? 230 : 200);
+    stage.replaceChildren(momentCrop(m.pages, full ? null : m.region, maxW, maxH, m.layout));
+    info.replaceChildren(h('span', { class: 'moment-tag', style: `--cat:${c.color}` }, momentIcon(m.cat, 16), c.label),
+      h('span', {}, `${m.chapter.label}${m.chapter.title ? ' · ' + m.chapter.title : ''} · ${m.missing ? 'page moved' : momentPageLabel(m.pages)}`),
+      h('span', { class: 'muted small' }, ago(m.t)),
+      ...(m.note ? [h('span', { class: 'moment-note' }, m.note)] : []));
+    counter.textContent = `${k + 1} / ${list.length}`;
+    prevBtn.hidden = nextBtn.hidden = list.length < 2;
+    fullBtn.hidden = !m.region || m.missing;
+    fullBtn.textContent = full ? 'Show selection' : (m.pages.length > 1 ? 'Show all pages' : 'Show full page');
+    readLink.href = momentReadUrl(mangaId, m); // a moved page still opens its chapter
+  }
+  async function edit() {
+    const m = list[k];
+    if (m.missing) return;
+    const saved = await momentSheet({ heading: 'Edit moment', context: [mangaTitle, `${m.chapter.label}${m.chapter.title ? ' · ' + m.chapter.title : ''}`],
+      pages: m.pages, layout: m.layout, initial: m,
+      save: async ({ region, cat, note }) => (await api('api/moments/update', { id: m.id, region, cat, note })).moment });
+    if (!saved) return;
+    list[k] = saved; draw(); onChange(list);
+  }
+  async function remove() {
+    if (!confirm('Delete this moment?')) return;
+    await api('api/moments/delete', { id: list[k].id });
+    list.splice(k, 1);
+    k = Math.min(k, list.length - 1);
+    onChange(list);
+    draw();
+  }
+
+  dialog.addEventListener('keydown', e => {
+    if (e.target.closest('input, textarea') || dialog.querySelector('dialog[open]')) return;
+    const action = keyAction(MOMENT_VIEWER_KEYS, e.key);
+    if (action === 'step') { e.preventDefault(); step(e.key === 'ArrowRight' ? 1 : -1); }
+  });
+  let swipe = null;
+  stage.addEventListener('pointerdown', e => { swipe = { x: e.clientX, y: e.clientY, t: Date.now() }; });
+  stage.addEventListener('pointerup', e => {
+    const s = swipe; swipe = null;
+    if (!s || Date.now() - s.t > 800) return;
+    const dx = e.clientX - s.x, dy = e.clientY - s.y;
+    if (Math.abs(dx) >= 50 && Math.abs(dx) > 2 * Math.abs(dy)) step(dx < 0 ? 1 : -1);
+  });
+  addEventListener('resize', draw);
+  draw();
+  dialog.showModal();
+}
+
+if (typeof module !== 'undefined') module.exports = { MOMENT_CATS, trimPages, arrange, momentPageLabel };

public/perf.js

@@ -0,0 +1,72 @@
+'use strict';
+/*
+ * Reader-side half of the performance trace (docs/performance.md). Only started when the server says its
+ * trace is on (`perf: true` in /api/chapter). It reports, in batches to POST api/perf:
+ *  - `res`  the browser's resource timing of every library image: queueing, connection, time to first byte,
+ *           download, size, the server's own `stat` time and whether the connection was reused;
+ *  - `view` a page turn (page/book mode): how long the new page(s) took to appear, and whether they were
+ *           preloaded already;
+ *  - `stall` flow mode: a page scrolled into view before its image had loaded, and how long it stayed empty.
+ */
+window.PerfTrace = {
+  start(pageName) {
+    let queue = [], on = true;
+    const push = e => { if (on) queue.push(e); };
+    const rel = url => { try { return decodeURIComponent(new URL(url).pathname); } catch { return String(url); } };
+    const flush = beacon => {
+      if (!queue.length || !on) return;
+      const body = JSON.stringify({ page: pageName, events: queue.splice(0, 300) });
+      if (beacon && navigator.sendBeacon) navigator.sendBeacon('api/perf', new Blob([body], { type: 'application/json' }));
+      else fetch('api/perf', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body, keepalive: true })
+        .then(r => r.json()).then(r => { if (r.on === false) on = false; }).catch(() => {});
+    };
+    setInterval(() => flush(false), 5000);
+    addEventListener('pagehide', () => flush(true));
+    push({ e: 'hello', ua: navigator.userAgent, conn: navigator.connection ? navigator.connection.effectiveType : '',
+      dpr: devicePixelRatio, vw: innerWidth, vh: innerHeight });
+
+    if (window.PerformanceObserver) {
+      new PerformanceObserver(list => {
+        for (const r of list.getEntries()) {
+          if (!/\/lib\//.test(r.name)) continue;
+          const st = (r.serverTiming || []).find(x => x.name === 'stat');
+          push({ e: 'res', url: rel(r.name), at: r.startTime,
+            queue: r.requestStart ? r.requestStart - r.startTime : null,        // waiting for a free connection
+            connect: r.connectEnd - r.connectStart, dns: r.domainLookupEnd - r.domainLookupStart,
+            ttfb: r.responseStart && r.requestStart ? r.responseStart - r.requestStart : null,
+            download: r.responseStart ? r.responseEnd - r.responseStart : null,
+            total: r.duration, size: r.transferSize, body: r.encodedBodySize, server: st ? st.duration : null,
+            proto: r.nextHopProtocol || '', cached: r.transferSize === 0 && r.encodedBodySize > 0 });
+        }
+      }).observe({ type: 'resource', buffered: true });
+    }
+
+    return {
+      // Called right after a page turn put new <img> elements on screen.
+      view(imgs, info) {
+        const t0 = performance.now(), waiting = imgs.filter(img => !img.complete);
+        const event = { e: 'view', ...info, n: imgs.length, preloaded: !waiting.length };
+        if (!waiting.length) { push({ ...event, wait: 0 }); return; }
+        Promise.all(waiting.map(img => (img.decode ? img.decode() : Promise.resolve()).catch(() => {})))
+          .then(() => requestAnimationFrame(() => push({ ...event, wait: performance.now() - t0,
+            url: rel(waiting[0].currentSrc || waiting[0].src) })));
+      },
+      // Flow mode: watch pages enter the real viewport (not the preload margin) before their image is there.
+      watchFlow(root, els) {
+        if (!window.IntersectionObserver) return;
+        const io = new IntersectionObserver(entries => {
+          for (const en of entries) {
+            const img = en.target.firstChild;
+            if (!en.isIntersecting || (img.complete && img.naturalWidth)) continue;
+            const t0 = performance.now(), hadSrc = !!img.getAttribute('src');
+            const done = () => push({ e: 'stall', wait: performance.now() - t0, hadSrc, url: rel(img.currentSrc || img.src) });
+            img.addEventListener('load', done, { once: true });
+            io.unobserve(en.target);
+          }
+        }, { root });
+        for (const el of els) io.observe(el);
+        return io;
+      },
+    };
+  },
+};

public/read.html

@@ -14,6 +14,9 @@
 <script src="common.js" defer></script>
 <script src="reading-clock-core.js" defer></script>
 <script src="reading-clock.js" defer></script>
+<script src="keys.js" defer></script>
+<script src="moments.js" defer></script>
+<script src="perf.js" defer></script>
 <script src="reader.js" defer></script>
 </head>
 <body class="reader">
@@ -23,6 +26,7 @@
   <a id="back" class="btn icon" href="./" title="Back to the manga" aria-label="Back">‹</a>
   <div id="title" class="grow"></div>
   <select id="chsel" title="Jump to a chapter" aria-label="Chapter"></select>
+  <button id="moment" class="btn icon moment-btn" title="Save a moment of this page (M)" aria-label="Save a moment"><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 3.5h10v17l-5-3.6l-5 3.6z"/><path d="M19.5 2.5v5M17 5h5"/></svg></button>
   <button id="fs" class="btn icon" title="Fullscreen" aria-label="Fullscreen"><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5"/></svg></button>
 </div>
 

public/reader.js

@@ -74,6 +74,9 @@
     D = payload;
   }
   catch (e) { canvas.textContent = ''; canvas.append(h('p', { class: 'loading' }, e.message + ' · ', h('a', { href: './' }, 'Library'))); return; }
+  // Timings for the server's performance trace, only while an admin has it switched on.
+  const perf = D.perf && window.PerfTrace ? PerfTrace.start('read') : null;
+  let perfFlow = null;
 
   // An already-open chapter also closes when a window ends or an unlock expires.
   const checkReadingAccess = async () => {
@@ -149,6 +152,8 @@
     const k = list.findIndex(x => x.i >= p);
     cur = k < 0 ? list.length - 1 : k;
   }
+  // A link to a page (e.g. "Open in reader" from a moment) wins over the saved position.
+  if (P.get('p') != null) { const k = list.findIndex(x => x.i >= +P.get('p')); if (k >= 0) cur = k; }
 
   // Book mode: pages pair up inside each run of single pages. Runs restart after every double page / cover,
   // so one missing pair never shifts the rest of the chapter. "Shift" makes a run start with a lone page.
@@ -248,11 +253,13 @@
     if (mode === 'flow') {
       els = list.map(p => canvas.appendChild(pageEl(p, true)));
       endEl = canvas.appendChild(endCard());
+      if (perf) { if (perfFlow) perfFlow.disconnect(); perfFlow = perf.watchFlow(stage, els); }
     } else if (atEnd) {
       endEl = canvas.appendChild(endCard());
     } else {
       shown = mode === 'page' ? [cur] : spreads[spreadIdx];
       els = shown.map(k => canvas.appendChild(pageEl(list[k])));
+      if (perf) perf.view(els.map(el => el.firstChild), { mode, page: list[shown[0]].i });
       // The pages on screen get the bandwidth first, then the next ones are fetched.
       const token = ++buildToken, waiting = els.map(el => el.firstChild).filter(img => !img.complete);
       Promise.all(waiting.map(img => new Promise(done => {
@@ -480,18 +487,69 @@
     else toggleBars();
   });
 
+  // Keys are looked up in READER_KEYS (keys.js), the same table Settings and "?" show.
+  const keyActions = {
+    turn: e => { e.preventDefault(); (e.key === (rtl ? 'ArrowLeft' : 'ArrowRight') ? next : prev)(); },
+    forward: e => { if (mode === 'flow') return; e.preventDefault(); (e.shiftKey ? prev : next)(); },
+    back: e => { if (mode === 'flow') return; e.preventDefault(); prev(); },
+    zoomIn: () => stepZoom(1),
+    zoomOut: () => stepZoom(-1),
+    zoomFit: () => setZoom(1),
+    moment: e => { e.preventDefault(); saveMoment(); },
+    bars: () => toggleBars(),
+    fullscreen: () => toggleFullscreen(),
+    help: () => showKeys(),
+  };
   addEventListener('keydown', e => {
     if ((e.target.closest && e.target.closest('input, select, textarea')) || e.ctrlKey || e.metaKey || e.altKey) return;
-    const k = e.key;
-    if (k === 'ArrowLeft' || k === 'ArrowRight') { e.preventDefault(); (k === (rtl ? 'ArrowLeft' : 'ArrowRight') ? next : prev)(); }
-    else if ((k === ' ' || k === 'PageDown') && mode !== 'flow') { e.preventDefault(); (e.shiftKey ? prev : next)(); }
-    else if (k === 'PageUp' && mode !== 'flow') { e.preventDefault(); prev(); }
-    else if (k === '+' || k === '=') stepZoom(1);
-    else if (k === '-') stepZoom(-1);
-    else if (k === '0') setZoom(1);
-    else if (k === 'm' || k === 'Escape') toggleBars();
-    else if (k === 'f') toggleFullscreen();
+    if (document.querySelector('dialog[open]')) return; // an open dialog handles its own keys (Esc closes it)
+    const action = keyAction(READER_KEYS, e.key);
+    if (action) keyActions[action](e);
   });
+  function showKeys() {
+    const dialog = openDialog('key-dialog', () => stage.focus({ preventScroll: true }));
+    dialog.append(
+      h('div', { class: 'moment-head' }, h('h2', {}, 'Keyboard shortcuts'),
+        h('button', { class: 'btn icon', type: 'button', 'aria-label': 'Close', onclick: () => dialog.done() }, '×')),
+      keyTable([{ title: 'Reader', keys: READER_KEYS }]),
+      h('p', { class: 'muted small' }, 'Also listed in Settings → Keyboard shortcuts.'));
+    dialog.showModal();
+  }
+
+  // ---------- moments ----------
+  const momentPages = new Set((D.moments || []).flatMap(x => x.pages));
+  const momentPage = p => ({ i: p.i, u: p.u, w: D.pages[p.i].w, h: D.pages[p.i].h, r: p.r });
+  // Positions in `list` of the page(s) on screen, in reading order. In Flow the page at the reading line.
+  function currentRange() {
+    if (atEnd && mode !== 'flow') return null;
+    const ks = (mode === 'book' ? shown : [cur]).filter(k => list[k]);
+    return ks.length ? [Math.min(...ks), Math.max(...ks)] : null;
+  }
+  function currentPages() {
+    const range = currentRange();
+    return range ? list.slice(range[0], range[1] + 1).map(momentPage) : [];
+  }
+  let momentOpen = false;
+  async function saveMoment() {
+    const range = currentRange();
+    if (!range) return toast('No page here');
+    if (momentOpen) return;
+    momentOpen = true;
+    const chapter = D.chapters.find(c => c.id === D.chapter.id), book = D.books.length > 1 && chapter && D.books.find(b => b.key === chapter.book);
+    // A picture can run over several pages: the sheet can add neighbours, stacked in Flow, side by side in Page/Book.
+    const saved = await momentSheet({
+      heading: 'Save moment', sequence: list.map(momentPage), range, layout: mode === 'flow' ? 'column' : 'row', rtl,
+      context: [D.manga.title, [book && book.label, D.chapter.label + (D.chapter.title ? ' · ' + D.chapter.title : '')].filter(Boolean).join(' · ')],
+      save: async v => (await api('api/moments', { m: D.manga.id, c: D.chapter.id, v: D.version, pages: v.pages.map(p => p.i), layout: v.layout,
+        region: v.region, cat: v.cat, note: v.note })).moment,
+    });
+    momentOpen = false;
+    stage.focus({ preventScroll: true });
+    if (!saved) return;
+    for (const p of saved.pages) momentPages.add(p.i);
+    updateUI();
+    toast(`Saved · ${momentCat(saved.cat).label} moment`, 1500);
+  }
 
   let scrollRaf = 0;
   stage.addEventListener('scroll', () => {
@@ -598,8 +656,8 @@
     const key = mode === 'flow' ? 'hint.flow' : 'hint.paged';
     if (store.get(key)) return;
     store.set(key, '1');
-    toast(mode === 'flow' ? 'Controls hidden · tap the middle of the screen or beside the pages to show them'
-      : 'Controls hidden · tap the middle of the page or beside it to show them', 3500);
+    toast(mode === 'flow' ? 'Controls hidden · tap the middle of the screen or beside the pages (or press I) to show them'
+      : 'Controls hidden · tap the middle of the page or beside it (or press I) to show them', 3500);
   }
 
   let toastTimer = 0;
@@ -625,6 +683,9 @@
     sh.hidden = mode !== 'book';
     sh.classList.toggle('on', shown.length > 0 && !solo(list[shown[0]]) && shift.has(list[runStart(shown[0])].i));
     $('#zoom').textContent = Math.round(zoom() * 100) + '%';
+    const hasMoment = currentPages().some(p => momentPages.has(p.i));
+    $('#moment').classList.toggle('on', hasMoment);
+    $('#moment').title = (hasMoment ? 'This page has a moment · save another' : 'Save a moment of this page') + ' (M)';
   }
 
   let saveTimer = 0;
@@ -669,6 +730,7 @@
   ver.onchange = () => { saveProgress(true); location.href = readUrl(D.manga.id, D.chapter.id, ver.value); };
   for (const b of modeBtns) b.onclick = () => { if (b.dataset.mode !== mode) setMode(b.dataset.mode, true); };
   toneButton.onclick = cycleTone;
+  $('#moment').onclick = saveMoment;
   $('#shift').onclick = toggleShift;
   $('#zoomout').onclick = () => stepZoom(-1);
   $('#zoom').onclick = () => setZoom(1);

public/settings-nav.js

@@ -5,6 +5,7 @@ const SETTINGS_SECTIONS = [
   { id: 'user/reading', group: 'User', title: 'Reading', hint: 'Reader modes, page spacing and zoom.' },
   { id: 'user/reading-hours', group: 'User', title: 'Reading hours', hint: 'When this server allows chapter reading.' },
   { id: 'user/reading-time', group: 'User', title: 'Reading time & privacy', hint: 'Your clock, Reading Story and personal data.' },
+  { id: 'user/shortcuts', group: 'User', title: 'Keyboard shortcuts', hint: 'Every key the reader understands. Press ? in the reader for the same list.' },
   { id: 'user/notifications', group: 'User', title: 'Notifications', hint: 'Chapter alerts and your optional webhook.' },
   { id: 'user/account', group: 'User', title: 'Account', hint: 'Your account and password.' },
   { id: 'admin/scraper', group: 'Admin', title: 'Scraper', hint: 'Live activity, downloads, update checks and sources.' },

public/settings.html

@@ -9,6 +9,7 @@
 <link rel="manifest" href="manifest.webmanifest">
 <meta name="theme-color" content="#121214">
 <script src="common.js" defer></script>
+<script src="keys.js" defer></script>
 <script src="settings-nav.js" defer></script>
 <script src="settings.js" defer></script>
 </head>

public/settings.js

@@ -15,11 +15,61 @@
   const saved = h('span', { class: 'saved', hidden: true }, 'Saved');
   shell.titleRow.append(saved);
   let savedTimer = 0;
+  let refreshSessions = () => {};
   async function save(patch) {
     Object.assign(S, (await api('api/settings', patch)).settings);
     saved.hidden = false;
     clearTimeout(savedTimer);
     savedTimer = setTimeout(() => { saved.hidden = true; }, 1500);
+    refreshSessions();
+  }
+
+  // Which login session holds which reader settings (reader-sessions.js on the server).
+  function readerSessionsCard() {
+    const TONE = { original: 'Original', inverted: 'Inverted', sepia: 'Sepia', dim: 'Dim', 'extra-dim': 'Extra dim' };
+    const START = { last: 'last mode', flow: 'always Flow', page: 'always Page', book: 'always Book' };
+    const summary = r => [`${LABEL[r.lastMode] || r.lastMode} (opens: ${START[r.startMode] || r.startMode})`, `tone ${TONE[r.pageTone] || r.pageTone}`,
+      'zoom ' + (Object.keys(r.zoom || {}).length ? Object.entries(r.zoom).map(([k, z]) => `${LABEL[k] || k} ${Math.round(z * 100)}%`).join(', ') : 'fit'),
+      r.skipExtras ? 'skips extras' : null, r.skipCovers ? 'skips covers' : null, r.flowPageGap === false ? 'no Flow gap' : null].filter(Boolean).join(' · ');
+    const state = h('div', {}, h('p', { class: 'muted' }, 'Loading sessions…'));
+    const message = h('span', { class: 'small' });
+    async function act(id, action, current) {
+      try {
+        draw(await api('api/reader-sessions', { id, action }));
+        // This page's controls show this session's settings; reload them when they changed.
+        if (current && action === 'follow') location.reload();
+      } catch (error) { message.textContent = error.message; message.className = 'small error'; }
+    }
+    function draw(o) {
+      const current = o.sessions.find(s => s.current), source = o.sessions.find(s => s.id === o.latestFrom);
+      const latestText = !o.latestFrom ? 'one shared set (changed while per-session settings were off, or never changed)'
+        : source ? (source.current ? 'this session' : `${source.device}, active ${ago(source.seen)}`) : 'a session that has since signed out';
+      const intent = !o.enabled ? 'Off: every session uses the same reader settings, and a change applies everywhere.'
+        : current?.locked ? 'This session has its own reader settings. Changes here stay here and become the starting point for new sessions.'
+        : 'This session follows the latest reader settings. Your first change here gives it its own copy, which stays put when other sessions change theirs.';
+      state.replaceChildren(
+        h('p', {}, h('b', {}, 'Now: '), intent),
+        o.enabled ? h('p', { class: 'muted small' }, 'New sessions start from the latest settings: ', h('b', {}, summary(o.latest)), ` — from ${latestText}.`)
+          : h('p', { class: 'muted small' }, 'Shared settings: ', h('b', {}, summary(o.latest))),
+        h('ul', { class: 'reader-sessions' }, o.sessions.map(s => h('li', {},
+          h('div', {}, h('b', {}, s.device), s.current ? ' (this session)' : '', ' · ',
+            h('span', { class: 'muted small' }, `signed in ${new Date(s.created).toLocaleDateString()}, active ${ago(s.seen)}`)),
+          h('div', { class: 'small' }, !o.enabled ? 'Uses the shared settings' + (s.locked ? ' (its own copy is kept for when this is on again)' : '')
+            : s.locked ? 'Own settings: ' + summary(s.reader) : 'Follows the latest settings'),
+          o.enabled ? h('div', { class: 'row' },
+            s.locked ? h('button', { class: 'btn small', onclick: () => act(s.id, 'follow', s.current) }, 'Follow latest again') : null,
+            s.locked && s.id !== o.latestFrom ? h('button', { class: 'btn small', onclick: () => act(s.id, 'latest', s.current) }, 'Use for new sessions') : null) : null))),
+        message);
+    }
+    refreshSessions = () => api('api/reader-sessions').then(draw, error => { message.textContent = error.message; message.className = 'small error'; });
+    refreshSessions();
+    return h('section', { class: 'card' },
+      h('h2', {}, 'Reader settings per session'),
+      // The controls above switch between this session's set and the shared one, so reload them.
+      h('label', { class: 'check' },
+        h('input', { type: 'checkbox', checked: !!S.readerPerSession, onchange: async e => { await save({ readerPerSession: e.target.checked }); location.reload(); } }),
+        h('span', {}, 'Keep reader settings per session', h('div', { class: 'muted small' }, 'Each sign-in (device or browser) keeps its own reader mode, zoom, tone and the other reader preferences above once you change one there. A new sign-in copies the settings of the session you used last. Turn this off for one shared set.'))),
+      state);
   }
   const check = (key, text, hint) => h('label', { class: 'check' },
     h('input', { type: 'checkbox', checked: !!S[key], onchange: e => save({ [key]: e.target.checked }) }),
@@ -90,6 +140,13 @@
       h('button', { class: 'btn small', onclick: async () => { await save({ zoom: {} }); zoomText.textContent = zooms(); } }, 'Reset to fit'),
       h('div', { class: 'muted small' }, '100% = the page fits the screen. Change it in the reader with Ctrl + mouse wheel, a pinch, or the + / - keys.'))));
 
+  section('user/reading').append(readerSessionsCard());
+
+  section('user/reading').append(h('section', { class: 'card' },
+    h('h2', {}, 'Library page'),
+    check('continueRow', 'Show "Continue where you left off" at the top',
+      'One row with the five manga you read most recently and have not finished. It hides itself while you search, filter by status, or sort by "Recently read".')));
+
   section('user/reading').append(h('section', { class: 'card' },
     h('h2', {}, 'Chapter list dates'),
     h('label', { class: 'field' }, h('span', {}, 'When I read a chapter'), readDate,
@@ -135,6 +192,7 @@
   const oldPw = h('input', { type: 'password', autocomplete: 'current-password', placeholder: 'Current password' });
   const newPw = h('input', { type: 'password', autocomplete: 'new-password', placeholder: 'New password' });
   const pwMsg = h('span', { class: 'small' });
+  section('user/shortcuts').append(h('section', { class: 'card' }, keyTable()));
   section('user/account').append(h('section', { class: 'card' },
     h('h2', {}, 'Account · ' + me.name),
     h('div', { class: 'row' }, oldPw, newPw, h('button', { class: 'btn', onclick: async () => {

reader-sessions.js

@@ -0,0 +1,88 @@
+'use strict';
+/* Reader settings per login session (docs/architecture.md, "Reader settings per session").
+ *
+ * The user's own reader settings (`user.settings`) are the "latest" set. A session that never changed a
+ * reader setting follows the latest set; the first change copies the latest set into the session and
+ * locks it there, and also makes it the new latest set. Using a locked session makes its set the latest
+ * again, so a new login starts from the last active session. With `readerPerSession: false` there is
+ * one set per user, as before; locked sets are kept and return when the switch is turned on again. */
+const crypto = require('crypto');
+
+const READER_KEYS = ['startMode', 'lastMode', 'adapt', 'skipExtras', 'skipCovers', 'flowPageGap', 'pageTone', 'zoom'];
+
+const perSession = settings => settings.readerPerSession !== false;
+const publicId = key => crypto.createHash('sha256').update('reader-session:' + key).digest('hex').slice(0, 16);
+
+function pick(settings) {
+  const out = {};
+  for (const k of READER_KEYS) if (settings[k] !== undefined) out[k] = k === 'zoom' ? { ...settings[k] } : settings[k];
+  return out;
+}
+
+// `base` is the user's merged settings (defaults + user.settings); the session's locked set wins over it.
+function effective(base, session) {
+  if (!perSession(base) || !session?.reader) return base;
+  return { ...base, ...pick(session.reader), zoom: { ...session.reader.zoom } };
+}
+
+// Splits a validated settings patch: reader keys go to the session (locking it) and to the latest set.
+function applyPatch({ user, base, session, key, patch }) {
+  const s = (user.settings = user.settings || {});
+  const reader = pick(patch), rest = Object.fromEntries(Object.entries(patch).filter(([k]) => !READER_KEYS.includes(k)));
+  Object.assign(s, rest);
+  if (!Object.keys(reader).length) return;
+  if (perSession({ ...base, ...rest }) && session) {
+    session.reader = { ...pick(effective(base, session)), ...reader };
+    Object.assign(s, pick(session.reader));
+    user.readerFrom = publicId(key);
+  } else {
+    Object.assign(s, reader);
+    user.readerFrom = null;
+  }
+}
+
+// A request from a locked session makes its set the latest one. Returns true when something changed.
+function noteActive(user, base, session, key) {
+  if (!perSession(base) || !session?.reader) return false;
+  const id = publicId(key);
+  if (user.readerFrom === id) return false;
+  user.settings = { ...(user.settings || {}), ...pick(session.reader) };
+  user.readerFrom = id;
+  return true;
+}
+
+function deviceLabel(agent) {
+  const a = String(agent || '');
+  if (!a) return 'Unknown device';
+  const os = /iPhone/.test(a) ? 'iPhone' : /iPad/.test(a) ? 'iPad' : /Android/.test(a) ? 'Android'
+    : /Windows/.test(a) ? 'Windows' : /Mac OS X|Macintosh/.test(a) ? 'Mac' : /CrOS/.test(a) ? 'ChromeOS' : /Linux/.test(a) ? 'Linux' : '';
+  const browser = /Edg\//.test(a) ? 'Edge' : /OPR\//.test(a) ? 'Opera' : /Firefox\//.test(a) ? 'Firefox'
+    : /Chrome\//.test(a) ? 'Chrome' : /Safari\//.test(a) ? 'Safari' : '';
+  return [browser, os].filter(Boolean).join(' on ') || a.slice(0, 60);
+}
+
+// What Settings shows: every login session of the user with its state and effective reader set.
+function overview(user, base, sessions, currentKey) {
+  const list = Object.entries(sessions).filter(([, s]) => s.u === user.name).map(([key, s]) => ({
+    id: publicId(key), device: deviceLabel(s.agent), created: s.t, seen: s.seen || s.t,
+    current: key === currentKey, locked: !!s.reader, reader: pick(effective(base, s)),
+  })).sort((a, b) => b.current - a.current || b.seen - a.seen);
+  return { enabled: perSession(base), current: currentKey ? publicId(currentKey) : null,
+    latestFrom: user.readerFrom || null, latest: pick(base), sessions: list };
+}
+
+// Settings actions on one of the user's sessions: 'follow' drops its lock, 'latest' makes its set the latest.
+function act(user, base, sessions, id, action) {
+  const entry = Object.entries(sessions).find(([key, s]) => s.u === user.name && publicId(key) === id);
+  if (!entry) return false;
+  const [key, session] = entry;
+  if (action === 'follow') { delete session.reader; if (user.readerFrom === id) user.readerFrom = null; return true; }
+  if (action === 'latest') {
+    user.settings = { ...(user.settings || {}), ...pick(effective(base, session)) };
+    user.readerFrom = session.reader ? publicId(key) : null;
+    return true;
+  }
+  return false;
+}
+
+module.exports = { READER_KEYS, publicId, pick, effective, applyPatch, noteActive, deviceLabel, overview, act };

scraper/daemon.js

@@ -35,6 +35,7 @@ async function body(req) {
       if (url.pathname === '/health') return json(res, 200, { ok: true, status: service.state.status });
       if (TOKEN && req.headers.authorization !== `Bearer ${TOKEN}`) return json(res, 401, { error: 'Unauthorized' });
       if (req.method === 'GET' && url.pathname === '/api/state') return json(res, 200, await service.publicState());
+      if (req.method === 'GET' && url.pathname === '/api/revision') return json(res, 200, service.revision());
       if (req.method !== 'POST') return json(res, 404, { error: 'Not found' });
       const input = await body(req);
       if (url.pathname === '/api/queue') return json(res, 200, { item: await service.enqueue(input), state: await service.publicState() });

scraper/service.js

@@ -16,6 +16,7 @@ const { writeJsonAtomic } = require('./lib/json-file');
 const { ReleaseDateSources, refreshMangaReleaseDates } = require('./metadata/release-dates');
 
 const RATE_KEYS = ['minMs', 'maxMs', 'chapterMinMs', 'chapterMaxMs'];
+const INVENTORY_SUMMARY_MS = 15 * 60000; // status summary age limit; decisions still scan (libraryInventory)
 const FAST_RATE_SETTINGS = {
   minMs: 1000, maxMs: 4000, chapterMinMs: 5000, chapterMaxMs: 15000,
 };
@@ -401,7 +402,7 @@ class ScraperService {
       } catch (error) { await this.event('warning', `Release dates for ${manga.title} failed: ${error.message}`, { mangaId: manga.id }); }
     }
     // The reader reconciles fully when the revision rises without a visible folder change.
-    if (written) { this.state.publishedRevision = Number(this.state.publishedRevision || 0) + 1; await this.persist(); }
+    if (written) { this.invalidateInventory(); this.state.publishedRevision = Number(this.state.publishedRevision || 0) + 1; await this.persist(); }
     await this.event('info', `Release dates: ${written} chapter${written === 1 ? '' : 's'} dated in ${checked} ongoing series`, { reason, checked, written });
     return { checked, written };
   }
@@ -583,6 +584,15 @@ class ScraperService {
     } catch { return null; }
   }
 
+  inventoryStale() {
+    return this.inventoryCacheGeneration !== this.inventoryGeneration || Date.now() - this.inventoryCachedAt >= INVENTORY_SUMMARY_MS;
+  }
+
+  // What the reader polls every few seconds: no library walk, no event log read.
+  revision() {
+    return { publishedRevision: this.state.publishedRevision || 0, status: this.state.status, paused: this.state.paused };
+  }
+
   async publicState() {
     const activeItems = this.state.queue.filter(item => Object.values(this.state.currentIds || {}).includes(item.id));
     const active = await Promise.all(activeItems.map(async current => ({
@@ -593,8 +603,9 @@ class ScraperService {
     const job = active[0]?.job || null;
     // Status and watchdog probes must not wait for thousands of bind-mount reads.
     // Share one background scan, serve the previous summary, and surface its age/error.
-    if (!this.inventoryRefresh && (this.inventoryCacheGeneration !== this.inventoryGeneration || Date.now() - this.inventoryCachedAt >= 60000)
-        && Date.now() - this.inventoryAttemptedAt >= 10000) {
+    // The scraper is the library's only writer and invalidates the summary on every publish, so the age
+    // limit only catches outside edits. A walk reads every chapter.json: on a NAS that is ~10,000 opens.
+    if (!this.inventoryRefresh && this.inventoryStale() && Date.now() - this.inventoryAttemptedAt >= 10000) {
       this.refreshInventory().catch(() => {});
     }
     const inventory = this.inventoryCache;
@@ -609,7 +620,7 @@ class ScraperService {
       updateChecks: Object.values(this.state.updateChecks || {}),
       libraryStatus: {
         ready: !!inventory, refreshing: !!this.inventoryRefresh,
-        stale: this.inventoryCacheGeneration !== this.inventoryGeneration || Date.now() - this.inventoryCachedAt >= 60000,
+        stale: this.inventoryStale(),
         updated: this.inventoryCachedAt ? new Date(this.inventoryCachedAt).toISOString() : null,
         error: this.inventoryError,
       },

scraper/test/inventory-cache.test.js

@@ -80,6 +80,23 @@ test('background inventory failures are visible without breaking controls or lau
   assert.equal(scans, 2);
 });
 
+test('status polling walks the library again only after a change or after 15 minutes', async () => {
+  let scans = 0;
+  const service = fixture(async () => { scans++; return inventory('Demo'); });
+  await service.libraryInventory(true);
+  service.inventoryCachedAt = Date.now() - 10 * 60000; service.inventoryAttemptedAt = 0;
+  for (let n = 0; n < 5; n++) await service.publicState();
+  assert.equal(scans, 1);
+  assert.deepEqual(service.revision(), { publishedRevision: 0, status: 'paused', paused: true });
+  assert.equal(scans, 1);
+  service.invalidateInventory();
+  await service.publicState(); await service.inventoryRefresh;
+  assert.equal(scans, 2);
+  service.inventoryCachedAt = Date.now() - 16 * 60000; service.inventoryAttemptedAt = 0;
+  await service.publicState(); await service.inventoryRefresh;
+  assert.equal(scans, 3);
+});
+
 test('dashboard polling reuses a recent snapshot while decisions still force a fresh scan', async () => {
   let scans = 0;
   const service = fixture(async () => { scans++; return inventory('Demo'); });

server.js

@@ -12,6 +12,8 @@
  *   SCRAPER_URL=http://127.0.0.1:8091   scraper daemon API
  *   SCRAPER_TOKEN=...                    shared daemon token (optional on loopback)
  *   BACKUP=/backup       folder for built-in DATA backups (unset = backups off)
+ *   READ_AHEAD=1         read an opened chapter's pages (then the next chapter's) into the OS cache, 0 = off
+ *   PERF_TRACE=1         performance trace to DATA/perf/ (or touch DATA/perf/trace.on at runtime; docs/performance.md)
  */
 const http = require('http'), fs = require('fs'), path = require('path'), crypto = require('crypto');
 const { scanLibrary, scanChangedLibrary, libraryStamps, snapshotIndex, restoreIndex } = require('./library');
@@ -19,6 +21,7 @@ const { Catalog, CatalogError, collectionViews, TYPES, ROLES } = require('./cata
 const { RATINGS: GREATEST_RATINGS, loadCatalog: loadGreatestCatalog, findOwned: findGreatestOwned,
   countsFor: greatestCounts, scoreFor: greatestScore } = require('./greatest');
 const { hosterLinks } = require('./greatest/hosters');
+const { GreatestCovers } = require('./greatest/covers');
 const { secret } = require('./runtime/config');
 const { PeeringState, requirePeer } = require('./peering/state');
 const peerClient = require('./peering/client');
@@ -34,6 +37,10 @@ const {
 const { chapterDates } = require('./chapter-dates');
 const { parseSchedule, publicSchedule, loadQuestionBank, createReadingAccess } = require('./reading-access');
 const { BackupService, BackupError } = require('./backup');
+const moments = require('./moments');
+const { Tracer, requestTrace } = require('./perf/trace');
+const { ReadAhead } = require('./perf/read-ahead');
+const readerSessions = require('./reader-sessions');
 
 const PORT = +process.env.PORT || 8080;
 const LIB = path.resolve(process.env.LIBRARY || 'library');
@@ -62,11 +69,18 @@ const MIME = {
 
 // ---------- storage: one JSON file, written atomically ----------
 fs.mkdirSync(DATA, { recursive: true });
+const tracer = new Tracer({ dir: path.join(DATA, 'perf') }).start();
+const readAhead = process.env.READ_AHEAD === '0' ? null
+  : new ReadAhead({ onBatch: batch => tracer.log({ k: 'ahead', ...batch }) });
 const catalog = new Catalog(DATA);
 const greatestCatalog = loadGreatestCatalog();
 const greatestById = new Map(greatestCatalog.entries.map(entry => [entry.id, entry]));
+const greatestCovers = new GreatestCovers(path.join(DATA, 'greatest-covers'));
+// The versioned URL lets browsers keep a cover for a year; a new catalog URL changes `v`.
+const greatestCoverUrl = entry => entry.cover
+  ? `api/greatest-cover?id=${encodeURIComponent(entry.id)}&v=${greatestCovers.version(entry.cover)}` : null;
 const DB_FILE = path.join(DATA, 'db.json'), CACHE_FILE = path.join(DATA, 'scan-cache.json'), INDEX_FILE = path.join(DATA, 'library-index.json');
-const db = { users: {}, sessions: {}, progress: {}, reading: {}, readingAccess: {}, follows: {}, notes: {}, votes: {}, greatestRatings: {}, discoveryFeedback: {}, known: {} };
+const db = { users: {}, sessions: {}, progress: {}, reading: {}, readingAccess: {}, follows: {}, notes: {}, votes: {}, greatestRatings: {}, discoveryFeedback: {}, moments: {}, known: {} };
 // A corrupt db.json stops the server instead of silently starting empty and overwriting it.
 if (fs.existsSync(DB_FILE)) Object.assign(db, JSON.parse(fs.readFileSync(DB_FILE, 'utf8')));
 function writeAtomic(file, text) { fs.writeFileSync(file + '.tmp', text); fs.renameSync(file + '.tmp', file); }
@@ -106,8 +120,10 @@ function checkPw(pw, stored) {
 }
 const DUMMY_HASH = hashPw('x');
 const DEFAULTS = { startMode: 'last', lastMode: 'page', adapt: true, skipExtras: false, skipCovers: false, flowPageGap: true, pageTone: 'original', readingClock: false, readingStory: true,
-  readDate: 'hour', releaseDate: true, discoveryEnabled: false, discoveryReadingActivity: false, discoveryMature: false, zoom: {}, webhook: '' };
-const settingsOf = u => ({ ...DEFAULTS, ...u.settings, zoom: { ...(u.settings && u.settings.zoom) } });
+  continueRow: true, readDate: 'hour', releaseDate: true, discoveryEnabled: false, discoveryReadingActivity: false, discoveryMature: false, zoom: {}, webhook: '', readerPerSession: true };
+const userSettingsOf = u => ({ ...DEFAULTS, ...u.settings, zoom: { ...(u.settings && u.settings.zoom) } });
+// With a login session, its locked reader settings (reader-sessions.js) win over the user's latest set.
+const settingsOf = (u, sess) => readerSessions.effective(userSettingsOf(u), sess);
 
 function createUser(name, pw, admin, replace) {
   name = String(name || '').trim().toLowerCase(); pw = String(pw || '');
@@ -119,13 +135,21 @@ function createUser(name, pw, admin, replace) {
   save();
   return db.users[name];
 }
-function startSession(res, user) {
+function startSession(req, res, user) {
   const token = crypto.randomBytes(32).toString('base64url');
-  db.sessions[sha(token)] = { u: user.name, t: Date.now() };
+  db.sessions[sha(token)] = { u: user.name, t: Date.now(), agent: String(req.headers['user-agent'] || '').slice(0, 300) };
   save();
   res.setHeader('Set-Cookie', `sid=${token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=31536000${SECURE_COOKIE ? '; Secure' : ''}`);
 }
 const tokenOf = req => { const m = /(?:^|;\s*)sid=([^;]+)/.exec(req.headers.cookie || ''); return m ? m[1] : null; };
+function sessionKeyOf(req) { const t = tokenOf(req); return t ? sha(t) : null; }
+// Last-seen time (coarse, to keep db.json writes rare) and device label of a login session.
+function touchSession(u, sess, key, req) {
+  let changed = false;
+  if (!sess.agent && req.headers['user-agent']) { sess.agent = String(req.headers['user-agent']).slice(0, 300); changed = true; }
+  if (Date.now() - (sess.seen || 0) > 5 * 60e3) { sess.seen = Date.now(); changed = true; }
+  if (changed) save();
+}
 function userOf(req) { const t = tokenOf(req), s = t && db.sessions[sha(t)]; return (s && db.users[s.u]) || null; }
 for (const [k, s] of Object.entries(db.sessions)) if (Date.now() - s.t > 365 * 864e5 || !db.users[s.u]) delete db.sessions[k];
 
@@ -169,8 +193,10 @@ async function performScan(mode) {
       scanState = { at: Date.now(), ms: Date.now() - t0, mode, changedMangas: changed.length,
         mangas: lib.mangas.length, chapters, pages, stale: false, error: null };
       console.log(`[scan] ${mode}: ${changed.length} changed manga, ${lib.mangas.length} manga, ${chapters} chapters, ${pages} pages in ${scanState.ms} ms`);
+      tracer.log({ k: 'scan', mode, ms: scanState.ms, changed: changed.length });
       return scanState;
     } catch (e) {
+      tracer.log({ k: 'scan', mode, ms: Date.now() - t0, error: e.message });
       scanState = { ...scanState, at: Date.now(), error: e.message };
       console.error('[scan] failed:', e.message);
       return scanState;
@@ -226,6 +252,15 @@ const progressOf = (u, m) => (db.progress[u.name] && db.progress[u.name][m.id])
 const mangaReadingOf = (u, m) => (db.reading[u.name] && db.reading[u.name][m.id]) || {};
 const readingOf = (u, m, ch) => (db.reading[u.name] && db.reading[u.name][m.id] && db.reading[u.name][m.id][ch.id]) || null;
 const unreadOf = u => (db.notes[u.name] || []).filter(n => !n.read).length;
+const momentsOf = u => (db.moments[u.name] ||= []);
+const momentOf = (u, id) => momentsOf(u).find(x => x.id === String(id || '')) || bad(404, 'Moment not found');
+const fileSha = async rel => sha256File(path.join(LIB, rel)).catch(() => null);
+function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    fs.createReadStream(file).on('error', reject).on('data', d => hash.update(d)).on('end', () => resolve(hash.digest('hex')));
+  });
+}
 const admin = u => u.admin || bad(403, 'Admins only');
 const READING_LEASE_MS = 15000;
 const readingLeases = new Map();
@@ -238,9 +273,14 @@ async function scraperRequest(endpoint, body) {
     options.method = 'POST'; headers['content-type'] = 'application/json'; options.body = JSON.stringify(body);
   }
   let response;
+  const t0 = performance.now();
   try { response = await fetch(SCRAPER_URL + endpoint, options); }
-  catch (error) { throw new HttpError(503, `Scraper service unavailable: ${error.message}`); }
+  catch (error) {
+    tracer.log({ k: 'scraper', endpoint, ms: Math.round(performance.now() - t0), error: error.message });
+    throw new HttpError(503, `Scraper service unavailable: ${error.message}`);
+  }
   const data = await response.json().catch(() => ({}));
+  tracer.log({ k: 'scraper', endpoint, ms: Math.round(performance.now() - t0), status: response.status });
   if (!response.ok) throw new HttpError(response.status >= 500 ? 502 : response.status, data.error || `Scraper HTTP ${response.status}`);
   return data;
 }
@@ -418,6 +458,17 @@ function continueOf(m, prog, s) {
   const next = m.chapters.slice(m.chapters.indexOf(last.ch) + 1).find(ok);
   return next ? { c: next.id, text: 'Read next · ' + next.label } : { c: last.ch.id, v: last.p.v, text: 'Read again · ' + last.ch.label };
 }
+// From the saved page on, then the pages before it; afterwards the next chapter's preferred version.
+function warmChapter(u, m, ch, v, progress, s) {
+  const from = Math.min(Math.max(0, +(progress && progress.v === v.id && progress.p) || 0), v.pages.length);
+  const pages = v.pages.slice(from).concat(v.pages.slice(0, from)).map(p => path.join(LIB, v.rel, p.f));
+  readAhead.warm(pages, `${m.id}/${ch.id}`, u.name);
+  const next = neighbour(m, ch, 1, s), nextCh = next && m.chapterById.get(next.id);
+  if (nextCh) {
+    const nv = ranked(m, nextCh)[0].v;
+    readAhead.then(nv.pages.map(p => path.join(LIB, nv.rel, p.f)), `${m.id}/${nextCh.id}`, u.name);
+  }
+}
 function neighbour(m, ch, step, s) {
   for (let i = m.chapters.indexOf(ch) + step; i >= 0 && i < m.chapters.length; i += step) {
     const c = m.chapters[i];
@@ -431,11 +482,11 @@ const PUBLIC = new Set(['/api/auth', '/api/login', '/api/signup']);
 const routes = {
   'GET /api/health': () => ({ ok: !scanState.error, service: 'reader', uptime: Math.round(process.uptime()), scan: scanState }),
   'GET /api/collections': ({ u }) => ({ collections: routes['GET /api/library']({ u }).collections }),
-  'GET /api/collection': ({ u, q }) => {
+  'GET /api/collection': ({ u, q, sess }) => {
     const view = routes['GET /api/library']({ u }).collections.find(c => c.id === q.get('id')) || bad(404, 'Collection not found');
     const next = view.members.find(m => m.read < m.chapters) || view.members[0];
     const manga = mangaOf(next.id);
-    return { ...view, continue: { m: next.id, ...continueOf(manga, progressOf(u, manga), settingsOf(u)) },
+    return { ...view, continue: { m: next.id, ...continueOf(manga, progressOf(u, manga), settingsOf(u, sess)) },
       relations: catalog.state.relations.filter(r => r.state === 'confirmed' && view.members.some(m => m.id === r.from || m.id === r.to)) };
   },
   'GET /api/admin/catalog': ({ u }) => { admin(u); return { ...catalog.state, types: TYPES, roles: ROLES, mangas: lib.mangas.map(m => ({ id: m.id, title: m.title })) }; },
@@ -483,16 +534,16 @@ const routes = {
   },
   'GET /api/auth': () => ({ firstRun: !Object.keys(db.users).length, signup: OPEN_SIGNUP }),
 
-  'POST /api/signup': ({ b, res }) => {
+  'POST /api/signup': ({ req, b, res }) => {
     const first = !Object.keys(db.users).length;
     if (!first && !OPEN_SIGNUP) bad(403, 'Sign-up is closed. Ask an admin for an account.');
-    startSession(res, createUser(b.name, b.password, first));
+    startSession(req, res, createUser(b.name, b.password, first));
     return { ok: true };
   },
-  'POST /api/login': ({ b, res }) => {
+  'POST /api/login': ({ req, b, res }) => {
     const user = db.users[String(b.name || '').trim().toLowerCase()], pw = String(b.password || '');
     if (!checkPw(pw, user ? user.hash : DUMMY_HASH) || !user) bad(403, 'Wrong user name or password.');
-    startSession(res, user);
+    startSession(req, res, user);
     return { ok: true };
   },
   'POST /api/logout': ({ req, res }) => {
@@ -501,7 +552,18 @@ const routes = {
     res.setHeader('Set-Cookie', 'sid=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0');
     return { ok: true };
   },
-  'GET /api/me': ({ u }) => ({ name: u.name, admin: !!u.admin, settings: settingsOf(u), unread: unreadOf(u) }),
+  // Every page loads /api/me, so a page view marks its session as the last active one for reader settings.
+  'GET /api/me': ({ u, sess, sk }) => {
+    if (sess && readerSessions.noteActive(u, userSettingsOf(u), sess, sk)) save();
+    return { name: u.name, admin: !!u.admin, settings: settingsOf(u, sess), unread: unreadOf(u) };
+  },
+  'GET /api/reader-sessions': ({ u, sk }) => readerSessions.overview(u, userSettingsOf(u), db.sessions, sk),
+  'POST /api/reader-sessions': ({ u, b, sk }) => {
+    if (!['follow', 'latest'].includes(b.action)) bad(400, 'Unknown action');
+    if (!readerSessions.act(u, userSettingsOf(u), db.sessions, String(b.id || ''), b.action)) bad(404, 'Session not found');
+    save();
+    return readerSessions.overview(u, userSettingsOf(u), db.sessions, sk);
+  },
 
   'GET /api/reading-schedule': () => publicSchedule(readingSchedule),
   'GET /api/reading-access': ({ u, q }) => { mangaOf(q.get('m')); return readingAccess.status(u.name, true); },
@@ -518,22 +580,23 @@ const routes = {
     return { ok: true };
   },
 
-  'POST /api/settings': ({ u, b }) => {
+  'POST /api/settings': ({ u, b, sess, sk }) => {
     if (typeof b.webhook === 'string' && b.webhook.trim() && !/^https?:\/\/\S+$/i.test(b.webhook.trim())) bad(400, 'The webhook must be an http(s) URL.');
-    const s = (u.settings = u.settings || {});
+    const base = userSettingsOf(u), s = {};
     if (['last', 'flow', 'page', 'book'].includes(b.startMode)) s.startMode = b.startMode;
     if (['flow', 'page', 'book'].includes(b.lastMode)) s.lastMode = b.lastMode;
     if (['original', 'inverted', 'sepia', 'dim', 'extra-dim'].includes(b.pageTone)) s.pageTone = b.pageTone;
     if (['off', 'date', 'hour'].includes(b.readDate)) s.readDate = b.readDate;
-    for (const k of ['adapt', 'skipExtras', 'skipCovers', 'flowPageGap', 'readingClock', 'readingStory', 'releaseDate',
-      'discoveryEnabled', 'discoveryReadingActivity', 'discoveryMature']) if (typeof b[k] === 'boolean') s[k] = b[k];
+    for (const k of ['adapt', 'skipExtras', 'skipCovers', 'flowPageGap', 'readingClock', 'readingStory', 'releaseDate', 'continueRow',
+      'discoveryEnabled', 'discoveryReadingActivity', 'discoveryMature', 'readerPerSession']) if (typeof b[k] === 'boolean') s[k] = b[k];
     if (b.zoom && typeof b.zoom === 'object') {
       s.zoom = {};
       for (const k of ['flow', 'page', 'book', 'strip']) if (+b.zoom[k] > 0) s.zoom[k] = Math.min(8, Math.max(0.1, +b.zoom[k]));
     }
     if (typeof b.webhook === 'string') s.webhook = b.webhook.trim().slice(0, 500);
+    readerSessions.applyPatch({ user: u, base, session: sess, key: sk, patch: s });
     save();
-    return { settings: settingsOf(u) };
+    return { settings: settingsOf(u, sess) };
   },
   'POST /api/password': ({ u, b }) => {
     if (!checkPw(String(b.old || ''), u.hash)) bad(403, 'The current password is wrong.');
@@ -620,7 +683,7 @@ const routes = {
       const counts = greatestCounts(entry.id, db.greatestRatings || {}, db.users);
       return {
         ...entry,
-        cover: owned?.cover ? url(owned.cover) : entry.cover,
+        cover: owned?.cover ? url(owned.cover) : greatestCoverUrl(entry),
         chapters: owned ? owned.chapters.length : entry.chapters,
         status: owned?.meta?.status || entry.status,
         library: owned ? { id: owned.id, chapters: owned.chapters.length } : null,
@@ -661,8 +724,8 @@ const routes = {
     return { results: await searchGreatestMangaDex(entry) };
   },
 
-  'GET /api/manga': ({ u, q }) => {
-    const m = mangaOf(q.get('m')), prog = progressOf(u, m), s = settingsOf(u), showStory = s.readingStory;
+  'GET /api/manga': ({ u, q, sess }) => {
+    const m = mangaOf(q.get('m')), prog = progressOf(u, m), s = settingsOf(u, sess), showStory = s.readingStory;
     const records = mangaReadingOf(u, m);
     return {
       chapterDates: { read: s.readDate, release: s.releaseDate },
@@ -679,7 +742,7 @@ const routes = {
         dates: s.releaseDate ? chapterDates(ch.versions) : null,
       })),
       reading: showStory ? mangaInsight(records, m.chapters.map(ch => ch.id)) : null,
-      continue: continueOf(m, prog, settingsOf(u)),
+      continue: continueOf(m, prog, s),
     };
   },
 
@@ -720,15 +783,17 @@ const routes = {
     return { ok: true, deleted: m.id };
   },
 
-  'GET /api/chapter': ({ u, q }) => {
-    const m = mangaOf(q.get('m')), ch = chapterOf(m, q.get('c')), s = settingsOf(u), prog = progressOf(u, m);
+  'GET /api/chapter': ({ u, q, sess }) => {
+    const m = mangaOf(q.get('m')), ch = chapterOf(m, q.get('c')), s = settingsOf(u, sess), prog = progressOf(u, m);
     if (!readingAccess.status(u.name).allowed) bad(423, 'Reading is outside the deployment schedule. Complete the five-question challenge to unlock it.');
     const v = ch.versions.find(x => x.id === q.get('v')) || ranked(m, ch)[0].v;
     // Opening a chapter clears its "new chapter" notification.
     let seen = false;
     for (const n of db.notes[u.name] || []) if (!n.read && n.m === m.id && n.c === ch.id) seen = n.read = true;
     if (seen) save();
+    if (readAhead) warmChapter(u, m, ch, v, prog[ch.id], s);
     return {
+      perf: tracer.on,
       manga: { id: m.id, title: m.title },
       chapter: { id: ch.id, label: ch.label, title: ch.title, extra: ch.extra },
       version: v.id, versions: versionsOf(m, ch, u), direction: v.direction,
@@ -736,6 +801,9 @@ const routes = {
       prev: neighbour(m, ch, -1, s), next: neighbour(m, ch, 1, s),
       progress: prog[ch.id] || null,
       reading: s.readingClock ? publicSummary(readingOf(u, m, ch), v.id, eligiblePages(v, s)) : null,
+      // the user's moments on this version, so the reader can mark pages that already have one
+      moments: momentsOf(u).filter(x => x.m === m.id && x.c === ch.id && x.v === v.id)
+        .map(x => ({ id: x.id, cat: x.cat, pages: (moments.locate(x, m) || { pages: [] }).pages })),
       // for the chapter picker: the whole manga across all books
       books: m.books.map(b => ({ key: b.key, label: b.label, title: b.title })),
       chapters: m.chapters.map(c => ({ id: c.id, book: c.book, label: c.label, title: c.title, extra: c.extra, done: !!(prog[c.id] && prog[c.id].done) })),
@@ -822,6 +890,56 @@ const routes = {
     save();
     return { following: !!f[m.id] };
   },
+
+  // Moments (BL-0055): private to their user; one category each, no uncategorised saves.
+  'GET /api/moments': ({ u, q }) => {
+    const m = mangaOf(q.get('m'));
+    return { moments: momentsOf(u).filter(x => x.m === m.id).map(x => moments.view(x, m, url)).sort(moments.storyCompare) };
+  },
+  'POST /api/moments': async ({ u, b }) => {
+    const m = mangaOf(b.m), ch = chapterOf(m, b.c), v = ch.versions.find(x => x.id === b.v) || bad(404, 'Version not found');
+    const pages = moments.cleanPages(b.pages, v);
+    const moment = { id: crypto.randomBytes(6).toString('hex'), m: m.id, c: ch.id, v: v.id, i: pages, f: pages.map(i => v.pages[i].f),
+      layout: moments.cleanLayout(b.layout),
+      region: moments.cleanRegion(b.region), cat: moments.cleanCategory(b.cat), note: moments.cleanNote(b.note), t: Date.now() };
+    const list = momentsOf(u);
+    if (list.length >= moments.MAX_PER_USER) bad(409, `You already have ${moments.MAX_PER_USER} moments.`);
+    moment.sha = await Promise.all(moment.f.map(f => fileSha(v.rel + '/' + f)));
+    list.push(moment);
+    save();
+    return { moment: moments.view(moment, m, url) };
+  },
+  'POST /api/moments/update': ({ u, b }) => {
+    const moment = momentOf(u, b.id);
+    if ('cat' in b) moment.cat = moments.cleanCategory(b.cat);
+    if ('region' in b) moment.region = moments.cleanRegion(b.region);
+    if ('note' in b) moment.note = moments.cleanNote(b.note);
+    moment.edited = Date.now();
+    save();
+    return { moment: moments.view(moment, lib.byId.get(moment.m), url) };
+  },
+  'POST /api/moments/delete': ({ u, b }) => {
+    const list = momentsOf(u), moment = momentOf(u, b.id);
+    list.splice(list.indexOf(moment), 1);
+    save();
+    return { ok: true };
+  },
+
+  // Timings the reader page measured (resource timing, decode, page-turn waits) while the trace is on.
+  'POST /api/perf': ({ u, b }) => {
+    if (!tracer.on) return { on: false };
+    const events = Array.isArray(b.events) ? b.events.slice(0, 300) : [];
+    for (const e of events) if (e && typeof e === 'object' && !Array.isArray(e)) {
+      const clean = {};
+      for (const [key, value] of Object.entries(e).slice(0, 30)) {
+        if (key === 't' || key === 'k') continue; // the server's clock and kind
+        if (typeof value === 'number' && Number.isFinite(value)) clean[key] = Math.round(value * 10) / 10;
+        else if (typeof value === 'string' || typeof value === 'boolean') clean[key] = typeof value === 'string' ? value.slice(0, 300) : value;
+      }
+      tracer.log({ ...clean, k: 'client', user: u.name, page: b.page ? String(b.page).slice(0, 40) : undefined });
+    }
+    return { on: true };
+  },
   'GET /api/notifications': ({ u }) => ({ items: (db.notes[u.name] || []).slice().reverse() }),
   'POST /api/notifications/read': ({ u, b }) => {
     for (const n of db.notes[u.name] || []) if (b.all || n.id === b.id) n.read = true;
@@ -863,7 +981,7 @@ const routes = {
     admin(u);
     const name = String(b.name || '');
     if (name === u.name) bad(400, "You can't delete your own account.");
-    delete db.users[name]; delete db.progress[name]; delete db.reading[name]; delete db.follows[name]; delete db.notes[name];
+    delete db.users[name]; delete db.progress[name]; delete db.reading[name]; delete db.follows[name]; delete db.notes[name]; delete db.moments[name];
     if (db.discoveryFeedback) delete db.discoveryFeedback[name];
     if (db.greatestRatings) delete db.greatestRatings[name];
     for (const [k, s] of Object.entries(db.sessions)) if (s.u === name) delete db.sessions[k];
@@ -1007,23 +1125,32 @@ async function handleApi(req, res, u, route, q) {
     if (!/^application\/json/.test(req.headers['content-type'] || '') || req.headers['sec-fetch-site'] === 'cross-site') bad(403, 'Bad request origin');
     b = (await readBody(req)) || {};
   }
-  sendJson(res, 200, await route({ req, res, u, b, q }));
+  const sk = u && sessionKeyOf(req), sess = sk && db.sessions[sk];
+  if (sess) touchSession(u, sess, sk, req);
+  sendJson(res, 200, await route({ req, res, u, b, q, sess, sk }));
 }
-function serveFile(req, res, root, rel, cacheControl, only) {
+function serveFile(req, res, root, rel, cacheControl, only, trace) {
   let file;
   try { file = path.resolve(root, decodeURIComponent(rel)); } catch { return sendJson(res, 400, { error: 'Bad path' }); }
   if (!file.startsWith(root + path.sep) || (only && !only.test(file))) return sendJson(res, 404, { error: 'Not found' });
   fs.stat(file, (err, st) => {
+    if (trace) trace.mark('stat');
     if (err || !st.isFile()) return sendJson(res, 404, { error: 'Not found' });
     const etag = `"${st.size.toString(36)}-${Math.round(st.mtimeMs).toString(36)}"`;
     if (req.headers['if-none-match'] === etag) { res.writeHead(304, { ETag: etag, 'Cache-Control': cacheControl }); return res.end(); }
-    res.writeHead(200, { 'Content-Type': MIME[path.extname(file).toLowerCase()] || 'application/octet-stream', 'Content-Length': st.size, ETag: etag, 'Cache-Control': cacheControl });
+    const headers = { 'Content-Type': MIME[path.extname(file).toLowerCase()] || 'application/octet-stream', 'Content-Length': st.size, ETag: etag, 'Cache-Control': cacheControl };
+    // The browser's resource timing shows this, so a slow page can be matched to the server's share.
+    if (trace && trace.on) headers['Server-Timing'] = `stat;dur=${trace.elapsed()}`;
+    res.writeHead(200, headers);
     if (req.method === 'HEAD') return res.end();
-    fs.createReadStream(file).on('error', () => res.destroy()).pipe(res);
+    const stream = fs.createReadStream(file).on('error', () => res.destroy());
+    if (trace) trace.stream(stream);
+    stream.pipe(res);
   });
 }
 
 http.createServer(async (req, res) => {
+  const trace = requestTrace(tracer, req, res);
   try {
     const { pathname, searchParams } = new URL(req.url, 'http://localhost');
     const u = userOf(req);
@@ -1034,6 +1161,16 @@ http.createServer(async (req, res) => {
       if (!c?.customCover) bad(404, 'Cover not found');
       return serveFile(req, res, path.join(DATA, 'collection-covers'), c.customCover, 'private, no-cache', IMG);
     }
+    if (pathname === '/api/greatest-cover' && req.method === 'GET') {
+      if (!u) bad(401, 'Please log in');
+      const entry = greatestById.get(searchParams.get('id'));
+      if (!entry?.cover) bad(404, 'Cover not found');
+      const file = greatestCovers.file(entry.cover);
+      if (file) return serveFile(req, res, greatestCovers.dir, path.basename(file), 'private, max-age=31536000, immutable', IMG);
+      // Not downloaded yet: the browser fetches the catalog's own URL this once.
+      res.writeHead(302, { Location: entry.cover, 'Cache-Control': 'no-store' });
+      return res.end();
+    }
     if (pathname === '/api/peering/cover' && req.method === 'GET') {
       if (!u) bad(401, 'Please log in');
       admin(u);
@@ -1061,19 +1198,39 @@ http.createServer(async (req, res) => {
       const parts = relative.split(path.sep);
       if (parts.length >= 4 && !readingAccess.status(u.name).allowed)
         bad(423, 'Reading is outside the deployment schedule.');
-      return serveFile(req, res, LIB, pathname.slice(5), readingSchedule && parts.length >= 4 ? 'private, no-store' : 'private, max-age=86400', IMG);
+      trace.mark('access');
+      return serveFile(req, res, LIB, pathname.slice(5), readingSchedule && parts.length >= 4 ? 'private, no-store' : 'private, max-age=86400', IMG, trace);
     }
-    serveFile(req, res, PUB, pathname === '/' ? 'index.html' : pathname.slice(1), 'no-cache');
+    serveFile(req, res, PUB, pathname === '/' ? 'index.html' : pathname.slice(1), 'no-cache', null, trace);
   } catch (e) {
-    const expected = e instanceof HttpError || e instanceof CatalogError;
+    const expected = e instanceof HttpError || e instanceof CatalogError || e instanceof moments.MomentError;
     if (!expected) console.error(e);
     if (!res.headersSent) sendJson(res, expected ? e.code : 500, expected ? { error: e.message, ...e.extra } : { error: 'Internal error' });
   }
 }).listen(PORT, () => console.log(`MangaCircus on http://localhost:${PORT}  (library: ${LIB}, data: ${DATA})`));
 
+// The trace's storage probe reads a random page of the library (rarely in the OS cache).
+tracer.setProbeSource(() => {
+  const m = lib.mangas[Math.floor(Math.random() * lib.mangas.length)];
+  const ch = m && m.chapters[Math.floor(Math.random() * m.chapters.length)], v = ch && ch.versions[0];
+  const p = v && v.pages[Math.floor(Math.random() * v.pages.length)];
+  return p ? path.join(LIB, v.rel, p.f) : null;
+});
 if (lib.mangas.length) refreshChanged();
 else rescan();
 if (SCAN_MINUTES > 0) setInterval(() => refreshChanged(), SCAN_MINUTES * 60000).unref();
+// Fetch missing Greatest covers shortly after start and retry failures once a day;
+// covers already on disk cost nothing.
+async function warmGreatestCovers() {
+  try {
+    const result = await greatestCovers.warm(greatestCatalog.entries.map(entry => entry.cover));
+    if (result.fetched || result.failed || result.stopped) console.log('[greatest] covers', JSON.stringify(result));
+  } catch (error) { console.error('[greatest] covers', error.message); }
+}
+if (process.env.GREATEST_COVER_WARM !== '0') {
+  setTimeout(warmGreatestCovers, 10000).unref();
+  setInterval(warmGreatestCovers, 86400000).unref();
+}
 // Persist the last reconciliation time. Restarting a healthy reader should not
 // trigger another full tree walk; overdue reconciliations run within a minute.
 if (FULL_SCAN_MINUTES > 0) setInterval(() => {
@@ -1086,10 +1243,13 @@ if (FULL_SCAN_MINUTES > 0) setInterval(() => {
 
 // A completed scraper publish increments a durable revision. Polling it here keeps the
 // reader index fresh without exposing an unauthenticated rescan endpoint to the daemon.
-let scraperRevision = null;
+let scraperRevision = null, revisionRoute = true;
 async function pollScraper() {
   try {
-    const state = await scraperRequest('/api/state');
+    // /api/revision is a few bytes; the full state is ~100 KB and makes the scraper summarise the library.
+    let state;
+    if (revisionRoute) state = await scraperRequest('/api/revision').catch(error => { if (error.code !== 404) throw error; revisionRoute = false; });
+    if (!revisionRoute) state = await scraperRequest('/api/state'); // a scraper from before /api/revision
     const revision = Number(state.publishedRevision || 0);
     if (scraperRevision === null || revision > scraperRevision) {
       const checked = await refreshChanged();

test/admin-role.test.js

@@ -21,7 +21,8 @@ test('only admins can promote or demote, nobody can demote themselves, and chang
     const port = await freePort(), output = [];
     child = spawn(process.execPath, ['server.js'], { cwd: path.resolve(__dirname, '..'), windowsHide: true,
       env: { ...process.env, LIBRARY: library, DATA: data, PORT: String(port), SCAN_INTERVAL: '0', FULL_SCAN_INTERVAL: '0',
-        SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', BACKUP: '' } });
+        SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', BACKUP: '',
+        GREATEST_COVER_WARM: '0' } });
     child.stdout.on('data', d => output.push(String(d)));
     child.stderr.on('data', d => output.push(String(d)));
     const base = `http://127.0.0.1:${port}`;

test/backup.test.js

@@ -251,7 +251,7 @@ test('reader and scraper: admin backup API pauses and resumes the real queue', {
     const base = `http://127.0.0.1:${rp}`, token = 'backup-test-only';
     const env = { ...process.env, DATA: f.data, LIBRARY: library, SCRAPER_DATA: path.join(f.data, 'scraper'), BACKUP: f.target,
       PORT: String(rp), SCRAPER_PORT: String(sp), SCRAPER_HOST: '127.0.0.1', SCRAPER_URL: `http://127.0.0.1:${sp}`, SENTINEL_URL: 'http://127.0.0.1:9',
-      SCRAPER_TOKEN: token, SCRAPER_TOKEN_FILE: '', SCAN_INTERVAL: '0' };
+      SCRAPER_TOKEN: token, SCRAPER_TOKEN_FILE: '', SCAN_INTERVAL: '0', GREATEST_COVER_WARM: '0' };
     for (const script of ['server.js', 'scraper/daemon.js']) {
       const child = spawn(process.execPath, [script], { cwd: root, env, windowsHide: true }); children.push(child);
       for (const stream of [child.stdout, child.stderr]) stream.on('data', chunk => output.push(chunk.toString()));

test/discovery-server.test.js

@@ -81,7 +81,7 @@ async function startReader({ anilist, discovery = {}, mangaMeta = null, scraperU
   const child = spawn(process.execPath, ['server.js'], { cwd: path.resolve(__dirname, '..'), windowsHide: true,
     env: { ...process.env, LIBRARY: library, DATA: data, PORT: String(port), SCAN_INTERVAL: '0', FULL_SCAN_INTERVAL: '0',
       SCRAPER_URL: scraperUrl, SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', BACKUP: '',
-      DISCOVERY_ANILIST_URL: anilist ? anilist.url : 'http://127.0.0.1:9/', DISCOVERY_HARVEST_AT: '' } });
+      DISCOVERY_ANILIST_URL: anilist ? anilist.url : 'http://127.0.0.1:9/', DISCOVERY_HARVEST_AT: '', GREATEST_COVER_WARM: '0' } });
   child.stdout.on('data', d => output.push(String(d)));
   child.stderr.on('data', d => output.push(String(d)));
   const base = `http://127.0.0.1:${port}`;

test/dockerfile.test.js

@@ -0,0 +1,33 @@
+'use strict';
+// The image copies top-level modules by name; a new module missing there crashes the reader at start.
+const test = require('node:test'), assert = require('node:assert/strict');
+const fs = require('fs'), path = require('path');
+const root = path.resolve(__dirname, '..');
+const allowedNames = () => new Set(fs.readFileSync(path.join(root, '.dockerignore'), 'utf8').split(/\r?\n/).filter(line => line.startsWith('!')).map(line => line.slice(1)));
+
+test('every top-level module the reader requires is copied into the image', () => {
+  const dockerfile = fs.readFileSync(path.join(root, 'Dockerfile'), 'utf8');
+  const copied = new Set(dockerfile.split('\n').filter(line => line.startsWith('COPY ')).flatMap(line => line.split(/\s+/).slice(1, -1)));
+  const pending = ['server.js'], seen = new Set();
+  while (pending.length) {
+    const file = pending.pop();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    const source = fs.readFileSync(path.join(root, file), 'utf8');
+    for (const [, dir] of source.matchAll(/require\('\.\/([\w.-]+)\/[^']+'\)/g)) {
+      assert.ok(copied.has(dir), `${dir}/ is not copied`);
+      assert.ok(allowedNames().has(dir + '/'), `${dir}/ is not allowed through .dockerignore`);
+    }
+    for (const [, name] of source.matchAll(/require\('\.\/([\w.-]+?)(?:\.js)?'\)/g)) {
+      // A folder (e.g. ./greatest) is copied as a whole; only single files need their own name in COPY.
+      if (fs.existsSync(path.join(root, name)) && fs.statSync(path.join(root, name)).isDirectory()) assert.ok(copied.has(name), `${name}/ is not copied`);
+      else pending.push(name + '.js');
+    }
+  }
+  // .dockerignore is an allowlist too: a file not let through never reaches COPY.
+  const allowed = allowedNames();
+  for (const file of seen) {
+    assert.ok(copied.has(file), `${file} is required but not copied by the Dockerfile`);
+    assert.ok(allowed.has(file), `${file} is required but not allowed through .dockerignore`);
+  }
+});

test/greatest-cover-route.test.js

@@ -0,0 +1,75 @@
+'use strict';
+// BL-0053: Greatest covers are served from the reader's own copy, with a redirect until one exists.
+const test = require('node:test'), assert = require('node:assert/strict');
+const fs = require('fs'), os = require('os'), path = require('path'), net = require('net'), crypto = require('crypto');
+const { spawn } = require('child_process');
+const { loadCatalog } = require('../greatest');
+const { GreatestCovers } = require('../greatest/covers');
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const hashPw = pw => { const salt = crypto.randomBytes(16).toString('hex'); return salt + ':' + crypto.scryptSync(pw, salt, 32).toString('hex'); };
+const sha = s => crypto.createHash('sha256').update(s).digest('hex');
+const PNG = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+
+async function freePort() {
+  const listener = net.createServer();
+  await new Promise(resolve => listener.listen(0, '127.0.0.1', resolve));
+  const port = listener.address().port;
+  await new Promise(resolve => listener.close(resolve));
+  return port;
+}
+
+test('Greatest covers come from the local copy, else redirect to the catalog URL', async t => {
+  const entries = loadCatalog().entries.filter(entry => entry.cover);
+  const [cached, missing] = entries;
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mc-greatest-cover-'));
+  const library = path.join(root, 'library'), data = path.join(root, 'data');
+  fs.mkdirSync(library, { recursive: true });
+  fs.mkdirSync(path.join(data, 'greatest-covers'), { recursive: true });
+  const version = new GreatestCovers(path.join(data, 'greatest-covers')).version(cached.cover);
+  fs.writeFileSync(path.join(data, 'greatest-covers', `${version}.png`), PNG);
+  const token = crypto.randomBytes(32).toString('base64url');
+  fs.writeFileSync(path.join(data, 'db.json'), JSON.stringify({
+    users: { reader: { name: 'reader', hash: hashPw('reader-password'), admin: false, created: Date.now(), settings: {} } },
+    sessions: { [sha(token)]: { u: 'reader', t: Date.now() } } }));
+
+  const port = await freePort(), output = [];
+  const child = spawn(process.execPath, ['server.js'], { cwd: path.resolve(__dirname, '..'), windowsHide: true,
+    env: { ...process.env, LIBRARY: library, DATA: data, PORT: String(port), SCAN_INTERVAL: '0', FULL_SCAN_INTERVAL: '0',
+      SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', BACKUP: '',
+      GREATEST_COVER_WARM: '0' } });
+  child.stdout.on('data', d => output.push(String(d)));
+  child.stderr.on('data', d => output.push(String(d)));
+  t.after(async () => {
+    await new Promise(resolve => { if (child.exitCode !== null) return resolve(); child.once('exit', resolve); child.kill(); });
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+  const base = `http://127.0.0.1:${port}`;
+  let ready = false;
+  for (let n = 0; n < 100 && !ready; n++) {
+    ready = await fetch(base + '/health').then(r => r.ok).catch(() => false);
+    if (!ready) await sleep(50);
+  }
+  assert.ok(ready, output.join(''));
+  const get = (url, cookie = `sid=${token}`) => fetch(base + '/' + url, { headers: cookie ? { cookie } : {}, redirect: 'manual' });
+
+  const listing = await (await get('api/greatest')).json();
+  const coverOf = id => listing.entries.find(entry => entry.id === id).cover;
+  assert.equal(coverOf(cached.id), `api/greatest-cover?id=${encodeURIComponent(cached.id)}&v=${version}`);
+  assert.match(coverOf(missing.id), /^api\/greatest-cover\?id=.+&v=[0-9a-f]{16}$/);
+
+  const hit = await get(coverOf(cached.id));
+  assert.equal(hit.status, 200);
+  assert.equal(hit.headers.get('content-type'), 'image/png');
+  assert.equal(hit.headers.get('cache-control'), 'private, max-age=31536000, immutable');
+  assert.deepEqual(Buffer.from(await hit.arrayBuffer()), PNG);
+
+  const miss = await get(coverOf(missing.id));
+  assert.equal(miss.status, 302);
+  assert.equal(miss.headers.get('location'), missing.cover);
+  assert.equal(miss.headers.get('cache-control'), 'no-store');
+
+  assert.equal((await get(coverOf(cached.id), null)).status, 401);
+  assert.equal((await get('api/greatest-cover?id=not-in-the-catalog')).status, 404);
+  assert.equal((await get('api/greatest-cover?id=../../db.json')).status, 404);
+});

test/greatest-covers.test.js

@@ -0,0 +1,84 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { GreatestCovers } = require('../greatest/covers');
+
+const PNG = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+const image = (body = PNG, type = 'image/png') => new Response(body, { status: 200, headers: { 'content-type': type } });
+
+function setup(t, responses, options = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mc-greatest-covers-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  const calls = [];
+  const fetchImpl = async (url, init) => {
+    calls.push({ url, init });
+    const next = responses[url];
+    if (next instanceof Error) throw next;
+    return typeof next === 'function' ? next() : next || new Response('missing', { status: 404 });
+  };
+  const sleeps = [];
+  const covers = new GreatestCovers(dir, { fetchImpl, sleep: async ms => { sleeps.push(ms); }, ...options });
+  return { dir, calls, sleeps, covers };
+}
+
+test('warm downloads each cover once and serves it from disk afterwards', async t => {
+  const a = 'https://img.example/a.png', b = 'https://img.example/b.jpg';
+  const { dir, calls, sleeps, covers } = setup(t, { [a]: () => image(), [b]: () => image(PNG, 'image/jpeg') });
+  const result = await covers.warm([a, b, a]);
+  assert.deepEqual(result, { fetched: 2, skipped: 1, failed: 0, stopped: null });
+  assert.equal(calls.length, 2);
+  assert.deepEqual(sleeps, [1000], 'one pause between two downloads, none before the first');
+  assert.ok(covers.file(a).endsWith('.png') && fs.existsSync(covers.file(a)));
+  assert.ok(covers.file(b).endsWith('.jpg'));
+  assert.equal(covers.file('https://img.example/other.png'), null);
+
+  // A restarted reader finds the stored files and asks nobody.
+  const reopened = new GreatestCovers(dir, { fetchImpl: async () => { throw new Error('must not fetch'); } });
+  assert.deepEqual(await reopened.warm([a, b]), { fetched: 0, skipped: 2, failed: 0, stopped: null });
+  assert.equal(reopened.file(a), covers.file(a));
+});
+
+test('a changed cover URL is a new file', async t => {
+  const { covers } = setup(t, { 'https://img.example/v1.png': () => image(), 'https://img.example/v2.png': () => image() });
+  await covers.warm(['https://img.example/v1.png', 'https://img.example/v2.png']);
+  assert.notEqual(covers.file('https://img.example/v1.png'), covers.file('https://img.example/v2.png'));
+  assert.notEqual(covers.version('https://img.example/v1.png'), covers.version('https://img.example/v2.png'));
+});
+
+test('non-images, oversized files, plain http and errors are skipped', async t => {
+  const html = 'https://img.example/page', big = 'https://img.example/big.png', declaredBig = 'https://img.example/declared.png';
+  const broken = 'https://img.example/broken.png', gone = 'https://img.example/gone.png';
+  const { covers, calls } = setup(t, {
+    [html]: () => new Response('<html>', { status: 200, headers: { 'content-type': 'text/html' } }),
+    [big]: () => image(Buffer.alloc(64)),
+    [declaredBig]: () => new Response(PNG, { status: 200, headers: { 'content-type': 'image/png', 'content-length': '999999' } }),
+    [broken]: new TypeError('fetch failed'),
+  }, { maxBytes: 32 });
+  const result = await covers.warm([html, big, declaredBig, broken, gone, 'http://img.example/plain.png', '', null]);
+  assert.deepEqual(result, { fetched: 0, skipped: 0, failed: 5, stopped: null });
+  assert.equal(calls.length, 5, 'plain http and empty URLs are never requested');
+  for (const url of [html, big, declaredBig, broken, gone]) assert.equal(covers.file(url), null);
+  assert.deepEqual(fs.readdirSync(covers.dir).filter(name => !name.startsWith('.')), []);
+});
+
+test('429 and 403 stop the run at once', async t => {
+  for (const status of [429, 403]) {
+    const first = 'https://img.example/1.png', second = 'https://img.example/2.png';
+    const { covers, calls } = setup(t, { [first]: () => new Response('', { status }), [second]: () => image() });
+    const result = await covers.warm([first, second]);
+    assert.equal(result.stopped, `HTTP ${status}`);
+    assert.equal(calls.length, 1);
+    assert.equal(covers.file(second), null);
+  }
+});
+
+test('requests carry a timeout and a fixed user agent', async t => {
+  const a = 'https://img.example/a.png';
+  const { covers, calls } = setup(t, { [a]: () => image() });
+  await covers.warm([a]);
+  assert.ok(calls[0].init.signal instanceof AbortSignal);
+  assert.match(calls[0].init.headers['user-agent'], /^MangaCircus/);
+});

test/library-index.test.js

@@ -78,7 +78,7 @@ test('reader serves a saved index immediately after restart and verifies it in b
     const output = [];
     child = spawn(process.execPath, ['server.js'], { cwd: path.resolve(__dirname, '..'), windowsHide: true,
       env: { ...process.env, LIBRARY: library, DATA: data, PORT: String(port), SCAN_INTERVAL: '0', FULL_SCAN_INTERVAL: '0',
-        SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '' } });
+        SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', GREATEST_COVER_WARM: '0' } });
     child.stdout.on('data', data => output.push(String(data)));
     child.stderr.on('data', data => output.push(String(data)));
     const base = `http://127.0.0.1:${port}`;

test/moments.test.js

@@ -0,0 +1,150 @@
+'use strict';
+// BL-0055: Moments, a reader's saved pages or page regions with exactly one category.
+const test = require('node:test'), assert = require('node:assert/strict');
+const fs = require('fs'), os = require('os'), path = require('path'), net = require('net');
+const { spawn } = require('child_process');
+const { Canvas } = require('../tools/png');
+const moments = require('../moments');
+const { trimPages, momentPageLabel } = require('../public/moments');
+const { READER_KEYS, MOMENT_VIEWER_KEYS, keyAction } = require('../public/keys');
+
+test('regions are clamped fractions; a whole-page rectangle means no region', () => {
+  assert.deepEqual(moments.cleanRegion({ x: 0.1, y: 0.2, w: 0.3, h: 0.4 }), { x: 0.1, y: 0.2, w: 0.3, h: 0.4 });
+  assert.deepEqual(moments.cleanRegion({ x: -1, y: 0.5, w: 3, h: 2 }), { x: 0, y: 0.5, w: 1, h: 0.5 });
+  assert.equal(moments.cleanRegion({ x: 0, y: 0, w: 1, h: 1 }), null);
+  assert.equal(moments.cleanRegion(null), null);
+  assert.throws(() => moments.cleanRegion({ x: 0.5, y: 0.5, w: 0.001, h: 0.5 }), /too small/);
+  assert.throws(() => moments.cleanRegion({ x: 'a', y: 0, w: 1, h: 1 }), /Invalid/);
+});
+
+test('exactly one known category is required; notes are trimmed and capped', () => {
+  for (const cat of ['twist', 'hot', 'awesome', 'cute', 'funny', 'feels']) assert.equal(moments.cleanCategory(cat), cat);
+  assert.throws(() => moments.cleanCategory(undefined), /Pick one category/);
+  assert.throws(() => moments.cleanCategory('meh'), /Pick one category/);
+  assert.equal(moments.cleanNote('  so   good \n'), 'so good');
+  assert.equal(moments.cleanNote('x'.repeat(500)).length, moments.NOTE_MAX);
+});
+
+const near = (a, b) => Math.abs(a - b) < 1e-9;
+test('side by side: a region inside one page of a spread becomes that page alone', () => {
+  const left = { i: 5, w: 700, h: 1000 }, right = { i: 4, w: 700, h: 1000 };
+  const one = trimPages([left, right], { x: 0.6, y: 0.1, w: 0.2, h: 0.3 });
+  assert.deepEqual(one.pages, [right]);
+  assert.ok(near(one.region.x, 0.2) && near(one.region.w, 0.4) && one.region.y === 0.1);
+  assert.equal(trimPages([left, right], { x: 0.3, y: 0.1, w: 0.4, h: 0.3 }).pages.length, 2);
+});
+
+test('stacked (Flow): a picture across the break keeps only the pages it touches', () => {
+  const pages = [0, 1, 2, 3].map(i => ({ i, w: 800, h: 400 })); // each page is half as tall as wide: 0.5 of the width
+  // The stack is 2 units tall; y 0.4–0.6 is the lower half of page 1 and the upper half of page 2.
+  const cut = trimPages(pages, { x: 0.1, y: 0.4, w: 0.8, h: 0.2 }, 'column');
+  assert.deepEqual(cut.pages.map(p => p.i), [1, 2]);
+  assert.ok(near(cut.region.y, 0.3) && near(cut.region.h, 0.4) && cut.region.x === 0.1);
+  assert.deepEqual(trimPages(pages, null, 'column').pages.length, 4);
+  assert.equal(momentPageLabel(cut.pages), 'p. 2–3');
+});
+
+test('every reader key is bound once and the M / I split holds', () => {
+  const keys = READER_KEYS.flatMap(entry => entry.keys);
+  assert.equal(new Set(keys).size, keys.length);
+  assert.equal(keyAction(READER_KEYS, 'm'), 'moment');
+  assert.equal(keyAction(READER_KEYS, 'i'), 'bars');
+  assert.equal(keyAction(READER_KEYS, 'Escape'), 'bars');
+  assert.equal(keyAction(READER_KEYS, '?'), 'help');
+  assert.equal(keyAction(MOMENT_VIEWER_KEYS, 'ArrowLeft'), 'step');
+  assert.ok(READER_KEYS.every(entry => entry.label && entry.text));
+});
+
+async function freePort() {
+  const listener = net.createServer();
+  await new Promise(resolve => listener.listen(0, '127.0.0.1', resolve));
+  const port = listener.address().port;
+  await new Promise(resolve => listener.close(resolve));
+  return port;
+}
+
+test('moments are private, validated, editable and survive page renumbering as "moved"', { timeout: 30000 }, async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mc-moments-'));
+  let child;
+  try {
+    const library = path.join(root, 'library'), data = path.join(root, 'data');
+    const chapterDir = path.join(library, 'Moon Garden', 'v01', 'c001 Roots');
+    fs.mkdirSync(chapterDir, { recursive: true }); fs.mkdirSync(data);
+    for (const n of [1, 2, 3]) fs.writeFileSync(path.join(chapterDir, `00${n}.png`), new Canvas(60, 90, [40 * n, 60, 120]).png());
+    const port = await freePort(), output = [];
+    child = spawn(process.execPath, ['server.js'], { cwd: path.resolve(__dirname, '..'), windowsHide: true,
+      env: { ...process.env, LIBRARY: library, DATA: data, PORT: String(port), SCAN_INTERVAL: '0', FULL_SCAN_INTERVAL: '0',
+        SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', BACKUP: '', GREATEST_COVER_WARM: '0' } });
+    child.stdout.on('data', d => output.push(String(d)));
+    child.stderr.on('data', d => output.push(String(d)));
+    const base = `http://127.0.0.1:${port}`;
+    let ready = false;
+    for (let n = 0; n < 100 && !ready; n++) {
+      ready = await fetch(base + '/health').then(r => r.ok).catch(() => false);
+      if (!ready) await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    assert.ok(ready, output.join(''));
+    const post = (cookie, url, body) => fetch(base + url, { method: 'POST',
+      headers: { 'content-type': 'application/json', ...(cookie ? { cookie } : {}) }, body: JSON.stringify(body) });
+    const get = (cookie, url) => fetch(base + url, { headers: { cookie } }).then(r => r.json());
+    const session = r => r.headers.get('set-cookie').split(';')[0];
+
+    const alice = session(await post(null, '/api/signup', { name: 'alice', password: 'alice-password' }));
+    await post(alice, '/api/admin/user', { name: 'bob', password: 'bob-password' });
+    const bob = session(await post(null, '/api/login', { name: 'bob', password: 'bob-password' }));
+    await post(alice, '/api/admin/rescan', { full: true });
+
+    const manga = await get(alice, '/api/manga?m=' + encodeURIComponent('Moon Garden'));
+    const c = manga.chapters[0].id, v = manga.chapters[0].versions[0].id;
+    const base3 = { m: 'Moon Garden', c, v };
+
+    // A category is required: nothing is ever dumped into an uncategorised pile.
+    assert.equal((await post(alice, '/api/moments', { ...base3, pages: [1] })).status, 400);
+    assert.equal((await post(alice, '/api/moments', { ...base3, pages: [9], cat: 'hot' })).status, 400);
+
+    const created = await (await post(alice, '/api/moments', { ...base3, pages: [1], cat: 'awesome', region: { x: 0.1, y: 0.5, w: 0.5, h: 0.25 }, note: ' big  fight ' })).json();
+    assert.equal(created.moment.cat, 'awesome');
+    assert.equal(created.moment.note, 'big fight');
+    assert.equal(created.moment.pages[0].i, 1);
+    assert.match(created.moment.pages[0].u, /^lib\/Moon%20Garden\/v01\/c001%20Roots\/002\.png$/);
+    const spread = (await (await post(alice, '/api/moments', { ...base3, pages: [2, 0], cat: 'twist' })).json()).moment;
+    assert.deepEqual(spread.pages.map(p => p.i), [2, 0]);
+    assert.equal(spread.layout, 'row');
+    // Flow: a picture stacked over three pages; more than four pages or an unknown layout is refused.
+    const stacked = (await (await post(alice, '/api/moments', { ...base3, pages: [0, 1, 2], layout: 'column', cat: 'awesome', region: { x: 0, y: 0.2, w: 1, h: 0.5 } })).json()).moment;
+    assert.equal(stacked.layout, 'column');
+    assert.equal((await post(alice, '/api/moments', { ...base3, pages: [0, 1, 2, 0], cat: 'hot' })).status, 400);
+    assert.equal((await post(alice, '/api/moments', { ...base3, pages: [0], layout: 'grid', cat: 'hot' })).status, 400);
+    assert.equal((await post(alice, '/api/moments/delete', { id: stacked.id })).status, 200);
+
+    // Story order: page 0/2 spread starts before page 1.
+    const listed = (await get(alice, '/api/moments?m=Moon%20Garden')).moments;
+    assert.deepEqual(listed.map(x => x.id), [spread.id, created.moment.id]);
+    const chapter = await get(alice, `/api/chapter?m=Moon%20Garden&c=${encodeURIComponent(c)}`);
+    assert.deepEqual(chapter.moments.map(x => x.pages).sort(), [[1], [2, 0]].sort());
+
+    // Private: bob sees nothing and cannot touch alice's moments.
+    assert.deepEqual((await get(bob, '/api/moments?m=Moon%20Garden')).moments, []);
+    assert.equal((await get(bob, `/api/chapter?m=Moon%20Garden&c=${encodeURIComponent(c)}`)).moments.length, 0);
+    assert.equal((await post(bob, '/api/moments/update', { id: created.moment.id, cat: 'hot' })).status, 404);
+    assert.equal((await post(bob, '/api/moments/delete', { id: created.moment.id })).status, 404);
+
+    const edited = (await (await post(alice, '/api/moments/update', { id: created.moment.id, cat: 'feels', region: null })).json()).moment;
+    assert.equal(edited.cat, 'feels'); assert.equal(edited.region, null);
+    assert.equal((await post(alice, '/api/moments/update', { id: created.moment.id, cat: '' })).status, 400);
+
+    // The file of page 2 goes away: the moment shows as moved instead of pointing at another picture.
+    fs.renameSync(path.join(chapterDir, '002.png'), path.join(chapterDir, '009.png'));
+    await post(alice, '/api/admin/rescan', { full: true });
+    const after = (await get(alice, '/api/moments?m=Moon%20Garden')).moments;
+    assert.equal(after.find(x => x.id === created.moment.id).missing, true);
+    assert.equal(after.find(x => x.id === spread.id).missing, false);
+
+    assert.equal((await post(alice, '/api/moments/delete', { id: spread.id })).status, 200);
+    assert.equal((await get(alice, '/api/moments?m=Moon%20Garden')).moments.length, 1);
+  } finally {
+    // The server writes db.json on SIGTERM; removing the folder before it exits races that write.
+    if (child && child.exitCode === null) await new Promise(resolve => { child.once('exit', resolve); child.kill(); });
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

test/perf.test.js

@@ -0,0 +1,117 @@
+'use strict';
+const test = require('node:test'), assert = require('node:assert/strict');
+const fs = require('fs'), os = require('os'), path = require('path'), http = require('http');
+const { Tracer, requestTrace } = require('../perf/trace');
+const { ReadAhead } = require('../perf/read-ahead');
+const { analyse } = require('../tools/perf-report');
+
+const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'circus-perf-'));
+const lines = dir => fs.readdirSync(dir).filter(n => n.endsWith('.jsonl'))
+  .flatMap(n => fs.readFileSync(path.join(dir, n), 'utf8').trim().split('\n')).filter(Boolean).map(JSON.parse);
+
+test('tracer is off without the flag file and writes nothing', () => {
+  const dir = tmp(), tracer = new Tracer({ dir, env: {} });
+  tracer.check(); tracer.log({ k: 'x' }); tracer.flush();
+  assert.equal(tracer.on, false);
+  assert.deepEqual(fs.readdirSync(dir), []);
+});
+
+test('the flag file switches the trace on and off at runtime', () => {
+  const dir = tmp(), tracer = new Tracer({ dir, env: {} });
+  fs.writeFileSync(path.join(dir, 'trace.on'), '');
+  tracer.check(); tracer.log({ k: 'x', a: 1 });
+  fs.rmSync(path.join(dir, 'trace.on'));
+  tracer.check(); tracer.log({ k: 'x', a: 2 }); tracer.flush();
+  const events = lines(dir);
+  assert.deepEqual(events.map(e => e.k), ['trace', 'x', 'trace']);
+  assert.equal(events[1].a, 1);
+  assert.equal(events[2].on, false);
+  assert.ok(events.every(e => typeof e.t === 'number'));
+});
+
+test('a served file is traced with storage and network phases', async () => {
+  const dir = tmp(), tracer = new Tracer({ dir, env: { PERF_TRACE: '1' } });
+  tracer.check();
+  const file = path.join(dir, 'page.jpg');
+  fs.writeFileSync(file, Buffer.alloc(3 * 1024 * 1024, 7));
+  const server = http.createServer((req, res) => {
+    const trace = requestTrace(tracer, req, res);
+    fs.stat(file, (err, st) => {
+      trace.mark('stat');
+      res.writeHead(200, { 'Content-Length': st.size });
+      const stream = fs.createReadStream(file);
+      trace.stream(stream);
+      stream.pipe(res);
+    });
+  });
+  await new Promise(r => server.listen(0, r));
+  const { port } = server.address();
+  const r = await fetch(`http://127.0.0.1:${port}/lib/M/B/C/page.jpg`);
+  assert.equal((await r.arrayBuffer()).byteLength, 3 * 1024 * 1024);
+  await new Promise(r => setTimeout(r, 50));
+  server.close(); tracer.stopSampler(); tracer.flush();
+  const req = lines(dir).find(e => e.k === 'req');
+  assert.equal(req.status, 200);
+  assert.equal(req.bytes, 3 * 1024 * 1024);
+  assert.equal(req.path, '/lib/M/B/C/page.jpg');
+  for (const field of ['stat', 'open', 'first', 'readEnd', 'disk', 'netWait', 'ms']) assert.equal(typeof req[field], 'number', field);
+  assert.ok(req.ms >= req.readEnd && req.readEnd >= req.first && req.first >= req.open);
+});
+
+test('read-ahead reads files in order and a newer chapter replaces the queued one', async () => {
+  const dir = tmp(), files = [];
+  for (let i = 0; i < 6; i++) { const f = path.join(dir, `p${i}.jpg`); fs.writeFileSync(f, Buffer.alloc(1000 + i)); files.push(f); }
+  const batches = [];
+  const ahead = new ReadAhead({ concurrency: 1, onBatch: b => batches.push(b) });
+  const done = new Promise(resolve => { const check = () => (batches.some(b => b.tag === 'B' && !b.replaced) ? resolve() : setTimeout(check, 5)); check(); });
+  ahead.warm(files.slice(0, 4), 'A');
+  ahead.warm(files.slice(3), 'B');
+  await done;
+  assert.equal(batches[0].tag, 'A'); assert.equal(batches[0].replaced, true);
+  const b = batches.find(x => x.tag === 'B');
+  assert.equal(b.done, 3); assert.equal(b.bytes, 1003 + 1004 + 1005);
+  // Files read recently are skipped the next time.
+  batches.length = 0;
+  ahead.warm(files.slice(4), 'C');
+  assert.deepEqual(batches.map(x => [x.tag, x.files, x.skipped]), [['C', 0, 2]]);
+});
+
+test('read-ahead keeps one queue per reader and serves them in turn', async () => {
+  const dir = tmp(), mk = n => { const f = path.join(dir, n); fs.writeFileSync(f, n); return f; };
+  const order = [], batches = [];
+  const ahead = new ReadAhead({ concurrency: 1, onBatch: b => batches.push(b) });
+  const read = ahead.readFile.bind(ahead);
+  ahead.readFile = f => { order.push(path.basename(f)); return read(f); };
+  ahead.warm([mk('a1'), mk('a2')], 'A', 'ann');
+  ahead.warm([mk('b1'), mk('b2')], 'B', 'bob');
+  await new Promise(r => { const check = () => (batches.length === 2 ? r() : setTimeout(check, 5)); check(); });
+  assert.deepEqual(order, ['a1', 'b1', 'a2', 'b2']);
+  assert.ok(batches.every(b => !b.replaced && b.done === 2));
+});
+
+test('read-ahead runs the follow-up batch after the current one', async () => {
+  const dir = tmp(), a = path.join(dir, 'a.jpg'), b = path.join(dir, 'b.jpg');
+  fs.writeFileSync(a, 'a'); fs.writeFileSync(b, 'bb');
+  const tags = [];
+  const ahead = new ReadAhead({ onBatch: x => tags.push(x.tag) });
+  ahead.warm([a], 'now'); ahead.then([b], 'next');
+  await new Promise(r => { const check = () => (tags.length === 2 ? r() : setTimeout(check, 5)); check(); });
+  assert.deepEqual(tags, ['now', 'next']);
+});
+
+test('the report blames the storage for slow first reads', () => {
+  const t = Date.parse('2026-10-29T20:00:00Z');
+  const events = [
+    { t, k: 'req', m: 'GET', path: '/lib/M/B/C/1.jpg', status: 200, bytes: 300000, stat: 2, open: 3, first: 1900, readEnd: 1950, disk: 1947, netWait: 0, ms: 1955, conn: 1 },
+    { t: t + 1000, k: 'req', m: 'GET', path: '/lib/M/B/C/2.jpg', status: 200, bytes: 300000, stat: 1, open: 2, first: 5, readEnd: 20, disk: 18, netWait: 0, ms: 22, conn: 2 },
+    { t: t + 2000, k: 'client', e: 'res', url: '/lib/M/B/C/1.jpg', total: 2100, ttfb: 30, download: 2000, queue: 1, connect: 0, dns: 0 },
+    { t: t + 3000, k: 'client', e: 'view', wait: 2050, preloaded: false },
+    { t: t + 4000, k: 'nas', firstMs: 2500, ms: 2600, bytes: 1 },
+  ];
+  const o = analyse(events, { slow: 500 });
+  assert.equal(o.slowServer.count, 1);
+  assert.deepEqual(o.slowServer.by, { firstRead: 1 });
+  assert.deepEqual(o.slowBrowser.by, { server: 1 });
+  assert.equal(o.pageTurns.over1s, 1);
+  assert.match(o.verdict.join('\n'), /first read from storage/);
+});

test/reader-sessions.test.js

@@ -0,0 +1,106 @@
+'use strict';
+// Reader settings per login session: a session follows the latest set until it changes one, then keeps its own.
+const test = require('node:test'), assert = require('node:assert/strict');
+const fs = require('fs'), os = require('os'), path = require('path'), net = require('net');
+const { spawn } = require('child_process');
+const readerSessions = require('../reader-sessions');
+
+async function freePort() {
+  const listener = net.createServer();
+  await new Promise(resolve => listener.listen(0, '127.0.0.1', resolve));
+  const port = listener.address().port;
+  await new Promise(resolve => listener.close(resolve));
+  return port;
+}
+
+test('device labels name browser and system', () => {
+  assert.equal(readerSessions.deviceLabel('Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 Version/17.0 Mobile/15E148 Safari/604.1'), 'Safari on iPhone');
+  assert.equal(readerSessions.deviceLabel('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/130.0 Safari/537.36 Edg/130.0'), 'Edge on Windows');
+  assert.equal(readerSessions.deviceLabel(''), 'Unknown device');
+});
+
+test('sessions lock their reader settings on the first change, new ones copy the last active one', { timeout: 20000 }, async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mc-reader-sessions-'));
+  let child;
+  try {
+    const library = path.join(root, 'library'), data = path.join(root, 'data');
+    fs.mkdirSync(library); fs.mkdirSync(data);
+    const port = await freePort(), output = [];
+    child = spawn(process.execPath, ['server.js'], { cwd: path.resolve(__dirname, '..'), windowsHide: true,
+      env: { ...process.env, LIBRARY: library, DATA: data, PORT: String(port), SCAN_INTERVAL: '0', FULL_SCAN_INTERVAL: '0',
+        SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', BACKUP: '',
+        GREATEST_COVER_WARM: '0' } });
+    child.stdout.on('data', d => output.push(String(d)));
+    child.stderr.on('data', d => output.push(String(d)));
+    const base = `http://127.0.0.1:${port}`;
+    let ready = false;
+    for (let n = 0; n < 100 && !ready; n++) {
+      ready = await fetch(base + '/health').then(r => r.ok).catch(() => false);
+      if (!ready) await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    assert.ok(ready, output.join(''));
+
+    const json = async r => { const body = await r.json(); assert.equal(r.status, 200, JSON.stringify(body)); return body; };
+    const post = (cookie, url, body) => fetch(base + url, { method: 'POST',
+      headers: { 'content-type': 'application/json', 'user-agent': 'Mozilla/5.0 (X11; Linux x86_64) Firefox/130.0', ...(cookie ? { cookie } : {}) },
+      body: JSON.stringify(body) }).then(async r => (url.endsWith('login') || url.endsWith('signup') ? r : json(r)));
+    const me = async cookie => (await json(await fetch(base + '/api/me', { headers: { cookie } }))).settings;
+    const overview = cookie => fetch(base + '/api/reader-sessions', { headers: { cookie } }).then(json);
+    const login = async () => (await post(null, '/api/login', { name: 'reader', password: 'reader-password' })).headers.get('set-cookie').split(';')[0];
+
+    const a = (await post(null, '/api/signup', { name: 'reader', password: 'reader-password' })).headers.get('set-cookie').split(';')[0];
+    // First session: defaults, following the latest set.
+    assert.equal((await me(a)).lastMode, 'page');
+    assert.equal((await overview(a)).sessions[0].locked, false);
+
+    // Session B exists before A changes anything: it follows A's change.
+    const b = await login();
+    await post(a, '/api/settings', { lastMode: 'flow', zoom: { flow: 1.5 } });
+    assert.equal((await me(b)).lastMode, 'flow');
+    assert.equal((await me(b)).zoom.flow, 1.5);
+
+    // B changes its own: B locks, A keeps its own set.
+    await post(b, '/api/settings', { pageTone: 'sepia' });
+    assert.equal((await me(b)).pageTone, 'sepia');
+    assert.equal((await me(b)).lastMode, 'flow');
+    assert.equal((await me(a)).pageTone, 'original');
+
+    // A non-reader setting is shared and does not lock anything.
+    const c = await login();
+    await post(c, '/api/settings', { continueRow: false });
+    assert.equal((await me(a)).continueRow, false);
+    assert.equal((await overview(c)).sessions.find(s => s.current).locked, false);
+    // C follows the last active session, which is A (it loaded /api/me last).
+    assert.equal((await me(c)).pageTone, 'original');
+    await me(b);
+    assert.equal((await me(c)).pageTone, 'sepia');
+
+    // Overview: three sessions, labels, intent.
+    const o = await overview(a);
+    assert.equal(o.enabled, true);
+    assert.equal(o.sessions.length, 3);
+    assert.equal(o.sessions[0].current, true);
+    assert.equal(o.sessions[0].device, 'Firefox on Linux');
+    assert.deepEqual(o.sessions.map(s => s.locked).sort(), [false, true, true]);
+
+    // "Follow latest again" drops A's lock; "Use for new sessions" makes a set the latest.
+    const idA = o.sessions[0].id, idB = o.sessions.find(s => !s.current && s.locked).id;
+    await post(a, '/api/reader-sessions', { id: idA, action: 'follow' });
+    assert.equal((await me(a)).pageTone, 'sepia');
+    assert.equal((await fetch(base + '/api/reader-sessions', { method: 'POST', headers: { 'content-type': 'application/json', cookie: a },
+      body: JSON.stringify({ id: 'nope', action: 'follow' }) })).status, 404);
+    assert.equal((await post(a, '/api/reader-sessions', { id: idB, action: 'latest' })).latestFrom, idB);
+
+    // Off: one shared set; a change applies everywhere and locks nothing. On again: kept locks return.
+    await post(b, '/api/settings', { readerPerSession: false });
+    await post(a, '/api/settings', { pageTone: 'dim' });
+    assert.equal((await me(b)).pageTone, 'dim');
+    assert.equal((await me(c)).pageTone, 'dim');
+    await post(a, '/api/settings', { readerPerSession: true });
+    assert.equal((await me(b)).pageTone, 'sepia');
+    assert.equal((await me(a)).pageTone, 'sepia');
+  } finally {
+    if (child && child.exitCode === null) { child.kill(); await new Promise(resolve => child.once('exit', resolve)); }
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

test/services.test.js

@@ -29,7 +29,7 @@ test('three services integrate collections, auth, custom covers and private heal
     const token = 'integration-test-only';
     const env = { ...process.env, DATA: data, LIBRARY: library, SCRAPER_DATA: path.join(data, 'scraper'),
       PORT: String(rp), SCRAPER_PORT: String(sp), SCRAPER_HOST: '127.0.0.1',
-      READER_URL: base, SCRAPER_URL: scraper, SCRAPER_TOKEN: token, SCRAPER_TOKEN_FILE: '', SCAN_INTERVAL: '0', COOKIE_SECURE: '0' };
+      READER_URL: base, SCRAPER_URL: scraper, SCRAPER_TOKEN: token, SCRAPER_TOKEN_FILE: '', SCAN_INTERVAL: '0', COOKIE_SECURE: '0', GREATEST_COVER_WARM: '0' };
     for (const script of ['server.js', 'scraper/daemon.js']) {
       const child = spawn(process.execPath, [script], { cwd: root, env, windowsHide: true }); children.push(child);
       for (const stream of [child.stdout, child.stderr]) stream.on('data', chunk => output.push(chunk.toString()));
@@ -67,6 +67,10 @@ test('three services integrate collections, auth, custom covers and private heal
     assert.equal((await (await request('/api/settings', { pageTone: 'sepia' })).json()).settings.pageTone, 'sepia');
     assert.equal((await (await request('/api/settings', { pageTone: 'invalid' })).json()).settings.pageTone, 'sepia');
     assert.equal((await (await anotherRequest('/api/me')).json()).settings.pageTone, 'original');
+    assert.equal((await (await request('/api/me')).json()).settings.continueRow, true);
+    assert.equal((await (await request('/api/settings', { continueRow: false })).json()).settings.continueRow, false);
+    assert.equal((await (await request('/api/settings', { continueRow: 'no' })).json()).settings.continueRow, false);
+    assert.equal((await (await anotherRequest('/api/me')).json()).settings.continueRow, true);
     assert.equal((await fetch(base + '/api/discovery')).status, 401);
     assert.equal((await anotherRequest('/api/admin/discovery/run', {})).status, 403);
     assert.equal((await request('/api/settings', { discoveryEnabled: true })).status, 200);

tools/perf-bench.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * Load test for the reader: N simulated readers each open random chapters and fetch the pages one after
+ * another with a think time, the way a person paging through a chapter does, plus a small look-ahead.
+ * Measures time to first byte and total per page from this machine. Read-only apart from the login; it
+ * never writes progress. Run it with the server's trace on to see the server's share (docs/performance.md).
+ *
+ *   node tools/perf-bench.js --url http://host:8080 --user bench --password-env BENCH_PASSWORD \
+ *        [--readers 4] [--chapters 3] [--pages 40] [--think 400] [--ahead 2] [--manga Berserk] [--json]
+ *   --cookie 'sid=…' instead of user/password.  --chapter-only skips the page fetches (API timings only).
+ */
+
+function parseArgs(argv) {
+  const o = { url: 'http://localhost:8080', readers: 4, chapters: 3, pages: 40, think: 400, ahead: 2, manga: '', json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i].replace(/^--/, ''), next = () => argv[++i];
+    if (['readers', 'chapters', 'pages', 'think', 'ahead'].includes(key)) o[key] = +next();
+    else if (key === 'password-env') o.password = process.env[next()] || '';
+    else if (['url', 'user', 'cookie', 'manga'].includes(key)) o[key] = next();
+    else if (key === 'json' || key === 'chapter-only') o[key.replace('-o', 'O')] = true;
+    else if (key === 'h' || key === 'help') o.help = true;
+  }
+  o.url = o.url.replace(/\/$/, '');
+  return o;
+}
+
+async function login(o) {
+  if (o.cookie) return o.cookie;
+  const r = await fetch(o.url + '/api/login', { method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: o.user, password: o.password }) });
+  if (!r.ok) throw new Error(`login failed: HTTP ${r.status} ${await r.text()}`);
+  const cookie = (r.headers.get('set-cookie') || '').split(';')[0];
+  if (!cookie) throw new Error('login returned no session cookie');
+  return cookie;
+}
+
+async function timed(url, cookie) {
+  const t0 = performance.now();
+  const r = await fetch(url, { headers: { cookie } });
+  const ttfb = performance.now() - t0;
+  let bytes = 0;
+  for await (const chunk of r.body) bytes += chunk.length;
+  return { status: r.status, ttfb, ms: performance.now() - t0, bytes, server: r.headers.get('server-timing') || '' };
+}
+const json = async (o, cookie, path) => {
+  const t0 = performance.now(), r = await fetch(o.url + path, { headers: { cookie } });
+  if (!r.ok) throw new Error(`${path}: HTTP ${r.status}`);
+  return { data: await r.json(), ms: performance.now() - t0 };
+};
+const pick = list => list[Math.floor(Math.random() * list.length)];
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+async function reader(o, cookie, mangas, out, id) {
+  for (let c = 0; c < o.chapters; c++) {
+    const m = pick(mangas);
+    const manga = await json(o, cookie, '/api/manga?m=' + encodeURIComponent(m.id));
+    out.api.push({ path: '/api/manga', ms: manga.ms });
+    const ch = pick(manga.data.chapters);
+    const chapter = await json(o, cookie, `/api/chapter?m=${encodeURIComponent(m.id)}&c=${encodeURIComponent(ch.id)}`);
+    out.api.push({ path: '/api/chapter', ms: chapter.ms });
+    if (o.chapterOnly) continue;
+    const pages = chapter.data.pages.slice(0, o.pages);
+    // The browser keeps `ahead` pages in flight while the reader looks at the current one.
+    const inflight = new Map();
+    const start = k => { if (k < pages.length && !inflight.has(k)) inflight.set(k, timed(o.url + '/' + pages[k].u, cookie)); };
+    for (let k = 0; k < pages.length; k++) {
+      const waitFrom = performance.now();
+      start(k);
+      for (let a = 1; a <= o.ahead; a++) start(k + a);
+      const r = await inflight.get(k);
+      out.pages.push({ reader: id, manga: m.id, chapter: ch.id, page: k, wait: performance.now() - waitFrom, ...r });
+      await sleep(o.think * (0.5 + Math.random()));
+    }
+    await Promise.all(inflight.values());
+  }
+}
+
+const pct = (v, p) => { const s = v.slice().sort((a, b) => a - b); return s.length ? Math.round(s[Math.min(s.length - 1, Math.floor(p / 100 * s.length))]) : null; };
+const sum = v => ({ n: v.length, p50: pct(v, 50), p90: pct(v, 90), p99: pct(v, 99), max: v.length ? Math.round(Math.max(...v)) : null });
+
+async function main() {
+  const o = parseArgs(process.argv.slice(2));
+  if (o.help || (!o.cookie && !o.user)) {
+    console.log('usage: node tools/perf-bench.js --url URL (--user NAME --password-env VAR | --cookie sid=…) [--readers N] [--chapters N] [--pages N] [--think ms] [--ahead N] [--manga text] [--chapter-only] [--json]');
+    process.exit(o.help ? 0 : 2);
+  }
+  const cookie = await login(o);
+  let mangas = (await json(o, cookie, '/api/library')).data.mangas;
+  if (o.manga) mangas = mangas.filter(m => m.title.toLowerCase().includes(o.manga.toLowerCase()));
+  if (!mangas.length) throw new Error('no manga to read');
+  const out = { pages: [], api: [] }, t0 = Date.now();
+  await Promise.all(Array.from({ length: o.readers }, (_, i) => reader(o, cookie, mangas, out, i)));
+  const ok = out.pages.filter(p => p.status === 200), mb = ok.reduce((a, p) => a + p.bytes, 0) / 1048576;
+  const result = {
+    readers: o.readers, seconds: Math.round((Date.now() - t0) / 1000), pages: out.pages.length, errors: out.pages.length - ok.length,
+    MB: Math.round(mb), wait: sum(ok.map(p => p.wait)), ttfb: sum(ok.map(p => p.ttfb)), total: sum(ok.map(p => p.ms)),
+    waitedOver300: ok.filter(p => p.wait >= 300).length, waitedOver1s: ok.filter(p => p.wait >= 1000).length,
+    api: Object.fromEntries([...new Set(out.api.map(a => a.path))].map(p => [p, sum(out.api.filter(a => a.path === p).map(a => a.ms))])),
+    worst: ok.sort((a, b) => b.wait - a.wait).slice(0, 8).map(p => ({ wait: Math.round(p.wait), ttfb: Math.round(p.ttfb), ms: Math.round(p.ms), kb: Math.round(p.bytes / 1024), at: `${p.manga} ${p.chapter} p${p.page}` })),
+  };
+  if (o.json) return console.log(JSON.stringify(result, null, 2));
+  console.log(`${result.readers} readers, ${result.pages} pages (${result.MB} MB) in ${result.seconds} s, ${result.errors} errors`);
+  for (const k of ['wait', 'ttfb', 'total']) console.log(`  ${k.padEnd(6)} ms ${JSON.stringify(result[k])}`);
+  console.log(`  page waits >= 300 ms: ${result.waitedOver300}, >= 1 s: ${result.waitedOver1s}  (wait = time the reader looked at an empty page)`);
+  for (const [p, s] of Object.entries(result.api)) console.log(`  ${p} ${JSON.stringify(s)}`);
+  for (const w of result.worst) console.log(`    wait ${w.wait} ms (ttfb ${w.ttfb}, total ${w.ms}, ${w.kb} KB) ${w.at}`);
+}
+
+main().catch(e => { console.error(e.message); process.exit(1); });

tools/perf-report.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * Summarise a performance trace (docs/performance.md) and say where slow page loads spend their time.
+ *
+ *   node tools/perf-report.js DATA/perf                       all trace files in the folder
+ *   node tools/perf-report.js trace-2026-10-29.jsonl --since 2026-10-29T18:00 --until …  --slow 500 --json
+ *
+ * Plain text by default (readable by people and agents); --json prints the numbers only.
+ */
+const fs = require('fs'), path = require('path');
+
+function parseArgs(argv) {
+  const opts = { files: [], since: null, until: null, slow: 500, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--since') opts.since = Date.parse(argv[++i]);
+    else if (a === '--until') opts.until = Date.parse(argv[++i]);
+    else if (a === '--slow') opts.slow = +argv[++i];
+    else if (a === '--json') opts.json = true;
+    else if (a === '-h' || a === '--help') opts.help = true;
+    else opts.files.push(a);
+  }
+  return opts;
+}
+
+function readEvents(inputs, { since, until }) {
+  const files = inputs.flatMap(p => fs.statSync(p).isDirectory()
+    ? fs.readdirSync(p).filter(n => /^trace-.*\.jsonl$/.test(n)).sort().map(n => path.join(p, n)) : [p]);
+  const events = [];
+  for (const file of files) for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    if (!line) continue;
+    let e; try { e = JSON.parse(line); } catch { continue; }
+    if ((since && e.t < since) || (until && e.t > until)) continue;
+    events.push(e);
+  }
+  return events.sort((a, b) => a.t - b.t);
+}
+
+const pct = (values, p) => {
+  const v = values.filter(x => typeof x === 'number').sort((a, b) => a - b);
+  if (!v.length) return null;
+  return v[Math.min(v.length - 1, Math.floor((p / 100) * v.length))];
+};
+const stats = values => {
+  const v = values.filter(x => typeof x === 'number');
+  return v.length ? { n: v.length, p50: pct(v, 50), p90: pct(v, 90), p99: pct(v, 99), max: Math.max(...v) } : { n: 0 };
+};
+const isPageImage = e => e.k === 'req' && e.path.startsWith('/lib/') && e.path.split('/').length >= 6;
+
+// Where one served image spent its time on the server.
+function serverPhases(e) {
+  const stat = e.stat ?? 0, open = e.open != null ? e.open - stat : 0, firstRead = e.first != null && e.open != null ? e.first - e.open : 0;
+  const rest = Math.max(0, (e.disk ?? 0) - firstRead), net = e.netWait ?? 0;
+  const tail = e.readEnd != null ? Math.max(0, e.ms - e.readEnd) : 0;
+  const r = v => Math.round(v * 10) / 10;
+  return { stat: r(stat), open: r(open), firstRead: r(firstRead), readRest: r(rest), netWait: r(net), tail: r(tail) };
+}
+const dominant = phases => Object.entries(phases).sort((a, b) => b[1] - a[1])[0][0];
+
+function analyse(events, { slow }) {
+  const out = { window: events.length ? { from: new Date(events[0].t).toISOString(), to: new Date(events.at(-1).t).toISOString() } : null };
+  const reqs = events.filter(e => e.k === 'req');
+  const imgs = reqs.filter(isPageImage), served = imgs.filter(e => e.status === 200 && !e.aborted);
+  out.requests = { total: reqs.length, pageImages: imgs.length, served: served.length,
+    notModified: imgs.filter(e => e.status === 304).length, aborted: imgs.filter(e => e.aborted).length,
+    errors: imgs.filter(e => e.status >= 400).length, keepAliveReuse: imgs.length ? round(imgs.filter(e => e.conn > 1).length / imgs.length) : null };
+  out.serverImage = { total: stats(served.map(e => e.ms)), stat: stats(served.map(e => e.stat)),
+    firstRead: stats(served.map(e => serverPhases(e).firstRead)), disk: stats(served.map(e => e.disk)),
+    netWait: stats(served.map(e => e.netWait)), kbytes: stats(served.map(e => e.bytes / 1024)) };
+  const slowServed = served.filter(e => e.ms >= slow);
+  out.slowServer = { count: slowServed.length, share: served.length ? round(slowServed.length / served.length) : null, by: {} };
+  for (const e of slowServed) { const d = dominant(serverPhases(e)); out.slowServer.by[d] = (out.slowServer.by[d] || 0) + 1; }
+  out.slowServer.worst = slowServed.sort((a, b) => b.ms - a.ms).slice(0, 10)
+    .map(e => ({ at: new Date(e.t).toISOString(), ms: e.ms, ...serverPhases(e), path: e.path }));
+
+  const api = {};
+  for (const e of reqs.filter(e => e.path.startsWith('/api/'))) (api[e.path] ||= []).push(e.ms);
+  out.api = Object.fromEntries(Object.entries(api).map(([p, v]) => [p, stats(v)]).sort((a, b) => (b[1].p99 || 0) - (a[1].p99 || 0)).slice(0, 12));
+
+  // Browser view, matched to the server's record of the same file where possible.
+  const res = events.filter(e => e.k === 'client' && e.e === 'res'), byPath = new Map();
+  const decoded = p => { try { return decodeURIComponent(p); } catch { return p; } };
+  for (const e of imgs) { const key = decoded(e.path); (byPath.get(key) || byPath.set(key, []).get(key)).push(e); }
+  const matched = res.map(r => {
+    const cands = (byPath.get(r.url) || []).filter(s => s.t <= r.t + 1000 && s.t >= r.t - 120000);
+    const s = cands.at(-1);
+    return { ...r, serverMs: s ? s.ms : null };
+  });
+  const loaded = matched.filter(r => !r.cached);
+  out.browserImage = { total: stats(loaded.map(r => r.total)), queue: stats(loaded.map(r => r.queue)),
+    ttfb: stats(loaded.map(r => r.ttfb)), download: stats(loaded.map(r => r.download)),
+    connect: stats(loaded.map(r => r.connect)), dns: stats(loaded.map(r => r.dns)), fromCache: matched.length - loaded.length };
+  const slowBrowser = loaded.filter(r => r.total >= slow);
+  out.slowBrowser = { count: slowBrowser.length, share: loaded.length ? round(slowBrowser.length / loaded.length) : null, by: {} };
+  for (const r of slowBrowser) {
+    const parts = { server: r.serverMs ?? 0, network: Math.max(0, (r.ttfb ?? 0) + (r.download ?? 0) - (r.serverMs ?? 0)),
+      queue: r.queue ?? 0, connect: (r.connect ?? 0) + (r.dns ?? 0) };
+    const d = r.serverMs == null ? 'unmatched' : dominant(parts);
+    out.slowBrowser.by[d] = (out.slowBrowser.by[d] || 0) + 1;
+  }
+  const views = events.filter(e => e.k === 'client' && e.e === 'view'), stalls = events.filter(e => e.k === 'client' && e.e === 'stall');
+  out.pageTurns = { count: views.length, preloaded: views.filter(v => v.preloaded).length, wait: stats(views.map(v => v.wait)),
+    over300ms: views.filter(v => v.wait >= 300).length, over1s: views.filter(v => v.wait >= 1000).length };
+  out.flowStalls = { count: stalls.length, wait: stats(stalls.map(s => s.wait)), over1s: stalls.filter(s => s.wait >= 1000).length };
+  out.clients = [...new Set(events.filter(e => e.k === 'client' && e.e === 'hello').map(e => `${e.user}: ${e.ua}`))].slice(0, 10);
+
+  // Storage probe: cold reads of random pages; a long read after quiet time points at disks waking up.
+  const nas = events.filter(e => e.k === 'nas' && !e.error);
+  // Library reads that finished before a probe started (a probe's own read does not count).
+  const ioEnds = events.filter(e => isPageImage(e) || e.k === 'nas' || e.k === 'ahead').map(e => e.t);
+  out.nas = { probes: nas.length, errors: events.filter(e => e.k === 'nas' && e.error).length, first: stats(nas.map(e => e.firstMs)), total: stats(nas.map(e => e.ms)) };
+  out.nas.slow = nas.filter(e => e.firstMs >= 1000).map(e => {
+    const start = e.t - e.ms, before = ioEnds.filter(t => t < start).at(-1);
+    return { at: new Date(e.t).toISOString(), firstMs: e.firstMs, quietMinBefore: before ? round((start - before) / 60000) : null };
+  }).slice(0, 30);
+
+  const loops = events.filter(e => e.k === 'loop');
+  out.eventLoop = { samples: loops.length, lagP99: stats(loops.map(e => e.lagP99)), lagMax: stats(loops.map(e => e.lagMax)), cpu: stats(loops.map(e => e.cpu)), rssMB: stats(loops.map(e => e.rss)) };
+
+  const scans = events.filter(e => e.k === 'scan');
+  out.scans = { count: scans.length, ms: stats(scans.map(e => e.ms)) };
+  const during = e => scans.some(s => e.t >= s.t - s.ms && e.t - e.ms <= s.t);
+  out.scans.slowImagesDuringScan = slowServed.filter(during).length;
+  const span = events.length ? events.at(-1).t - events[0].t : 0;
+  out.scans.timeShare = span ? round(scans.reduce((a, s) => a + s.ms, 0) / span) : null;
+
+  const ahead = events.filter(e => e.k === 'ahead');
+  out.readAhead = { batches: ahead.length, replaced: ahead.filter(e => e.replaced).length, files: ahead.reduce((a, e) => a + e.done, 0),
+    MBps: stats(ahead.filter(e => e.ms > 0 && e.bytes > 0).map(e => round(e.bytes / 1048.576 / e.ms))) };
+  const scraper = events.filter(e => e.k === 'scraper');
+  out.scraper = { calls: scraper.length, errors: scraper.filter(e => e.error).length, ms: stats(scraper.map(e => e.ms)) };
+  out.verdict = verdict(out, slow);
+  return out;
+}
+
+function verdict(o, slow) {
+  const lines = [];
+  const top = by => Object.entries(by).sort((a, b) => b[1] - a[1]);
+  if (o.slowServer.count) {
+    const [[phase, n]] = top(o.slowServer.by);
+    const name = { stat: 'the file lookup (stat) on the storage', open: 'opening the file', firstRead: 'the first read from storage',
+      readRest: 'reading the rest of the file from storage', netWait: 'the client receiving data (network)', tail: 'flushing to the client' }[phase];
+    lines.push(`${o.slowServer.count} of ${o.serverImage.total.n} served pages took >= ${slow} ms on the server; ${n} of them mostly in ${name}.`);
+  } else if (o.serverImage.total.n) lines.push(`No served page took >= ${slow} ms on the server (p99 ${o.serverImage.total.p99} ms).`);
+  if (o.slowBrowser.count) {
+    const [[part, n]] = top(o.slowBrowser.by);
+    lines.push(`${o.slowBrowser.count} of ${o.browserImage.total.n} page loads took >= ${slow} ms in the browser; mostly ${part} (${n}).`);
+  }
+  if (o.pageTurns.count) lines.push(`Page turns: ${o.pageTurns.preloaded}/${o.pageTurns.count} preloaded, ${o.pageTurns.over300ms} waited >= 300 ms, ${o.pageTurns.over1s} >= 1 s (p90 ${o.pageTurns.wait.p90 ?? 0} ms).`);
+  if (o.flowStalls.count) lines.push(`Flow mode: ${o.flowStalls.count} pages were on screen before their image (p90 ${o.flowStalls.wait.p90} ms, ${o.flowStalls.over1s} >= 1 s).`);
+  if (o.nas.probes) {
+    lines.push(`Storage probe (cold page): first byte p50 ${o.nas.first.p50} ms, p99 ${o.nas.first.p99} ms, max ${o.nas.first.max} ms; ${o.nas.slow.length} probes >= 1 s.`);
+    const sleepy = o.nas.slow.filter(s => s.quietMinBefore >= 5).length;
+    if (sleepy) lines.push(`${sleepy} slow probes followed >= 5 min without library reads: disks waking from standby is likely.`);
+  }
+  if (o.eventLoop.samples && (o.eventLoop.lagMax.max || 0) >= 200) lines.push(`Event loop blocked up to ${o.eventLoop.lagMax.max} ms (reader CPU work holds requests back).`);
+  if (o.scans.slowImagesDuringScan) lines.push(`${o.scans.slowImagesDuringScan} slow pages overlapped a library scan (scans ran ${Math.round((o.scans.timeShare || 0) * 100)}% of the time).`);
+  return lines;
+}
+
+function print(o) {
+  const s = x => (x && x.n ? `n=${x.n} p50=${x.p50} p90=${x.p90} p99=${x.p99} max=${x.max}` : 'n=0');
+  const out = [];
+  out.push(`Trace ${o.window ? `${o.window.from} .. ${o.window.to}` : '(empty)'}`, '', 'Verdict:', ...o.verdict.map(l => '  - ' + l), '');
+  out.push('Requests', `  ${JSON.stringify(o.requests)}`);
+  out.push('Server, page images (ms)');
+  for (const k of ['total', 'stat', 'firstRead', 'disk', 'netWait', 'kbytes']) out.push(`  ${k.padEnd(10)} ${s(o.serverImage[k])}`);
+  out.push(`  slow by phase ${JSON.stringify(o.slowServer.by)}`);
+  for (const w of o.slowServer.worst) out.push(`    ${w.at} ${w.ms} ms stat=${w.stat} first=${w.firstRead} rest=${w.readRest} net=${w.netWait} ${w.path}`);
+  out.push('Browser, page images (ms)');
+  for (const k of ['total', 'queue', 'ttfb', 'download', 'connect', 'dns']) out.push(`  ${k.padEnd(10)} ${s(o.browserImage[k])}`);
+  out.push(`  from browser cache ${o.browserImage.fromCache}; slow by part ${JSON.stringify(o.slowBrowser.by)}`);
+  out.push(`Page turns  ${o.pageTurns.count} (${o.pageTurns.preloaded} preloaded) wait ${s(o.pageTurns.wait)}`);
+  out.push(`Flow stalls ${o.flowStalls.count} wait ${s(o.flowStalls.wait)}`);
+  out.push(`Storage probe first byte ${s(o.nas.first)}  total ${s(o.nas.total)}  errors ${o.nas.errors}`);
+  for (const p of o.nas.slow) out.push(`    ${p.at} first=${p.firstMs} ms after ${p.quietMinBefore ?? '?'} min quiet`);
+  out.push(`Event loop lagP99 ${s(o.eventLoop.lagP99)}  lagMax ${s(o.eventLoop.lagMax)}  cpu% ${s(o.eventLoop.cpu)}  rssMB ${s(o.eventLoop.rssMB)}`);
+  out.push(`Scans ${o.scans.count} ${s(o.scans.ms)}`);
+  out.push(`Read-ahead ${JSON.stringify(o.readAhead)}`);
+  out.push(`Scraper calls ${o.scraper.calls} errors ${o.scraper.errors} ${s(o.scraper.ms)}`);
+  out.push('API (ms, slowest p99 first)');
+  for (const [p, v] of Object.entries(o.api)) out.push(`  ${p.padEnd(28)} ${s(v)}`);
+  if (o.clients.length) out.push('Clients', ...o.clients.map(c => '  ' + c));
+  return out.join('\n');
+}
+
+const round = v => Math.round(v * 100) / 100;
+
+if (require.main === module) {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help || !opts.files.length) { console.log('usage: node tools/perf-report.js <trace.jsonl|folder>... [--since ISO] [--until ISO] [--slow ms] [--json]'); process.exit(opts.help ? 0 : 2); }
+  const result = analyse(readEvents(opts.files, opts), opts);
+  console.log(opts.json ? JSON.stringify(result, null, 2) : print(result));
+}
+
+module.exports = { analyse, readEvents, print };

tools/test-compose.js

@@ -69,6 +69,7 @@ for (const [index, name] of ['Moon Garden', 'Before the Rain', 'Iron Harbor'].en
 const env = { ...process.env, LIBRARY_PATH: library, DATA_PATH: data, SCRAPER_DATA_PATH: path.join(data, 'scraper'),
   SCRAPER_TOKEN_PATH: tokenFile, BACKUP_PATH: backupDir, READER_PORT: port, READER_BIND: '127.0.0.1', COOKIE_SECURE: '0', APP_IMAGE: process.env.APP_IMAGE || 'mangacircus:local',
   READER_IMAGE: process.env.APP_IMAGE || 'mangacircus:local',
+  GREATEST_COVER_WARM: '0', // QA stacks never download catalog covers
   ...(readingGateQa ? { READING_WINDOWS_JSON: '{"0":[],"1":[],"2":[],"3":[],"4":[],"5":[],"6":[]}',
     READING_TIMEZONE: 'Europe/Berlin', READING_QUIZ_UNLOCK_MINUTES: '60', READING_QUIZ_CATALOG_PATH: '/data/reading-quiz.json' }
     : { READING_WINDOWS_JSON: '', READING_QUIZ_CATALOG_PATH: '' }),

tools/test-greatest-ui.js

@@ -40,7 +40,7 @@ async function freePort() {
   const scraperPort = fakeScraper.address().port;
   const child = spawn(process.execPath, ['server.js'], { cwd: root, windowsHide: true,
     env: { ...process.env, PORT: String(port), LIBRARY: library, DATA: data, SCAN_INTERVAL: '0',
-      FULL_SCAN_INTERVAL: '0', SCRAPER_URL: `http://127.0.0.1:${scraperPort}`, COOKIE_SECURE: '0' }, stdio: 'ignore' });
+      FULL_SCAN_INTERVAL: '0', SCRAPER_URL: `http://127.0.0.1:${scraperPort}`, COOKIE_SECURE: '0', GREATEST_COVER_WARM: '0' }, stdio: 'ignore' });
   let browser;
   try {
     for (let i = 0; i < 80; i++) {