lowkey-doc 0.0.0-stage → 1.0.0

package/src/sections.mjs

@@ -0,0 +1,63 @@
+// sections.mjs
+// ------------------------------------------------------------------
+// Every heading takes ownership of the blocks that follow it, so the page can
+// fold a whole section away and space two of them apart with one rule instead
+// of a stack of heading margins. Numbers come from the nesting, not the level:
+// a document whose top level is ## still starts at 1.
+// ------------------------------------------------------------------
+
+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 HEAD_RE = /^<h([1-6]) id="([^"]+)">([\s\S]*)<\/h[1-6]>$/;
+const ANCHOR_RE = /^<a class="h-anchor"[^>]*>#<\/a>/;
+export const SECNUM_RE = /^(\d+(?:\.\d+)*)[.)]?\s+(?=\S)/;
+
+export function nestSections(blocks, ctx) {
+  // A --- written just above a heading is the author drawing the section break
+  // by hand. The section itself draws that rule now, so drop the duplicate.
+  blocks = blocks.filter((html, n) =>
+    html !== '<hr>' || !(blocks[n + 1] || '').match(HEAD_RE));
+
+  const root = { level: 0, kids: [] };
+  const stack = [root];
+  for (const html of blocks) {
+    const m = html.match(HEAD_RE);
+    if (!m) { stack[stack.length - 1].kids.push(html); continue; }
+    const level = +m[1];
+    while (stack.length > 1 && stack[stack.length - 1].level >= level) stack.pop();
+    const node = { level, id: m[2], inner: m[3], kids: [] };
+    stack[stack.length - 1].kids.push(node);
+    stack.push(node);
+  }
+  return emitSections(root, [], ctx);
+}
+
+function emitSections(node, prefix, ctx) {
+  let n = 0;
+  return node.kids.map((kid) => {
+    if (typeof kid === 'string') return kid;
+    n++;
+    const anchor = (kid.inner.match(ANCHOR_RE) || [''])[0];
+    let text = kid.inner.slice(anchor.length);
+
+    // A heading that numbers itself keeps its own number: the prose around it
+    // says things like "the diagram in 1.2", and a second number invented here
+    // would both duplicate it and contradict the cross-reference.
+    const own = text.match(SECNUM_RE);
+    const num = own ? own[1].split('.') : prefix.concat(n);
+    const label = num.join('.');
+    if (own) text = text.slice(own[0].length);
+    ctx.numbers.set(kid.id, label);
+
+    const head = '<h' + kid.level + ' id="' + kid.id + '" class="sec-head">' +
+      '<span class="sec-gut">' +
+        '<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 +
+      '</h' + kid.level + '>';
+    return '<section class="sec" data-sec="' + kid.id + '">' + head +
+      '<div class="sec-body">' + emitSections(kid, num, ctx) + '</div></section>';
+  }).join('\n');
+}

package/src/vendor.mjs

