lowkey-doc 1.0.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lowkey-doc",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "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/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,98 @@ export const APP_JS = String.raw`
     return true;
   }
 
+  /* ---------------- 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. */
+
+  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;
+    }
+    return null;
+  }
+
+  // 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 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 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();
+  }
+
+  function paintBtn(btn, on, what){
+    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';
+  }
+
+  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, isReviewed(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 (count){
+      var c = rvCount(d, null);
+      count.textContent = c.done && c.done < c.of ? c.done + ' of ' + c.of + ' sections' : '';
+    }
+  }
+
+  function toggleReview(btn){
+    var d = byId[current];
+    if (!d) 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));
+  }
+
   /* ---------------- lightbox ---------------- */
 
   var box = document.getElementById('lightbox');
@@ -293,6 +396,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');
@@ -901,6 +1006,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 +1026,7 @@ export const APP_JS = String.raw`
     restoreFolds(main);
     if (window.__diagrams) window.__diagrams.drawAll(main);
     renderComments();
+    paintReviews();
     watch();
     keepPlace(at);
 
@@ -938,7 +1045,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');

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 ---- */

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/collect.mjs

@@ -12,7 +12,7 @@
 
 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 { titleCase } from './config.mjs';
 
@@ -93,7 +93,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: [], reviews: cfg.reviews !== false,
     uniqueSlug(base) {
       const key = base || 'section';
       const n = seen.get(key) || 0;
@@ -114,23 +114,19 @@ 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);
   } 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>';
   }
@@ -139,6 +135,7 @@ export function buildDoc(entry, byFile, cfg, raw = fs.readFileSync(entry.abs, 'u
 
   return {
     id, title, subtitle, html, badge,
+    outline: ctx.outline,
     group: entry.group,
     file: entry.rel || entry.file,
     words: raw.split(/\s+/).filter(Boolean).length,

package/src/config.mjs

@@ -24,7 +24,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 +68,7 @@ const DEFAULTS = {
   },
   // Reader features. Turn off what a given project does not want.
   comments: true,
+  reviews: true,
   search: true,
 };
 

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

@@ -17,6 +17,7 @@ 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

package/src/sections.mjs

@@ -8,6 +8,12 @@
 
 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 +36,11 @@ 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) }));
+  ctx.outline = outline(root);
   return emitSections(root, [], ctx);
 }
 
@@ -55,7 +66,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>';