lowkey-doc 1.0.1 → 1.1.1

package/src/client/diagrams.mjs

@@ -800,36 +800,101 @@ export const DIAGRAMS_JS = String.raw`
     return out;
   }
 
-  function shapeEl(x, y, w, h, shape){
+  // the corners of the shapes that are drawn as polygons, null for the rest
+  function polyPoints(x, y, w, h, shape){
     var s;
     switch (shape){
       case 'diamond': case 'question': case 'rhombus':
-        return mk('polygon', { points: (x+w/2)+','+y+' '+(x+w)+','+(y+h/2)+' '+(x+w/2)+','+(y+h)+' '+x+','+(y+h/2) });
-      case 'stadium': case 'pill':
-        return mk('rect', { x:x, y:y, width:w, height:h, rx:h/2, ry:h/2 });
-      case 'circle': case 'doublecircle': case 'state':
-        return mk('ellipse', { cx:x+w/2, cy:y+h/2, rx:w/2, ry:h/2 });
-      case 'cylinder': case 'database':
-        var e = Math.min(11, h/5);
-        return mk('path', { d:'M'+x+','+(y+e)+' A'+(w/2)+','+e+' 0 0 1 '+(x+w)+','+(y+e)+
-          ' L'+(x+w)+','+(y+h-e)+' A'+(w/2)+','+e+' 0 0 1 '+x+','+(y+h-e)+' Z'+
-          ' M'+x+','+(y+e)+' A'+(w/2)+','+e+' 0 0 0 '+(x+w)+','+(y+e) });
+        return [[x+w/2,y], [x+w,y+h/2], [x+w/2,y+h], [x,y+h/2]];
       case 'hexagon':
         s = Math.min(18, w/5);
-        return mk('polygon', { points:(x+s)+','+y+' '+(x+w-s)+','+y+' '+(x+w)+','+(y+h/2)+' '+
-          (x+w-s)+','+(y+h)+' '+(x+s)+','+(y+h)+' '+x+','+(y+h/2) });
+        return [[x+s,y], [x+w-s,y], [x+w,y+h/2], [x+w-s,y+h], [x+s,y+h], [x,y+h/2]];
       case 'lean_right': case 'lean_r':
         s = Math.min(22, w/6);
-        return mk('polygon', { points:(x+s)+','+y+' '+(x+w)+','+y+' '+(x+w-s)+','+(y+h)+' '+x+','+(y+h) });
+        return [[x+s,y], [x+w,y], [x+w-s,y+h], [x,y+h]];
       case 'lean_left': case 'lean_l':
         s = Math.min(22, w/6);
-        return mk('polygon', { points:x+','+y+' '+(x+w-s)+','+y+' '+(x+w)+','+(y+h)+' '+(x+s)+','+(y+h) });
+        return [[x,y], [x+w-s,y], [x+w,y+h], [x+s,y+h]];
       case 'trapezoid':
         s = Math.min(22, w/6);
-        return mk('polygon', { points:(x+s)+','+y+' '+(x+w-s)+','+y+' '+(x+w)+','+(y+h)+' '+x+','+(y+h) });
+        return [[x+s,y], [x+w-s,y], [x+w,y+h], [x,y+h]];
       case 'inv_trapezoid':
         s = Math.min(22, w/6);
-        return mk('polygon', { points:x+','+y+' '+(x+w)+','+y+' '+(x+w-s)+','+(y+h)+' '+(x+s)+','+(y+h) });
+        return [[x,y], [x+w,y], [x+w-s,y+h], [x+s,y+h]];
+    }
+    return null;
+  }
+
+  // The outline shapeEl draws, as a closed ring of points, its curves walked
+  // in short steps.
+  function outline(x, y, w, h, shape){
+    var poly = polyPoints(x, y, w, h, shape);
+    if (poly) return poly.map(function(p){ return { x:p[0], y:p[1] }; });
+    var ring = [];
+    var arc = function(cx, cy, rx, ry, a0, a1){
+      var n = Math.max(2, Math.ceil(Math.abs(a1 - a0) / (Math.PI/24)));
+      for (var i=0;i<=n;i++){
+        var t = a0 + (a1 - a0) * i/n;
+        ring.push({ x: cx + rx*Math.cos(t), y: cy + ry*Math.sin(t) });
+      }
+    };
+    var rounded = function(r){
+      r = Math.min(r, w/2, h/2);
+      arc(x+w-r, y+r, r, r, -Math.PI/2, 0);
+      arc(x+w-r, y+h-r, r, r, 0, Math.PI/2);
+      arc(x+r, y+h-r, r, r, Math.PI/2, Math.PI);
+      arc(x+r, y+r, r, r, Math.PI, Math.PI*1.5);
+    };
+    switch (shape){
+      case 'stadium': case 'pill': rounded(h/2); break;
+      case 'circle': case 'doublecircle': case 'state': arc(x+w/2, y+h/2, w/2, h/2, 0, Math.PI*2); break;
+      case 'cylinder': case 'database':
+        var e = Math.min(11, h/5);
+        arc(x+w/2, y+e, w/2, e, Math.PI, Math.PI*2);
+        arc(x+w/2, y+h-e, w/2, e, 0, Math.PI);
+        break;
+      case 'squareRect': case 'rect': case 'square': rounded(3); break;
+      default: rounded(8);
+    }
+    return ring;
+  }
+
+  // ELK knows a node only as its box, and ends every edge on the box. A shape
+  // that does not fill its box - a diamond most of all - would leave arrows
+  // stopping short in the air beside it, so each end is carried on, straight
+  // in across the side of the box it arrived at, until it meets the outline.
+  // The route is orthogonal, so that is the direction its last run already had.
+  function onOutline(p, a){
+    var ring = outline(a.x, a.y, a.w, a.h, a.n.shape);
+    var gap = [Math.abs(p.y - a.y), Math.abs(a.y + a.h - p.y), Math.abs(p.x - a.x), Math.abs(a.x + a.w - p.x)];
+    var side = gap.indexOf(Math.min.apply(null, gap));
+    var ux = [0, 0, 1, -1][side], uy = [1, -1, 0, 0][side];
+    // from just outside the box, the first crossing of the outline
+    var ox = p.x - ux*2, oy = p.y - uy*2, best = Infinity;
+    for (var i=0;i<ring.length;i++){
+      var q = ring[i], r = ring[(i+1) % ring.length];
+      var ex = r.x - q.x, ey = r.y - q.y, den = ux*ey - uy*ex;
+      if (Math.abs(den) < 1e-9) continue;
+      var qx = q.x - ox, qy = q.y - oy;
+      var t = (qx*ey - qy*ex) / den, s = (qx*uy - qy*ux) / den;
+      if (s >= -1e-6 && s <= 1 + 1e-6 && t >= 0 && t < best) best = t;
+    }
+    return best < Infinity ? { x: ox + ux*best, y: oy + uy*best } : p;
+  }
+
+  function shapeEl(x, y, w, h, shape){
+    var poly = polyPoints(x, y, w, h, shape);
+    if (poly) return mk('polygon', { points: poly.map(function(p){ return p[0]+','+p[1]; }).join(' ') });
+    switch (shape){
+      case 'stadium': case 'pill':
+        return mk('rect', { x:x, y:y, width:w, height:h, rx:h/2, ry:h/2 });
+      case 'circle': case 'doublecircle': case 'state':
+        return mk('ellipse', { cx:x+w/2, cy:y+h/2, rx:w/2, ry:h/2 });
+      case 'cylinder': case 'database':
+        var e = Math.min(11, h/5);
+        return mk('path', { d:'M'+x+','+(y+e)+' A'+(w/2)+','+e+' 0 0 1 '+(x+w)+','+(y+e)+
+          ' L'+(x+w)+','+(y+h-e)+' A'+(w/2)+','+e+' 0 0 1 '+x+','+(y+h-e)+' Z'+
+          ' M'+x+','+(y+e)+' A'+(w/2)+','+e+' 0 0 0 '+(x+w)+','+(y+e) });
       case 'squareRect': case 'rect': case 'square':
         return mk('rect', { x:x, y:y, width:w, height:h, rx:3, ry:3 });
       default:
@@ -1020,22 +1085,46 @@ export const DIAGRAMS_JS = String.raw`
 
   // Right-angle bends look mechanical when they are exactly square; a small
   // radius reads as a route rather than as a staircase.
