lowkey-doc 1.0.1 → 1.1.1

package/package.json

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

@@ -34,6 +34,7 @@ export const APP_JS = String.raw`
   }
 
   var CARET = '<svg class="caret" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6"><path d="M6 4l4 4-4 4"/></svg>';
+  var CHECK = '<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>';
 
   function buildNav(){
     var group = null;
@@ -47,6 +48,7 @@ export const APP_JS = String.raw`
       item.title = d.file;
       item.appendChild(el('span', 'num', d.badge));
       item.appendChild(el('span', 'item-title', d.title));
+      if (RV_ON) item.insertAdjacentHTML('beforeend', '<span class="rv-mark" title="Reviewed">' + CHECK + '</span>');
       if (d.sections.length) item.insertAdjacentHTML('beforeend', CARET);
       item.addEventListener('click', function(e){
         if (e.target.closest('.caret') && current === d.id){ item.classList.toggle('open'); return; }
@@ -62,6 +64,8 @@ export const APP_JS = String.raw`
         a.title = (s.num ? s.num + '  ' : '') + s.text;
         if (s.num) a.appendChild(el('span', 'sub-n', s.num));
         a.appendChild(el('span', 'sub-t', s.text));
+        if (RV_ON) a.insertAdjacentHTML('beforeend', '<span class="rv-mark" title="Reviewed">' + CHECK + '</span>');
+        a.dataset.sec = s.id;
         subs.appendChild(a);
       });
       nav.appendChild(subs);
@@ -106,6 +110,7 @@ export const APP_JS = String.raw`
       restoreFolds(main);
       if (window.__diagrams) window.__diagrams.drawAll(main);
       renderComments();
+      paintReviews();
       watch();
     }
     if (anchor && reveal(anchor, false)) return;
@@ -130,9 +135,15 @@ export const APP_JS = String.raw`
     var head = el('header', 'head');
     head.appendChild(el('h1', null, d.title));
     if (d.subtitle){
-      var p = el('p');
-      p.innerHTML = d.subtitle;
-      head.appendChild(p);
+      var lede = el('div', 'lede');
+      lede.innerHTML = d.subtitle;
+      head.appendChild(lede);
+    }
+    if (RV_ON){
+      var rvBar = el('div', 'rv-bar');
+      rvBar.appendChild(el('span', 'rv-count'));
+      rvBar.insertAdjacentHTML('beforeend', '<button class="rv rv-doc" type="button" aria-pressed="false" aria-label="Reviewed">' + CHECK + '</button>');
+      head.appendChild(rvBar);
     }
     wrap.appendChild(head);
 
@@ -201,6 +212,157 @@ export const APP_JS = String.raw`
     return true;
   }
 
+  /* ---------------- reviews ----------------
+     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 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]);
+    }
+    var out = {};
+    all.forEach(function(n){ if (mine[n.id]) out[n.id] = mine[n.id]; });
+    return out;
+  }
+
+  function putMarks(file, marks){
+    if (marks && Object.keys(marks).length) reviews[file] = marks; else delete reviews[file];
+  }
+
+  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' });
+  }
+
+  // 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, 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' + (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(){
+    if (!RV_ON) return;
+    nav.querySelectorAll('.item').forEach(function(item){
+      var d = byId[item.dataset.doc];
+      if (!d) return;
+      item.classList.toggle('is-reviewed', isReviewed(d, null));
+      var subs = nav.querySelector('[data-subs="' + d.id + '"]');
+      if (subs) subs.querySelectorAll('.sub').forEach(function(a){
+        a.classList.toggle('is-reviewed', isReviewed(d, a.dataset.sec));
+      });
+    });
+    var d = byId[current];
+    if (!d) return;
+    main.querySelectorAll('.sec').forEach(function(sec){
+      var btn = sec.querySelector(':scope > .sec-head > .rv');
+      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, d, null, 'the whole document');
+    if (count){
+      // 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;
+    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 ---------------- */
 
   var box = document.getElementById('lightbox');
@@ -293,6 +455,8 @@ export const APP_JS = String.raw`
       if (reveal(href.slice(1), true)) history.replaceState(null, '', '#/' + current + '/' + href.slice(1));
       return;
     }
+    var rv = e.target.closest('.rv');
+    if (rv){ toggleReview(rv); return; }
     // anywhere on a heading folds its section - unless the click was really the
     // end of a drag that selected some of it
     var head = e.target.closest('.sec-head');
@@ -852,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]; }));
     };
@@ -888,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;
   }
 
@@ -901,6 +1068,7 @@ export const APP_JS = String.raw`
       n.classList.toggle('open', !!open[n.dataset.doc] || n.dataset.doc === current);
     });
     if (search && search.value) search.dispatchEvent(new Event('input'));
