@liggi/figkit 0.4.0 → 0.6.0

package/viz/draw.js

@@ -1,6 +1,8 @@
 /* The chart types, drawn into a host element styled by runtime/fig.css. Figures use them through runtime/fig.js. */
 import * as Plot from '@observablehq/plot';
 import { drawSequence } from './sequence.js';
+import { drawStates } from './states.js';
+import { drawMap } from './map.js';
 const NS = 'http://www.w3.org/2000/svg';
 const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 
@@ -84,11 +86,15 @@ export function drawSplit(host, parts, unit) {
  * A few numbers compared into a <fig-bars>, on an axis from zero to max (default: the largest value or high). A bar
  * with `low` and `high` gets a range drawn across its end, and its number moves past the range; `n` goes under its label.
  */
-export function drawBars(host, bars, unit, max, each) {
-  const top = max ?? Math.max(...bars.map((b) => Math.max(b.value, b.high ?? 0)));
+export function drawBars(host, bars, unit, max, each, ref) {
+  const top = max ?? Math.max(...bars.map((b) => Math.max(b.value, b.high ?? 0)), ref?.value ?? 0);
   host.innerHTML = '';
+  host.classList.toggle('has-ref', !!ref);
+  // A reference is its own first row, in the second colour; a bar above it (its whole range, when it has one) is
+  // accented and every other bar is grey.
+  if (ref) bars = [{ ...ref, text: String(ref.value), tone: 'second', isRef: true }, ...bars.map((b) => ({ ...b, tone: (b.low ?? b.value) > ref.value ? 'accent' : undefined }))];
   const fills = bars.map((b) => {
-    const label = Object.assign(document.createElement('div'), { className: 'fb-label', innerHTML: b.label + (b.n !== undefined ? `<span class="fb-n">${each ? `${esc(b.n.toLocaleString('en-GB'))} ${esc(each)}` : `n = ${esc(b.n.toLocaleString('en-GB'))}`}</span>` : '') });
+    const label = Object.assign(document.createElement('div'), { className: 'fb-label' + (b.isRef ? ' ref' : ''), innerHTML: b.label + (b.n !== undefined ? `<span class="fb-n">${each ? `${esc(b.n.toLocaleString('en-GB'))} ${esc(each)}` : `n = ${esc(b.n.toLocaleString('en-GB'))}`}</span>` : '') });
     const track = Object.assign(document.createElement('div'), { className: 'fb-track' });
     const tone = b.tone ? ' ' + b.tone : '';
     const ranged = b.low !== undefined;
@@ -109,6 +115,20 @@ export function drawBars(host, bars, unit, max, each) {
     f.range.style.width = at(f.hi - f.lo);
     f.val.style.marginLeft = `max(0px, calc((100% - ${room}px) * ${f.hi - f.ratio} - 3px))`;
   }
+  if (!ref) return;
+  // The reference level as a dashed line from the end of its bar down through every other row; a value that would
+  // sit on the line is moved past it.
+  const line = document.createElement('div');
+  line.className = 'fb-refline';
+  host.appendChild(line);
+  const hostBox = host.getBoundingClientRect();
+  const refBar = fills[0].bar.getBoundingClientRect(), last = fills[fills.length - 1].bar.parentElement.getBoundingClientRect();
+  const x = refBar.right - hostBox.left;
+  Object.assign(line.style, { left: `${x - 1}px`, top: `${refBar.bottom - hostBox.top}px`, height: `${last.bottom - refBar.bottom}px` });
+  for (const f of fills.slice(1)) {
+    const v = f.val.getBoundingClientRect();
+    if (v.left - hostBox.left < x + 8 && v.right - hostBox.left > x - 8) f.val.style.marginLeft = `${parseFloat(getComputedStyle(f.val).marginLeft) + (x + 10 - (v.left - hostBox.left))}px`;
+  }
 }
 
 /** What the ranges are, as a key line under the reading line: the mark as drawn, then the words. */
@@ -116,7 +136,8 @@ function rangeKey(spec) {
   const p = document.createElement('p');
   p.className = 'range-key';
   p.innerHTML = (spec.range ? `<span><i class="${spec.type === 'bars' ? 'whisker' : 'band'}"></i>${esc(spec.range)}</span>` : '')
-    + (spec.ref ? `<span><i class="dash"></i>${esc(spec.ref.label)}</span>` : '');
+    + (spec.ref && spec.type !== 'bars' ? `<span><i class="dash"></i>${esc(spec.ref.label)}</span>` : '')
+    + (spec.ref && spec.type === 'bars' && spec.bars.some((b) => (b.low ?? b.value) > spec.ref.value) ? `<span><i class="swatch"></i>${spec.range ? 'whole range ' : ''}above ${esc(spec.ref.label)}</span>` : '');
   return p;
 }
 
@@ -316,20 +337,45 @@ function drawEntities(spec, main) {
   }
 }
 
-const HOSTS = { split: 'fig-split', bars: 'fig-bars', 'before-after': 'fig-change', dumbbell: 'div', series: 'div', groups: 'div', lines: 'div', panels: 'div', heatmap: 'div', dots: 'div', scatter: 'div', units: 'div' };
+const HOSTS = { split: 'fig-split', bars: 'fig-bars', estimates: 'div', 'before-after': 'fig-change', dumbbell: 'div', series: 'div', groups: 'div', lines: 'div', panels: 'div', heatmap: 'div', dots: 'div', scatter: 'div', units: 'div' };
 
 /** A checked spec drawn into a figure: header, chart and footer, as figkit's own markup. */
 export function drawSpec(spec, main) {
   const header = document.createElement('header');
   header.innerHTML = `<h1>${esc(spec.title)}</h1>${spec.note ? `<p class="read">${esc(spec.note)}</p>` : ''}`;
   // What the ranges and a reference line are, said once under the reading line: there they never sit on the data.
-  if (spec.range || spec.ref) header.appendChild(rangeKey(spec));
+  if (spec.type === 'estimates') header.appendChild(estimatesKey(spec));
+  else if (spec.range || spec.ref) header.appendChild(rangeKey(spec));
   if (spec.type === 'entities') {
     main.append(header);
     drawEntities(spec, main);
     if (spec.source) { const footer = document.createElement('footer'); footer.innerHTML = `<p>${esc(spec.source)}</p>`; main.append(footer); }
     return { chart: main.querySelector('.entities'), draw: () => {} };
   }
+  if (spec.type === 'states') {
+    if (spec.moves.some((m) => m.count != null)) {
+      const key = document.createElement('p');
+      key.className = 'read st-key';
+      key.textContent = `Counts are ${spec.each} who made each move at least once${spec.shares ? '; % of those who reached the state it leaves' : ''}.`;
+      header.appendChild(key);
+    }
+    main.append(header);
+    const chart = drawStates(spec, main);
+    if (spec.source) { const footer = document.createElement('footer'); footer.innerHTML = `<p>${esc(spec.source)}</p>`; main.append(footer); }
+    return { chart, draw: () => {} };
+  }
+  if (spec.type === 'map') {
+    if (main.classList.contains('phone')) {
+      const key = document.createElement('p');
+      key.className = 'read mp-key';
+      key.textContent = 'Each box is a subsystem; numbers count the links between their parts.';
+      header.appendChild(key);
+    }
+    main.append(header);
+    const footer = spec.source ? Object.assign(document.createElement('footer'), { innerHTML: `<p>${esc(spec.source)}</p>` }) : null;
+    const ready = drawMap(spec, main).then((chart) => { if (footer) main.append(footer); return chart; });
+    return { chart: null, draw: () => {}, ready };
+  }
   if (spec.type === 'sequence') {
     main.append(header);
     const chart = drawSequence(spec, main);
@@ -346,6 +392,7 @@ export function drawSpec(spec, main) {
   const draw = () => {
     if (spec.type === 'before-after') return drawChange(chart, spec);
     if (spec.type === 'dumbbell') return drawDumbbell(chart, spec);
+    if (spec.type === 'estimates') return drawEstimates(chart, spec);
     if (spec.type === 'series') return drawSeries(chart, spec);
     if (spec.type === 'groups') return drawGroups(chart, spec, { unit: spec.unit, max: spec.max });
     if (spec.type === 'lines') return drawLines(chart, spec, { unit: spec.unit, xTicks: spec.xTicks });
@@ -356,7 +403,7 @@ export function drawSpec(spec, main) {
     if (spec.type === 'units') return drawUnits(chart, spec);
     const items = (spec.parts ?? spec.bars).map((x) => ({ ...x, text: String(x.value), label: esc(x.label) }));
     if (spec.type === 'split') drawSplit(chart, items, spec.unit);
-    else drawBars(chart, items, spec.unit, spec.max, spec.each);
+    else drawBars(chart, items, spec.unit, spec.max, spec.each, spec.ref && { ...spec.ref, label: esc(spec.ref.label) });
   };
   draw();
   return { chart, draw };
@@ -484,14 +531,26 @@ export function drawPanels(host, spec) {
  */
 export function drawHeatmap(host, spec) {
   const t = themeOf(host);
+  host.classList.add('heatmap');
   const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 420;
   const cells = spec.rows.flatMap((r, i) => spec.columns.map((c, j) => ({ r: String(r), c: String(c), v: spec.values[i][j] })));
   const vs = cells.map((d) => d.v), lo = Math.min(...vs), hi = Math.max(...vs);
-  // One hue, near white to dark: darker is always more, and busy does not read as alarm the way red does.
-  const scale = Plot.scale({ color: { type: 'linear', scheme: 'blues', domain: [lo - (hi - lo) * 0.08, hi] } });
-  const colour = (v) => scale.apply(v);
-  const ramp = [0, 0.25, 0.5, 0.75, 1].map((p) => colour(lo + (hi - lo) * p)).join(', ');
-  const fmt = (v) => num(v) + (spec.unit ?? '');
+  // Any value below zero makes the grid signed: a diverging scale around zero, orange below and blue above, equal
+  // distances from zero equally strong. Otherwise one hue, near white to dark: darker is always more.
+  const diverging = lo < 0;
+  const places = placesOf(vs);
+  const fmt = (v) => (diverging ? signed(v, places) : Number(v.toFixed(places)).toLocaleString('en-GB', { minimumFractionDigits: places })) + (spec.unit ?? '');
+  const scale = diverging ? null : Plot.scale({ color: { type: 'linear', scheme: 'blues', domain: [lo - (hi - lo) * 0.08, hi] } });
+  const MID = '#f2f2f0', NEG = '#a63603', POS = '#08519c', far = Math.max(-lo, hi) || 1;
+  const colour = (v) => (!diverging ? scale.apply(v) : v < 0 ? mix(MID, NEG, -v / far) : mix(MID, POS, v / far));
+  // Cell text in dark or white, whichever reads against the cell, whatever the theme's ink.
+  const lum = (c) => { const m = /rgb\((\d+), (\d+), (\d+)\)/.exec(c); const x = m ? m.slice(1).map(Number) : hex(c) ?? [0, 0, 0]; const [r, g, b] = x.map((v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; }); return 0.2126 * r + 0.7152 * g + 0.0722 * b; };
+  const textOn = (v) => { const L = lum(colour(v)); return (L + 0.05) / (lum('#1d2130') + 0.05) >= 1.05 / (L + 0.05) ? '#1d2130' : '#ffffff'; };
+  const K = phone ? 120 : 200, z = Math.round((100 * -lo) / (hi - lo || 1));
+  // Signed: one bar through zero, with 0 marked where it falls on the scale.
+  const ramp = diverging
+    ? `<span>${esc(fmt(lo))}</span><i class="hm-signed" style="width:${K}px;background:linear-gradient(90deg, ${colour(lo)}, ${MID} ${z}%, ${colour(Math.max(hi, 0))})"><b style="left:${z}%">0</b></i><span>${esc(fmt(hi))}</span>`
+    : `<span>${esc(fmt(lo))}</span><i style="background:linear-gradient(90deg, ${[0, 0.25, 0.5, 0.75, 1].map((p) => colour(lo + (hi - lo) * p)).join(', ')})"></i><span>${esc(fmt(hi))}</span>`;
   const cols = spec.columns.map(String), rows = spec.rows.map(String);
   const labelW = Math.ceil(widest(host, rows, t.small)) + 12;
   const cellW = (width - labelW - 8) / cols.length;
@@ -502,7 +561,7 @@ export function drawHeatmap(host, spec) {
   const rowH = phone ? 30 : 36;
   const key = document.createElement('p');
   key.className = 'hm-key';
-  key.innerHTML = `<span>${esc(fmt(lo))}</span><i style="background:linear-gradient(90deg, ${ramp})"></i><span>${esc(fmt(hi))}</span>`
+  key.innerHTML = ramp
     + (spec.mark ? `<span style="margin-left:14px;white-space:nowrap;display:inline-flex;align-items:center;gap:8px;color:${t.ink};font-weight:600"><i style="width:16px;height:16px;border:2.5px solid ${t.accent};border-radius:2px;background:none"></i>${esc(spec.mark.label)}</span>` : '');
   plotInto(host, t, {
     width, height: rows.length * rowH + 36, marginLeft: labelW, marginRight: 8, marginTop: 0, marginBottom: 36,
@@ -510,7 +569,7 @@ export function drawHeatmap(host, spec) {
     y: { domain: rows, label: null, tickSize: 0, padding: 0.08 },
     marks: [
       Plot.cell(cells, { x: 'c', y: 'r', fill: (d) => colour(d.v), inset: 0.5 }),
-      show ? Plot.text(cells, { x: 'c', y: 'r', text: (d) => fmt(d.v), fill: (d) => ((d.v - lo) / (hi - lo || 1) > 0.55 ? '#ffffff' : t.ink), fontSize: t.small }) : null,
+      show ? Plot.text(cells, { x: 'c', y: 'r', text: (d) => fmt(d.v), fill: (d) => textOn(d.v), fontSize: t.small }) : null,
       // The marked cell: an accent ring, the one thing in the chart that is not the scale.
       spec.mark ? Plot.cell([{ r: String(spec.mark.row), c: String(spec.mark.column) }], { x: 'c', y: 'r', fill: 'none', stroke: t.accent, strokeWidth: 2.5 }) : null,
     ],
@@ -519,6 +578,101 @@ export function drawHeatmap(host, spec) {
   host.prepend(key);
 }
 
+// ---------- signed estimates with ranges around zero (a forest plot) ----------
+
+/** Decimal places the author wrote, at most 3, so -0.18 is not printed as -0.2. */
+const placesOf = (vs) => Math.min(3, Math.max(0, ...vs.map((v) => { const m = /\.(\d+)/.exec(String(v)); return m ? m[1].length : 0; })));
+/** A signed number with a true minus sign: +7.4, −0.7, 0. */
+const signed = (v, places) => { const r = Math.abs(v).toFixed(places); return (+r === 0 ? '' : v > 0 ? '+' : '−') + r; };
+
+/**
+ * One row per estimate into a .chart: a dot at the value, a line across its range and a zero line through all of
+ * them. A row whose range clears zero is coloured; one whose range includes zero is grey with a hollow dot. Each row's
+ * value and range are printed in a column at the right; on a phone they go on a line above the row with its label.
+ */
+export function drawEstimates(host, spec) {
+  const t = themeOf(host);
+  host.classList.add('estimates');
+  const width = Math.floor(host.clientWidth) || 640;
+  const places = placesOf(spec.rows.flatMap((r) => [r.value, r.low, r.high]));
+  const u = spec.unit ?? '';
+  const rows = spec.rows.map((r, i) => {
+    const clear = r.low > 0 || r.high < 0;
+    const good = spec.better ? (r.value > 0) === (spec.better === 'higher') : null;
+    const color = !clear ? t.soft : good === null ? t.accent : good ? t.good : t.bad;
+    const n = r.n === undefined ? '' : spec.each ? `${r.n.toLocaleString('en-GB')} ${spec.each}` : `n = ${r.n.toLocaleString('en-GB')}`;
+    return { ...r, i, clear, color, n, val: signed(r.value, places) + u, span: `${signed(r.low, places)} to ${signed(r.high, places)}` };
+  });
+  // Zero always shows, with room on its empty side, so the line it is measured from is never the frame's edge.
+  const lo0 = Math.min(0, ...rows.map((r) => r.low)), hi0 = Math.max(0, ...rows.map((r) => r.high));
+  const room = (hi0 - lo0 || 1) * 0.1;
+  let lo = Math.min(lo0 - room * 0.5, -room), hi = Math.max(hi0 + room * 0.5, room);
+  const spanW = Math.ceil(widest(host, rows.map((r) => r.span), t.small));
+  const labelW = Math.ceil(widest(host, rows.map((r) => r.label), t.body));
+  const side = 12, plotW = width - 2 * side, ticks = Math.max(3, Math.min(6, Math.floor(plotW / 120)));
+  // Room each side of zero for the words saying what that side means, so they meet at the zero line.
+  if (spec.sides) {
+    const need = (txt) => Math.min(plotW * 0.35, widest(host, [txt], t.small) + 24);
+    const nb = need('← ' + spec.sides.below), na = need(spec.sides.above + ' →');
+    if (-lo / (hi - lo) * plotW < nb) lo = -(nb * hi) / (plotW - nb);
+    if (hi / (hi - lo) * plotW < na) hi = (na * -lo) / (plotW - na);
+  }
+  // Each row is a line of text (its label at the left, its value and range at the right) over its range. y runs in
+  // row units from the top: the text sits at a third of the row, the range at 0.72 of it.
+  const rowH = 84, T = 0.32, M = 0.72;
+  const halo = { stroke: t.paper, strokeWidth: 8, paintOrder: 'stroke' };
+  const tick = (d) => signed(d, Math.max(0, places - 1)) + (u.length <= 2 ? u : '');
+  const raw = (hi - lo) / ticks, mag = 10 ** Math.floor(Math.log10(raw)), step = [1, 2, 2.5, 5, 10].map((k) => k * mag).find((k) => (hi - lo) / k <= ticks + 1);
+  const tickVals = []; for (let v = Math.ceil(lo / step) * step; v <= hi + 1e-9; v += step) tickVals.push(+v.toFixed(10));
+  // The grid and the zero line run from just under each row's text to the next row, never through text.
+  const spans = rows.map((r) => ({ y1: r.i + 0.5, y2: r.i + 1 }));
+  const nW = rows[0].n ? Math.ceil(widest(host, rows.map((r) => r.n), t.small)) : 0;
+  plotInto(host, t, {
+    width, height: rows.length * rowH + 40, marginLeft: side, marginRight: side, marginTop: 0, marginBottom: 40,
+    x: { domain: [lo, hi], ticks: tickVals, label: null, tickFormat: tick, tickSize: 0 },
+    y: { domain: [0, rows.length], range: [0, rows.length * rowH], axis: null },
+    marks: [
+      ...tickVals.filter((v) => v !== 0).map((v) => Plot.ruleX(spans, { x: () => v, y1: 'y1', y2: 'y2', stroke: t.hair })),
+      Plot.ruleX(spans, { x: () => 0, y1: 'y1', y2: 'y2', stroke: t.ink, strokeWidth: 1.5 }),
+      Plot.link(rows, { x1: 'low', x2: 'high', y1: (r) => r.i + M, y2: (r) => r.i + M, stroke: 'color', strokeWidth: 3 }),
+      Plot.ruleX(rows.flatMap((r) => [{ ...r, x: r.low }, { ...r, x: r.high }]), { x: 'x', y1: (r) => r.i + M - 9 / rowH, y2: (r) => r.i + M + 9 / rowH, stroke: 'color', strokeWidth: 3 }),
+      Plot.dot(rows, { x: 'value', y: (r) => r.i + M, r: 7.5, fill: (r) => (r.clear ? r.color : t.paper), stroke: 'color', strokeWidth: 2.5 }),
+      Plot.text(rows, { y: (r) => r.i + T, frameAnchor: 'left', dx: -side, text: 'label', textAnchor: 'start', fill: t.ink, fontSize: t.body, ...halo }),
+      nW ? Plot.text(rows, { y: (r) => r.i + T, frameAnchor: 'left', dx: -side + labelW + 12, text: 'n', textAnchor: 'start', fill: t.soft, fontSize: t.small, ...halo }) : null,
+      Plot.text(rows, { y: (r) => r.i + T, frameAnchor: 'right', dx: side - spanW - 12, text: 'val', textAnchor: 'end', fill: (r) => (r.clear ? r.color : t.muted), fontWeight: (r) => (r.clear ? 600 : 400), fontSize: t.body, ...halo }),
+      Plot.text(rows, { y: (r) => r.i + T, frameAnchor: 'right', dx: side, text: 'span', textAnchor: 'end', fill: t.muted, fontSize: t.small, ...halo }),
+    ],
+  });
+  // What each side of zero means, under the axis, each reading away from the zero line.
+  if (spec.sides) {
+    const x0 = host.querySelector('svg').scale('x').apply(0);
+    const p = document.createElement('div');
+    p.className = 'est-sides';
+    p.innerHTML = `<span>← ${esc(spec.sides.below)}</span><span>${esc(spec.sides.above)} →</span>`;
+    host.appendChild(p);
+    const [below, above] = p.children;
+    const bw = below.offsetWidth, aw = above.offsetWidth;
+    if (x0 - 12 - bw < 0) window.fig?.problems.push(`sides.below: "${spec.sides.below}" is too long to end at the zero line; shorten it`);
+    if (x0 + 12 + aw > width) window.fig?.problems.push(`sides.above: "${spec.sides.above}" is too long to start at the zero line; shorten it`);
+    const bLeft = Math.max(0, x0 - 12 - bw);
+    const aLeft = Math.min(width - aw, Math.max(x0 + 12, bLeft + bw + 24));
+    below.style.left = `${bLeft}px`;
+    above.style.left = `${aLeft}px`;
+  }
+}
+
+/** The estimates key, under the reading line: what the ranges are, and what a filled or hollow dot says. */
+function estimatesKey(spec) {
+  const clear = spec.rows.map((r) => r.low > 0 || r.high < 0);
+  const p = document.createElement('p');
+  p.className = 'range-key';
+  const ink = spec.better ? 'var(--ink)' : 'var(--accent)';
+  p.innerHTML = `<span><i class="whisker"></i>${esc(spec.range)}</span>`
+    + (clear.some(Boolean) ? `<span><i class="est-dot" style="background:${ink};border-color:${ink}"></i>clear of 0</span>` : '')
+    + (clear.some((c) => !c) ? '<span><i class="est-dot" style="border-color:var(--soft)"></i>includes 0</span>' : '');
+  return p;
+}
+
 // ---------- every value as a dot, two measures against each other, small counts as units ----------
 
 /**

package/viz/map-spec.js

@@ -0,0 +1,121 @@
+/* The "map" spec: a whole system, its parts grouped by subsystem and the links between them. spec.js adds it to the union. */
+import { z } from 'zod';
+
+const slug = z.string({ error: 'needs an id, e.g. "queue"' }).regex(/^[a-z][a-z0-9-]{0,31}$/, 'ids are short lowercase words, e.g. "queue" or "canary-gate"');
+const tone = z.literal('accent', { error: 'tone: only "accent", on what the question is about' }).optional();
+
+/** Limits, kept in one place so the guide and the refusals say the same numbers. */
+export const MAP_LIMITS = { parts: 24, minParts: 6, subsystems: 6, perSubsystem: 8, links: 30, accentLinks: 28, sideLinks: 3 };
+
+/**
+ * A system with many parts: each part sits in one subsystem, and each link says one part uses, calls or feeds another.
+ * figkit lays it out; the author only says what exists and what connects.
+ */
+export const mapShape = {
+  subsystems: z.array(z.object({
+    id: slug,
+    name: z.string({ error: 'needs a name' }).trim().min(1, 'needs a name').max(32, 'keep subsystem names to 32 characters'),
+    kind: z.string().trim().min(1).max(36, 'keep the kind to 36 characters: where it lives, e.g. "ash_builder/detectors/"').optional(),
+  }).strict()).min(2, 'at least 2 subsystems; with one, draw a plain figure').max(MAP_LIMITS.subsystems, `at most ${MAP_LIMITS.subsystems} subsystems; more do not read as regions, so merge the small ones or draw two maps`),
+  parts: z.array(z.object({
+    id: slug,
+    name: z.string({ error: 'needs a name' }).trim().min(1, 'needs a name').max(28, 'keep part names to 28 characters'),
+    kind: z.string().trim().min(1).max(32, 'keep the kind to 32 characters: what it is or the file it lives in').optional(),
+    in: slug.optional(),
+    tone,
+  }).strict()).min(MAP_LIMITS.minParts, `at least ${MAP_LIMITS.minParts} parts; fewer is a plain figure of at most 5 boxes`).max(MAP_LIMITS.parts, `at most ${MAP_LIMITS.parts} parts; past that the links tangle even full screen, so draw the subsystems as one map and the busiest subsystem as a second`),
+  links: z.array(z.object({
+    from: slug,
+    to: slug,
+    label: z.string().trim().min(1).max(22, 'keep link labels to 22 characters: a verb or the thing passed, e.g. "writes rows"').optional(),
+    tone,
+  }).strict()).min(1, 'at least 1 link').max(MAP_LIMITS.links, `at most ${MAP_LIMITS.links} links; more cross too often to follow, so leave out links the question does not need and say so in the note`),
+};
+
+const list = (ids) => ids.map((x) => `"${x}"`).join(', ');
+/** The id one or two letters away from a mistyped one, if there is exactly one. */
+function near(id, ids) {
+  const d = (a, b) => {
+    const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+      let prev = row[0]; row[0] = i;
+      for (let j = 1; j <= b.length; j++) { const t = row[j]; row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1)); prev = t; }
+    }
+    return row[b.length];
+  };
+  const close = ids.filter((x) => d(id, x) <= 2);
+  return close.length === 1 ? `; did you mean "${close[0]}"?` : '';
+}
+
+/** Rules that span fields: ids that exist, every part in a subsystem, every part linked, no repeats. */
+export function mapChecks(s) {
+  const out = [];
+  const subIds = s.subsystems.map((x) => x.id), partIds = s.parts.map((x) => x.id);
+  const all = [...subIds, ...partIds];
+  const dup = all.find((id, i) => all.indexOf(id) !== i);
+  if (dup) return [`ids: "${dup}" is used twice; every part and subsystem needs its own id`];
+  const names = s.parts.map((p) => p.name.toLowerCase());
+  const twice = s.parts.find((p, i) => names.indexOf(p.name.toLowerCase()) !== i);
+  if (twice) out.push(`parts: two parts are named "${twice.name}"; name each part so the reader can tell them apart`);
+
+  s.parts.forEach((p, i) => {
+    if (p.in == null) out.push(`parts[${i}]: "${p.id}" is in no subsystem; give it "in", one of ${list(subIds)}. Something outside the system still goes in a subsystem, such as "Outside"`);
+    else if (!subIds.includes(p.in)) out.push(`parts[${i}].in: no subsystem has the id "${p.in}"${partIds.includes(p.in) ? ' (that is a part; parts cannot hold parts)' : ''}; the subsystems are ${list(subIds)}`);
+  });
+  s.links.forEach((l, i) => {
+    for (const end of ['from', 'to']) if (!partIds.includes(l[end])) {
+      out.push(`links[${i}].${end}: no part has the id "${l[end]}"${subIds.includes(l[end]) ? '; that is a subsystem, and links join parts, so name the part inside it' : near(l[end], partIds)}`);
+    }
+  });
+  if (out.length) return out;
+
+  for (const sub of s.subsystems) {
+    const n = s.parts.filter((p) => p.in === sub.id).length;
+    if (n === 0) out.push(`subsystems: "${sub.id}" has no parts; put parts in it with "in": "${sub.id}", or leave it out`);
+    if (n > MAP_LIMITS.perSubsystem) out.push(`subsystems: "${sub.id}" has ${n} parts, more than ${MAP_LIMITS.perSubsystem}; split it in two, or merge parts the question does not need`);
+  }
+  const seen = new Map();
+  s.links.forEach((l, i) => {
+    if (l.from === l.to) out.push(`links[${i}]: "${l.from}" links to itself; say what it does to itself in its kind instead`);
+    const key = l.from + '>' + l.to;
+    if (seen.has(key)) out.push(`links[${i}]: a second link from "${l.from}" to "${l.to}" (links[${seen.get(key)}] is the first); make it one link with one label`);
+    const back = seen.get(l.to + '>' + l.from);
+    if (back != null) out.push(`links[${i}]: "${l.from}" and "${l.to}" link both ways (links[${back}] is the other); keep the one from the part that starts the exchange, the reply is implied`);
+    seen.set(key, i);
+  });
+  const loose = partIds.filter((id) => !s.links.some((l) => l.from === id || l.to === id));
+  if (loose.length) out.push(`parts: ${list(loose)} ${loose.length === 1 ? 'is' : 'are'} in no link; a part with no link says nothing on a map, so link ${loose.length === 1 ? 'it' : 'them'} or leave ${loose.length === 1 ? 'it' : 'them'} out`);
+  const accented = s.parts.filter((p) => p.tone).length + s.links.filter((l) => l.tone).length;
+  if (accented && accented === s.parts.length + s.links.length) out.push('tone: everything is accented, so nothing stands out; accent only what the question is about');
+  if (s.links.some((l) => l.tone)) {
+    // Measured on two real maps: the highlighted path stays one straight run at 28 links, but not at 29 or 30, and not with 4 grey links on one part of it.
+    if (s.links.length > MAP_LIMITS.accentLinks) out.push(`links: ${s.links.length} links with a highlighted path; at most ${MAP_LIMITS.accentLinks}, or figkit cannot keep the path one straight run, so leave out links the question does not need and say so in the note`);
+    const onPath = new Set(s.parts.filter((p) => p.tone).map((p) => p.id));
+    for (const l of s.links) if (l.tone) { onPath.add(l.from); onPath.add(l.to); }
+    for (const id of onPath) {
+      const grey = s.links.filter((l) => !l.tone && (l.from === id || l.to === id));
+      if (grey.length > MAP_LIMITS.sideLinks) out.push(`links: "${id}" is on the highlighted path and has ${grey.length} grey links (${grey.map((l) => `${l.from} → ${l.to}`).join(', ')}); a part on the path holds at most ${MAP_LIMITS.sideLinks}, because the path takes its top and bottom and the grey links must come in from the sides. Leave out the ones the question does not need`);
+    }
+  }
+  if (s.parts.filter((p) => p.tone).length > 8) out.push('parts: more than 8 parts are accented; a map points at one corner of the system, so accent only that corner');
+  return out;
+}
+
+/**
+ * The map with each subsystem as one box: the links between subsystems counted, the links inside one left out.
+ * For the phone layout, where the full map cannot be read.
+ */
+export function collapse(s) {
+  const where = Object.fromEntries(s.parts.map((p) => [p.id, p.in]));
+  const pairs = new Map();
+  for (const l of s.links) {
+    const a = where[l.from], b = where[l.to];
+    if (a === b) continue;
+    const key = a + '>' + b;
+    const e = pairs.get(key) ?? { from: a, to: b, count: 0, tone: undefined };
+    e.count++;
+    if (l.tone) e.tone = 'accent';
+    pairs.set(key, e);
+  }
+  return [...pairs.values()];
+}