lowkey-doc 1.1.0 → 1.1.2

package/bin/lowkey-doc.mjs

@@ -24,6 +24,7 @@ import { loadConfig, CLI, VERSION } from '../src/config.mjs';
 import { build } from '../src/build.mjs';
 import { init } from '../src/init.mjs';
 import { watch, DEFAULT_PORT } from '../src/watch.mjs';
+import { checkForUpdate } from '../src/update.mjs';
 
 // Every option each mode accepts, and whether it takes a value. Anything else
 // is an error: a typo that silently does something else is worse than a stop.
@@ -59,6 +60,10 @@ init
   --title <name>     the dashboard title
   --force            replace the Claude command and skills with this version's.
                      An existing config is never replaced: --docs and --title edit it.
+
+Update check
+  A maximum of one time each day, lowkey-doc asks npm for the latest version.
+  To stop the update check, set NO_UPDATE_NOTIFIER=1.
 `;
 
 const usage = (msg) => { throw new Error(msg + '\nSee: ' + CLI + ' --help'); };
@@ -120,6 +125,14 @@ async function main() {
   if (opts['-h'] || opts['--help']) { console.log(HELP); return; }
   if (opts['-v'] || opts['--version']) { console.log(VERSION); return; }
 
+  // asked while the command runs, told once it is done
+  const update = checkForUpdate();
+  await run(mode, folder, opts);
+  const notice = await update();
+  if (notice) console.error(notice);
+}
+
+async function run(mode, folder, opts) {
   if (mode === 'init') {
     const r = init(folder, { docs: opts['--docs'], title: opts['--title'], force: !!opts['--force'] });
     console.log('lowkey-doc init  ' + r.root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lowkey-doc",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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

@@ -96,6 +96,7 @@ export const APP_JS = String.raw`
       current = id;
       keep('last', id);
 
+      light(null);    // a document is kept once built: left lit, it would light again on its return
       main.textContent = '';
       main.appendChild(bodyFor(d));
 
@@ -208,67 +209,132 @@ export const APP_JS = String.raw`
     revealed = id;
     unfoldTo(t);
     t.scrollIntoView(smooth ? { behavior: 'smooth' } : undefined);
+    var head = t.closest('.sec-head');    // the heading, or an <a id> the author put in it
+    if (head) light(head.parentNode);
     requestAnimationFrame(sync);   // at the foot of the page nothing scrolls, so no scroll event would
     return true;
   }
 
+  // The section a link led to lights up (.is-lit) and fades. The ring is drawn
+  // round everything in it that is on view, inside the reading area.
+  var lit = null;
+  function light(sec){
+    if (lit) lit.classList.remove('is-lit');
+    lit = sec;
+    if (!sec) return;
+    var box = sec.getBoundingClientRect(), area = main.getBoundingClientRect();
+    var l = box.left, r = box.right;
+    sec.querySelectorAll('.sec-gut,.diagram,.table-wrap').forEach(function(n){
+      if (!n.offsetParent) return;                    // inside a folded section
+      var b = n.getBoundingClientRect();
+      l = Math.min(l, b.left); r = Math.max(r, b.right);
+    });
+    sec.style.setProperty('--lit-l', Math.round(box.left - Math.max(area.left + 4, l - 16)) + 'px');
+    sec.style.setProperty('--lit-r', Math.round(Math.min(area.right - 4, r + 16) - box.right) + 'px');
+    void sec.offsetWidth;                             // lit again: the fade starts over
+    sec.classList.add('is-lit');
+  }
+  main.addEventListener('animationend', function(e){
+    if (e.animationName === 'sec-lit') e.target.classList.remove('is-lit');
+  });
+
   /* ---------------- 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 +352,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 ---------------- */
@@ -391,7 +476,11 @@ export const APP_JS = String.raw`
     var a = e.target.closest('a[href^="#"]');
     if (a){
       var href = a.getAttribute('href');
-      if (href.indexOf('#/') === 0) return;
+      if (href.indexOf('#/') === 0){
+        // a link to where the page already is changes no hash, so would do nothing
+        if (a.hash === location.hash){ e.preventDefault(); route(); }
+        return;
+      }
       e.preventDefault();
       if (reveal(href.slice(1), true)) history.replaceState(null, '', '#/' + current + '/' + href.slice(1));
       return;
@@ -408,11 +497,19 @@ export const APP_JS = String.raw`
     fold(sec, !sec.classList.contains('shut'), true);
   });
 
-  document.getElementById('toggle').addEventListener('click', function(){
-    var on = layout.classList.toggle('collapsed');
+  var sideBtn = document.getElementById('toggle');
+  function setSide(on){
+    layout.classList.toggle('collapsed', on);
+    sideBtn.title = (on ? 'Show' : 'Hide') + ' sidebar  [';
+  }
+  function toggleSide(){
+    layout.classList.add('anim');    // slid when the reader asks, never on load
+    var on = !layout.classList.contains('collapsed');
+    setSide(on);
     keep('collapsed', on ? '1' : '');
     schedulePlace();
-  });
+  }
+  sideBtn.addEventListener('click', toggleSide);
 
   if (search) search.addEventListener('input', function(){
     var q = search.value.trim().toLowerCase();
@@ -448,7 +545,7 @@ export const APP_JS = String.raw`
     }
     if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') return;
     if (e.key === '/' && search){ e.preventDefault(); search.focus(); }
