lowkey-doc 1.1.1 → 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.1",
+  "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/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,10 +209,35 @@ 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. Every section owns the
      words directly under its heading, and the document owns its standfirst
@@ -450,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;
@@ -467,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();
@@ -507,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(){
@@ -824,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
@@ -1013,7 +1051,7 @@ 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, marks){
@@ -1347,7 +1385,7 @@ export const APP_JS = String.raw`
     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/page.mjs

@@ -61,16 +61,16 @@ export function renderPage({ cfg, docs, reviews = {}, fontCss, mermaidTag, elkTa
 </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}

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;
+  };
+}