Chapter dates: read date setting and tiered release dates (BL-0047)

- Chapter rows show when you first finished a chapter (setting: date + hour,
  date, off) from a new durable progress doneAt; older reads fall back to the
  reading clock's earliest remembered completion.
- chapter.json keeps added (arrival in this library, now kept on replace) plus
  x-dates.source (source upload, bulk imports flagged), x-dates.release
  (official, for a later metadata job) and x-dates.ecosystem (first entry into
  any Manga Circus library; carried over peering, earliest wins, clamped).
- Rows show one release date by tier: official > source upload > ecosystem >
  library, with all known dates in the tooltip (setting to hide).
- Fixes: WeebCentral dates came from the chapter page, which has none (every
  chapter got the download time); they now come from the full chapter list.
  MangaDex no longer writes a group's publishAt into added. Peering sends dates.
- tools/backfill-chapter-dates.js migrates an existing library (dry run default).
- Coverage dry run on the server: docs/chapter-dates-coverage-2026-10-24.md.

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

scraper/adapters/mangadex.js

@@ -3,6 +3,7 @@
 const API = 'https://api.mangadex.org';
 const { parse } = require('../plugins/registry');
 const { localizedTitle, chapterNumber, selectChapterReleases, availabilitySummary, pageUrls } = require('../plugins/mangadex');