+    paintReviews();
     nav.scrollTop = top;
   }
 
@@ -920,6 +1088,7 @@ export const APP_JS = String.raw`
     restoreFolds(main);
     if (window.__diagrams) window.__diagrams.drawAll(main);
     renderComments();
+    paintReviews();
     watch();
     keepPlace(at);
 
@@ -938,7 +1107,7 @@ export const APP_JS = String.raw`
     var out = [];
     var head = holder.querySelector('.head');
     if (was.title !== d.title) out.push(head.querySelector('h1'));
-    if (was.subtitle !== d.subtitle && head.querySelector('p')) out.push(head.querySelector('p'));
+    if (was.subtitle !== d.subtitle && head.querySelector('.lede')) out.push(head.querySelector('.lede'));
 
     var body = holder.querySelector('.doc');
     var t = document.createElement('template');
@@ -1172,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/css.mjs

@@ -9,6 +9,8 @@ html{-webkit-text-size-adjust:100%}
   --line-2:rgba(255,255,255,.16); --surface:#13161b; --surface-2:#1a1e24; --hover:rgba(255,255,255,.05);
   /* the one accent: an electric blue, used for what is lit, current or alive */
   --accent:#4da3ff; --accent-soft:rgba(77,163,255,.12); --accent-ring:rgba(77,163,255,.36);
+  /* reviewed: a green as light and as cool as the blue, so the two sit together */
+  --ok:#45cf98; --ok-soft:rgba(69,207,152,.12); --ok-ring:rgba(69,207,152,.36);
   /* a filled button is white with dark text */
   --on-ink:#0b0d10; --ink-hover:#dde2e8;
   --serif:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
