lowkey-doc 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lowkey-doc",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Render a folder of Markdown into one self-contained documentation dashboard, with flowcharts and ER diagrams that stay readable when they get dense.",
   "repository": {
     "type": "git",

package/skills/write-doc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-doc
-description: Write a new high-level product document for this project's documentation folder. Use when asked to document a feature, flow, or area for a non-technical reader — "write a doc about X", "document the checkout flow", "add a docs page for onboarding".
+description: Write a new high-level product document for this project's documentation folder, or change an existing one. Use when asked to document a feature, flow, or area for a non-technical reader — "write a doc about X", "document the checkout flow", "add a docs page for onboarding", "update the onboarding doc".
 ---
 
 # Writing a document
@@ -86,6 +86,28 @@ For an `erDiagram`, the entity is drawn as a table with the keys pinned to its r
 ## Appendix — implementation direction   (only if a decision must be recorded)
 ```
 
+## Changing what someone has reviewed
+
+Readers mark sections **Reviewed** on the dashboard, and the marks are kept in `docs.reviews.json`
+beside `docs.config.json`. A mark means a person read those words and agreed with them, so it must
+not outlive them. Before editing a document, look for its file name in `docs.reviews.json`:
+
+- **Every section whose words you change loses its mark: delete its line.** A section is keyed by
+  its heading's GitHub-style anchor (`## 2. Inviting somebody in` → `"2-inviting-somebody-in"`),
+  and `""` is the document's own words: the blockquote under the title and anything before the
+  first section.
+- **A mark covers only the words directly under its heading**, up to the next heading of any level.
+  Changing a sub-section removes the sub-section's line, not its chapter's; the chapter and the
+  document show as open on their own until the changed part is reviewed again.
+- **Renaming a heading or moving a section** changes its anchor: delete its old line as well.
+- Re-wrapping lines or changing only formatting leaves the words as they were: keep the mark.
+- **Never add or change a mark yourself.** Only a person reviews.
+- **Say which reviewed sections you changed** at the end of your reply, so the reviewer knows what
+  to read again.
+
+The dashboard would show a changed section as open anyway, since each mark carries a fingerprint
+of its words; deleting the line keeps the file honest in git as well.
+
 ## Filing
 
 - Name: `<n>. TITLE-IN-CAPS.md` in the documents folder, `<n>` being the next free number.

package/src/build.mjs

@@ -6,13 +6,15 @@ import { execFile } from 'node:child_process';
 import { listDocs, assignIds, buildDoc } from './collect.mjs';
 import { vendorMermaid, vendorElk, vendorFont, writeNotices } from './vendor.mjs';
 import { renderPage } from './page.mjs';
+import { readReviews } from './reviews.mjs';
 import { DEFAULTS, CLI, VERSION } from './config.mjs';
 
 export async function build(cfg, { open = true, refresh = false, quiet = false } = {}) {
   const { docs } = collectDocs(cfg);
 
   const assets = await vendorAssets(cfg, refresh);
-  const html = pageFor(cfg, docs, assets);
+  const marks = readReviews(cfg);
+  const html = pageFor(cfg, docs, assets, marks.reviews);
 
   const outFile = path.join(cfg.outDir, 'index.html');
   fs.writeFileSync(outFile, html);
@@ -22,6 +24,7 @@ export async function build(cfg, { open = true, refresh = false, quiet = false }
     docs,
     bytes: fs.statSync(outFile).size,
     notes: { mermaid: assets.mermaid.note, elk: assets.elk.note, font: assets.font.note },
+    reviews: marks.error,
   };
 
   if (!quiet) print(cfg, report);
@@ -97,9 +100,11 @@ export async function vendorAssets(cfg, refresh = false) {
   return assets;
 }
 
-export function pageFor(cfg, docs, assets) {
+// reviews: the marks read from docs.reviews.json. The watcher leaves them out
+// of the page it fingerprints as its shell, so saving one never reloads a page.
+export function pageFor(cfg, docs, assets, reviews = {}) {
   return renderPage({
-    cfg, docs,
+    cfg, docs, reviews,
     fontCss: assets.font.css,
     mermaidTag: assets.mermaid.tag,
     elkTag: assets.elk.tag,
@@ -117,6 +122,7 @@ function print(cfg, r) {
   console.log('  mermaid: ' + r.notes.mermaid);
   console.log('  elk:     ' + r.notes.elk);
   console.log('  font:    ' + r.notes.font);
+  if (r.reviews) console.log('  reviews: not shown - ' + r.reviews);
   console.log('  -> ' + r.outFile + '  (' + (r.bytes / 1024).toFixed(0) + ' KB)');
 }
 

package/src/client/app.mjs

@@ -213,62 +213,102 @@ export const APP_JS = String.raw`
   }
 
   /* ---------------- reviews ----------------
-     A reader marks what they have read and agree with. The mark is kept on the
-     smallest sections only: a section with sections under it is reviewed when
-     every one of them is, and the document when all of its sections are. So
-     marking a document or a chapter marks everything in it, reviewing the last
-     open section of a chapter completes the chapter, and a section written
-     later opens its chapter and its document again until it is read too.
-     Like comments, the marks live in this browser and nowhere else. */
+     A reader marks what they have read and agree with. Every section owns the
+     words directly under its heading, and the document owns its standfirst
+     and whatever comes before its first section; each of those is marked on
+     its own, with a fingerprint of the words it was given for. A section is
+     reviewed when its own words are and every section under it is. So marking
+     a chapter or the document marks everything in it, reviewing the last open
+     section of a chapter completes the chapter, and clearing one opens what is
+     above it again. Words edited after their review, and a section written
+     later, leave their chapter and document open until they are read too.
+
+     The marks are the project's, in docs.reviews.json: the page shows the ones
+     its build read, and only lowkey-doc --watch can save a change (app.saveReviews). */
 
   var RV_ON = CFG.reviews !== false;
-  var reviewed = {};
-  try {
-    var rvSaved = JSON.parse(recall('reviewed') || '{}');
-    if (rvSaved && rvSaved.docs && typeof rvSaved.docs === 'object') reviewed = rvSaved.docs;
-  } catch (e) { reviewed = {}; }
-
-  function findSec(list, id){
-    for (var i = 0; i < list.length; i++){
-      if (list[i].id === id) return list[i];
-      var hit = findSec(list[i].kids, id);
-      if (hit) return hit;
+  var reviews = DATA.reviews || {};
+  var rvSaving = 0;
+
+  // the document as the root of its own outline; its own words are the "" mark
+  function rvRoot(d){ return { id: '', sig: d.sig, kids: d.outline || [] }; }
+
+  // the nodes from the document down to one of its sections (id null: the document)
+  function rvTrail(d, id){
+    var trail = [rvRoot(d)];
+    if (!id) return trail;
+    var seek = function(list){
+      for (var i = 0; i < list.length; i++){
+        trail.push(list[i]);
+        if (list[i].id === id || seek(list[i].kids)) return true;
+        trail.pop();
+      }
+      return false;
+    };
+    return seek(trail[0].kids) ? trail : null;
+  }
+
+  function ownDone(marks, n){ var m = marks[n.id]; return n.sig == null || !!(m && m.sig === n.sig); }
+  function allDone(marks, n){ return ownDone(marks, n) && n.kids.every(function(k){ return allDone(marks, k); }); }
+
+  function isReviewed(d, id){
+    var trail = rvTrail(d, id);
+    return !!trail && allDone(reviews[d.file] || {}, trail[trail.length - 1]);
+  }
+
+  // A document's marks once one part of it is marked (on) or cleared: the
+  // part and everything in it, then upwards - marking completes each chapter
+  // whose sections are now all reviewed, clearing opens every one above.
+  function rvNext(d, id, on){
+    var trail = rvTrail(d, id);
+    if (!trail) return null;
+    var was = reviews[d.file] || {}, mine = {}, all = [];
+    var t = new Date(), today = t.getFullYear() + '-' + ('0' + (t.getMonth() + 1)).slice(-2) + '-' + ('0' + t.getDate()).slice(-2);
+    (function walk(n){ all.push(n); n.kids.forEach(walk); })(trail[0]);
+    all.forEach(function(n){ if (was[n.id] && n.sig != null) mine[n.id] = was[n.id]; });
+    var set = function(n){
+      if (n.sig == null) return;
+      var m = was[n.id];
+      mine[n.id] = m && m.sig === n.sig ? m : { sig: n.sig, at: today };
+    };
+    (function each(n){ if (on) set(n); else delete mine[n.id]; n.kids.forEach(each); })(trail[trail.length - 1]);
+    for (var i = trail.length - 2; i >= 0; i--){
+      if (!on){ delete mine[trail[i].id]; continue; }
+      if (!trail[i].kids.every(function(k){ return allDone(mine, k); })) break;
+      set(trail[i]);
     }
-    return null;
+    var out = {};
+    all.forEach(function(n){ if (mine[n.id]) out[n.id] = mine[n.id]; });
+    return out;
   }
 
-  // what a review of the document (id null) or of one section stands for: the
-  // smallest sections under it, or the document itself if it has no sections
-  function rvKeys(d, id){
-    var outline = d.outline || [];
-    var node = id ? findSec(outline, id) : { kids: outline };
-    if (!node) return [];
-    if (!node.kids.length) return [id || ''];
-    var out = [];
-    (function walk(list){
-      list.forEach(function(k){ if (k.kids.length) walk(k.kids); else out.push(k.id); });
-    })(node.kids);
-    return out;
+  function putMarks(file, marks){
+    if (marks && Object.keys(marks).length) reviews[file] = marks; else delete reviews[file];
   }
 
-  function rvCount(d, id){
-    var mine = reviewed[d.id] || {}, keys = rvKeys(d, id);
-    return { done: keys.filter(function(k){ return mine[k]; }).length, of: keys.length };
+  function day(at){
+    var p = String(at).split('-');
+    var t = new Date(+p[0], +p[1] - 1, +p[2]);
+    return isNaN(t) ? at : t.toLocaleDateString(undefined, { day: 'numeric', month: 'short', year: 'numeric' });
   }
-  function isReviewed(d, id){ var c = rvCount(d, id); return c.of > 0 && c.done === c.of; }
 
-  function setReviewed(d, id, on){
-    var mine = reviewed[d.id] || {}, now = Date.now();
-    rvKeys(d, id).forEach(function(k){ if (on) mine[k] = mine[k] || now; else delete mine[k]; });
-    if (Object.keys(mine).length) reviewed[d.id] = mine; else delete reviewed[d.id];
-    keep('reviewed', JSON.stringify({ version: 1, docs: reviewed }));
-    paintReviews();
+  // the latest day anything in this part was reviewed, and whether its own
+  // words have changed since
+  function rvAbout(d, id){
+    var trail = rvTrail(d, id), marks = reviews[d.file] || {}, last = '';
+    if (!trail) return {};
+    var node = trail[trail.length - 1], m = marks[node.id];
+    (function walk(n){ if (marks[n.id] && marks[n.id].at > last) last = marks[n.id].at; n.kids.forEach(walk); })(node);
+    return { last: last, changed: !!(m && node.sig != null && m.sig !== node.sig) ? m.at : '' };
   }
 
-  function paintBtn(btn, on, what){
+  function paintBtn(btn, d, id, what){
+    var on = isReviewed(d, id), about = rvAbout(d, id);
     btn.classList.toggle('is-on', on);
     btn.setAttribute('aria-pressed', on ? 'true' : 'false');
-    btn.title = on ? 'Reviewed. Click to open ' + what + ' again' : 'Mark ' + what + ' as reviewed';
+    btn.title = on ? 'Reviewed' + (about.last ? ' on ' + day(about.last) : '') + '. Click to open ' + what + ' again'
+      : about.changed ? 'Changed since it was reviewed on ' + day(about.changed) + '. Click to review it again'
+      : 'Mark ' + what + ' as reviewed';
   }
 
   function paintReviews(){
@@ -286,22 +326,41 @@ export const APP_JS = String.raw`
     if (!d) return;
     main.querySelectorAll('.sec').forEach(function(sec){
       var btn = sec.querySelector(':scope > .sec-head > .rv');
-      if (btn) paintBtn(btn, isReviewed(d, sec.dataset.sec), 'this section');
+      if (btn) paintBtn(btn, d, sec.dataset.sec, 'this section');
     });
     var whole = main.querySelector('.rv-doc'), count = main.querySelector('.rv-count');
-    if (whole) paintBtn(whole, isReviewed(d, null), 'the whole document');
+    if (whole) paintBtn(whole, d, null, 'the whole document');
     if (count){
-      var c = rvCount(d, null);
-      count.textContent = c.done && c.done < c.of ? c.done + ' of ' + c.of + ' sections' : '';
+      // the sections with words of their own to review
+      var marks = reviews[d.file] || {}, done = 0, of = 0;
+      (function walk(list){
+        list.forEach(function(n){ if (n.sig != null){ of++; if (ownDone(marks, n)) done++; } walk(n.kids); });
+      })(d.outline || []);
+      count.textContent = done && !isReviewed(d, null) ? done + ' of ' + of + ' sections' : '';
     }
   }
 
+  // Shown at once, saved behind; a save that fails puts the marks back.
   function toggleReview(btn){
     var d = byId[current];
     if (!d) return;
+    if (!app.saveReviews){
+      toast('Reviews are saved to the project by lowkey-doc --watch. This page was opened from its file, so it can only show them.');
+      return;
+    }
     var sec = btn.classList.contains('rv-doc') ? null : btn.closest('.sec');
     var id = sec ? sec.dataset.sec : null;
-    setReviewed(d, id, !isReviewed(d, id));
+    var before = reviews[d.file], next = rvNext(d, id, !isReviewed(d, id));
+    if (!next) return;
+    putMarks(d.file, next);
+    paintReviews();
+    rvSaving++;
+    app.saveReviews(d.file, next).then(function(){ rvSaving--; }, function(err){
+      rvSaving--;
+      putMarks(d.file, before);
+      paintReviews();
+      toast('Review not saved: ' + (err && err.message || err));
+    });
   }
 
   /* ---------------- lightbox ---------------- */
@@ -957,8 +1016,10 @@ export const APP_JS = String.raw`
   var TOP_EDGE = 64;         // below the sticky top bar
   var hold = null;
 
-  function applyUpdate(next){
+  function applyUpdate(next, marks){
     var old = byId, before = docs;
+    // while this page is saving a review, its own marks are the newest there are
+    if (marks && !rvSaving) reviews = marks;
     var navOf = function(list){
       return JSON.stringify(list.map(function(d){ return [d.id, d.title, d.badge, d.group, d.file, d.sections]; }));
     };
@@ -993,6 +1054,7 @@ export const APP_JS = String.raw`
       return r;
     }
     if (navMoved || changed.indexOf(current) >= 0) patch(old[current], byId[current], r);
+    else paintReviews();
     return r;
   }
 
@@ -1279,6 +1341,7 @@ export const APP_JS = String.raw`
 
   var app = window.__lowkey_doc = {
     save: null,
+    saveReviews: null,
     apply: applyUpdate,
     bring: bring,
     doc: function(id){ return byId[id]; }

package/src/client/live.mjs

@@ -79,7 +79,7 @@ export const LIVE_JS = String.raw`
     }).then(function(data){
       if (!app) return location.reload();
       version = data.version;
-      tell(app.apply(data.docs));
+      tell(app.apply(data.docs, data.reviews));
     }).catch(function(err){
       say('Could not load the update: ' + (err && err.message || err), 'bad', null, 0);
     }).then(function(){
@@ -128,6 +128,20 @@ export const LIVE_JS = String.raw`
     }).then(function(){ saving--; }, function(err){ saving--; throw err; });
   };
 
+  /* ---------------- saving reviews ---------------- */
+
+  // One document's marks, all of them, to docs.reviews.json. The save comes
+  // back to every open page - this one too - as a new version of the data.
+  if (app) app.saveReviews = function(file, marks){
+    return fetch('/__lowkey-doc/reviews', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ file: file, marks: marks })
+    }).then(function(r){
+      return r.json().catch(function(){ return {}; }).then(function(body){
+        if (!r.ok) throw new Error(body.error || 'HTTP ' + r.status);
+      });
+    });
+  };
+
   /* ---------------- listening ---------------- */
 
   if (!window.EventSource) return say('Live updates need a newer browser', 'off', null, 0);

package/src/collect.mjs

@@ -14,6 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { esc, plain, slugify, parkFences, renderBlocks, takeQuote } from './markdown.mjs';
 import { nestSections, SECNUM_RE } from './sections.mjs';
+import { words, fingerprint } from './reviews.mjs';
 import { titleCase } from './config.mjs';
 
 function orderKey(name) {
@@ -93,7 +94,7 @@ export function buildDoc(entry, byFile, cfg, raw = fs.readFileSync(entry.abs, 'u
   const id = byFile.get(entry.file);
   const seen = new Map();
   const ctx = {
-    blocks: [], headings: [], byFile, numbers: new Map(), outline: [], reviews: cfg.reviews !== false,
+    blocks: [], headings: [], byFile, numbers: new Map(), outline: [], intro: '', reviews: cfg.reviews !== false,
     uniqueSlug(base) {
       const key = base || 'section';
       const n = seen.get(key) || 0;
@@ -102,7 +103,9 @@ export function buildDoc(entry, byFile, cfg, raw = fs.readFileSync(entry.abs, 'u
     },
   };
 
-  let title = name, subtitle = '', html;
+  // own: the document's own words, for reviews - its standfirst and whatever
+  // comes before its first section; a verbatim file is all its own words
+  let title = name, subtitle = '', html, own;
 
   if (cfg.extensions.includes(extOf(entry.file))) {
     const lines = parkFences(raw, ctx);
@@ -124,11 +127,13 @@ export function buildDoc(entry, byFile, cfg, raw = fs.readFileSync(entry.abs, 'u
     }
 
     html = nestSections(renderBlocks(lines, ctx, true), ctx);
+    own = (words(subtitle) + ' ' + ctx.intro).trim();
   } else {
     const kind = extOf(entry.file).slice(1);
     subtitle = '<p>Kept verbatim as <code>' + esc(kind) + '</code>.</p>';
     html = '<div class="code-wrap"><span class="code-lang">' + esc(kind) +
       '</span><pre class="code"><code>' + esc(raw) + '</code></pre></div>';
+    own = raw.replace(/\s+/g, ' ').trim();
   }
 
   const badge = (name.match(/^(\d+)/) || [])[1] || (name.trim()[0] || '?').toUpperCase();
@@ -136,6 +141,7 @@ export function buildDoc(entry, byFile, cfg, raw = fs.readFileSync(entry.abs, 'u
   return {
     id, title, subtitle, html, badge,
     outline: ctx.outline,
+    sig: own || !ctx.outline.length ? fingerprint(own) : null,
     group: entry.group,
     file: entry.rel || entry.file,
     words: raw.split(/\s+/).filter(Boolean).length,

package/src/config.mjs

@@ -15,6 +15,8 @@ import path from 'node:path';
 export const MARGIN_MIN = 20, MARGIN_MAX = 480;
 
 export const CONFIG_NAMES = ['docs.config.json', '.lowkey-doc.json'];
+// where the Reviewed marks are kept, at the project root beside the config
+export const REVIEWS_FILE = 'docs.reviews.json';
 
 export const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 
@@ -139,6 +141,7 @@ export function loadConfig({ root, docs, folder, out, title, configPath, engine
   cfg.docsDir = path.resolve(projectRoot, cfg.docs);
   cfg.outDir = path.resolve(projectRoot, cfg.out);
   cfg.configFile = file;
+  cfg.reviewsFile = cfg.reviews === false ? null : path.join(projectRoot, REVIEWS_FILE);
   if (!cfg.title) cfg.title = titleCase(path.basename(projectRoot)) + ' Docs';
 
   // Namespace for everything the reader's browser remembers. Two dashboards

package/src/page.mjs

@@ -9,7 +9,7 @@ import { MARGIN_MIN, MARGIN_MAX } from './config.mjs';
 const escAttr = (s) => String(s)
   .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 
-export function renderPage({ cfg, docs, fontCss, mermaidTag, elkTag }) {
+export function renderPage({ cfg, docs, reviews = {}, fontCss, mermaidTag, elkTag }) {
   const runtime = {
     title: cfg.title,
     ns: cfg.ns,
@@ -24,7 +24,7 @@ export function renderPage({ cfg, docs, fontCss, mermaidTag, elkTag }) {
   const rootAttrs = cfg.layout.margin == null ? ''
     : ' class="fixed-margin" style="--margin:' + Number(cfg.layout.margin) + 'px"';
 
-  const data = JSON.stringify({ docs }).replace(/</g, '\\u003c');
+  const data = JSON.stringify({ docs, reviews: cfg.reviews === false ? {} : reviews }).replace(/</g, '\\u003c');
 
   // a script from the CDN carries its pinned hash: the browser refuses any other bytes
   const script = (tag) => !tag ? '' : '<script src="' + escAttr(tag.src) + '"' +
@@ -49,8 +49,7 @@ export function renderPage({ cfg, docs, fontCss, mermaidTag, elkTag }) {
 
   const commentBits = cfg.comments === false ? '' : `
 <button class="cmt-add" id="cmt-add" type="button" hidden>Comment</button>
-<div class="cmt-pop" id="cmt-pop" hidden></div>
-<div class="cmt-toast" id="cmt-toast" hidden></div>`;
+<div class="cmt-pop" id="cmt-pop" hidden></div>`;
 
   return `<!doctype html>
 <html lang="en"${rootAttrs}>
@@ -90,7 +89,8 @@ export function renderPage({ cfg, docs, fontCss, mermaidTag, elkTag }) {
     <div id="main"></div>
   </div>
 </div>
-${commentBits}
+${commentBits}${cfg.comments === false && cfg.reviews === false ? '' : `
+<div class="cmt-toast" id="cmt-toast" hidden></div>`}
 <div class="settings-veil" id="settings-veil" hidden></div>
 <div class="settings" id="settings" role="dialog" aria-modal="true" aria-label="Settings" hidden>
   <div class="settings-head">

package/src/reviews.mjs

@@ -0,0 +1,82 @@
+// reviews.mjs
+// ------------------------------------------------------------------
+// The reader's Reviewed marks belong to the project, not to one browser: they
+// are kept in docs.reviews.json beside docs.config.json, committed like any
+// other file, so a team shares one set of marks and git says who changed them.
+// Every build reads the file into the page. Only lowkey-doc --watch writes it:
+// a page opened from its file cannot write anything.
+//
+// A mark carries a fingerprint of the words it was given for. Edit those words
+// and the mark stops matching, so the section reads as open again - and so do
+// the chapter and the document above it - until someone reviews it again.
+// ------------------------------------------------------------------
+
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+
+const SIG_RE = /^[0-9a-f]{12}$/;
+const DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+// The words of some rendered HTML: what a reader agrees with. Markup and the
+// page's own buttons are left out, so a change in how Lowkey Doc draws a page
+// does not reopen every review.
+export const words = (html) => html
+  .replace(/<button\b[\s\S]*?<\/button>/g, ' ')
+  .replace(/<[^>]+>/g, ' ')
+  .replace(/\s+/g, ' ')
+  .trim();
+
+export const fingerprint = (text) => crypto.createHash('sha1').update(text).digest('hex').slice(0, 12);
+
+// Only well-formed marks survive: { "<file>": { "<section id>": { sig, at } } },
+// with "" standing for the document's own words.
+function clean(docs) {
+  const out = {};
+  if (!docs || typeof docs !== 'object' || Array.isArray(docs)) return out;
+  for (const [file, marks] of Object.entries(docs)) {
+    if (!marks || typeof marks !== 'object' || Array.isArray(marks)) continue;
+    const kept = {};
+    for (const [key, m] of Object.entries(marks)) {
+      if (m && SIG_RE.test(m.sig) && DAY_RE.test(m.at)) kept[key] = { sig: m.sig, at: m.at };
+    }
+    if (Object.keys(kept).length) out[file] = kept;
+  }
+  return out;
+}
+
+// The marks in the project, and why they could not be read if they could not.
+export function readReviews(cfg) {
+  if (!cfg.reviewsFile) return { reviews: {}, raw: null, error: null };
+  let raw;
+  try { raw = fs.readFileSync(cfg.reviewsFile, 'utf8'); } catch { return { reviews: {}, raw: null, error: null }; }
+  try {
+    return { reviews: clean(JSON.parse(raw).docs), raw, error: null };
+  } catch (err) {
+    return { reviews: {}, raw, error: cfg.reviewsFile + ' could not be read: ' + err.message };
+  }
+}
+
+// One line per mark, documents in name order: a diff shows exactly which
+// sections were reviewed, and two people reviewing different documents do not
+// touch the same lines.
+export function formatReviews(reviews) {
+  const q = JSON.stringify;
+  const files = Object.keys(reviews).sort((a, b) => a.localeCompare(b));
+  return '{\n  "version": 1,\n  "docs": {' + (files.length ? '\n' + files.map((f) =>
+    '    ' + q(f) + ': {\n' + Object.entries(reviews[f]).map(([key, m]) =>
+      '      ' + q(key) + ': { "sig": ' + q(m.sig) + ', "at": ' + q(m.at) + ' }').join(',\n') +
+    '\n    }').join(',\n') + '\n  ' : '') + '}\n}\n';
+}
+
+// Replace one document's marks and write the file. A file that cannot be read
+// is never written over: it may be one merge away from holding everyone's work.
+export function saveReviews(cfg, file, marks) {
+  const now = readReviews(cfg);
+  if (now.error) throw new Error(now.error + '. Fix it, and nothing in it is lost.');
+  const reviews = { ...now.reviews };
+  const kept = clean({ [file]: marks })[file];
+  if (kept) reviews[file] = kept; else delete reviews[file];
+  const text = formatReviews(reviews);
+  if (text !== now.raw) fs.writeFileSync(cfg.reviewsFile, text);
+  return { reviews, raw: text };
+}

package/src/sections.mjs

@@ -6,6 +6,8 @@
 // a document whose top level is ## still starts at 1.
 // ------------------------------------------------------------------
 
+import { words, fingerprint } from './reviews.mjs';
+
 const FOLD_SVG = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.7" ' +
   'stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3.5 6L8 10.5 12.5 6"/></svg>';
 const CHECK_SVG = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4" ' +
@@ -36,11 +38,16 @@ export function nestSections(blocks, ctx) {
     stack[stack.length - 1].kids.push(node);
     stack.push(node);
   }
-  // the shape of the sections alone, which the page needs for reviews without
-  // having to read it back out of the HTML
-  const outline = (node) => node.kids.filter((k) => typeof k !== 'string')
-    .map((k) => ({ id: k.id, kids: outline(k) }));
+  // The shape of the sections, for reviews, with a fingerprint of the words
+  // each one holds directly under its heading. A chapter with nothing of its
+  // own before its first section has nothing of its own to review (sig null).
+  const own = (node) => words(node.kids.filter((k) => typeof k === 'string').join('\n'));
+  const outline = (node) => node.kids.filter((k) => typeof k !== 'string').map((k) => {
+    const kids = outline(k), text = own(k);
+    return { id: k.id, sig: text || !kids.length ? fingerprint(text) : null, kids };
+  });
   ctx.outline = outline(root);
+  ctx.intro = own(root);
   return emitSections(root, [], ctx);
 }
 

package/src/watch.mjs

@@ -12,6 +12,8 @@
 // Changes are detected by content, not by timestamp, so a sync client or an
 // editor touching a file without changing it costs nothing and shows nothing.
 // Editing docs.config.json reloads the configuration and the page with it.
+// The page's Reviewed marks are saved here, to docs.reviews.json, and reach
+// every open page; an edit to that file from outside (a git pull) does too.
 // ------------------------------------------------------------------
 
 import fs from 'node:fs';
@@ -20,6 +22,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { loadConfig, jsonLike, CONFIG_NAMES, MARGIN_MIN, MARGIN_MAX, VERSION } from './config.mjs';
 import { collectDocs, vendorAssets, pageFor, openInBrowser } from './build.mjs';
+import { readReviews, saveReviews } from './reviews.mjs';
 import { LIVE_CSS, LIVE_JS } from './client/live.mjs';
 
 export const DEFAULT_PORT = 4747;
@@ -45,6 +48,7 @@ export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refr
   let assets = await vendorAssets(cfg, refresh);
   let configRaw = readOr(cfg.configFile);
   let shell = shellOf(cfg, assets);
+  let marks = readReviews(cfg);
 
   const boot = crypto.randomBytes(3).toString('hex');
   let memo = null, docs = [], html = '', seq = 0, error = null;
@@ -79,7 +83,18 @@ export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refr
     const gone = docs.filter((d) => !r.docs.some((n) => n.id === d.id));
     docs = r.docs;
     error = null;
-    html = pageFor(cfg, docs, assets);
+    publish();
+
+    if (seq === 1) return;
+    const what = r.changed.length > 3 ? r.changed.length + ' documents'
+      : r.changed.map((id) => docs.find((d) => d.id === id).file)
+        .concat(gone.map((d) => d.file + ' (removed)')).join(', ') || 'document order';
+    log('updated  ' + what + '  (' + (Date.now() - t0) + ' ms)');
+  }
+
+  // a new version of the page: on disk, and to every open copy
+  function publish() {
+    html = pageFor(cfg, docs, assets, marks.reviews);
     seq++;
     try {
       fs.writeFileSync(path.join(cfg.outDir, 'index.html'), html);
@@ -87,16 +102,19 @@ export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refr
       log('could not write index.html: ' + err.message);
     }
     broadcast();
-
-    if (seq === 1) return;
-    const what = r.changed.length > 3 ? r.changed.length + ' documents'
-      : r.changed.map((id) => docs.find((d) => d.id === id).file)
-        .concat(gone.map((d) => d.file + ' (removed)')).join(', ') || 'document order';
-    log('updated  ' + what + '  (' + (Date.now() - t0) + ' ms)');
   }
 
   const soon = () => { clearTimeout(settle); settle = setTimeout(rebuild, SETTLE_MS); };
 
+  // docs.reviews.json changed from outside: a pull, a merge, a hand edit
+  function rereadReviews() {
+    if (!cfg.reviewsFile || readOr(cfg.reviewsFile) === marks.raw) return;
+    marks = readReviews(cfg);
+    if (marks.error) log('reviews  ' + marks.error);
+    else log('reviews  ' + path.basename(cfg.reviewsFile) + ' reloaded');
+    if (seq) publish();
+  }
+
   async function reconfigure() {
     const raw = readOr(cfg.configFile);
     if (raw === configRaw) return;
@@ -106,6 +124,7 @@ export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refr
       if (next.outDir !== cfg.outDir) assets = await vendorAssets(next);
       cfg = next;
       shell = shellOf(cfg, assets);   // a new shell tells open pages to reload
+      marks = readReviews(cfg);
       memo = null;
       log('config   ' + (cfg.configFile ? path.basename(cfg.configFile) : 'defaults') + ' reloaded');
       arm();
@@ -138,14 +157,17 @@ export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refr
     // new name), and the config file usually lives there too.
     const docsName = path.basename(cfg.docsDir);
     const configName = cfg.configFile && path.basename(cfg.configFile);
+    const reviewsName = cfg.reviewsFile && path.basename(cfg.reviewsFile);
     const parents = new Set([path.dirname(cfg.docsDir)]);
     if (cfg.configFile) parents.add(path.dirname(cfg.configFile));
+    if (cfg.reviewsFile) parents.add(path.dirname(cfg.reviewsFile));
     for (const dir of parents) {
       try {
         const w = fs.watch(dir, (_, name) => {
           name = name && String(name);
           if (dir === path.dirname(cfg.docsDir) && (!name || name === docsName)) soon();
           if (configName && dir === path.dirname(cfg.configFile) && (!name || name === configName)) reconfigure();
+          if (reviewsName && dir === path.dirname(cfg.reviewsFile) && (!name || name === reviewsName)) rereadReviews();
         });
         w.on('error', () => {});
         watchers.push(w);
@@ -183,27 +205,35 @@ export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refr
     return at < 0 ? page + tail : page.slice(0, at) + tail + page.slice(at);
   };
 
-  /* -------------------------------------------------------------- settings */
-
-  // The page's settings panel saves here. They are the project's settings, so
-  // they go into its config file - created next to the documents' project if
-  // there is none - and the page is rendered again with them. The page that
-  // saved already shows them and takes the new shell from the reply; any
-  // other open page reloads to pick them up.
-  function saveSettings(req, res) {
+  // A JSON body POSTed by this page, handed to then(value, json) - or an
+  // answer saying why not. Only this page may change the project, not any
+  // site the browser has open.
+  function posted(req, res, limit, then) {
     const json = (status, body) => reply(res, status, TYPES['.json'], JSON.stringify(body));
     if (req.method !== 'POST') return json(405, { error: 'POST only' });
-    // only this page may change the project, not any site the browser has open
     const origin = req.headers.origin;
     if (origin && origin !== 'http://' + req.headers.host) return json(403, { error: 'Not from this page' });
     if (!/^application\/json\b/.test(req.headers['content-type'] || '')) return json(415, { error: 'JSON only' });
 
     let body = '';
     req.setEncoding('utf8');
-    req.on('data', (chunk) => { body += chunk; if (body.length > 4096) req.destroy(); });
+    req.on('data', (chunk) => { body += chunk; if (body.length > limit) req.destroy(); });
     req.on('end', () => {
-      let next;
-      try { next = JSON.parse(body); } catch { return json(400, { error: 'Not JSON' }); }
+      let value;
+      try { value = JSON.parse(body); } catch { return json(400, { error: 'Not JSON' }); }
+      then(value, json);
+    });
+  }
+
+  /* -------------------------------------------------------------- settings */
+
+  // The page's settings panel saves here. They are the project's settings, so
+  // they go into its config file - created next to the documents' project if
+  // there is none - and the page is rendered again with them. The page that
+  // saved already shows them and takes the new shell from the reply; any
+  // other open page reloads to pick them up.
+  function saveSettings(req, res) {
+    posted(req, res, 4096, (next, json) => {
       const margin = next && next.margin;
       if (margin !== null && !(Number.isFinite(margin) && margin >= MARGIN_MIN && margin <= MARGIN_MAX)) {
         return json(400, { error: 'margin must be null or ' + MARGIN_MIN + '–' + MARGIN_MAX });
@@ -227,7 +257,7 @@ export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refr
       }
 
       shell = shellOf(cfg, assets);
-      html = pageFor(cfg, docs, assets);
+      html = pageFor(cfg, docs, assets, marks.reviews);
       try { fs.writeFileSync(path.join(cfg.outDir, 'index.html'), html); }
       catch (err) { log('could not write index.html: ' + err.message); }
       log('settings saved to ' + path.basename(file) + '  (margin ' + (margin === null ? 'automatic' : Math.round(margin) + ' px') + ')');
@@ -236,6 +266,35 @@ export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refr
     });
   }
 
+  /* --------------------------------------------------------------- reviews */
+
+  // The page sends one document's marks, all of them, each time one changes:
+  // { file, marks: { "<section id>" | "": { sig, at } } }. Only the sections
+  // that document has now are taken, which is also how the marks of a section
+  // that has since been removed leave the file.
+  function saveReview(req, res) {
+    posted(req, res, 1 << 20, (body, json) => {
+      if (!cfg.reviewsFile) return json(404, { error: 'Reviews are turned off for this project' });
+      const doc = body && docs.find((d) => d.file === body.file);
+      if (!doc) return json(400, { error: 'No such document' });
+      const ids = new Set(['']);
+      (function walk(list) { for (const s of list) { ids.add(s.id); walk(s.kids); } })(doc.outline);
+      const given = body.marks && typeof body.marks === 'object' ? body.marks : {};
+      const kept = {};
+      for (const [key, m] of Object.entries(given)) if (ids.has(key)) kept[key] = m;
+
+      try {
+        marks = { ...saveReviews(cfg, doc.file, kept), error: null };
+      } catch (err) {
+        return json(500, { error: err.message });
+      }
+      const n = Object.keys(marks.reviews[doc.file] || {}).length;
+      log('reviews  ' + doc.file + '  (' + n + (n === 1 ? ' mark' : ' marks') + ')');
+      publish();
+      json(200, { version: state().version });
+    });
+  }
+
   const server = http.createServer((req, res) => {
     if (!LOCAL_HOST.test(req.headers.host || '')) return reply(res, 403, 'text/plain; charset=utf-8', 'Forbidden');
     let p;
@@ -252,9 +311,10 @@ export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refr
     }
     if (p === '/__lowkey-doc/data.json') {
       return reply(res, 200, TYPES['.json'],
-        JSON.stringify({ version: state().version, docs }));
+        JSON.stringify({ version: state().version, docs, reviews: marks.reviews }));
     }
     if (p === '/__lowkey-doc/settings') return saveSettings(req, res);
+    if (p === '/__lowkey-doc/reviews') return saveReview(req, res);
     if (p === '/' || p === '/index.html') {
       const page = html || '<!doctype html><meta charset="utf-8"><title>' + escHtml(cfg.title) +
         '</title><body><pre>' + escHtml(error || 'Building…') + '</pre></body>';
@@ -279,6 +339,7 @@ export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refr
     console.log('  ' + docs.length + (docs.length === 1 ? ' document' : ' documents') + ' from ' + cfg.docsDir);
     console.log('  mermaid: ' + assets.mermaid.note + '  ·  elk: ' + assets.elk.note + '  ·  font: ' + assets.font.note);
     console.log('  -> ' + path.join(cfg.outDir, 'index.html'));
+    if (marks.error) console.log('  reviews: not shown - ' + marks.error);
     console.log('\n  live at ' + url + '   (Ctrl+C to stop)\n');
   }
   if (open) openInBrowser(url);