@liggi/figkit 0.2.0 → 0.4.0

package/viz/draw.js

@@ -1,5 +1,6 @@
 /* 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';
 const NS = 'http://www.w3.org/2000/svg';
 const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 
@@ -79,21 +80,44 @@ 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). */
-export function drawBars(host, bars, unit, max) {
-  const top = max ?? Math.max(...bars.map((b) => b.value));
+/**
+ * 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)));
   host.innerHTML = '';
   const fills = bars.map((b) => {
-    const label = Object.assign(document.createElement('div'), { className: 'fb-label', innerHTML: b.label });
+    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 track = Object.assign(document.createElement('div'), { className: 'fb-track' });
     const tone = b.tone ? ' ' + b.tone : '';
-    track.innerHTML = `<div class="fb-bar${tone}"></div><div class="fb-val${b.tone ? ' lead ' + b.tone : ''}">${esc(shown(b, unit))}${b.note ? `<span class="fb-sub">${esc(b.note)}</span>` : ''}</div>`;
+    const ranged = b.low !== undefined;
+    // With a range, the bar steps back and the range, in the bar's colour, leads; its ends are printed after the value.
+    const ends = ranged ? `<span class="fb-sub">${esc(num(b.low))}–${esc(num(b.high))}${esc(unit ?? '')}</span>` : '';
+    track.innerHTML = `<div class="fb-bar${tone}${ranged ? ' dim' : ''}"></div>${ranged ? `<div class="fb-range${tone}"></div>` : ''}<div class="fb-val${b.tone ? ' lead ' + b.tone : ''}">${esc(shown(b, unit))}${ends}${b.note ? `<span class="fb-sub">${esc(b.note)}</span>` : ''}</div>`;
     host.append(label, track);
-    return { bar: track.firstChild, ratio: top > 0 ? Math.max(0, b.value) / top : 0 };
+    const r = (v) => (top > 0 ? Math.max(0, v) / top : 0);
+    return { b, bar: track.firstChild, range: track.querySelector('.fb-range'), val: track.querySelector('.fb-val'), ratio: r(b.value), lo: r(b.low ?? 0), hi: r(b.high ?? 0) };
   });
-  // The longest bar leaves room for the widest value and note, so no label runs past the edge.
+  // The longest bar or range leaves room for the widest value and note, so no label runs past the edge.
   const room = Math.max(...[...host.querySelectorAll('.fb-val')].map((v) => v.offsetWidth)) + 12;
-  for (const f of fills) f.bar.style.width = `calc((100% - ${room}px) * ${f.ratio})`;
+  const at = (ratio) => `calc((100% - ${room}px) * ${ratio})`;
+  for (const f of fills) {
+    f.bar.style.width = at(f.ratio);
+    if (!f.range) continue;
+    f.range.style.left = at(f.lo);
+    f.range.style.width = at(f.hi - f.lo);
+    f.val.style.marginLeft = `max(0px, calc((100% - ${room}px) * ${f.hi - f.ratio} - 3px))`;
+  }
+}
+
+/** What the ranges are, as a key line under the reading line: the mark as drawn, then the words. */
+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>` : '');
+  return p;
 }
 
 const ARROW = '<svg width="56" height="24" viewBox="0 0 56 24" aria-hidden="true"><path d="M2 12 H48 M38 3 L50 12 L38 21" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/></svg>';
@@ -108,7 +132,7 @@ export function drawChange(host, spec) {
 
 const themeOf = (host) => {
   const css = (n) => getComputedStyle(host).getPropertyValue(n).trim();
-  return { css, ink: css('--ink'), muted: css('--muted'), soft: css('--soft'), line: css('--line'), accent: css('--accent'), second: css('--second'), good: css('--good'), bad: css('--bad'), small: parseFloat(css('--small')) || 15, body: parseFloat(css('--body')) || 16, sans: css('--sans') };
+  return { css, ink: css('--ink'), muted: css('--muted'), soft: css('--soft'), fill: css('--fill'), fill2: css('--fill2'), hair: css('--hair'), paper: css('--paper'), line: css('--line'), accent: css('--accent'), second: css('--second'), good: css('--good'), bad: css('--bad'), small: parseFloat(css('--small')) || 15, body: parseFloat(css('--body')) || 16, sans: css('--sans') };
 };
 const toX = (v) => (typeof v === 'number' ? v : new Date(v));
 const num = (n) => (Math.abs(n) >= 100 ? Math.round(n) : Math.round(n * 10) / 10).toLocaleString('en-GB');
@@ -153,7 +177,7 @@ export function drawDumbbell(host, spec) {
     marks: [
       Plot.text(rows, { y: 'label', text: 'label', frameAnchor: 'left', dx: -(Math.ceil(labelW) + 28), textAnchor: 'start', fill: t.ink, fontSize: t.body }),
       Plot.link(rows, { x1: 'a', x2: 'b', y1: 'label', y2: 'label', stroke: 'color', strokeWidth: 3 }),
-      Plot.dot(rows, { x: 'a', y: 'label', r: 6.5, fill: t.soft }),
+      Plot.dot(rows, { x: 'a', y: 'label', r: 6.5, fill: t.fill }),
       // A fixed-size head at the end, pointing the way the row moved.
       // A fixed-size head whose tip, not its middle, sits on the end value.
       Plot.dot(rows.filter((r) => r.b >= r.a), { x: 'b', y: 'label', symbol: 'triangle2', r: 7.5, dx: -5, fill: 'color', rotate: 90 }),
@@ -165,6 +189,7 @@ export function drawDumbbell(host, spec) {
   const key = document.createElement('p');
   key.className = 'fd-key';
   key.innerHTML = `<span class="fd-from"><i></i>${esc(spec.fromLabel)}</span><span class="fd-to${rows.every((r) => r.b < r.a) ? ' back' : ''}" style="color:${t.accent}"><i></i>${esc(spec.toLabel)}</span>`;
+  key.style.marginLeft = labelW + 'px';
   host.prepend(key);
 }
 
@@ -172,12 +197,13 @@ export function drawDumbbell(host, spec) {
 export function drawSeries(host, spec) {
   const t = themeOf(host);
   const width = Math.floor(host.clientWidth) || 640;
-  const pts = spec.points.map((p) => ({ x: toX(p.x), y: p.y }));
+  const pts = spec.points.map((p) => ({ x: toX(p.x), y: p.y, low: p.low, high: p.high }));
+  const band = pts[0].low !== undefined;
   const i = pts.findIndex((p) => +p.x === +toX(spec.mark.x));
   const mark = pts[i];
   const near = pts.slice(Math.max(0, i - 3), i + 4).map((p) => p.y);
   const high = mark.y >= near.reduce((s, y) => s + y, 0) / near.length;
-  const ys = pts.map((p) => p.y), zero = spec.zero ?? true;
+  const ys = [...pts.flatMap((p) => (band ? [p.y, p.low, p.high] : [p.y])), ...(spec.ref ? [spec.ref.y] : [])], zero = spec.zero ?? true;
   const top = Math.max(...ys), bottom = zero ? Math.min(0, ...ys) : Math.min(...ys);
   const fmt = (d) => num(d) + (spec.unit ?? '');
   const tickW = widest(host, [fmt(top), fmt(bottom)], t.small);
@@ -187,16 +213,23 @@ export function drawSeries(host, spec) {
   const right = at + 14 + widest(host, [spec.mark.label], t.body, 600) <= width - 20;
   // Above a high point; level with a low one, lifted clear of the axis when it sits near the bottom.
   const lift = zero ? ((mark.y - bottom) / (top * 1.04 - bottom)) * (340 - 30 - 40) : Infinity;
-  const dy = high ? -12 : Math.min(0, lift - 18);
+  let dy = high ? -12 : Math.min(0, lift - 18);
+  // A label to the left of its point sits on the side away from the line coming in: above it when the previous
+  // point is lower, below when higher.
+  if (!right && i > 0) dy = pts[i - 1].y <= mark.y ? -18 : 20;
+  // Above or below, the label ends just past the point, so it does not reach back over the line.
+  const dx = right ? 14 : i > 0 ? 8 : -14;
   plotInto(host, t, {
     width, height: 340, marginLeft: left0, marginRight: 20, marginTop: 30, marginBottom: 40,
     x: { label: null, ticks: width < 600 ? 4 : 5, insetLeft: 18 },
     y: { label: null, grid: true, ticks: 4, tickSize: 0, domain: zero ? [bottom, top * 1.04] : undefined, tickFormat: fmt },
     marks: [
       zero ? Plot.ruleY([0], { stroke: t.line }) : null,
-      Plot.lineY(pts, { x: 'x', y: 'y', stroke: t.soft, strokeWidth: 2.5 }),
+      band ? Plot.areaY(pts, { x: 'x', y1: 'low', y2: 'high', fill: t.fill, fillOpacity: 0.3 }) : null,
+      spec.ref ? Plot.ruleY([spec.ref.y], { stroke: t.soft, strokeWidth: 1.5, strokeDasharray: '5,4' }) : null,
+      Plot.lineY(pts, { x: 'x', y: 'y', stroke: band ? t.muted : t.fill, strokeWidth: 2.5 }),
       Plot.dot([mark], { x: 'x', y: 'y', r: 6.5, fill: t.accent }),
-      Plot.text([mark], { x: 'x', y: 'y', text: () => spec.mark.label, dx: right ? 14 : -14, dy, textAnchor: right ? 'start' : 'end', fill: t.accent, fontWeight: 600, fontSize: t.body }),
+      Plot.text([mark], { x: 'x', y: 'y', text: () => spec.mark.label, dx, dy, textAnchor: right ? 'start' : 'end', fill: t.accent, fontWeight: 600, fontSize: t.body }),
     ],
   });
 }
@@ -283,18 +316,26 @@ function drawEntities(spec, main) {
   }
 }
 
-const HOSTS = { split: 'fig-split', bars: 'fig-bars', 'before-after': 'fig-change', dumbbell: 'div', series: 'div' };
+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' };
 
 /** 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 === '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 === 'sequence') {
+    main.append(header);
+    const chart = drawSequence(spec, main);
+    if (spec.source) { const footer = document.createElement('footer'); footer.innerHTML = `<p>${esc(spec.source)}</p>`; main.append(footer); }
+    return { chart, draw: () => {} };
+  }
   const chart = document.createElement(HOSTS[spec.type]);
   main.append(header, chart);
   if (spec.source) {
@@ -306,10 +347,401 @@ export function drawSpec(spec, main) {
     if (spec.type === 'before-after') return drawChange(chart, spec);
     if (spec.type === 'dumbbell') return drawDumbbell(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 });
+    if (spec.type === 'panels') return drawPanels(chart, spec);
+    if (spec.type === 'heatmap') return drawHeatmap(chart, spec);
+    if (spec.type === 'dots') return drawDots(chart, spec);
+    if (spec.type === 'scatter') return drawScatter(chart, spec);
+    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);
+    else drawBars(chart, items, spec.unit, spec.max, spec.each);
   };
   draw();
   return { chart, draw };
 }
+
+// ---------- grouped bars, several lines, panels, heat maps ----------
+
+const hex = (c) => { const m = /^#?([0-9a-f]{6})$/i.exec(c.trim()); return m ? [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16)) : null; };
+/** a mixed with b, p of the way to b, as #rrggbb; a when either is not a plain hex colour. */
+function mix(a, b, p) {
+  const x = hex(a), y = hex(b);
+  if (!x || !y) return a;
+  return '#' + x.map((v, i) => Math.round(v + (y[i] - v) * p).toString(16).padStart(2, '0')).join('');
+}
+const phoneOf = (host) => !!host.closest('.phone');
+
+/**
+ * Bars in groups into a .chart: a heading per group, a row per series labelled with its name, so no legend is needed.
+ * opts.max fixes the end of the axis (panels share one), opts.unit follows each number.
+ */
+export function drawGroups(host, data, opts = {}) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 420;
+  const { series, groups, accent } = data;
+  const tone = t[accent.tone ?? 'accent'];
+  const rows = groups.flatMap((g) => series.map((s, i) => ({ g: g.label, s, v: g.values[i], hi: (accent.series === undefined || accent.series === s) && (accent.group === undefined || accent.group === g.label) })));
+  const fmt = (v) => num(v) + (opts.unit ?? '');
+  const top = opts.max ?? Math.max(...rows.map((r) => r.v));
+  const indent = 0;
+  const labelW = Math.ceil(Math.max(widest(host, series, t.body) + indent, widest(host, groups.map((g) => g.label), t.body, 600))) + 14;
+  const valueW = Math.ceil(widest(host, rows.map((r) => fmt(r.v)), t.body, 600)) + 12;
+  // A group's heading sits close above its own bars, with more room above it, so the groups read as blocks.
+  const rowH = Math.max(phone ? 34 : 38, Math.ceil(t.body * 1.75)), headH = Math.max(30, Math.ceil(t.body * 1.7)), above = 22;
+  const step = series.length * rowH + headH + above;
+  plotInto(host, t, {
+    width, height: groups.length * step - above + 8, marginLeft: labelW, marginRight: valueW, marginTop: headH, marginBottom: 8,
+    // Every bar carries its number, so an axis would only repeat it; the zero line is kept.
+    x: { domain: [0, top], axis: null },
+    y: { domain: series, axis: null, padding: 0.18 },
+    fy: { domain: groups.map((g) => g.label), axis: null, paddingInner: (headH + above) / step, paddingOuter: 0 },
+    marks: [
+      Plot.ruleX([0], { stroke: t.line }),
+      Plot.barX(rows, { x: 'v', y: 's', fy: 'g', fill: (r) => (r.hi ? tone : t.fill), rx: 2 }),
+      Plot.text(rows, { x: 'v', y: 's', fy: 'g', text: (r) => fmt(r.v), dx: 6, textAnchor: 'start', fill: (r) => (r.hi ? tone : t.ink), fontWeight: (r) => (r.hi ? 600 : 400), fontSize: t.body }),
+      Plot.text(rows, { x: 0, y: 's', fy: 'g', text: 's', dx: -labelW + indent, textAnchor: 'start', fill: t.ink, fontSize: t.body }),
+      Plot.text(groups.map((g) => g.label), { fy: (d) => d, frameAnchor: 'top-left', dx: -labelW, dy: -headH + 2, text: (d) => d, textAnchor: 'start', lineAnchor: 'top', fill: opts.quietGroups ? t.muted : t.ink, fontWeight: 600, fontSize: t.body * 1.06 }),
+    ],
+  });
+}
+
+/**
+ * Two or three lines on one axis into a .chart. Each is named at its right end in its own colour; the accent line is
+ * drawn last and thicker, the others in two greys. opts.domain fixes the y axis (panels share one).
+ */
+export function drawLines(host, data, opts = {}) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 420;
+  const greys = [t.fill2, t.fill];
+  const lines = data.series.map((l) => ({ ...l, band: l.points[0].low !== undefined, pts: l.points.map((p) => ({ x: toX(p.x), y: p.y, low: p.low, high: p.high, s: l.label })) }));
+  const others = lines.filter((l) => l.label !== data.accent);
+  others.forEach((l, i) => { l.color = greys[i % 2]; l.w = 2.25; });
+  const hi = lines.find((l) => l.label === data.accent);
+  hi.color = t.accent; hi.w = 3.25;
+  const ys = lines.flatMap((l) => l.pts.flatMap((p) => (l.band ? [p.y, p.low, p.high] : [p.y])));
+  const zero = data.zero ?? true;
+  const domain = opts.domain ?? [zero ? Math.min(0, ...ys) : Math.min(...ys), Math.max(...ys) * 1.04];
+  const fmt = (d) => num(d) + (opts.unit ?? '');
+  const height = phone ? 260 : 300, mt = data.mark ? 28 : 10, mb = 36;
+  const ends = [...others, hi].map((l) => ({ l, last: l.pts[l.pts.length - 1] }));
+  const labelW = Math.ceil(widest(host, ends.map((e) => e.l.label), t.small, 600)) + 14;
+  // Each name sits level with its line's last point, pushed apart when two would overlap.
+  const py = (v) => mt + (1 - (v - domain[0]) / (domain[1] - domain[0])) * (height - mt - mb);
+  const placed = ends.map((e) => ({ ...e, y: py(e.last.y) })).sort((a, b) => a.y - b.y);
+  const gap = t.small * 1.3;
+  for (let i = 1; i < placed.length; i++) placed[i].y = Math.max(placed[i].y, placed[i - 1].y + gap);
+  for (let i = placed.length - 2; i >= 0; i--) placed[i].y = Math.min(placed[i].y, placed[i + 1].y - gap);
+  const tickW = Math.ceil(widest(host, [fmt(domain[1]), fmt(domain[0])], t.small)) + 12;
+  const markPt = data.mark && hi.pts.find((p) => +p.x === +toX(data.mark.x));
+  plotInto(host, t, {
+    width, height, marginLeft: tickW, marginRight: labelW, marginTop: mt, marginBottom: mb,
+    x: opts.xTicks ? { label: null, insetLeft: 18, ticks: opts.xTicks.map((k) => toX(k.x)), tickFormat: (d) => opts.xTicks.find((k) => +toX(k.x) === +d)?.label ?? '' }
+      : { label: null, insetLeft: 18, ticks: width < 520 ? 3 : 5, tickFormat: typeof lines[0].pts[0].x === 'number' ? (d) => num(d) : undefined },
+    y: { domain, nice: false, label: null, grid: true, ticks: 4, tickSize: 0, tickFormat: fmt },
+    marks: [
+      zero ? Plot.ruleY([0], { stroke: t.line }) : null,
+      ...[...others, hi].filter((l) => l.band).map((l) => Plot.areaY(l.pts, { x: 'x', y1: 'low', y2: 'high', fill: l.color, fillOpacity: l === hi ? 0.22 : 0.18 })),
+      ...[...others, hi].map((l) => Plot.lineY(l.pts, { x: 'x', y: 'y', stroke: l.color, strokeWidth: l.w })),
+      Plot.text(placed, { x: (e) => e.last.x, y: (e) => domain[0] + (1 - (e.y - mt) / (height - mt - mb)) * (domain[1] - domain[0]), text: (e) => e.l.label, dx: 8, textAnchor: 'start', fill: (e) => (e.l === hi ? t.accent : t.muted), fontWeight: 600, fontSize: t.small }),
+      markPt ? Plot.dot([markPt], { x: 'x', y: 'y', r: 6, fill: t.accent }) : null,
+      markPt ? Plot.text([markPt], { x: 'x', y: 'y', text: () => data.mark.label, dy: -16, fill: t.accent, fontWeight: 600, fontSize: t.small }) : null,
+    ],
+  });
+}
+
+/** The same chart for each part, side by side on one scale; stacked on a phone. */
+export function drawPanels(host, spec) {
+  host.className = 'panels';
+  host.innerHTML = '';
+  const charts = spec.panels.map((p) => {
+    const box = document.createElement('div');
+    box.className = 'panel';
+    box.innerHTML = `<h2>${esc(p.label)}</h2>`;
+    const chart = document.createElement('div');
+    box.appendChild(chart);
+    host.appendChild(box);
+    return { p, chart };
+  });
+  if (spec.chart === 'groups') {
+    const max = spec.max ?? Math.max(...spec.panels.flatMap((p) => p.groups.flatMap((g) => g.values)));
+    for (const { p, chart } of charts) {
+      const accent = spec.accent.group && !p.groups.some((g) => g.label === spec.accent.group) ? { ...spec.accent, series: '\u0000' } : spec.accent;
+      drawGroups(chart, { series: spec.series, groups: p.groups, accent }, { unit: spec.unit, max, quietGroups: true });
+    }
+  } else {
+    const ys = spec.panels.flatMap((p) => p.series.flatMap((l) => l.points.flatMap((q) => (q.low !== undefined ? [q.y, q.low, q.high] : [q.y]))));
+    const zero = spec.zero ?? true;
+    const domain = [zero ? Math.min(0, ...ys) : Math.min(...ys), Math.max(...ys) * 1.04];
+    for (const { p, chart } of charts) drawLines(chart, { series: p.series, accent: spec.accent, zero }, { unit: spec.unit, domain, xTicks: spec.xTicks });
+  }
+}
+
+/**
+ * A heat map into a .chart: the colour runs from pale to the accent, one hue, so darker is always more. The scale is
+ * drawn above the grid at readable size. A marked cell is outlined and named in the scale line.
+ */
+export function drawHeatmap(host, spec) {
+  const t = themeOf(host);
+  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 ?? '');
+  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;
+  const show = cellW >= 48 && cells.length <= 72;
+  // Label every k-th column, k a divisor of the count where one exists, so 24 hours read 12am, 6am, 12pm, 6pm.
+  const most = phone ? 5 : 9, steps = [1, 2, 3, 4, 5, 6, 8, 10, 12].filter((k) => cols.length / k <= most);
+  const every = steps.find((k) => cols.length % k === 0) ?? steps[0] ?? Math.ceil(cols.length / most);
+  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>`
+    + (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,
+    x: { domain: cols, label: null, tickSize: 0, tickFormat: (d, i) => (i % every === 0 ? d : '') , padding: 0.06 },
+    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,
+      // 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,
+    ],
+  });
+  key.style.marginLeft = labelW + 'px';
+  host.prepend(key);
+}
+
+// ---------- every value as a dot, two measures against each other, small counts as units ----------
+
+/**
+ * Offsets that stack dots of radius r along a row so none overlaps another, nearest the middle first (a beeswarm).
+ * xs are pixel positions; returns a pixel offset from the row's centre line for each.
+ */
+export function swarm(xs, r) {
+  const d = 2 * r + 1, order = xs.map((x, i) => i).sort((a, b) => xs[a] - xs[b]);
+  const out = new Array(xs.length), placed = [];
+  for (const i of order) {
+    const x = xs[i], near = placed.filter((p) => Math.abs(p.x - x) < d);
+    const free = (y) => near.every((p) => (p.x - x) ** 2 + (p.y - y) ** 2 >= d * d - 1e-6);
+    const tries = [0, ...near.flatMap((p) => { const h = Math.sqrt(Math.max(0, d * d - (p.x - x) ** 2)); return [p.y + h, p.y - h]; })]
+      .sort((a, b) => Math.abs(a) - Math.abs(b) || b - a);
+    const y = tries.find(free) ?? 0;
+    out[i] = y;
+    placed.push({ x, y });
+  }
+  return out;
+}
+
+const middle = (vs) => { const s = [...vs].sort((a, b) => a - b), m = s.length >> 1; return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2; };
+
+/**
+ * Every value as a dot into a .chart: one row per group on a shared axis, dots stacked where they would overlap.
+ * The group's name and count sit to the left (above, on a phone); a median or mean is a line across the row.
+ */
+export function drawDots(host, spec) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 460;
+  const fmt = (v) => num(v) + (spec.unit ?? '');
+  const all = spec.groups.flatMap((g) => g.values);
+  const lo = spec.zero ? 0 : Math.min(...all), hi = spec.max ?? Math.max(...all);
+  const counts = spec.groups.map((g) => (spec.each ? `${g.values.length.toLocaleString('en-GB')} ${spec.each}` : `n = ${g.values.length.toLocaleString('en-GB')}`));
+  const many = spec.groups.length > 1;
+  const labelW = phone || !many ? 0 : Math.ceil(Math.max(widest(host, spec.groups.map((g) => g.label), t.body, 600), widest(host, counts, t.small))) + 24;
+  // Room for half the first tick label, so "0 min" does not stick out past the text edge.
+  const ml = Math.max(labelW + 10, Math.ceil(widest(host, [fmt(lo)], t.small) / 2) + 2), mr = 18;
+  const x = Plot.scale({ x: { domain: [lo, hi === lo ? lo + 1 : hi], range: [ml, width - mr], nice: true } });
+  // As many ticks as fit with a clear gap between their labels.
+  const nt = Math.max(2, Math.min(6, Math.floor((width - ml - mr) / (widest(host, x.domain.map(fmt), t.small) + 32))));
+  // The largest dots that keep the tallest stack within reach of the row.
+  const most = phone ? 56 : 64;
+  let r = phone ? 6 : 7.5, offs;
+  for (;;) {
+    offs = spec.groups.map((g) => swarm(g.values.map((v) => x.apply(v)), r));
+    const tallest = Math.max(...offs.flat().map(Math.abs));
+    if (tallest <= most || r <= 2.5) break;
+    r -= 0.5;
+  }
+  const sumName = spec.summary, dots = [], rows = [];
+  // A single group needs no name in the chart: the title and note say what it is.
+  const head = (phone && many ? Math.ceil(t.small * 2.7) : 0) + (sumName ? Math.ceil(t.small * 1.6) : 0);
+  let y = 6;
+  spec.groups.forEach((g, gi) => {
+    const half = Math.max(...offs[gi].map(Math.abs)) + r;
+    const top = y + head, mid = top + half;
+    const s = sumName === 'mean' ? g.values.reduce((a, v) => a + v, 0) / g.values.length : sumName ? middle(g.values) : null;
+    const colour = g.tone ? t[g.tone] : t.fill;
+    g.values.forEach((v, i) => dots.push({ v, y: mid + offs[gi][i], colour, g: g.label }));
+    rows.push({ g, top, mid, bottom: mid + half, s, label: g.label, count: counts[gi], colour, tone: g.tone });
+    y = mid + half + (phone ? 22 : 26);
+  });
+  const height = y - (phone ? 22 : 26) + 8 + 40;
+  const mark = spec.mark && dots.find((d) => d.g === spec.mark.group && d.v === spec.mark.value);
+  // The mark's label sits above its dot, reaching away from the nearer edge, so it never covers the dots beside it.
+  const markEnd = mark && x.apply(mark.v) + widest(host, [spec.mark.label], t.small, 600) > width - mr;
+  plotInto(host, t, {
+    width, height, marginLeft: ml, marginRight: mr, marginTop: 0, marginBottom: 40,
+    x: { domain: x.domain, nice: false, label: null, ticks: nt, tickFormat: fmt },
+    y: { type: 'identity', axis: null },
+    marks: [
+      Plot.gridX({ ticks: nt, stroke: t.hair, strokeOpacity: 1, y1: 0, y2: height - 40 }),
+      // The summary line runs behind the dots and out past both ends of the row, so it shows without cutting a dot.
+      sumName ? Plot.ruleX(rows, { x: 's', y1: (d) => d.top - 6, y2: (d) => d.bottom + 6, stroke: t.ink, strokeWidth: 2.5 }) : null,
+      Plot.dot(dots, { x: 'v', y: 'y', r, fill: 'colour', stroke: t.paper, strokeWidth: 1 }),
+      sumName ? Plot.text(rows, { x: 's', y: (d) => d.top - 10, text: (d) => `${sumName} ${fmt(d.s)}`, lineAnchor: 'bottom', fill: t.muted, fontSize: t.small, stroke: t.paper, strokeWidth: 6, paintOrder: 'stroke' }) : null,
+      many && !phone ? Plot.text(rows, { frameAnchor: 'left', y: (d) => d.mid - t.small * 0.6, text: 'label', textAnchor: 'start', dx: -ml, fill: (d) => (d.tone ? t[d.tone] : t.ink), fontWeight: 600, fontSize: t.body }) : null,
+      many && !phone ? Plot.text(rows, { frameAnchor: 'left', y: (d) => d.mid + t.small * 0.7, text: 'count', textAnchor: 'start', dx: -ml, fill: t.muted, fontSize: t.small }) : null,
+      many && phone ? Plot.text(rows, { frameAnchor: 'left', y: (d) => d.top - head + 2, text: 'label', textAnchor: 'start', lineAnchor: 'top', dx: -ml, fill: (d) => (d.tone ? t[d.tone] : t.ink), fontWeight: 600, fontSize: t.small, stroke: t.paper, strokeWidth: 6, paintOrder: 'stroke' }) : null,
+      many && phone ? Plot.text(rows, { frameAnchor: 'left', y: (d) => d.top - head + 2 + t.small * 1.3, text: 'count', textAnchor: 'start', lineAnchor: 'top', dx: -ml, fill: t.muted, fontSize: t.small, stroke: t.paper, strokeWidth: 6, paintOrder: 'stroke' }) : null,
+      mark ? Plot.dot([mark], { x: 'v', y: 'y', r: r + 3.5, stroke: t.accent, strokeWidth: 2.5, fill: 'none' }) : null,
+      mark ? Plot.text([mark], { x: 'v', y: (d) => d.y - r - 9, text: () => spec.mark.label, dx: markEnd ? r + 3.5 : -(r + 3.5), lineAnchor: 'bottom', textAnchor: markEnd ? 'end' : 'start', fill: t.accent, fontWeight: 600, fontSize: t.small }) : null,
+    ],
+  });
+  if (!many) {
+    const p = document.createElement('p');
+    p.className = 'dots-n';
+    p.textContent = counts[0];
+    host.prepend(p);
+  }
+}
+
+const SECONDS = { seconds: 1, minutes: 60, hours: 3600, days: 86400 };
+const SPANS = [[1, '1 s', 1], [10, '10 s', 2], [60, '1 min', 1], [600, '10 min', 2], [3600, '1 h', 1], [21600, '6 h', 2], [86400, '1 day', 1], [604800, '1 wk', 1], [2592000, '1 mo', 1], [31536000, '1 yr', 1]];
+/** A duration in seconds as the reader says it: 40 s, 12 min, 5 h, 3 days. */
+function said(sec) {
+  const at = (n, u) => `${num(n)} ${u}`;
+  if (sec === 0) return '0';
+  if (sec < 60) return at(sec, 's');
+  if (sec < 3600) return at(sec / 60, 'min');
+  if (sec < 172800) return at(sec / 3600, 'h');
+  return at(sec / 86400, 'days');
+}
+
+/**
+ * One scatter axis: its domain, ticks and labels. A log axis runs to whole powers of ten (or, for time, to the
+ * nearest of 1 min, 1 h, 1 day...) beyond the data, so every dot sits inside a labelled tick.
+ */
+function scatterAxis(a, vs, host, t, room) {
+  const lo = Math.min(...vs), hi = Math.max(...vs);
+  const mult = a.time ? SECONDS[a.time] : 1;
+  const fmt = a.time ? (v) => said(v * mult) : (v) => (Math.abs(v) > 0 && Math.abs(v) < 1 ? String(+v.toPrecision(2)) : num(v)) + (a.unit ?? '');
+  if (a.log && a.time) {
+    const s0 = lo * mult, s1 = hi * mult;
+    const from = [...SPANS].reverse().find(([v]) => v <= s0) ?? SPANS[0];
+    const to = SPANS.find(([v]) => v >= s1) ?? SPANS[SPANS.length - 1];
+    let ticks = SPANS.filter(([v]) => v >= from[0] && v <= to[0]);
+    if (ticks.length > 7) ticks = ticks.filter((k) => k[2] === 1 || k === from || k === to);
+    return { type: 'log', domain: [from[0] / mult, to[0] / mult], ticks: ticks.map(([v]) => v / mult), fmt: (v) => SPANS.find(([s]) => Math.abs(s - v * mult) < 1e-6)?.[1] ?? said(v * mult) };
+  }
+  if (a.log) {
+    const e0 = Math.floor(Math.log10(lo)), e1 = Math.ceil(Math.log10(hi));
+    const ms = e1 - e0 > 3 ? [1] : [1, 3], ticks = [];
+    for (let e = e0; e <= e1; e++) for (const m of ms) if (m * 10 ** e <= 10 ** e1) ticks.push(m * 10 ** e);
+    return { type: 'log', domain: [10 ** e0, 10 ** e1], ticks, fmt };
+  }
+  const domain = a.zero ? [Math.min(0, lo), hi] : [lo, hi];
+  const n = Math.max(2, Math.min(6, Math.floor(room / (widest(host, domain.map(fmt), t.small) + 32))));
+  return { type: 'linear', domain, ticks: n, fmt, nice: true };
+}
+
+/**
+ * Two measures against each other into a .chart: a dot per thing, the named ones in colour and labelled beside them.
+ * With `medians`, the median y of each band of x is drawn across that band: the relation, without fitting a model.
+ */
+export function drawScatter(host, spec) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 460;
+  const pts = [...spec.points].sort((a, b) => (a.tone || a.label ? 1 : 0) - (b.tone || b.label ? 1 : 0));
+  const Y = scatterAxis(spec.y, pts.map((p) => p.y), host, t, 300);
+  const tickW = Math.ceil(widest(host, (Array.isArray(Y.ticks) ? Y.ticks : Y.domain).map(Y.fmt), t.small)) + 14;
+  const X = scatterAxis(spec.x, pts.map((p) => p.x), host, t, width - tickW - 16);
+  // A log axis is drawn as a linear axis over log10 of the values, with figkit's own ticks: Plot's log axis blanks
+  // every tick label that is not a power of ten, whatever the format.
+  const lin = (A) => (A.type === 'log' ? { ...A, type: 'linear', domain: A.domain.map(Math.log10), ticks: A.ticks.map(Math.log10), fmt: (l) => A.fmt(10 ** l), at: Math.log10 } : { ...A, at: (v) => v });
+  const XL = lin(X), YL = lin(Y);
+  const dots = pts.map((p) => ({ ...p, px: XL.at(p.x), py: YL.at(p.y) }));
+  const height = phone ? 340 : 420;
+  const r = (pts.length > 300 ? 3.5 : pts.length > 80 ? 4.5 : 6) * (phone ? 0.8 : 1);
+  const faint = pts.length > 150 ? 0.45 : 0.7;
+  // A label reads away from the nearer side of the plot: points in the right half are labelled to their left.
+  const f = (v) => (X.type === 'log' ? Math.log10(v) : v), [x0, x1] = X.domain.map(f);
+  const leftward = (p) => f(p.x) > (x0 + x1) / 2;
+  let bands = [];
+  if (spec.medians) {
+    const edges = X.type === 'log'
+      ? Array.from({ length: Math.round(x1 - x0) + 1 }, (_, i) => 10 ** (x0 + i))
+      : Array.from({ length: 6 }, (_, i) => X.domain[0] + ((X.domain[1] - X.domain[0]) * i) / 5);
+    for (let i = 0; i + 1 < edges.length; i++) {
+      const inside = pts.filter((p) => p.x >= edges[i] && (i + 2 === edges.length ? p.x <= edges[i + 1] : p.x < edges[i + 1]));
+      if (inside.length < 5) continue;
+      const ys = inside.map((p) => p.y).sort((u, v) => u - v), q = (k) => ys[Math.min(ys.length - 1, Math.max(0, Math.round(k * (ys.length - 1))))];
+      // Each band spans its own dots, so a band with few dots at its near end does not reach across empty space.
+      bands.push({ a: Math.min(...inside.map((p) => p.x)), b: Math.max(...inside.map((p) => p.x)), m: middle(ys), q1: q(0.25), q3: q(0.75) });
+    }
+  }
+  const mt = Math.ceil(t.small * 1.4) + 20, mb = Math.ceil(t.small * 2.6) + 14;
+  // Room for half the last x tick label, so "10,000" ends inside the card.
+  const last = Array.isArray(XL.ticks) ? XL.fmt(XL.ticks[XL.ticks.length - 1]) : XL.fmt(XL.domain[1]);
+  const mr = Math.max(16, Math.ceil(widest(host, [last], t.small) / 2) - r - 4);
+  plotInto(host, t, {
+    width, height, marginLeft: tickW, marginRight: mr, marginTop: mt, marginBottom: mb,
+    x: { domain: XL.domain, nice: XL.nice ?? false, inset: r + 6, label: null, ticks: XL.ticks, tickFormat: XL.fmt },
+    y: { domain: YL.domain, nice: YL.nice ?? false, inset: r + 6, label: null, grid: true, ticks: YL.ticks, tickSize: 0, tickFormat: YL.fmt },
+    marks: [
+      Plot.dot(dots, { x: 'px', y: 'py', r, fill: (p) => (p.tone ? t[p.tone] : t.fill), fillOpacity: (p) => (p.tone ? 1 : faint) }),
+      bands.length ? Plot.rect(bands, { x1: (d) => XL.at(d.a), x2: (d) => XL.at(d.b), y1: (d) => YL.at(d.q1), y2: (d) => YL.at(d.q3), fill: t.accent, fillOpacity: 0.14, insetLeft: 2, insetRight: 2 }) : null,
+      bands.length ? Plot.ruleY(bands, { y: (d) => YL.at(d.m), x1: (d) => XL.at(d.a), x2: (d) => XL.at(d.b), stroke: t.accent, strokeWidth: 4, insetLeft: 2, insetRight: 2 }) : null,
+      Plot.text(dots.filter((p) => p.label && !leftward(p)), { x: 'px', y: 'py', text: 'label', dx: r + 8, textAnchor: 'start', fill: (p) => (p.tone ? t[p.tone] : t.ink), fontWeight: 600, fontSize: t.small }),
+      Plot.text(dots.filter((p) => p.label && leftward(p)), { x: 'px', y: 'py', text: 'label', dx: -(r + 8), textAnchor: 'end', fill: (p) => (p.tone ? t[p.tone] : t.ink), fontWeight: 600, fontSize: t.small }),
+      // What each axis measures, written along it: the y label above its axis, the x label under the ticks at the right.
+      Plot.text([spec.y.label], { frameAnchor: 'top-left', dx: -tickW, dy: -mt + 2, text: (d) => d, textAnchor: 'start', lineAnchor: 'top', fill: t.muted, fontWeight: 600, fontSize: t.small }),
+      Plot.text([spec.x.label], { frameAnchor: 'bottom-right', dy: mb - 4, text: (d) => d, textAnchor: 'end', lineAnchor: 'bottom', fill: t.muted, fontWeight: 600, fontSize: t.small }),
+    ],
+  });
+  if (bands.length) {
+    const key = document.createElement('p');
+    key.className = 'range-key';
+    key.innerHTML = `<span><i class="median" style="background:${t.accent}"></i>median of each band of ${esc(spec.x.label.toLowerCase())}</span><span><i class="band" style="background:${t.accent};opacity:.3"></i>its middle half</span>`;
+    key.style.marginBottom = '14px';
+    host.prepend(key);
+  }
+}
+
+/**
+ * A small count as squares into a .chart: rows of ten, filled column by column so each part is one solid block from the
+ * left. No gutters: a gap between squares would read as a split the data does not have.
+ */
+export function drawUnits(host, spec) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 460;
+  const cols = Math.min(10, spec.total), rows = Math.ceil(spec.total / cols), gap = phone ? 5 : 7;
+  const size = Math.min(phone ? 34 : 48, Math.floor((width - gap * (cols - 1)) / cols));
+  const greys = [t.fill, t.fill2];
+  let g = 0;
+  const parts = spec.parts.map((p, i) => ({ ...p, colour: p.tone ? t[p.tone] : i === 0 ? t.accent : greys[g++ % 2] }));
+  host.className = 'units';
+  host.innerHTML = '';
+  const grid = document.createElement('div');
+  grid.className = 'un-grid';
+  grid.style.cssText = `grid-template-columns: repeat(${cols}, ${size}px); grid-template-rows: repeat(${rows}, ${size}px); grid-auto-flow: column; gap: ${gap}px; --un: ${size}px;`;
+  const cells = parts.flatMap((p) => Array(p.count).fill(p.colour));
+  for (let i = 0; i < spec.total; i++) {
+    const c = document.createElement('i');
+    if (cells[i]) c.style.background = cells[i];
+    else c.className = 'empty';
+    grid.appendChild(c);
+  }
+  const rest = spec.total - cells.length;
+  const key = document.createElement('div');
+  key.className = 'un-key';
+  key.innerHTML = parts.map((p) => `<span><i style="background:${p.colour}"></i><b style="color:${p.colour === t.accent || p.tone ? p.colour : t.ink}">${p.count}</b>${esc(p.label)}</span>`).join('')
+    + `<span><i class="empty"></i><b style="color:${t.muted}">${rest}</b>${esc(spec.rest)}</span>`;
+  host.append(grid, key);
+}