-    if (e.key === '[') document.getElementById('toggle').click();
+    if (e.key === '[') toggleSide();
   });
 
   function sync(){
@@ -765,7 +862,7 @@ export const APP_JS = String.raw`
     if (!m) return;
     unfoldTo(m);
     var r = m.getBoundingClientRect();
-    if (r.top < 70 || r.bottom > innerHeight - 20) m.scrollIntoView({ block: 'center' });
+    if (r.top < 84 || r.bottom > innerHeight - 20) m.scrollIntoView({ block: 'center' });
   }
 
   // a highlight and its card are one comment seen twice: hovering either lights
@@ -954,11 +1051,13 @@ export const APP_JS = String.raw`
 
   var BLOCKS = 'p,li,h1,h2,h3,h4,h5,h6,pre,table,blockquote,figure,img,hr';
   var MARK_SHARE = .5;       // past half the page changed, marking all of it says nothing
-  var TOP_EDGE = 64;         // below the sticky top bar
+  var TOP_EDGE = 78;         // 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 +1092,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,12 +1379,13 @@ 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]; }
   };
 
-  if (recall('collapsed')) layout.classList.add('collapsed');
+  if (recall('collapsed')) setSide(true);
   buildNav();
   route();
 })();

package/src/client/css.mjs

@@ -25,7 +25,8 @@ html{-webkit-text-size-adjust:100%}
      inside the sentence, not as a heavier typeface dropped into it. */
   --semi:560; --bold:620;
   --scroll:rgba(255,255,255,.12); --scroll-on:rgba(255,255,255,.22);
-  --rail:270px;
+  /* --side is the sidebar's own width, --rail the room the page gives it */
+  --side:270px; --rail:var(--side);
   /* content column: --measure is the text width, --gutter the breathing room
      either side of it. The column is centred in the main area. */
   --measure:92ch; --gutter:46px;
@@ -78,7 +79,12 @@ body::before{content:"";position:fixed;inset:0;z-index:-1;pointer-events:none;
     radial-gradient(circle,rgba(77,163,255,.16) 0 .6px,transparent 1.1px) 137px 71px/311px 283px}
 a{color:inherit;text-decoration:none}
 .layout{display:grid;grid-template-columns:var(--rail) 1fr;min-height:100vh}
-.layout.collapsed{--rail:62px}
+.layout.collapsed{--rail:0px}
+/* Hiding the sidebar slides it out whole: its column closes while the
+   sidebar moves left by as much, so nothing in it squeezes on the way out.
+   Only a toggle the reader makes is animated (.anim), never the state a page
+   opens in. */
+.layout.anim{transition:grid-template-columns .28s ease}
 
 /* ---- scrollbars ----
    Chrome and Safari take the ::-webkit rules. Firefox only understands the two
@@ -94,14 +100,16 @@ a{color:inherit;text-decoration:none}
 @supports (-moz-appearance:none){*{scrollbar-width:thin;scrollbar-color:var(--scroll) transparent}}
 
 /* ---- sidebar ---- */