@@ -153,9 +155,14 @@ a{color:inherit;text-decoration:none}
 .sub-n{flex:none;font-size:11px;color:var(--faint);font-variant-numeric:tabular-nums}
 .sub.current .sub-n{color:var(--muted)}
 .sub-t{flex:1;min-width:0;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+/* a reviewed document or section carries a green check in the sidebar */
+.rv-mark{display:none;flex:none;width:13px;height:13px;color:var(--ok)}
+.rv-mark svg{display:block;width:100%;height:100%}
+.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{display:none}
+.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}
@@ -249,7 +256,9 @@ export const CSS_MAIN = `
 @keyframes head-lamp{to{opacity:1}}
 @media (prefers-reduced-motion:reduce){.head::before,.head::after{animation:none}}
 .head h1{margin:0;max-width:22ch;font-size:36px;line-height:1.12;font-weight:650;letter-spacing:-.034em;color:var(--ink)}
-.head p{margin:14px 0 0;max-width:68ch;font-size:15.5px;line-height:1.62;color:var(--muted)}
+.head .lede{margin:14px 0 0;max-width:68ch;font-size:15.5px;line-height:1.62;color:var(--muted)}
+.lede>*{margin:0}
+.lede>*+*{margin-top:10px}
 .doc{padding:4px var(--gutter) 30px;width:100%;max-width:var(--column);margin-inline:auto}
 
 /* ---- prev / next ----
@@ -312,6 +321,32 @@ h4.sec-head,h5.sec-head,h6.sec-head{margin:0 0 8px;font-size:14px;font-weight:va
 .sec-head:hover .h-anchor{opacity:1}
 .h-anchor:hover{color:var(--ink)}
 
+/* ---- reviews ----
+   Every section, and the document in its header card, has a Reviewed button:
+   a grey check until the reader marks it, then green. On a heading the word
+   shows only on hover, so a page of unread headings is not a page of labels. */
+.rv{flex:none;align-self:center;margin-left:auto;display:inline-flex;align-items:center;gap:6px;
+  padding:3px 4px 3px 9px;border:1px solid transparent;border-radius:999px;background:none;
+  color:var(--faint);font:inherit;font-size:11.5px;font-weight:var(--semi);letter-spacing:0;line-height:1;
+  cursor:pointer;transition:color .15s,background .15s,border-color .15s}
+.rv svg{width:16px;height:16px;flex:none}
+.rv svg circle{transition:fill .15s,stroke .15s}
+.rv::before{content:"Reviewed";opacity:0;transition:opacity .15s}
+.sec-head:hover>.rv::before,.rv:focus-visible::before,.rv.is-on::before{opacity:1}
+.rv:hover{color:var(--ink);background:var(--hover)}
+.rv:focus-visible{outline:2px solid var(--ok-ring);outline-offset:1px}
+.rv.is-on{color:var(--ok)}
+.rv.is-on svg circle{fill:var(--ok);stroke:var(--ok)}
+.rv.is-on svg path{stroke:var(--on-ink)}
+.rv.is-on:hover{color:var(--ok);background:var(--ok-soft)}
+/* the document's own, in the corner of the header card: always labelled */
+.rv-bar{position:absolute;top:18px;right:18px;display:flex;align-items:center;gap:10px}
+.rv-count{font-size:11.5px;color:var(--muted);font-variant-numeric:tabular-nums}
+.rv-count:empty{display:none}
+.rv-doc{margin:0;border-color:var(--line-2);color:var(--muted)}
+.rv-doc::before{opacity:1}
+.rv-doc.is-on{border-color:var(--ok-ring)}
+
 /* ---- prose ---- */
 .doc p{margin:0 0 18px}
 .doc>p:first-child{margin-top:6px}
@@ -323,9 +358,9 @@ h4.sec-head,h5.sec-head,h6.sec-head{margin:0 0 8px;font-size:14px;font-weight:va
 .doc ul>li::marker{color:var(--accent)}
 .doc strong{font-weight:var(--semi);color:inherit}
 .doc em{font-style:italic}
-.doc a:not(.h-anchor){color:var(--ink);border-bottom:1px solid var(--line-2);padding-bottom:1px;
+.doc a:not(.h-anchor),.lede a{color:var(--ink);border-bottom:1px solid var(--line-2);padding-bottom:1px;
   transition:border-color .12s,color .12s}
-.doc a:not(.h-anchor):hover{border-bottom-color:var(--accent);color:var(--accent)}
+.doc a:not(.h-anchor):hover,.lede a:hover{border-bottom-color:var(--accent);color:var(--accent)}
 .doc hr{margin:32px 0;border:0;border-top:1px solid var(--line)}
 .doc blockquote{margin:0 0 18px;padding:2px 0 2px 17px;border-left:2px solid var(--accent-ring);color:var(--muted)}
 /* Inline code is a plate set into the sentence: a faint white fill that
@@ -334,12 +369,12 @@ h4.sec-head,h5.sec-head,h6.sec-head{margin:0 0 8px;font-size:14px;font-weight:va
    alone would vanish), and an ink a shade cooler than the prose, so a name
    reads as a name without shouting. Padding is in em, so the plate tracks
    the text it sits in, headings included. */
-.doc code{font-family:var(--mono);font-size:.84em;letter-spacing:-.01em;
+.doc code,.lede code{font-family:var(--mono);font-size:.84em;letter-spacing:-.01em;
   background:var(--code-bg);box-shadow:inset 0 0 0 1px var(--code-ring);
   border-radius:5px;padding:.1em .38em .12em;color:var(--code-ink);white-space:nowrap;
   -webkit-box-decoration-break:clone;box-decoration-break:clone}
 .api code{background:var(--code-bg-on-white)}
-.doc a:not(.h-anchor) code{color:var(--accent);box-shadow:inset 0 0 0 1px var(--accent-ring)}
+.doc a:not(.h-anchor) code,.lede a code{color:var(--accent);box-shadow:inset 0 0 0 1px var(--accent-ring)}
 .doc h1 code,.doc h2 code,.doc h3 code,.doc h4 code{font-size:.86em;font-weight:var(--semi)}
 /* a {placeholder} inside code: the braces fade, the name stays */
 .c-var{color:var(--code-var);font-style:italic}
@@ -491,6 +526,7 @@ mark{background:rgba(77,163,255,.22);color:var(--ink);border-radius:3px;padding:
   .docnav-btn.next{grid-column:1;text-align:left}
   .head{width:calc(100% - 20px);margin-top:14px;padding-block:34px 36px}
   .head h1{font-size:29px}
+  .rv-bar{position:static;margin-top:18px}
 }
 /* Not enough room beside the column to hang the arrow and the number in:
    bring them back into the heading row rather than let them fall off-screen. */
@@ -501,7 +537,7 @@ mark{background:rgba(77,163,255,.22);color:var(--ink);border-radius:3px;padding:
 @media print{
   .side{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{display:none}
+  .sec.shut>.sec-body{display:block}.sec-tog,.h-anchor,.rv,.rv-bar{display:none}
 }
 `;
 