package/viz/sequence-spec.js

@@ -0,0 +1,60 @@
+/* The "sequence" spec: who calls whom, in order. Kept beside spec.js, which adds it to the union of types. */
+import { z } from 'zod';
+
+const slug = z.string({ error: 'needs an id, e.g. "bot"' }).regex(/^[a-z][a-z0-9-]{0,23}$/, 'ids are short lowercase words, e.g. "bot" or "ci-job"');
+const text = (max, what, long) => z.string({ error: `needs ${what}` }).trim().min(1, `needs ${what}`).max(max, long);
+
+/**
+ * Who calls whom, in order: participants side by side, each message a numbered step down the page from one to another.
+ * A reply answers an earlier call; a message to its own sender is work it does itself.
+ */
+export const sequenceShape = {
+  participants: z.array(z.object({
+    id: slug,
+    name: text(28, 'a name', 'keep names to 28 characters'),
+    kind: z.string().trim().min(1).max(28, 'keep the kind to 28 characters, e.g. "GitHub Actions"').optional(),
+    tone: z.literal('accent', { error: 'tone: only "accent", on the one participant to notice' }).optional(),
+  }).strict()).min(2, 'at least 2 participants').max(5, 'at most 5 participants; more is two figures (the whole run with the parts merged, then one stage of it)'),
+  messages: z.array(z.object({
+    from: slug,
+    to: slug,
+    label: text(40, 'a label', 'keep labels to 40 characters: what is asked for or sent, not how'),
+    reply: z.boolean().optional(),
+    note: z.string().trim().min(1).max(40, 'keep the note to 40 characters').optional(),
+    tone: z.literal('accent', { error: 'tone: only "accent", on the steps to notice' }).optional(),
+  }).strict()).min(2, 'at least 2 messages; one call is a sentence').max(12, 'at most 12 messages; more is two figures (the run end to end, then the stage that needs detail)'),
+  repeats: z.array(z.object({
+    from: z.number().int().min(1),
+    to: z.number().int().min(1),
+    label: text(32, 'a label, e.g. "For each model"', 'keep the label to 32 characters'),
+  }).strict()).max(2, 'at most 2 repeated runs of steps').optional(),
+};
+
+/** Rules that span fields: ids that exist, replies that answer a call, repeats over real steps. */
+export function sequenceChecks(s) {
+  const out = [];
+  const ids = s.participants.map((p) => p.id);
+  const dup = ids.find((id, i) => ids.indexOf(id) !== i);
+  if (dup) return [`participants: two participants have the id "${dup}"`];
+  s.messages.forEach((m, i) => {
+    for (const end of ['from', 'to']) if (!ids.includes(m[end])) out.push(`messages[${i}].${end}: no participant has the id "${m[end]}"; the ids are ${ids.map((x) => `"${x}"`).join(', ')}`);
+    if (m.reply && m.from === m.to) out.push(`messages[${i}]: a reply to itself; make it a plain step, or leave it out`);
+    else if (m.reply && !s.messages.slice(0, i).some((c) => !c.reply && c.from === m.to && c.to === m.from)) {
+      out.push(`messages[${i}]: a reply from "${m.from}" to "${m.to}", but "${m.to}" never called "${m.from}" before it; a reply answers an earlier call`);
+    }
+  });
+  const unused = ids.filter((id) => !s.messages.some((m) => m.from === id || m.to === id));
+  if (unused.length) out.push(`participants: ${unused.map((x) => `"${x}"`).join(', ')} ${unused.length === 1 ? 'sends and receives' : 'send and receive'} nothing; leave ${unused.length === 1 ? 'it' : 'them'} out or add the message`);
+  const accentP = s.participants.filter((p) => p.tone).length, accentM = s.messages.filter((m) => m.tone).length;
+  if (accentP > 1) out.push('participants: accent at most one participant, the one to notice');
+  if (accentP && accentM) out.push('tone: accent one participant or some steps, not both');
+  if (accentM && accentM === s.messages.length) out.push('messages: every step is accented, so none stands out; accent only the steps the title is about');
+  const n = s.messages.length;
+  const reps = [...(s.repeats ?? [])].sort((a, b) => a.from - b.from);
+  reps.forEach((r, i) => {
+    if (r.to > n || r.from > n) out.push(`repeats[${i}]: steps run 1 to ${n}`);
+    else if (r.from > r.to) out.push(`repeats[${i}]: "from" is the first repeated step and "to" the last; ${r.from} is after ${r.to}`);
+    if (i > 0 && r.from <= reps[i - 1].to) out.push('repeats: two repeated runs share steps; make them one, or separate them');
+  });
+  return out;
+}