+  var BEND_R = 7;
+
+  // where the curve that rounds the bend at b starts and ends, or null if
+  // there is no room for one
+  function bendAt(a, b, c, r){
+    var l1=Math.hypot(b.x-a.x,b.y-a.y), l2=Math.hypot(c.x-b.x,c.y-b.y);
+    if (!l1 || !l2) return null;
+    var rr = Math.min(r, l1/2, l2/2);
+    return { from: { x: b.x+(a.x-b.x)/l1*rr, y: b.y+(a.y-b.y)/l1*rr },
+             to:   { x: b.x+(c.x-b.x)/l2*rr, y: b.y+(c.y-b.y)/l2*rr } };
+  }
+
   function roundedPath(pts, r){
     if (pts.length < 2) return '';
-    if (pts.length === 2) return 'M'+pts[0].x+','+pts[0].y+' L'+pts[1].x+','+pts[1].y;
     var d = 'M'+pts[0].x+','+pts[0].y;
     for (var i=1;i<pts.length-1;i++){
-      var a=pts[i-1], b=pts[i], c=pts[i+1];
-      var l1=Math.hypot(b.x-a.x,b.y-a.y), l2=Math.hypot(c.x-b.x,c.y-b.y);
-      if (!l1 || !l2){ d += ' L'+b.x+','+b.y; continue; }
-      var rr = Math.min(r, l1/2, l2/2);
-      d += ' L'+(b.x+(a.x-b.x)/l1*rr)+','+(b.y+(a.y-b.y)/l1*rr) +
-           ' Q'+b.x+','+b.y+' '+(b.x+(c.x-b.x)/l2*rr)+','+(b.y+(c.y-b.y)/l2*rr);
+      var b = pts[i], k = bendAt(pts[i-1], b, pts[i+1], r);
+      d += k ? ' L'+k.from.x+','+k.from.y+' Q'+b.x+','+b.y+' '+k.to.x+','+k.to.y : ' L'+b.x+','+b.y;
     }
     var e = pts[pts.length-1];
     return d + ' L'+e.x+','+e.y;
   }
 