@@ -753,19 +789,19 @@ export const CSS_CMT = `
    A highlight and its card are two views of one comment, so hovering either
    lights both (.hot); clicking either pins the pair (.on). */
 .body-wrap{position:relative;display:flex;flex-direction:column;min-height:100vh}
-.cmt-hl{background:rgba(250,204,21,.16);box-shadow:inset 0 -1px 0 rgba(250,204,21,.6);border-radius:3px;padding:0 1px;
+.cmt-hl{background:rgba(77,163,255,.16);box-shadow:inset 0 -1px 0 rgba(77,163,255,.6);border-radius:3px;padding:0 1px;
   color:inherit;cursor:pointer;transition:background .12s,box-shadow .12s}
-.cmt-hl.hot{background:rgba(250,204,21,.26);box-shadow:inset 0 -1px 0 rgba(250,204,21,.8)}
-.cmt-hl.on{background:rgba(250,204,21,.36);box-shadow:inset 0 -1px 0 #facc15}
+.cmt-hl.hot{background:rgba(77,163,255,.26);box-shadow:inset 0 -1px 0 rgba(77,163,255,.8)}
+.cmt-hl.on{background:rgba(77,163,255,.36);box-shadow:inset 0 -1px 0 var(--accent)}
 .cmt-layer{position:absolute;inset:0;pointer-events:none;z-index:2}
 .cmt-card{position:absolute;left:0;top:0;width:var(--cmt-w,264px);pointer-events:auto;padding:10px 12px;
   background:var(--surface);border:1px solid var(--line);border-radius:14px;cursor:pointer;
   font-size:12.5px;line-height:1.55;transition:border-color .15s ease,box-shadow .15s ease}
-.cmt-card.hot{border-color:rgba(250,204,21,.45);box-shadow:0 4px 16px rgba(0,0,0,.4)}
-.cmt-card.on{border-color:rgba(250,204,21,.7);box-shadow:0 6px 20px rgba(0,0,0,.5)}
+.cmt-card.hot{border-color:rgba(77,163,255,.45);box-shadow:0 4px 16px rgba(0,0,0,.4)}
+.cmt-card.on{border-color:rgba(77,163,255,.7);box-shadow:0 6px 20px rgba(0,0,0,.5)}
 .cmt-card[hidden]{display:none!important}
 .cmt-face{display:none}
-.cmt-quote{margin:0 0 7px;padding-left:9px;border-left:2px solid rgba(250,204,21,.6);color:var(--muted);
+.cmt-quote{margin:0 0 7px;padding-left:9px;border-left:2px solid rgba(77,163,255,.6);color:var(--muted);
   font-size:11.5px;line-height:1.45;overflow:hidden;
   display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical}
 .cmt-text{white-space:pre-wrap;overflow-wrap:anywhere}
@@ -774,14 +810,14 @@ export const CSS_CMT = `
 .cmt-act{padding:0;border:0;background:none;color:var(--muted);font:inherit;font-size:11px;
   cursor:pointer;border-bottom:1px solid transparent}
 .cmt-act:hover{color:var(--ink);border-bottom-color:var(--ink)}
-.cmt-lost{margin:0 0 5px;font-size:10px;letter-spacing:.06em;text-transform:uppercase;color:#e0b252}
+.cmt-lost{margin:0 0 5px;font-size:10px;letter-spacing:.06em;text-transform:uppercase;color:var(--accent)}
 
 /* tight gutters: the card shrinks to a numbered dot, opened as a popover */
 .cmt-layer.dots .cmt-card{width:22px;height:22px;padding:0;border-radius:50%;
-  background:#3a3215;border-color:#a8862a;display:grid;place-items:center;overflow:hidden}
-.cmt-layer.dots .cmt-card.hot,.cmt-layer.dots .cmt-card.on{background:#53461a;border-color:#facc15}
+  background:#10284d;border-color:#2f6db3;display:grid;place-items:center;overflow:hidden}
+.cmt-layer.dots .cmt-card.hot,.cmt-layer.dots .cmt-card.on{background:#16386b;border-color:var(--accent)}
 .cmt-layer.dots .cmt-full{display:none}
-.cmt-layer.dots .cmt-face{display:block;font-size:11px;font-weight:var(--bold);color:#f5d76e;
+.cmt-layer.dots .cmt-face{display:block;font-size:11px;font-weight:var(--bold);color:#a9d2ff;
   font-variant-numeric:tabular-nums}
 
 /* ---- comments: floating bits ---- */