+const { sourceDate } = require('../../chapter-dates');
 
 function mangaDexInfo(value) {
   let url;
@@ -71,8 +72,9 @@ async function discoverMangaDexChapter(ref, http) {
   const atHome = await jsonGet(http, `${API}/at-home/server/${ref.id}?forcePort443=true`);
   const groupName = ref.group?.name ? ` · ${ref.group.name}` : '';
   const parsed = parse('mangadex', 'atHome', { data: { response: atHome, chapterUrl: ref.url, expectedPages: ref.pages }, url: `${API}/at-home/server/${ref.id}` });
+  const source = sourceDate(ref.uploadedAt, `MangaDex${groupName}`, ref.uploadBatch);
   return {
-    number: ref.number, title: ref.title || '', added: ref.added,
+    number: ref.number, title: ref.title || '', ...(source ? { dates: { source } } : {}),
     ...(ref.special ? { special: true, label: ref.label, sourceId: ref.id, sourceNumber: ref.sourceNumber ?? null } : {}),
     source: { name: `MangaDex${groupName}`, url: ref.url },
     pages: parsed.pages,

scraper/adapters/weebcentral.js

@@ -4,6 +4,7 @@ const { SlowHttp } = require('../lib/http');
 const { fallbackDirection } = require('../../reading-direction');
 const parser = require('../plugins/weebcentral');
 const { parse } = require('../plugins/registry');
+const { sourceDate } = require('../../chapter-dates');
 
 function weebCentralInfo(value) {
   let url;
@@ -36,7 +37,8 @@ async function discoverWeebCatalog(seriesUrl, http) {
 
 async function discoverWeebChapter(chapter, http) {
   const pageHtml = await (await http.get(chapter.url, { accept: 'text/html' })).text();
-  const { manifestUrl, added } = parse('weebcentral', 'chapter', { html: pageHtml, url: chapter.url });
+  const { manifestUrl } = parse('weebcentral', 'chapter', { html: pageHtml, url: chapter.url });
+  const source = sourceDate(chapter.uploadedAt, 'WeebCentral', chapter.uploadBatch);
   const fragment = await (await http.get(`${manifestUrl}&reading_style=long_strip&current_page=1`, { accept: 'text/html' })).text();
   const parsed = parse('weebcentral', 'pages', { html: fragment, url: manifestUrl });
   const pages = parsed.pages.map(url => ({ url, headers: { referer: chapter.url } }));
@@ -46,7 +48,7 @@ async function discoverWeebChapter(chapter, http) {
     ...(chapter.special ? { special: true, label: chapter.label, sourceId: chapter.id,
       sourceNumber: chapter.volume, releaseKind: chapter.releaseKind, volume: chapter.volume } : {}),
     ...(chapter.book ? { book: chapter.book } : {}),
-    added,
+    ...(source ? { dates: { source } } : {}),
     source: { name: 'WeebCentral', url: chapter.url }, pages,
   };
 }

scraper/lib/publisher.js

@@ -12,6 +12,7 @@ const { directionFields } = require('../../reading-direction');
 const { mergeImportedMetadata } = require('./metadata-merge');
 const { normalizeWorkIdentity } = require('./work-identity');
 const { parseKey } = require('../../chapter-identity');
+const { publishedDates } = require('../../chapter-dates');
 
 const token = () => crypto.randomBytes(5).toString('hex');
 // Staging is a recovery asset, not disposable garbage. Legacy stages without an
@@ -180,7 +181,8 @@ async function stageChapter(bookDir, chapter, http, onPage, priorMeta = {}) {
     await fsp.writeFile(path.join(stage, 'chapter.json'), JSON.stringify({
       ...priorMeta,
       title: chapter.title || '', source: chapter.source,
-      added: chapter.added || new Date().toISOString(),
+      // "added" stays the first arrival in this library; x-dates keeps source/release/ecosystem.
+      ...publishedDates(priorMeta, { ...(chapter.dates || {}), added: chapter.added }),
       priority: Number(chapter.priority || 0), extra: !!chapter.extra,
       ...(chapter.special ? { special: true, label: chapter.label || 'Special', sourceId: chapter.sourceId,
         sourceNumber: chapter.sourceNumber ?? null,

scraper/plugins/mangadex.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { specialKey } = require('../../chapter-identity');
+const { batchFlags } = require('../../chapter-dates');
 
 function localizedTitle(attributes = {}) {
   const titles = attributes.title || {};
@@ -41,14 +42,18 @@ function selectChapterReleases(resources = [], specialLabel = 'Special') {
     const prior = selected.get(number);
     if (!prior || compareRank(resource, prior) < 0) selected.set(number, resource);
   }
-  return [...selected.entries()].map(([number, resource]) => {
+  const chosen = [...selected.entries()];
+  const uploaded = chosen.map(([, resource]) => resource.attributes?.publishAt || resource.attributes?.readableAt || resource.attributes?.createdAt);
+  const batches = batchFlags(uploaded);
+  return chosen.map(([number, resource], index) => {
     const group = groupFor(resource);
     return {
       id: resource.id, number, title: resource.attributes?.title || '',
       ...(!chapterNumber(resource.attributes?.chapter) ? { special: true, label: specialLabel, sourceId: resource.id, sourceNumber: resource.attributes?.chapter ?? null } : {}),
       ...(resource.attributes?.volume ? { volume: chapterNumber(resource.attributes.volume) || String(resource.attributes.volume) } : {}),
       pages: Number(resource.attributes?.pages || 0),
-      added: resource.attributes?.publishAt || resource.attributes?.readableAt || resource.attributes?.createdAt,
+      // A group's upload time, not an official release; bulk uploads are flagged.
+      ...(uploaded[index] ? { uploadedAt: uploaded[index], uploadBatch: !!batches[index] } : {}),
       group,
       url: `https://mangadex.org/chapter/${resource.id}`,
     };

scraper/plugins/weebcentral.js

@@ -1,5 +1,6 @@
 'use strict';
 const { volumeKey } = require('../../chapter-identity');
+const { batchFlags } = require('../../chapter-dates');
 
 // First-party, pure parsing functions. This module never fetches remote content.
 const decode = value => value.replace(/&amp;/g, '&').replace(/&#39;/g, "'").replace(/&quot;/g, '"').replace(/<[^>]+>/g, '').trim();
@@ -21,19 +22,26 @@ function catalog({ html, url }) {
     const volume = !regular ? text.match(/^Volume\s+([0-9]+(?:\.[0-9]+)?)(?!\d)/i)?.[1] : null;
     const prologue = text.match(/Prologue(?:\s+([0-9]+))?/i)?.[1];
     const number = regular || (prologue ? `0.${prologue.padStart(2, '0')}` : /Prologue/i.test(text) ? '0' : null);
+    // The full chapter list carries each upload time; the chapter page itself has none.
+    const uploaded = match[3].match(/datetime="([^"]+)"/i)?.[1];
+    const uploadedAt = uploaded && Number.isFinite(Date.parse(uploaded)) ? uploaded : undefined;
     if (number) found.push({
       id: match[2], number, title: regular ? '' : `Prologue ${prologue || ''}`.trim(),
       ...(season ? { book: { number: season, title: `Season ${season}` } } : {}),
-      url: absolute(url, match[1]), raw: text,
+      url: absolute(url, match[1]), raw: text, ...(uploadedAt ? { uploadedAt } : {}),
     });
     else if (volume) found.push({
       id: match[2], number: volumeKey(match[2]), title: '', special: true,
       label: `Volume ${volume}`, releaseKind: 'volume', volume,
       book: { number: Number(volume), title: `Volume ${volume}` },
-      url: absolute(url, match[1]), raw: text,
+      url: absolute(url, match[1]), raw: text, ...(uploadedAt ? { uploadedAt } : {}),
     });
   }
   const chapters = [...new Map(found.map(chapter => [chapter.id, chapter])).values()];
+  // Back-catalog chapters were imported together; their upload time is not a release date.
+  batchFlags(chapters.map(chapter => chapter.uploadedAt)).forEach((batch, index) => {
+    if (batch !== null) chapters[index].uploadBatch = batch;
+  });
   const chapterLinks = [...html.matchAll(/<a\b[^>]*href="[^"]*\/chapters\/[A-Z0-9]+[^"]*"/gi)].length;
   return { chapters, chapterLinks };
 }
@@ -42,7 +50,6 @@ function chapter({ html, url }) {
   return {
     manifestUrl: html.match(/['"](https?:\/\/weebcentral\.com\/chapters\/[^'"]+\/images\?is_prev=[^'"]+)['"]/i)?.[1]
       || `${url}/images?is_prev=False`,
-    added: html.match(/datetime="([^"]+)"/i)?.[1],
   };
 }
 

scraper/test/source-plugin.test.js

@@ -10,8 +10,8 @@ const { adapters, adapterFor } = require('../adapters');
 const seriesUrl = 'https://weebcentral.com/series/ABC/title';
 const chapterUrl = 'https://weebcentral.com/chapters/XYZ';
 const seriesHtml = '<h1>Test Manga</h1><div hx-get="/series/ABC/full-chapter-list"></div>';
-const listHtml = '<a href="/chapters/XYZ">Chapter 1</a><a href="/chapters/LMN">Log. 2</a>';
-const chapterHtml = '<time datetime="2026-01-01"></time>';
+const listHtml = '<a href="/chapters/XYZ"><span>Chapter 1</span><time datetime="2026-01-01T15:06:05.348Z">x</time></a><a href="/chapters/LMN">Log. 2</a>';
+const chapterHtml = '<div>no dates on the chapter page</div>';
 const imagesHtml = '<img src="https://img.example/1.jpg"><img data-src="https://img.example/2.jpg">';
 
 test('first-party registry rejects unknown plugins and malformed input', () => {
@@ -45,7 +45,9 @@ test('in-process parser preserves WeebCentral catalog and page discovery', async
   assert.deepEqual(catalog.chapters.map(chapter => chapter.number), ['1', '2']);
   const chapter = await discoverWeebChapter(catalog.chapters[0], http);
   assert.equal(chapter.pages.length, 2);
-  assert.equal(chapter.added, '2026-01-01');
+  assert.equal(chapter.added, undefined);
+  assert.deepEqual(chapter.dates, { source: { at: '2026-01-01T15:06:05.348Z', name: 'WeebCentral', batch: false } });
+  assert.equal(catalog.chapters[1].uploadedAt, undefined);
   assert.equal(requested.length, 4);
 });