@@ -0,0 +1,151 @@
+// vendor.mjs
+// ------------------------------------------------------------------
+// The page is a single file:// document with no server and no npm install,
+// so everything it needs travels with it. Each asset is fetched once and
+// cached under <out>/vendor; --refresh re-fetches.
+//
+// Every asset is pinned twice: by version, and by the SHA-384 of its bytes.
+// A download that does not match is refused, and so is a cached copy that
+// does not - which is also how a cache left by another version is replaced.
+// Whatever happens to the CDN, the page runs the bytes that were checked
+// here. Bumping a version means bumping its hash: take it from the file in
+// the npm tarball (npm pack <name>@<version>), never from the CDN.
+//
+// If a fetch fails the build still succeeds: mermaid falls back to its CDN
+// (the page then needs a network connection, and the browser checks the same
+// hash), ELK simply is not offered (flowcharts render with mermaid), and the
+// font falls back to the system.
+//
+// The licenses of all three ship in licenses/ and are written beside them as
+// vendor/THIRD-PARTY-NOTICES.txt. The font's goes inside the page as well,
+// since the font itself does.
+// ------------------------------------------------------------------
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// Pinned on purpose: a diagram that renders today should render the same way
+// in a year, and a surprise major version should not land in someone's docs.
+export const MERMAID_VERSION = '11.17.2';
+export const ELK_VERSION = '0.12.0';
+// @fontsource-variable/inter, which carries Inter 4.001
+export const INTER_VERSION = '5.3.0';
+
+export const NOTICES_FILE = 'THIRD-PARTY-NOTICES.txt';
+
+const CDN = 'https://cdn.jsdelivr.net/npm/';
+const LICENSES = new URL('../licenses/', import.meta.url);
+
+const MERMAID = {
+  url: CDN + 'mermaid@' + MERMAID_VERSION + '/dist/mermaid.min.js',
+  file: 'mermaid.min.js',
+  sha384: 'sha384-EOXBFmc3gx5mb+vn0vPvvGqACToJD24hhacX5Yx+8NUUQrHIle/Qi5Bg9o3zKwW2',
+};
+const ELK = {
+  url: CDN + 'elkjs@' + ELK_VERSION + '/lib/elk.bundled.js',
+  file: 'elk.bundled.js',
+  sha384: 'sha384-ww57TDqx4cGknIavPm0QKO+aygLUR1BLSn2Vhbnt1XdYKWcwLyWTFKX7aZMaKIi2',
+};
+// The variable font with both of its axes, optical size and weight. Latin
+// only - the other subsets triple the page for glyphs no doc uses.
+const INTER = [
+  { style: 'normal', sha384: 'sha384-J6qsAXAqf6o0318WxA4xhF/vxuL4NhwP9fFcjHZXsSqdyKns1va+jGgjyn5XiIJL' },
+  { style: 'italic', sha384: 'sha384-wxEgdtMgsytE2z0IplCB84KY2MIh0AXdBHiaX7U1ghRtSnew3nsMP2GBUCzhRCsP' },
+].map((face) => ({
+  ...face,
+  url: CDN + '@fontsource-variable/inter@' + INTER_VERSION + '/files/inter-latin-opsz-' + face.style + '.woff2',
+  file: 'inter-latin-' + face.style + '.woff2',
+}));
+
+const NOTICES = [
+  {
+    name: 'Mermaid ' + MERMAID_VERSION, where: 'vendor/' + MERMAID.file, license: 'mermaid.txt',
+    source: 'https://github.com/mermaid-js/mermaid',
+    more: 'mermaid.min.js also contains Mermaid\'s own dependencies, each under its own license:\n' +
+      'they are listed in Mermaid\'s package.json, at the source above.',
+  },
+  {
+    name: 'ELK (elkjs) ' + ELK_VERSION, where: 'vendor/' + ELK.file, license: 'elkjs.txt',
+    source: 'https://github.com/kieler/elkjs',
+    more: 'The source code of elkjs is available under the license below, at the address above.',
+  },
+  {
+    name: 'Inter 4.001 (@fontsource-variable/inter ' + INTER_VERSION + ')', where: 'inlined in index.html', license: 'inter.txt',
+    source: 'https://github.com/rsms/inter',
+  },
+];
+
+const sri = (bytes) => 'sha384-' + crypto.createHash('sha384').update(bytes).digest('base64');
+const license = (file) => fs.readFileSync(new URL(file, LICENSES), 'utf8');
+
+// The asset's bytes: the cached copy while it is still the pinned one, else a
+// fresh download, which is kept only if it is.
+async function pinned(asset, outDir, refresh) {
+  const dest = path.join(outDir, 'vendor', asset.file);
+  if (!refresh) {
+    try {
+      const cached = fs.readFileSync(dest);
+      if (sri(cached) === asset.sha384) return { bytes: cached, fresh: false };
+    } catch { /* not cached yet */ }
+  }
+  const res = await fetch(asset.url);
+  if (!res.ok) throw new Error('HTTP ' + res.status);
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (sri(bytes) !== asset.sha384) throw new Error('checksum mismatch, download refused');
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, bytes);
+  return { bytes, fresh: true };
+}
+
+async function vendorScript(asset, outDir, refresh, optional) {
+  try {
+    const { bytes, fresh } = await pinned(asset, outDir, refresh);
+    return {
+      tag: { src: 'vendor/' + asset.file },
+      note: fresh ? 'downloaded (' + (bytes.length / 1024 / 1024).toFixed(1) + ' MB)' : 'cached',
+    };
+  } catch (err) {
+    if (optional) return { tag: null, note: 'unavailable (' + err.message + ')' };
+    return { tag: { src: asset.url, integrity: asset.sha384 }, note: 'CDN fallback (' + err.message + ')' };
+  }
+}
+
+export const vendorMermaid = (outDir, refresh) => vendorScript(MERMAID, outDir, refresh, false);
+
+export const vendorElk = (outDir, refresh) => vendorScript(ELK, outDir, refresh, true);
+
+// Inter, as a variable font inlined into the page. A file:// origin will not
+// fetch a font over CORS even from the folder next to it, so the woff2 has to
+// travel as a data: URI, with its license in a comment above it.
+export async function vendorFont(outDir, refresh) {
+  // the stylesheet versions before the font was pinned cached in its place
+  fs.rmSync(path.join(outDir, 'vendor', 'inter.css'), { force: true });
+  try {
+    const faces = [];
+    let fetched = false;
+    for (const face of INTER) {
+      const { bytes, fresh } = await pinned(face, outDir, refresh);
+      fetched = fetched || fresh;
+      faces.push('@font-face{font-family:Inter;font-weight:100 900;font-display:swap;font-style:' + face.style +
+        ';src:url(data:font/woff2;base64,' + bytes.toString('base64') + ') format("woff2")}');
+    }
+    const css = '/*! The Inter typeface, inlined below\n\n' + license('inter.txt') + '*/\n' + faces.join('\n');
+    return { css, note: fetched ? 'downloaded (' + (Buffer.byteLength(css) / 1024).toFixed(0) + ' KB inlined)' : 'cached' };
+  } catch (err) {
+    return { css: '', note: 'system fallback (' + err.message + ')' };
+  }
+}
+
+// The licenses of everything above, beside the files they cover. Written on
+// every build, so it always matches the versions pinned here.
+export function writeNotices(outDir) {
+  const rule = '-'.repeat(72);
+  const text = 'Third-party software used by index.html\n\n' +
+    'Each component below keeps its own license, reproduced in full.\n\n' +
+    NOTICES.map((n) => rule + '\n' + n.name + '  -  ' + n.where + '\nSource: ' + n.source + '\n' +
+      (n.more ? n.more + '\n' : '') + rule + '\n\n' + license(n.license).trimEnd() + '\n').join('\n');
+  const dest = path.join(outDir, 'vendor', NOTICES_FILE);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, text);
+}