-.side{position:sticky;top:0;height:100vh;display:flex;flex-direction:column;
+.side{position:sticky;top:0;width:var(--side);height:100vh;display:flex;flex-direction:column;
   border-right:1px solid var(--line);overflow:hidden}
+.collapsed .side{transform:translateX(-100%);visibility:hidden}
+.anim .side{transition:transform .28s ease,visibility 0s}
+.anim.collapsed .side{transition:transform .28s ease,visibility 0s .28s}
 .side-top{padding:16px 14px 12px}
 .brand{min-width:0}
-/* the toggle shares a row with the title, so its 28px box - and the background
-   that appears under it on hover - is centred on the title's own line rather
-   than on the title-plus-subtitle block */
-.brand-row{display:flex;align-items:center;gap:8px;min-width:0}
+/* the toggle sits at the end of the title's row (it lives outside the sidebar,
+   see .side-btn), so the row keeps its 28px and the gap before it free */
+.brand-row{display:flex;align-items:center;min-width:0;padding-right:36px}
 .brand-name{flex:1;min-width:0;height:28px;line-height:28px;font-size:14px;font-weight:var(--bold);
   letter-spacing:-.012em;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .brand-name::before{content:"";display:inline-block;width:8px;height:8px;margin:0 9px 1px 2px;
@@ -111,6 +119,34 @@ a{color:inherit;text-decoration:none}
   transition:background .15s,color .15s,border-color .15s}
 .icon-btn:hover{background:var(--hover);color:var(--ink);border-color:var(--line)}
 .icon-btn svg{width:15px;height:15px}
+/* One button hides the sidebar and brings it back. It can't live in the
+   sidebar - the sidebar's slide would carry it off - so it is fixed over it,
+   on the title's row (.side-top's 16px down, 14px in from the edge). As the
+   sidebar slides out the button rides along until it reaches the corner,
+   12px in, and stops there; the sidebar coming back picks it up on its way.
+   That is the sidebar's own ease over 270px, cut off where the button's 215
+   run out (--ride-out), or starting only once the sidebar reaches it
+   (--ride-in) - both worked out for a --side of 270px.
+   Away, it gets a ring of its own, which comes in as it stops. */
+.side-btn{position:fixed;top:16px;left:12px;z-index:8;isolation:isolate;
+  transform:translateX(calc(var(--side) - 55px));
+  --ride-out:linear(0,.041 4.9%,.117 9.9%,.228 14.8%,.364 19.8%,.505 24.7%,.636 29.6%,.751 34.6%,.848 39.5%,.931 44.5%,1 49.4%,1);
+  --ride-in:linear(0,0 15.9%,.238 24.3%,.453 32.7%,.621 41.1%,.746 49.5%,.838 58%,.904 66.4%,.949 74.8%,.979 83.2%,.995 91.6%,1)}
+.side-btn::before{content:"";position:absolute;inset:-1px;z-index:-1;border:1px solid var(--line-2);
+  border-radius:inherit;background:var(--surface);box-shadow:0 6px 18px -8px rgba(0,0,0,.8);
+  opacity:0;transition:background .15s}
+.collapsed .side-btn{transform:none}
+.collapsed .side-btn::before{opacity:1}
+.collapsed .side-btn:hover::before{background:var(--surface-2)}
+.anim .side-btn{transition:transform .28s var(--ride-in),background .15s,color .15s,border-color .15s}
+.anim.collapsed .side-btn{transition:transform .28s var(--ride-out),background .15s,color .15s,border-color .15s}
+.anim .side-btn::before{transition:opacity .1s,background .15s}
+.anim.collapsed .side-btn::before{transition:opacity .14s ease .1s,background .15s}
+/* ...and the page keeps clear of it: the top bar's title, and the title card
+   when the column comes close enough to the corner (a step: 28px, or 59px) */
+.collapsed .topbar-in{padding-left:max(var(--gutter),calc(52px - max(0px,(100vw - var(--column)) / 2)))}
+.collapsed .head{margin-top:clamp(28px,calc((52px - (100vw - var(--column)) / 2) * 100),59px)}
+.anim .head{transition:margin-top .28s ease}
 .search{margin:8px 14px 6px;position:relative}
 .search input{width:100%;padding:7px 12px 7px 31px;border:1px solid var(--line);border-radius:999px;
   background:var(--surface);color:var(--ink);font:inherit;font-size:13px;outline:none;
@@ -161,18 +197,6 @@ a{color:inherit;text-decoration:none}
 .is-reviewed>.rv-mark{display:block}
 .sub .rv-mark{align-self:center;width:12px;height:12px}
 
-.collapsed .brand-name,.collapsed .search,.collapsed .nav-group,
-.collapsed .item-title,.collapsed .caret,.collapsed .foot-lbl,.collapsed .rv-mark{display:none}
-.collapsed .subs,.collapsed .item.open+.subs{display:none}
-.collapsed .side-top{padding:16px 0 12px}
-.collapsed .brand-row{justify-content:center}
-.collapsed .nav{padding:2px 8px;scrollbar-width:none}
-.collapsed .nav::-webkit-scrollbar{display:none}
-.collapsed .item{justify-content:center;padding:8px 0;margin-bottom:2px}
-.collapsed .num{min-width:0;font-size:12px}
-.collapsed .side-foot{padding:10px 8px}
-.collapsed .foot-btn{justify-content:center;padding:7px 0}
-
 /* the foot of the sidebar: the settings, an icon with its name beside it */
 .side-foot{display:flex;padding:10px 12px;border-top:1px solid var(--line)}
 .foot-btn{flex:1;display:flex;align-items:center;gap:9px;padding:7px 12px;border:1px solid transparent;
@@ -281,7 +305,7 @@ export const CSS_MAIN = `
    Every heading owns the blocks under it, so a section can be folded away and
    the space between two of them can be set as one rule instead of guessed at
    from heading margins. */
-.doc [id]{scroll-margin-top:88px}
+.doc [id]{scroll-margin-top:102px}
 .sec{margin-top:30px}
 .doc>.sec{margin-top:54px;padding-top:32px;border-top:1px solid var(--line)}
 .doc>.sec:first-child{margin-top:2px;padding-top:0;border-top:0}
@@ -291,7 +315,7 @@ export const CSS_MAIN = `
 .sec.shut>.sec-body{display:none}
 
 .sec-head{position:relative;display:flex;align-items:baseline;gap:11px;cursor:pointer;
-  line-height:1.32;letter-spacing:-.018em;scroll-margin-top:98px}
+  line-height:1.32;letter-spacing:-.018em;scroll-margin-top:112px}
 h1.sec-head{margin:0 0 15px;font-size:22px;font-weight:var(--bold)}
 h2.sec-head{margin:0 0 13px;font-size:18.5px;font-weight:var(--bold)}
 h3.sec-head{margin:0 0 10px;font-size:15.5px;font-weight:var(--semi)}
@@ -320,6 +344,22 @@ h4.sec-head,h5.sec-head,h6.sec-head{margin:0 0 8px;font-size:14px;font-weight:va
   opacity:0;transition:opacity .15s,color .15s}
 .sec-head:hover .h-anchor{opacity:1}
 .h-anchor:hover{color:var(--ink)}
+/* The section a link led to: a ring lights up round it and fades away, so
+   which part of the page the link meant is never a guess. It stands off the
+   text on every side - on the left past the numbers hanging in the margin, on
+   the right past a diagram spilling out of the column - by --lit-l and
+   --lit-r, measured when it is lit. It sits behind the section, so the text,
+   and every box with a face of its own, stays on top of it. */
+.sec.is-lit{position:relative;isolation:isolate}
+.sec.is-lit::after{content:"";position:absolute;z-index:-1;pointer-events:none;
+  top:-14px;bottom:-14px;left:calc(0px - var(--lit-l,16px));right:calc(0px - var(--lit-r,16px));
+  border:1px solid var(--accent-ring);border-radius:16px;
+  background:linear-gradient(var(--accent-soft),rgba(77,163,255,.025) 260px);
+  box-shadow:0 0 24px -6px var(--accent-ring);
+  animation:sec-lit 2.4s ease-in-out both}
+/* a chapter's box starts at the rule above it; the ring starts at its heading */
+.doc>.sec.is-lit:not(:first-child)::after{top:18px}
+@keyframes sec-lit{0%{opacity:0}16%,48%{opacity:1}100%{opacity:0}}
 
 /* ---- reviews ----
    Every section, and the document in its header card, has a Reviewed button:
@@ -518,7 +558,6 @@ tbody tr:last-child td{border-bottom:0}
 .empty{padding:60px var(--gutter);width:100%;max-width:var(--column);margin-inline:auto;color:var(--muted)}
 mark{background:rgba(77,163,255,.22);color:var(--ink);border-radius:3px;padding:0 2px}
 @media (max-width:820px){
-  .layout{grid-template-columns:var(--rail)}
   .layout:not(.collapsed) .main{display:none}
   :root{--gutter:20px}
   :root.fixed-margin{--column:100%}
@@ -535,17 +574,23 @@ mark{background:rgba(77,163,255,.22);color:var(--ink);border-radius:3px;padding:
   .sec-tog{opacity:1}
 }
 @media print{
-  .side{display:none}.layout{grid-template-columns:1fr}
+  .side,.side-btn{display:none}.layout{grid-template-columns:1fr}
   .head{border:0;border-radius:0;padding-block:20px;background:none}.head::before,.head::after{display:none}
-  .sec.shut>.sec-body{display:block}.sec-tog,.h-anchor,.rv,.rv-bar{display:none}
+  .sec.shut>.sec-body{display:block}.sec-tog,.h-anchor,.rv,.rv-bar,.sec.is-lit::after{display:none}
 }
 `;
 
+/* The bar is solid, not frosted. A backdrop blur on a fixed bar has to be
+   redrawn under it on every frame of a scroll, and when the browser misses one
+   the bar flickers between its glass and the bare page beneath - and without
+   the blur, anything short of opaque lets the text scrolling under it show.
+   It is 60px tall so the title centred in it sits on the sidebar title's line
+   (16px down, 28px high), and so does the corner button beside it. */
 export const CSS_BAR = `
 .topbar{position:fixed;top:0;left:var(--rail);right:0;z-index:6;pointer-events:none;
-  display:flex;height:46px;
-  background:rgba(8,9,11,.78);backdrop-filter:saturate(160%) blur(14px);
+  display:flex;height:60px;background:var(--bg);
   border-bottom:1px solid var(--line);transform:translateY(-101%);transition:transform .22s ease}
+.anim .topbar{transition:transform .22s ease,left .28s ease}
 .topbar.show{transform:none}
 .topbar-in{display:flex;align-items:center;gap:10px;min-width:0;width:100%;
   max-width:var(--column);margin-inline:auto;padding:0 var(--gutter)}

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}>
@@ -62,16 +61,16 @@ export function renderPage({ cfg, docs, fontCss, mermaidTag, elkTag }) {
 </head>
 <body>
 <div class="layout" id="layout">
+  <button class="icon-btn side-btn" id="toggle" type="button" title="Hide sidebar  [">
+    <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4">
+      <rect x="1.5" y="2.5" width="13" height="11" rx="2.5"/><path d="M6 2.5v11"/>
+    </svg>
+  </button>
   <aside class="side">
     <div class="side-top">
       <div class="brand">
         <div class="brand-row">
           <span class="brand-name">${escAttr(cfg.title)}</span>
-          <button class="icon-btn" id="toggle" type="button" title="Toggle sidebar  [">
-            <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4">
-              <rect x="1.5" y="2.5" width="13" height="11" rx="2.5"/><path d="M6 2.5v11"/>
-            </svg>
-          </button>
         </div>
       </div>
     </div>${searchBox}
@@ -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/update.mjs

@@ -0,0 +1,89 @@
+// update.mjs - say so when npm has a newer lowkey-doc than the one running.
+// ------------------------------------------------------------------
+// The registry is asked at most once a day, while the command does its own
+// work, and never for longer than WAIT: a slow or absent network costs the
+// notice and nothing else. The answer is kept in the user's cache folder, so
+// the runs in between only read a file.
+//
+// Off when stderr is not a terminal, on CI, and with NO_UPDATE_NOTIFIER set.
+// ------------------------------------------------------------------
+
+import fs from 'node:fs';
+import https from 'node:https';
+import os from 'node:os';
+import path from 'node:path';
+import { VERSION } from './config.mjs';
+
+const REGISTRY = 'https://registry.npmjs.org/lowkey-doc/latest';
+const DAY = 24 * 60 * 60 * 1000;
+const WAIT = 1500;
+
+export const UPDATE_FILE = path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'),
+  'lowkey-doc', 'update-check.json');
+
+const enabled = () => process.stderr.isTTY && !process.env.CI && !process.env.NO_UPDATE_NOTIFIER;
+
+// 1.10.0 is newer than 1.9.3; a pre-release is never offered
+export function newer(latest, current) {
+  if (!/^\d+\.\d+\.\d+$/.test(latest)) return false;
+  const a = latest.split('.').map(Number);
+  const b = current.split('-')[0].split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i];
+  return current.includes('-');
+}
+
+// What to type depends on how it was run: npx keeps its own copy, and npm
+// run uses the project's.
+function howTo(env = process.env) {
+  if (env.npm_command === 'exec') return 'npx lowkey-doc@latest';
+  if (env.npm_command === 'run-script') return 'npm install lowkey-doc@latest';
+  return 'npm install -g lowkey-doc@latest';
+}
+
+export const notice = (latest, current = VERSION, env = process.env) =>
+  '\n  Update available: lowkey-doc ' + current + ' → ' + latest + '\n  Run: ' + howTo(env) + '\n';
+
+function readCache() {
+  try { return JSON.parse(fs.readFileSync(UPDATE_FILE, 'utf8')); } catch { return null; }
+}
+
+function writeCache(data) {
+  try {
+    fs.mkdirSync(path.dirname(UPDATE_FILE), { recursive: true });
+    fs.writeFileSync(UPDATE_FILE, JSON.stringify(data) + '\n');
+  } catch { /* a cache we cannot write only means asking again next time */ }
+}
+
+// node:https rather than fetch: an aborted fetch still holds the process open
+// until its connection attempt times out, ten seconds on a network that drops
+// packets. A destroyed request lets go of its socket at once.
+function latestVersion() {
+  return new Promise((resolve) => {
+    const done = (version) => { clearTimeout(timer); resolve(version); };
+    const req = https.get(REGISTRY, { headers: { accept: 'application/json' } }, (res) => {
+      if (res.statusCode !== 200) { res.resume(); return done(null); }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => { try { done(JSON.parse(body).version || null); } catch { done(null); } });
+    });
+    req.on('error', () => done(null));
+    const timer = setTimeout(() => req.destroy(), WAIT);
+  });
+}
+
+// Starts the check, if one is due, and returns what to call once the command
+// is done: it resolves to the notice to print, or to null.
+export function checkForUpdate() {
+  if (!enabled()) return async () => null;
+  const cached = readCache();
+  // a failed check counts as one too, so being offline is not paid for on every run
+  const pending = cached && Date.now() - cached.checkedAt < DAY ? null : latestVersion().then((latest) => {
+    writeCache({ checkedAt: Date.now(), latest: latest || (cached && cached.latest) || null });
+    return latest;
+  });
+  return async () => {
+    const latest = (pending && await pending) || (cached && cached.latest);
+    return latest && newer(latest, VERSION) ? notice(latest) : null;
+  };
+}

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);