+  // The route as roundedPath draws it, its curves walked in short steps. A
+  // point found on this is on the line the reader sees; one found on the
+  // square corner it rounds off sits beside the line, in the air.
+  function roundedPts(pts, r){
+    var out = [pts[0]];
+    for (var i=1;i<pts.length-1;i++){
+      var b = pts[i], k = bendAt(pts[i-1], b, pts[i+1], r);
+      if (!k){ out.push(b); continue; }
+      for (var j=0;j<=8;j++){
+        var t = j/8, u = 1-t;
+        out.push({ x: u*u*k.from.x + 2*u*t*b.x + t*t*k.to.x, y: u*u*k.from.y + 2*u*t*b.y + t*t*k.to.y });
+      }
+    }
+    out.push(pts[pts.length-1]);
+    return out;
+  }
+
   function nearestOnPath(pts, px, py){
     var best = null, bd = Infinity;
     for (var i=0;i<pts.length-1;i++){
@@ -1187,9 +1276,15 @@ export const DIAGRAMS_JS = String.raw`
         runs.push([sec.startPoint].concat(sec.bendPoints || [], [sec.endPoint]).map(shift));
       });
       if (!runs.length) return;
+      // both ends on the shape itself, not on the box ELK knows it by
+      if (!isEr){
+        var first = runs[0], last = runs[runs.length-1];
+        if (abs[src] && !abs[src].n.isGroup) first[0] = onOutline(first[0], abs[src]);
+        if (abs[dst] && !abs[dst].n.isGroup) last[last.length-1] = onOutline(last[last.length-1], abs[dst]);
+      }
 
       runs.forEach(function(pts, i){
-        var d = roundedPath(pts, 7);
+        var d = roundedPath(pts, BEND_R);
         g.appendChild(mk('path', { d:d, fill:'none' }, 'dg-edge-hit'));
         var line = mk('path', { d:d, fill:'none' }, 'dg-edge-line');
         if (info.pattern === 'dashed') line.style.strokeDasharray = '7 4';
@@ -1232,7 +1327,7 @@ export const DIAGRAMS_JS = String.raw`
         var cx = lb.x + o.x + lb.width/2, cy = lb.y + o.y + lb.height/2;
         var pw = info._lw || lb.width, ph = info._lh || lb.height;
         var lx = cx - pw/2, ly = cy - ph/2;
-        var anchor = pts.length > 1 ? nearestOnPath(pts, cx, cy) : null;
+        var anchor = pts.length > 1 ? nearestOnPath(roundedPts(pts, BEND_R), cx, cy) : null;
         if (anchor){
           var dx = anchor.x - cx, dy = anchor.y - cy;
           var hw = pw/2 + 3, hh = ph/2 + 3, ax = cx, ay = cy;

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

@@ -12,8 +12,9 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { esc, plain, slugify, inline, parkFences, renderBlocks } from './markdown.mjs';
+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(),
+    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);
@@ -114,31 +117,31 @@ export function buildDoc(entry, byFile, cfg, raw = fs.readFileSync(entry.abs, 'u
       lines.splice(h1, 1);
     }
 
-    // the lede paragraph of the blockquote under it becomes the subtitle
+    // the blockquote under it - all of it, every paragraph - becomes the subtitle
     let j = 0;
     while (j < lines.length && !lines[j].trim()) j++;
     if (j < lines.length && /^ {0,3}>/.test(lines[j])) {
-      const lede = [];
-      while (j < lines.length && /^ {0,3}>/.test(lines[j]) && lines[j].replace(/^ {0,3}> ?/, '').trim()) {
-        lede.push(lines[j].replace(/^ {0,3}> ?/, '').trim());
-        j++;
-      }
-      subtitle = inline(lede.join(' '), ctx);
-      lines.splice(0, j);
+      const lede = takeQuote(lines, j);
+      subtitle = renderBlocks(lede.buf, ctx);
+      lines.splice(0, lede.end);
     }
 
     html = nestSections(renderBlocks(lines, ctx, true), ctx);
+    own = (words(subtitle) + ' ' + ctx.intro).trim();
   } else {
     const kind = extOf(entry.file).slice(1);
-    subtitle = 'Kept verbatim as <code>' + esc(kind) + '</code>.';
+    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();
 
   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;
 
@@ -24,7 +26,7 @@ export const CLI = process.env.npm_command === 'exec' ? 'npx lowkey-doc' : 'lowk
 
 const DEFAULTS = {
   // Shown in the sidebar, the browser tab, and used to namespace the
-  // per-reader state (which document was open, folded sections, comments).
+  // per-reader state (which document was open, folded sections, comments, reviews).
   title: null,                       // null -> derived from the project folder
   // Where the documents are, relative to the project root.
   docs: 'docs',
@@ -68,6 +70,7 @@ const DEFAULTS = {
   },
   // Reader features. Turn off what a given project does not want.
   comments: true,
+  reviews: true,
   search: true,
 };
 
@@ -138,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/markdown.mjs

@@ -303,8 +303,9 @@ export function inline(src, ctx) {
   s = s.replace(/~~([\s\S]+?)~~/g, '<del>$1</del>');
   s = s.replace(/\*\*([\s\S]+?)\*\*/g, '<strong>$1</strong>');
   s = s.replace(/(^|[^\w])__(\S[\s\S]*?\S|\S)__(?!\w)/g, '$1<strong>$2</strong>');
-  s = s.replace(/(^|[^*])\*(?!\s)([^*\n]+?)(?<!\s)\*(?!\*)/g, '$1<em>$2</em>');
-  s = s.replace(/(^|[^\w\\])_(?!\s)([^_\n]+?)(?<!\s)_(?!\w)/g, '$1<em>$2</em>');
+  // like strong, emphasis may run across a line break, never across a blank line
+  s = s.replace(/(^|[^*])\*(?!\s)((?:[^*\n]|\n(?!\n))+?)(?<!\s)\*(?!\*)/g, '$1<em>$2</em>');
+  s = s.replace(/(^|[^\w\\])_(?!\s)((?:[^_\n]|\n(?!\n))+?)(?<!\s)_(?!\w)/g, '$1<em>$2</em>');
 
   // 6. bare urls left in plain text
   s = s.replace(/(^|[\s(])(https?:\/\/[^\s<)]+[^\s<).,;:])/g,
@@ -359,6 +360,23 @@ const isDelim = (line) => {
 };
 const listMark = (line) => line.match(/^(\s*)([-*+]|\d+[.)])\s+(.*)$/);
 const indentOf = (line) => (line.match(/^\s*/) || [''])[0].length;
+const isRule = (line) => /^ {0,3}([-*_])(\s*\1){2,}\s*$/.test(line);
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+
+// The blockquote that starts at lines[i]: its lines without their markers, and
+// the index just past it. A line with no marker still belongs to it when it
+// carries on the quote's last paragraph, unless it starts a block of its own.
+export function takeQuote(lines, i) {
+  const buf = [];
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^ {0,3}>/.test(line)) buf.push(line.replace(/^ {0,3}> ?/, ''));
+    else if (buf.length && buf[buf.length - 1].trim() && line.trim() &&
+             !listMark(line) && !isRule(line) && !HEADING_RE.test(line) && !BLOCK_RE.test(line)) buf.push(line);
+    else break;
+  }
+  return { buf, end: i };
+}
 
 export function renderBlocks(lines, ctx, asArray) {
   const out = [];
@@ -380,7 +398,7 @@ export function renderBlocks(lines, ctx, asArray) {
     const park = line.match(BLOCK_RE);
     if (park) { flush(); out.push(ctx.blocks[+park[1]]); i++; continue; }
 
-    const head = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+    const head = line.match(HEADING_RE);
     if (head) {
       flush();
       const level = head[1].length;
@@ -393,16 +411,13 @@ export function renderBlocks(lines, ctx, asArray) {
       i++; continue;
     }
 
-    if (/^ {0,3}([-*_])(\s*\1){2,}\s*$/.test(line)) { flush(); out.push('<hr>'); i++; continue; }
+    if (isRule(line)) { flush(); out.push('<hr>'); i++; continue; }
 
     if (/^ {0,3}>/.test(line)) {
       flush();
-      const buf = [];
-      while (i < lines.length && (/^ {0,3}>/.test(lines[i]) || (buf.length && lines[i].trim() && !listMark(lines[i])))) {
-        buf.push(lines[i].replace(/^ {0,3}> ?/, ''));
-        i++;
-      }
-      out.push('<blockquote>' + renderBlocks(buf, ctx) + '</blockquote>');
+      const quote = takeQuote(lines, i);
+      out.push('<blockquote>' + renderBlocks(quote.buf, ctx) + '</blockquote>');
+      i = quote.end;
       continue;
     }
 

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,
@@ -17,13 +17,14 @@ export function renderPage({ cfg, docs, fontCss, mermaidTag, elkTag }) {
     nodeTextWidth: cfg.diagrams.nodeTextWidth,
     edgeTextWidth: cfg.diagrams.edgeTextWidth,
     comments: cfg.comments !== false,
+    reviews: cfg.reviews !== false,
     margin: cfg.layout.margin,
   };
   // fixed margins are set on the root, so the page is laid out right from its first paint
   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) + '"' +
@@ -48,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}>
@@ -89,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,8 +6,16 @@
 // 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" ' +
+  'stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="8" cy="8" r="6.3"/>' +
+  '<path d="M5.3 8.2l1.9 1.9 3.6-3.9"/></svg>';
+// The word on the button is drawn by CSS, so it is never part of the heading's
+// text: not copied with it, not matched by search, not quoted by a comment.
+const REVIEW_BTN = '<button class="rv" type="button" aria-pressed="false" aria-label="Reviewed">' + CHECK_SVG + '</button>';
 
 const HEAD_RE = /^<h([1-6]) id="([^"]+)">([\s\S]*)<\/h[1-6]>$/;
 const ANCHOR_RE = /^<a class="h-anchor"[^>]*>#<\/a>/;
@@ -30,6 +38,16 @@ export function nestSections(blocks, ctx) {
     stack[stack.length - 1].kids.push(node);
     stack.push(node);
   }
+  // 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);
 }
 
@@ -55,7 +73,7 @@ function emitSections(node, prefix, ctx) {
         '<button class="sec-tog" type="button" tabindex="-1" aria-label="Fold section">' + FOLD_SVG + '</button>' +
         '<span class="sec-num">' + label + '</span>' +
       '</span>' +
-      '<span class="sec-txt">' + text + '</span>' + anchor +
+      '<span class="sec-txt">' + text + '</span>' + anchor + (ctx.reviews ? REVIEW_BTN : '') +
       '</h' + kid.level + '>';
     return '<section class="sec" data-sec="' + kid.id + '">' + head +
       '<div class="sec-body">' + emitSections(kid, num, ctx) + '</div></section>';