package/src/watch.mjs

@@ -0,0 +1,374 @@
+// watch.mjs - lowkey-doc --watch: serve the page, render it again on every save.
+// ------------------------------------------------------------------
+// The built page stays a file:// document that needs nothing; this is the
+// writing-time half. The same page is served from localhost with a small live
+// client added (client/live.mjs), the documents folder is watched, and a save
+// renders again only the files whose bytes changed. The open page is told,
+// pulls the new data and patches itself in place: the document being read
+// keeps its scroll position, its folds and its comments, and a diagram whose
+// source did not change is not laid out again. index.html on disk is kept
+// current as well, so the file:// page never falls behind.
+//
+// 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.
+// ------------------------------------------------------------------
+
+import fs from 'node:fs';
+import http from 'node:http';
+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 { LIVE_CSS, LIVE_JS } from './client/live.mjs';
+
+export const DEFAULT_PORT = 4747;
+// one save is often several writes (truncate, write, rename); act on the last
+const SETTLE_MS = 120;
+// Any website can point a hostname of its own at 127.0.0.1 (DNS rebinding) and
+// would then read the documents through this server as if it were this page.
+// The Host header still names that site, so only a local name gets an answer.
+const LOCAL_HOST = /^(127\.0\.0\.1|localhost)(:\d+)?$/i;
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.webp': 'image/webp', '.woff2': 'font/woff2', '.pdf': 'application/pdf',
+};
+
+const clock = () => new Date().toTimeString().slice(0, 8) + '  ';
+const sha = (s) => crypto.createHash('sha1').update(s).digest('hex').slice(0, 12);
+
+export async function watch(configArgs, { port = DEFAULT_PORT, open = true, refresh = false, quiet = false } = {}) {
+  let cfg = loadConfig(configArgs);
+  let assets = await vendorAssets(cfg, refresh);
+  let configRaw = readOr(cfg.configFile);
+  let shell = shellOf(cfg, assets);
+
+  const boot = crypto.randomBytes(3).toString('hex');
+  let memo = null, docs = [], html = '', seq = 0, error = null;
+  let watchers = [], settle = null, retry = null;
+  const clients = new Set();
+  const log = quiet ? () => {} : (msg) => console.log(clock() + msg);
+
+  const state = () => ({ version: boot + ':' + seq, shell, error });
+  const send = (res, s) => res.write('event: state\ndata: ' + JSON.stringify(s) + '\n\n');
+  const broadcast = () => { const s = state(); for (const res of clients) send(res, s); };
+
+  /* ------------------------------------------------------------ rebuilding */
+
+  function rebuild() {
+    const t0 = Date.now();
+    let r;
+    try {
+      r = collectDocs(cfg, memo);
+    } catch (err) {
+      // the page keeps showing the last good build, with the reason beside it
+      const msg = String(err && err.message || err);
+      // before the first good build there is no page to keep: the caller throws, and prints it
+      if (msg !== error) { error = msg; broadcast(); if (seq) log('failed   ' + msg.split('\n')[0]); }
+      if (!fs.existsSync(cfg.docsDir)) waitForFolder();
+      return;
+    }
+    const ids = (list) => list.map((d) => d.id).join('\n');
+    const reordered = ids(docs) !== ids(r.docs);
+    memo = r.memo;
+    if (seq && !r.changed.length && !reordered && !error) return;   // touched, not changed
+
+    const gone = docs.filter((d) => !r.docs.some((n) => n.id === d.id));
+    docs = r.docs;
+    error = null;
+    html = pageFor(cfg, docs, assets);
+    seq++;
+    try {
+      fs.writeFileSync(path.join(cfg.outDir, 'index.html'), html);
+    } catch (err) {
+      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); };
+
+  async function reconfigure() {
+    const raw = readOr(cfg.configFile);
+    if (raw === configRaw) return;
+    configRaw = raw;
+    try {
+      const next = loadConfig(configArgs);
+      if (next.outDir !== cfg.outDir) assets = await vendorAssets(next);
+      cfg = next;
+      shell = shellOf(cfg, assets);   // a new shell tells open pages to reload
+      memo = null;
+      log('config   ' + (cfg.configFile ? path.basename(cfg.configFile) : 'defaults') + ' reloaded');
+      arm();
+      rebuild();
+    } catch (err) {
+      error = String(err && err.message || err);
+      broadcast();
+      log('failed   ' + error.split('\n')[0]);
+    }
+  }
+
+  /* -------------------------------------------------------------- watching */
+
+  function arm() {
+    disarm();
+    const outside = (name) => {
+      if (!name) return false;
+      const abs = path.resolve(cfg.docsDir, name);
+      return name.split(/[\\/]/).some((seg) => seg.startsWith('.')) ||
+        abs === cfg.outDir || abs.startsWith(cfg.outDir + path.sep);
+    };
+    try {
+      watchers = watchTree(cfg.docsDir, (name) => { if (!outside(name)) soon(); }, waitForFolder);
+    } catch {
+      return waitForFolder();
+    }
+
+    // The folder's own parent: renaming or deleting the watched folder is not
+    // reported from inside it (on Windows its watcher quietly follows it to the
+    // 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 parents = new Set([path.dirname(cfg.docsDir)]);
+    if (cfg.configFile) parents.add(path.dirname(cfg.configFile));
+    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();
+        });
+        w.on('error', () => {});
+        watchers.push(w);
+      } catch { /* the documents still update; only a rename or a config edit needs a restart */ }
+    }
+  }
+
+  function disarm() {
+    for (const w of watchers) { try { w.close(); } catch {} }
+    watchers = [];
+  }
+
+  // The documents folder went away (renamed, moved, a sync client replacing
+  // it): the page already says so. Let go of it - a watcher left on it would
+  // follow it to its new name - and pick it up again once it is back.
+  function waitForFolder() {
+    if (retry) return;
+    disarm();
+    retry = setInterval(() => {
+      if (!fs.existsSync(cfg.docsDir)) return;
+      clearInterval(retry);
+      retry = null;
+      arm();
+      rebuild();
+    }, 1000);
+  }
+
+  /* --------------------------------------------------------------- serving */
+
+  const withLive = (page) => {
+    const tail = '<style>' + LIVE_CSS + '</style>\n' +
+      '<script>window.__LOWKEY_DOC_LIVE__=' + JSON.stringify(state()).replace(/</g, '\\u003c') + ';<\/script>\n' +
+      '<script>' + LIVE_JS + '<\/script>\n';
+    const at = page.lastIndexOf('</body>');
+    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) {
+    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('end', () => {
+      let next;
+      try { next = JSON.parse(body); } catch { return json(400, { error: 'Not 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 });
+      }
+
+      const file = cfg.configFile || path.join(cfg.root, CONFIG_NAMES[0]);
+      const before = readOr(file);
+      try {
+        const obj = before == null ? {} : JSON.parse(before);
+        const layout = { ...(obj.layout || {}) };
+        if (margin === null) delete layout.margin; else layout.margin = Math.round(margin);
+        if (Object.keys(layout).length) obj.layout = layout; else delete obj.layout;
+        const text = jsonLike(before, obj);
+        if (text !== before) fs.writeFileSync(file, text);
+        // the watcher will see the write: it is already applied, so let it pass
+        configRaw = text;
+        if (!cfg.configFile) configArgs = { ...configArgs, configPath: file };
+        cfg = loadConfig(configArgs);
+      } catch (err) {
+        return json(500, { error: 'Could not update ' + path.basename(file) + ': ' + err.message });
+      }
+
+      shell = shellOf(cfg, assets);
+      html = pageFor(cfg, docs, assets);
+      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') + ')');
+      json(200, { shell });
+      broadcast();
+    });
+  }
+
+  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;
+    try { p = decodeURIComponent(new URL(req.url, 'http://localhost').pathname); }
+    catch { return reply(res, 400, 'text/plain; charset=utf-8', 'Bad request'); }
+
+    if (p === '/__lowkey-doc/events') {
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+      res.write('retry: 1000\n\n');
+      send(res, state());
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+    if (p === '/__lowkey-doc/data.json') {
+      return reply(res, 200, TYPES['.json'],
+        JSON.stringify({ version: state().version, docs }));
+    }
+    if (p === '/__lowkey-doc/settings') return saveSettings(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>';
+      return reply(res, 200, TYPES['.html'], withLive(page));
+    }
+    // the vendored scripts, then anything a document points at (images)
+    const file = inside(cfg.outDir, p) || inside(cfg.docsDir, p);
+    if (!file) return reply(res, 404, 'text/plain; charset=utf-8', 'Not found');
+    reply(res, 200, TYPES[path.extname(file).toLowerCase()] || 'application/octet-stream', fs.readFileSync(file));
+  });
+
+  rebuild();
+  if (!seq) throw new Error(error);
+  arm();
+
+  const url = await listen(server, port);
+  const beat = setInterval(() => { for (const res of clients) res.write(': ping\n\n'); }, 25000);
+  beat.unref();
+
+  if (!quiet) {
+    console.log(cfg.title + '  (lowkey-doc ' + VERSION + ')');
+    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'));
+    console.log('\n  live at ' + url + '   (Ctrl+C to stop)\n');
+  }
+  if (open) openInBrowser(url);
+
+  const close = () => new Promise((resolve) => {
+    clearInterval(beat);
+    clearTimeout(settle);
+    clearInterval(retry);
+    disarm();
+    for (const res of clients) res.end();
+    clients.clear();
+    server.close(() => resolve());
+    if (server.closeAllConnections) server.closeAllConnections();
+  });
+  return { url, close };
+}
+
+/* ------------------------------------------------------------------ helpers */
+
+// Recursive watching is native on Windows and macOS, and on Linux from Node 20.
+// Elsewhere: the folder, plus each folder directly inside it - as deep as
+// listDocs ever looks - following sub-folders as they come and go.
+function watchTree(dir, onEvent, onError) {
+  try {
+    const w = fs.watch(dir, { recursive: true }, (_, name) => onEvent(name && String(name)));
+    w.on('error', onError);
+    return [w];
+  } catch (err) {
+    if (err.code !== 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM') throw err;
+  }
+  const subs = new Map();
+  const follow = () => {
+    const now = new Set(fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name));
+    for (const [name, w] of subs) if (!now.has(name)) { w.close(); subs.delete(name); }
+    for (const name of now) {
+      if (subs.has(name)) continue;
+      try {
+        const w = fs.watch(path.join(dir, name), (_, f) => onEvent(name + '/' + (f || '')));
+        w.on('error', () => {});
+        subs.set(name, w);
+      } catch { /* gone again already */ }
+    }
+  };
+  const top = fs.watch(dir, (_, name) => {
+    try { follow(); } catch { /* the folder itself is going; its watcher reports that */ }
+    onEvent(name && String(name));
+  });
+  top.on('error', onError);
+  follow();
+  return [top, { close: () => { for (const w of subs.values()) w.close(); subs.clear(); } }];
+}
+
+// The page's shell is everything but the documents. When it changes - the
+// configuration, or Lowkey Doc itself after a restart - an open page reloads
+// rather than patching.
+function shellOf(cfg, assets) {
+  return sha(pageFor(cfg, [], assets) + LIVE_CSS + LIVE_JS);
+}
+
+function listen(server, port, tries = 20) {
+  return new Promise((resolve, reject) => {
+    const onError = (err) => {
+      server.off('listening', onListening);
+      if (err.code === 'EADDRINUSE' && port && tries > 1) resolve(listen(server, port + 1, tries - 1));
+      else reject(err);
+    };
+    const onListening = () => {
+      server.off('error', onError);
+      resolve('http://127.0.0.1:' + server.address().port + '/');
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+function inside(base, p) {
+  const file = path.resolve(base, p.replace(/^[\\/]+/, ''));
+  if (file !== base && !file.startsWith(base + path.sep)) return null;
+  try { return fs.statSync(file).isFile() ? file : null; } catch { return null; }
+}
+
+function reply(res, status, type, body) {
+  res.writeHead(status, { 'Content-Type': type, 'Cache-Control': 'no-store' });
+  res.end(body);
+}
+
+function readOr(file) {
+  try { return file ? fs.readFileSync(file, 'utf8') : null; } catch { return null; }
+}
+
+const escHtml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');