@arjunkhera/atlas 0.3.7 → 0.3.9

package/door/lib/design-build.mjs

@@ -0,0 +1,409 @@
+// The design page builder. It turns one design folder into one page, the
+// same way every time: a left rail that folds as a whole and per group, a
+// fixed top bar, a fixed Back and Next bar, the arrow keys, and a light and
+// a dark theme from one token set.
+//
+// A design keeps no state. The page shows the tracker's facts only from the
+// JSON file the lead passes with --tracker, and the builder makes no network
+// call. Each field is a field of a tracker record, copied as the Atlas tools
+// return it; the builder refuses any other field. Approval and lock, and
+// Since approval, are derived from those fields, never written by hand:
+//
+//   { "read_at": "2026-10-09T13:30:00Z",
+//     "item": { "id", "title", "lifecycle", "stage", "tier",
+//               "locked_at": "<ISO time>" | null,
+//               "origin": { "text", "source", "date" } },   the owner's words; at a lock, the approval
+//     "questions": [ { "id", "text", "status": "open" | "answered", "answer": "<the answer's decision text>" } ],
+//     "decisions": [ { "id", "kind", "date", "text", "source" } ],
+//     "links":     [ { "kind", "url", "role", "note" } ],
+//     "family":    [ { "id", "title", "lifecycle", "url" } ] }
+//
+// Every field may be left out, except that the file is one object.
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, basename } from 'node:path';
+import { readDesign, loadRegistry, checkDesign } from './design.mjs';
+import { render, esc } from './markdown.mjs';
+
+export const WOODCUT = 'https://cdn.jsdelivr.net/npm/@arjunkhera/woodcut@0.4.0/src/index.js';
+
+// One token set. Each name has a light value and a dark value.
+export const TOKENS = Object.freeze({
+  paper: ['#FAF9F5', '#1F1E1B'], ink: ['#141413', '#ECE9E1'], card: ['#FFFFFF', '#2A2925'], rail: ['#F4F1EA', '#262521'],
+  line: ['#E6E1D6', '#3A3833'], 'line-soft': ['#EEE9DF', '#33312C'], 'line-strong': ['#DDD6C8', '#45423B'],
+  faint: ['#C9C1B2', '#57534B'], sep: ['#B9B2A4', '#6E695F'], num: ['#A39A8A', '#857D70'], quiet: ['#7D776C', '#9A9387'],
+  muted: ['#5E5A52', '#B3AC9F'], body: ['#3A3732', '#D4CFC4'],
+  accent: ['#B5502F', '#E08A63'], 'accent-ink': ['#8A3A20', '#F0B394'], 'accent-bg': ['#FBEFE8', '#3B2A22'], 'accent-line': ['#E9C2B0', '#6B4433'],
+  'trk-ink': ['#22496B', '#9CC3E6'], 'trk-bg': ['#F2F5F8', '#1E2833'], 'trk-line': ['#C9D6E3', '#34475A'], 'trk-label': ['#4F6C86', '#8FA9C2'],
+  yes: ['#2F5D3A', '#8FCB9C'], no: ['#A3352B', '#F08A7E'], warn: ['#8A5A12', '#E3B865'],
+  'btn-bg': ['#141413', '#ECE9E1'], 'btn-ink': ['#FFFFFF', '#1F1E1B'],
+});
+
+const tokenBlock = (index) => Object.entries(TOKENS).map(([name, pair]) => `--${name}:${pair[index]}`).join(';');
+
+const CSS = `
+:root{${tokenBlock(0)};color-scheme:light;
+--wc-paper:var(--paper);--wc-ink:var(--ink);--wc-body:var(--body);--wc-muted:var(--muted);--wc-faint:var(--quiet);--wc-line:var(--line);--wc-line-strong:var(--line-strong);--wc-accent:var(--accent);--wc-accent-soft:var(--accent-bg);--wc-panel:var(--rail);--wc-card:var(--card);--wc-danger:var(--no);--wc-danger-soft:var(--accent-bg);
+--wc-serif:Lora,Georgia,serif;--wc-mono:'IBM Plex Mono',ui-monospace,Menlo,monospace;--wc-dur-fast:150ms;--wc-dur-base:220ms;--wc-dur-step:450ms;--wc-dur-draw:700ms;
+--serif:Lora,Georgia,serif;--sans:Poppins,system-ui,sans-serif;--mono:'IBM Plex Mono',ui-monospace,Menlo,monospace}
+:root[data-theme="dark"]{${tokenBlock(1)};color-scheme:dark}
+*{box-sizing:border-box}
+html,body{margin:0;height:100%}
+body{background:var(--paper);color:var(--ink);font-family:var(--sans);font-size:16px;line-height:1.6;overflow:hidden}
+a{color:var(--accent);text-underline-offset:3px}
+button{font:inherit;cursor:pointer}
+.app{display:flex;height:100vh;height:100dvh}
+.rail{flex:0 0 272px;width:272px;height:100%;overflow-y:auto;border-right:1px solid var(--line);background:var(--rail);padding:18px 14px 40px;display:flex;flex-direction:column;gap:14px}
+.rail.mini{flex-basis:52px;width:52px;padding:18px 0;align-items:center;gap:4px}
+.rail .full{display:flex;flex-direction:column;gap:14px}
+.rail.mini .full,.rail:not(.mini) .strip{display:none}
+.strip{display:flex;flex-direction:column;align-items:center;gap:4px}
+.railhead{display:flex;align-items:flex-start;justify-content:space-between;gap:8px}
+.railhead b{font-family:var(--serif);font-weight:600;font-size:17px;line-height:1.3}
+.lbl{font-family:var(--mono);font-size:12px;letter-spacing:.12em;text-transform:uppercase;color:var(--accent)}
+.sq{border:1px solid var(--line-strong);background:var(--card);border-radius:6px;padding:2px 9px;color:var(--body);font-size:14px}
+.pill{border:1px solid var(--line-strong);background:var(--card);border-radius:99px;padding:2px 10px;color:var(--body);font-size:12px}
+.row{display:flex;gap:6px;flex-wrap:wrap}
+.group{display:flex;flex-direction:column;gap:2px}
+.ghead{font-size:12px;letter-spacing:.06em;text-transform:uppercase;font-weight:500;text-align:left;display:flex;gap:8px;align-items:center;width:100%;padding:6px 8px;border:0;background:transparent;color:var(--muted)}
+.ghead .n{font-family:var(--mono);font-size:11px;color:var(--quiet);margin-left:auto}
+.group.ro .ghead,.item.ro,.mini-item.ro{color:var(--trk-ink)}
+.item{font-size:14px;line-height:1.35;text-align:left;display:flex;gap:10px;align-items:baseline;width:100%;padding:6px 10px;border:0;border-radius:6px;border-left:3px solid transparent;background:transparent;color:var(--body)}
+.item .n{font-family:var(--mono);font-size:11px;min-width:18px;color:var(--num)}
+.item.on{border-left-color:var(--accent);background:var(--accent-bg);color:var(--accent-ink)}
+.item.on .n{color:var(--accent)}
+.group.shut .item{display:none}
+.mini-item{font-family:var(--mono);font-size:11px;width:30px;height:24px;border-radius:6px;border:1px solid transparent;background:transparent;color:var(--muted)}
+.mini-item.on{border-color:var(--accent);background:var(--accent-bg);color:var(--accent-ink)}
+main{flex:1 1 auto;min-width:0;height:100%;display:flex;flex-direction:column}
+.bar{flex:none;padding:0 40px;background:var(--paper)}
+.bar.top{border-bottom:1px solid var(--line)}
+.bar.foot{border-top:1px solid var(--line)}
+.inner{max-width:1000px;margin:0 auto}
+nav.inner{display:flex;flex-wrap:wrap;align-items:center;gap:6px;padding:14px 0;font-size:14px;color:var(--body)}
+nav .sep{color:var(--sep)}
+nav .tag{margin-left:auto}
+.tag{display:inline-block;font-family:var(--mono);font-size:11px;padding:1px 8px;border-radius:99px;border:1px solid var(--line-strong);color:var(--muted);white-space:nowrap}
+#scroll{flex:1 1 auto;min-height:0;overflow-y:auto;padding:26px 40px 48px}
+#scroll>.inner{display:flex;flex-direction:column;gap:26px}
+h1{margin:0;font-family:var(--serif);font-weight:600;font-size:42px;line-height:1.12}
+.trkstrip{display:flex;flex-wrap:wrap;align-items:center;gap:22px;background:var(--trk-bg);border:1px solid var(--trk-line);border-radius:8px;padding:10px 16px}
+.trkh{font-family:var(--mono);font-size:10px;letter-spacing:.12em;text-transform:uppercase;color:var(--trk-ink)}
+.kv{display:flex;flex-direction:column}
+.kv span:first-child{font-family:var(--mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--trk-label)}
+.kv span:last-child{font-size:14px;color:var(--trk-ink);font-weight:500}
+.pos{display:flex;align-items:center;gap:10px;padding-top:6px;font-family:var(--mono);font-size:12px;color:var(--quiet)}
+.pos::after{content:"";flex:1;height:1px;background:var(--line)}
+.part{display:flex;flex-direction:column;gap:18px}
+.part[hidden]{display:none}
+.part h2{margin:0;font-family:var(--serif);font-weight:600;font-size:32px;line-height:1.2}
+.part h3{margin:8px 0 0;font-family:var(--serif);font-weight:600;font-size:21px}
+.part h4{margin:4px 0 0;font-size:16px;font-weight:600}
+.part p,.part ul,.part ol{margin:0;max-width:780px}
+.part ul,.part ol{padding-left:22px;display:flex;flex-direction:column;gap:6px}
+.holds{font-size:18px;color:var(--body)}
+.part.ro .holds{color:var(--trk-ink)}
+.tablewrap{overflow-x:auto}
+table{width:100%;border-collapse:collapse;font-size:15px}
+th{text-align:left;font-family:var(--mono);font-size:11px;letter-spacing:.1em;text-transform:uppercase;color:var(--muted);font-weight:500;padding:8px 10px;border-bottom:1px solid var(--line-strong)}
+td{padding:9px 10px;border-bottom:1px solid var(--line-soft);vertical-align:top}
+code{font-family:var(--mono);font-size:.88em;background:var(--rail);border:1px solid var(--line);border-radius:4px;padding:0 4px}
+pre.code{margin:0;font-family:var(--mono);font-size:13px;background:var(--card);border:1px solid var(--line);border-radius:8px;padding:12px 14px;overflow-x:auto;line-height:1.55}
+pre.code code{background:none;border:0;padding:0}
+blockquote{margin:0;border-left:3px solid var(--accent);padding:6px 0 6px 16px;font-family:var(--serif);font-size:19px;line-height:1.5;display:flex;flex-direction:column;gap:10px}
+.path{font-family:var(--mono);font-size:.9em;color:var(--muted)}
+.fig{margin:0;border-top:1px solid var(--line-strong);border-bottom:1px solid var(--line-strong);padding:12px 0}
+.trk{background:var(--trk-bg);border:1px solid var(--trk-line);border-radius:8px;padding:14px 16px;display:flex;flex-direction:column;gap:10px}
+.trk .trkh{font-size:11px}
+.trk td,.trk th{border-color:var(--trk-line)}
+.none{color:var(--muted);font-style:italic}
+.draft{margin:0;border:1px solid var(--accent);background:var(--accent-bg);color:var(--accent-ink);border-radius:8px;padding:10px 14px}
+.st{font-family:var(--mono);font-size:12px}
+.st.open{color:var(--warn)}.st.answered,.st.done,.st.delivered{color:var(--yes)}
+.meter{height:10px;border-radius:99px;background:var(--line);overflow:hidden;display:flex}
+.meter i{display:block;height:100%;background:var(--yes)}
+.foot .inner{display:flex;align-items:center;gap:12px;padding:12px 0}
+.nav{font-size:14px;border-radius:8px;padding:6px 14px;width:240px;max-width:40vw;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+#prev{text-align:left;border:1px solid var(--line-strong);background:var(--card);color:var(--ink)}
+#next{text-align:right;border:0;background:var(--btn-bg);color:var(--btn-ink)}
+.nav:disabled{cursor:default;color:var(--faint)}
+#next:disabled{background:var(--line);color:var(--num)}
+.mid{flex:1;text-align:center;font-family:var(--mono);font-size:12px;color:var(--quiet);white-space:nowrap}
+kbd{border:1px solid var(--line-strong);border-radius:4px;padding:0 5px;font-family:var(--mono)}
+@media (max-width:760px){
+ .bar,#scroll{padding-left:16px;padding-right:16px}
+ .rail:not(.mini){position:fixed;z-index:5;left:0;top:0;bottom:0;box-shadow:0 0 0 100vmax rgba(0,0,0,.25)}
+ h1{font-size:30px}.part h2{font-size:25px}
+ .mid .keys{display:none}
+}
+@media print{body{overflow:visible}.app{display:block;height:auto}.rail,.bar.foot{display:none}#scroll{overflow:visible}.part[hidden]{display:flex}}
+`;
+
+const SCRIPT = `
+(function () {
+  var data = JSON.parse(document.getElementById('design-data').textContent);
+  var flat = [];
+  data.groups.forEach(function (g) { g.items.forEach(function (it) { flat.push(it); }); });
+  var root = document.documentElement;
+  var store = {
+    get: function (k) { try { return window.localStorage.getItem('atlas-design:' + k); } catch (e) { return null; } },
+    set: function (k, v) { try { window.localStorage.setItem('atlas-design:' + k, v); } catch (e) {} }
+  };
+  var dark = false;
+  try { dark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches; } catch (e) {}
+  var theme = store.get('theme') || (dark ? 'dark' : 'light');
+  var themeBtn = document.getElementById('theme');
+  function setTheme(t) { theme = t; root.setAttribute('data-theme', t); themeBtn.textContent = t === 'dark' ? '\\u2600 Light' : '\\u263E Dark'; }
+  setTheme(theme);
+  themeBtn.addEventListener('click', function () { setTheme(theme === 'dark' ? 'light' : 'dark'); store.set('theme', theme); });
+
+  var rail = document.getElementById('rail');
+  var narrow = false;
+  try { narrow = window.matchMedia('(max-width: 760px)').matches; } catch (e) {}
+  if (narrow || store.get('rail') === 'mini') rail.classList.add('mini');
+  document.querySelectorAll('[data-rail]').forEach(function (b) {
+    b.addEventListener('click', function () { rail.classList.toggle('mini'); store.set('rail', rail.classList.contains('mini') ? 'mini' : 'open'); });
+  });
+  document.querySelectorAll('.group .ghead').forEach(function (b) {
+    b.addEventListener('click', function () { var g = b.parentNode; g.classList.toggle('shut'); b.setAttribute('aria-expanded', String(!g.classList.contains('shut'))); b.querySelector('.chev').textContent = g.classList.contains('shut') ? '\\u25B8' : '\\u25BE'; });
+  });
+  function setAll(open) { document.querySelectorAll('.group').forEach(function (g) { g.classList.toggle('shut', !open); var b = g.querySelector('.ghead'); b.setAttribute('aria-expanded', String(open)); b.querySelector('.chev').textContent = open ? '\\u25BE' : '\\u25B8'; }); }
+  document.getElementById('open-all').addEventListener('click', function () { setAll(true); });
+  document.getElementById('close-all').addEventListener('click', function () { setAll(false); });
+
+  var scroll = document.getElementById('scroll');
+  var prev = document.getElementById('prev');
+  var next = document.getElementById('next');
+  var idx = 0;
+  function go(i, keepHash) {
+    if (i < 0 || i >= flat.length) return;
+    idx = i;
+    var cur = flat[i];
+    document.querySelectorAll('.part').forEach(function (s) { s.hidden = s.getAttribute('data-part') !== cur.id; });
+    document.querySelectorAll('[data-go]').forEach(function (b) {
+      var on = b.getAttribute('data-go') === cur.id;
+      b.classList.toggle('on', on);
+      if (on) b.setAttribute('aria-current', 'true'); else b.removeAttribute('aria-current');
+    });
+    document.getElementById('pos').textContent = 'PART ' + (i + 1) + ' OF ' + flat.length + ' \\u00B7 ' + cur.name.toUpperCase() + (cur.ro ? ' \\u00B7 FROM THE TRACKER' : '');
+    document.getElementById('count').textContent = (i + 1) + ' / ' + flat.length;
+    prev.disabled = i === 0; next.disabled = i === flat.length - 1;
+    prev.textContent = '\\u2190 ' + (i > 0 ? flat[i - 1].name : 'Start');
+    next.textContent = (i < flat.length - 1 ? flat[i + 1].name : 'End') + ' \\u2192';
+    scroll.scrollTop = 0;
+    if (!keepHash) { try { history.replaceState(null, '', '#' + cur.id); } catch (e) {} }
+    if (narrow) rail.classList.add('mini');
+  }
+  function find(id) { for (var i = 0; i < flat.length; i++) if (flat[i].id === id) return i; return -1; }
+  document.querySelectorAll('[data-go]').forEach(function (b) { b.addEventListener('click', function () { go(find(b.getAttribute('data-go'))); }); });
+  document.addEventListener('click', function (ev) {
+    var a = ev.target.closest && ev.target.closest('a[data-part]');
+    if (!a) return;
+    var i = find(a.getAttribute('data-part'));
+    if (i >= 0) { ev.preventDefault(); go(i); }
+  });
+  prev.addEventListener('click', function () { go(idx - 1); });
+  next.addEventListener('click', function () { go(idx + 1); });
+  document.addEventListener('keydown', function (ev) {
+    if (ev.metaKey || ev.ctrlKey || ev.altKey || ev.shiftKey) return;
+    var t = ev.target;
+    if (t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.tagName === 'SELECT' || t.isContentEditable)) return;
+    if (ev.key === 'ArrowRight') { ev.preventDefault(); go(idx + 1); }
+    if (ev.key === 'ArrowLeft') { ev.preventDefault(); go(idx - 1); }
+  });
+  var start = find((location.hash || '').slice(1));
+  go(start >= 0 ? start : 0, start < 0);
+})();
+`;
+
+const dateOf = (value) => (value ? String(value).slice(0, 10) : '');
+const stateTag = (value) => `<span class="st ${esc(String(value ?? '').toLowerCase())}">${esc(value ?? '')}</span>`;
+const table = (head, rows) => `<div class="tablewrap"><table><thead><tr>${head.map((cell) => `<th>${cell}</th>`).join('')}</tr></thead><tbody>${rows.map((row) => `<tr>${row.map((cell) => `<td>${cell}</td>`).join('')}</tr>`).join('')}</tbody></table></div>`;
+const linkTo = (label, url) => (url && /^https?:\/\//.test(url) ? `<a href="${esc(url)}" target="_blank" rel="noopener">${esc(label)}</a>` : esc(label));
+
+// The tracker file's shape: each key and the type of its value. A key that
+// is not here is refused, so a hand-made field cannot reach the page.
+const SHAPE = {
+  top: { read_at: 'string', item: 'object', questions: 'array', decisions: 'array', links: 'array', family: 'array' },
+  item: { id: 'string', title: 'string', lifecycle: 'string', stage: 'string', tier: 'string', locked_at: 'string|null', origin: 'object|null' },
+  origin: { text: 'string', source: 'string', date: 'string' },
+  questions: { id: 'string', text: 'string', status: 'string', answer: 'string|null' },
+  decisions: { id: 'string', kind: 'string', date: 'string', text: 'string', source: 'string' },
+  links: { kind: 'string', url: 'string', role: 'string', note: 'string' },
+  family: { id: 'string', title: 'string', lifecycle: 'string', url: 'string' },
+};
+const typeOf = (value) => (value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value);
+
+export function validateTracker(data) {
+  const faults = [];
+  const fields = (value, shape, where) => {
+    if (typeOf(value) !== 'object') { faults.push(`${where} must be an object`); return; }
+    for (const [key, one] of Object.entries(value)) {
+      if (!Object.hasOwn(shape, key)) { faults.push(`${where}.${key} is not a tracker field`); continue; }
+      if (!shape[key].split('|').includes(typeOf(one))) faults.push(`${where}.${key} must be ${shape[key].replace('|', ' or ')}`);
+    }
+  };
+  fields(data, SHAPE.top, 'the tracker file');
+  if (faults.length) return faults;
+  if (data.item) {
+    fields(data.item, SHAPE.item, 'item');
+    if (data.item.origin) fields(data.item.origin, SHAPE.origin, 'item.origin');
+  }
+  for (const list of ['questions', 'decisions', 'links', 'family']) (data[list] ?? []).forEach((row, index) => fields(row, SHAPE[list], `${list}[${index}]`));
+  for (const row of data.questions ?? []) if (row.status !== undefined && !['open', 'answered'].includes(row.status)) faults.push(`a question's status must be open or answered, not "${row.status}"`);
+  return faults;
+}
+
+// The body of each tracker part, from the JSON. Never from the folder.
+function trackerBody(id, tracker) {
+  if (!tracker) return '<p class="none">This page was built with no tracker data. The lead passes it with --tracker.</p>';
+  const item = tracker.item ?? {};
+  const questions = tracker.questions ?? [];
+  const decisions = tracker.decisions ?? [];
+  const family = tracker.family ?? [];
+  const lockedOn = item.locked_at ? dateOf(item.locked_at) : null;
+  const decisionRows = (rows) => rows.map((one) => `<div class="kv"><span>${esc(dateOf(one.date))}${one.kind ? ` · ${esc(one.kind)}` : ''}</span></div><blockquote><p>${esc(one.text)}</p></blockquote>`).join('\n');
+  switch (id) {
+    case 'questions':
+      return questions.length
+        ? table(['Question', 'State', 'Answer'], questions.map((one) => [esc(one.text), stateTag(one.status), esc(one.answer ?? '')]))
+        : '<p class="none">No questions.</p>';
+    case 'decisions':
+      return decisions.length ? decisionRows(decisions) : '<p class="none">No decisions yet.</p>';
+    case 'approval':
+      if (!lockedOn) return '<p class="none">Not approved yet. The owner approves the design in his own words, and the lock records them.</p>';
+      return `${item.origin?.text ? `<blockquote><p>${esc(item.origin.text)}</p></blockquote>` : ''}<p>Approved and locked ${esc(lockedOn)}${item.origin?.source ? `, ${esc(item.origin.source)}` : ''}.</p>`;
+    case 'since': {
+      if (!lockedOn) return '<p class="none">Not approved yet, so nothing has changed since approval.</p>';
+      const after = decisions.filter((one) => dateOf(one.date) > lockedOn);
+      return after.length ? decisionRows(after) : '<p class="none">No change since approval.</p>';
+    }
+    case 'family':
+      return family.length
+        ? table(['Design', 'State'], family.map((one) => [linkTo(one.title ?? one.id ?? '', one.url), stateTag(one.lifecycle)]))
+        : '<p class="none">No linked designs.</p>';
+    case 'rollup': {
+      if (!family.length) return '<p class="none">No linked designs.</p>';
+      const done = family.filter((one) => one.lifecycle === 'done').length;
+      const counts = new Map();
+      for (const one of family) counts.set(one.lifecycle, (counts.get(one.lifecycle) ?? 0) + 1);
+      return `<p>${done} of ${family.length} designs done.</p><div class="meter" role="img" aria-label="${done} of ${family.length} done"><i style="width:${Math.round((100 * done) / family.length)}%"></i></div>${table(['State', 'Designs'], [...counts].map(([state, count]) => [stateTag(state), String(count)]))}`;
+    }
+    default: return '';
+  }
+}
+
+// A design with check findings builds only as a draft, and the page says so.
+export function buildDesign(folder, { tracker = null, draft = false, registry = loadRegistry() } = {}) {
+  if (tracker) {
+    const faults = validateTracker(tracker);
+    if (faults.length) throw new Error(`the tracker data is refused: ${faults.join('; ')}`);
+  }
+  const design = readDesign(folder);
+  const findings = checkDesign(design, registry);
+  if (findings.length && !draft) return { html: null, findings, parts: 0, groups: 0, figures: 0 };
+  const meta = design.meta ?? {};
+  const kinds = Array.isArray(meta.kinds) ? meta.kinds.filter((kind) => registry.kindIds.includes(kind)) : [];
+  const fileOf = new Map(design.parts.filter((one) => registry.byId.has(one.part)).map((one) => [one.part, one]));
+  const partByFile = new Map([...fileOf].map(([id, one]) => [one.file, id]));
+  const figures = [];
+
+  // The rail: each group with the parts this folder holds, in registry
+  // order, then the tracker group.
+  const groups = [];
+  for (const group of registry.groups) {
+    if (group.id === 'tracker') continue;
+    const items = registry.parts.filter((part) => part.group === group.id && fileOf.has(part.id)).map((part) => ({ id: part.id, name: part.name, ro: false }));
+    if (items.length) groups.push({ id: group.id, name: group.name, ro: false, items });
+  }
+  const trackerParts = registry.tracker.filter((row) => (row.id === 'rollup' ? kinds.includes('initiative') : row.id === 'family' ? kinds.includes('initiative') || (tracker?.family ?? []).length > 0 : true));
+  const trackerGroup = registry.groups.find((group) => group.id === 'tracker');
+  groups.push({ id: 'tracker', name: trackerGroup.name, ro: true, items: trackerParts.map((row) => ({ id: row.id, name: row.name, ro: true })) });
+
+  const sections = [];
+  let number = 0;
+  for (const group of groups) {
+    for (const item of group.items) {
+      number += 1;
+      if (item.ro) {
+        const row = registry.tracker.find((one) => one.id === item.id);
+        sections.push(`<section class="part ro" data-part="${item.id}" id="part-${item.id}" hidden><h2>${esc(row.name)}</h2><p class="holds">${esc(row.holds)}</p><div class="trk"><span class="trkh">From the tracker · read only${tracker?.read_at ? ` · read ${esc(String(tracker.read_at).replace('T', ' ').slice(0, 16))}` : ''}</span>${trackerBody(item.id, tracker)}</div></section>`);
+        continue;
+      }
+      const one = fileOf.get(item.id);
+      const ctx = { file: one.file, page: item.id, figures, partOf: (href) => partByFile.get(href.split('#')[0]) ?? null };
+      const { title, html } = render(one.body, ctx);
+      const heading = one.title ?? title ?? item.name;
+      sections.push(`<section class="part" data-part="${item.id}" id="part-${item.id}" hidden><h2>${esc(heading)}</h2>\n${html}\n</section>`);
+    }
+  }
+
+  const strip = tracker
+    ? [['Item', tracker.item?.title ?? tracker.item?.id ?? '—'], ['Lifecycle', tracker.item?.lifecycle ?? '—'], ['Stage', tracker.item?.stage ?? '—'],
+      ['Open questions', String((tracker.questions ?? []).filter((one) => one.status === 'open').length)], ['Read', String(tracker.read_at ?? '—').replace('T', ' ').slice(0, 16)]]
+    : [['Tracker', 'Not read for this build']];
+  const kindLabel = `${kinds.map((kind) => registry.kinds.find((one) => one.id === kind).name).join(' + ') || 'No kind'}${meta.shared ? ' · shared' : ''}`;
+  const title = meta.title ?? basename(design.root);
+  const crumbs = [meta.product, 'Design docs'].filter(Boolean).map((one) => `<span>${esc(one)}</span><span class="sep">/</span>`).join('');
+  const data = { groups: groups.map((group) => ({ id: group.id, items: group.items })) };
+  let n = 0;
+  const railGroups = groups.map((group) => `<div class="group${group.ro ? ' ro' : ''}"><button type="button" class="ghead" aria-expanded="true"><span class="chev">▾</span><span>${esc(group.name)}</span><span class="n">${group.items.length}</span></button>${group.items.map((item) => { n += 1; return `<button type="button" class="item${item.ro ? ' ro' : ''}" data-go="${item.id}"><span class="n">${n}</span><span>${esc(item.name)}</span></button>`; }).join('')}</div>`).join('\n');
+  let m = 0;
+  const miniItems = groups.flatMap((group) => group.items).map((item) => { m += 1; return `<button type="button" class="mini-item${item.ro ? ' ro' : ''}" data-go="${item.id}" title="${esc(item.name)}">${m}</button>`; }).join('');
+  const woodcut = figures.some((one) => one !== 'custom');
+
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Lora:ital,wght@0,500;0,600;1,500&family=Poppins:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
+<style>${CSS}</style>
+<noscript><style>body{overflow:auto}.app{display:block;height:auto}.rail,.bar.foot,.pos{display:none}#scroll{overflow:visible}.part[hidden]{display:flex;margin-bottom:40px}</style></noscript>
+</head>
+<body>
+<div class="app">
+<aside class="rail" id="rail" aria-label="Parts of the design">
+<div class="full">
+<div class="railhead"><div class="kv"><span class="lbl">${esc(kindLabel)}</span><b>${esc(title)}</b></div><button type="button" class="sq" data-rail aria-label="Fold the side rail" title="Fold">«</button></div>
+<div class="row"><button type="button" class="pill" id="open-all">Expand all</button><button type="button" class="pill" id="close-all">Collapse all</button></div>
+${railGroups}
+</div>
+<div class="strip"><button type="button" class="sq" data-rail aria-label="Open the side rail" title="Open" style="margin-bottom:10px">»</button>${miniItems}</div>
+</aside>
+<main>
+<div class="bar top"><nav class="inner">${crumbs}<b style="font-weight:500">${esc(title)}</b><span class="tag">${esc(kindLabel.toUpperCase())}</span><button type="button" class="pill" id="theme" aria-label="Switch light or dark">☾ Dark</button></nav></div>
+<div id="scroll"><div class="inner">
+<header style="display:flex;flex-direction:column;gap:12px"><h1>${esc(title)}</h1>
+<div class="trkstrip"><span class="trkh">From the tracker</span>${strip.map(([k, v]) => `<span class="kv"><span>${esc(k)}</span><span>${esc(v)}</span></span>`).join('')}</div></header>
+${findings.length ? `<p class="draft">Draft: <code>atlas design check</code> has ${findings.length} finding(s) on this design.</p>` : ''}
+<div class="pos" id="pos"></div>
+${sections.join('\n')}
+</div></div>
+<div class="bar foot"><div class="inner"><button type="button" class="nav" id="prev" aria-label="Previous part"></button><span class="mid"><span id="count"></span><span class="keys"> · <kbd>←</kbd> <kbd>→</kbd> to move</span></span><button type="button" class="nav" id="next" aria-label="Next part"></button></div></div>
+</main>
+</div>
+<script type="application/json" id="design-data">${JSON.stringify(data).replace(/<\//g, '<\\/')}</script>
+${woodcut ? `<script type="module" src="${WOODCUT}"></script>\n` : ''}<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+  return { html, findings, parts: number, groups: groups.length, figures: figures.length };
+}
+
+export function readTracker(path) {
+  let data;
+  try { data = JSON.parse(readFileSync(path, 'utf8')); }
+  catch (error) { throw new Error(`the tracker file ${path} is not JSON: ${error.message}`); }
+  const faults = validateTracker(data);
+  if (faults.length) throw new Error(`the tracker file ${path} is refused: ${faults.join('; ')}`);
+  return data;
+}
+
+export function writeDesignPage(folder, out, options = {}) {
+  const result = buildDesign(folder, options);
+  if (!result.html) return result;
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, result.html);
+  return result;
+}