@liggi/figkit 0.0.0-stage → 0.2.0

package/viz/build.mjs

@@ -0,0 +1,27 @@
+/* Bundles viz/ into dist/viz.iife.js (window.figkitViz), which figure pages load to draw split bars, bars and chart specs. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HOME = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SOURCES = ['viz/draw.js', 'package.json'].map((f) => path.join(HOME, f));
+const OUT = path.join(HOME, 'dist/viz.iife.js');
+
+const mtime = (f) => (fs.existsSync(f) ? fs.statSync(f).mtimeMs : 0);
+
+/**
+ * Builds dist/ when a source is newer than it, so `fig` never runs a stale bundle. An installed package ships dist/
+ * without esbuild, and npm gives every file the same date, so there the shipped bundle is used as it is.
+ */
+export async function ensureBuilt({ force = false } = {}) {
+  const newest = Math.max(...SOURCES.map(mtime));
+  if (!force && mtime(OUT) >= newest) return;
+  const esbuild = await import('esbuild').catch(() => null);
+  if (!esbuild) {
+    if (fs.existsSync(OUT)) return;
+    throw new Error('dist/viz.iife.js is missing and esbuild is not installed: run npm install in the figkit folder.');
+  }
+  await esbuild.build({ entryPoints: [path.join(HOME, 'viz/draw.js')], bundle: true, minify: true, format: 'iife', globalName: 'figkitViz', outfile: OUT, logLevel: 'warning' });
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await ensureBuilt({ force: true });

package/viz/draw.js

@@ -0,0 +1,315 @@
+/* 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';
+const NS = 'http://www.w3.org/2000/svg';
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+
+/** Each item: { value, text (the printed number), show?, label (HTML), tone?, note? }. */
+const shown = (x, unit) => x.show ?? x.text + (unit ?? '');
+
+/** Parts of a whole into a <fig-split>. Labels too wide for their segment move to a line under the bar. */
+export function drawSplit(host, parts, unit) {
+  const total = parts.reduce((s, p) => s + p.value, 0);
+  host.innerHTML = '';
+  const bar = Object.assign(document.createElement('div'), { className: 'fs-bar' });
+  const rest = Object.assign(document.createElement('div'), { className: 'fs-rest' });
+  host.append(bar, rest);
+  const segs = parts.map((p) => {
+    const seg = document.createElement('div');
+    seg.className = 'fs-seg' + (p.tone ? ' ' + p.tone : '');
+    seg.style.flex = `${p.value / total} 1 0`;
+    seg.innerHTML = `<b>${esc(shown(p, unit))}</b><span>${p.label}</span>`;
+    bar.appendChild(seg);
+    return { p, seg };
+  });
+  const outs = segs.filter((s) => s.seg.scrollWidth > s.seg.clientWidth + 1);
+  if (!outs.length) { rest.remove(); return; }
+  const hostBox = host.getBoundingClientRect();
+  for (const o of outs) {
+    o.seg.classList.add('fs-out');
+    o.item = document.createElement('span');
+    o.item.innerHTML = `<b>${esc(shown(o.p, unit))}</b> ${o.p.label}`;
+    o.item.style.cssText = 'position: absolute; white-space: nowrap;';
+    rest.appendChild(o.item);
+  }
+  const W = hostBox.width, GAP = 22;
+  for (const o of outs) { const r = o.seg.getBoundingClientRect(); o.cx = r.left - hostBox.left + r.width / 2; o.w = o.item.offsetWidth; }
+  const line = getComputedStyle(host).getPropertyValue('--line').trim();
+  const paths = [];
+  let height;
+  // One line unless a label, pushed apart from its neighbours and kept inside the bar, would sit under another small
+  // segment and read as its label; then one label per line beside them, if there is room on a side.
+  for (const o of outs) o.x = Math.max(0, Math.min(W - o.w, o.cx - o.w / 2));
+  for (let i = 1; i < outs.length; i++) outs[i].x = Math.max(outs[i].x, outs[i - 1].x + outs[i - 1].w + GAP);
+  for (let i = outs.length - 1; i >= 0; i--) { const cap = i === outs.length - 1 ? W - outs[i].w : outs[i + 1].x - GAP - outs[i].w; outs[i].x = Math.min(outs[i].x, cap); }
+  const PAD = 28, widest = Math.max(...outs.map((o) => o.w));
+  const minCx = Math.min(...outs.map((o) => o.cx)), maxCx = Math.max(...outs.map((o) => o.cx));
+  const side = minCx - PAD >= widest ? 'left' : W - maxCx - PAD >= widest ? 'right' : null;
+  const misleading = outs.some((o) => outs.some((q) => q !== o && q.cx > o.x && q.cx < o.x + o.w));
+  if (!misleading || !side) {
+    const DROP = 26;
+    for (const o of outs) {
+      o.y = DROP;
+      const tx = Math.max(o.x + 8, Math.min(o.x + o.w - 8, o.cx));
+      paths.push(`M${o.cx},-8 V${DROP / 2 - 4} H${tx} V${DROP - 3}`);
+    }
+    height = DROP + outs[0].item.offsetHeight;
+  } else {
+    // Each label joined to its segment by an elbow; rows nearest the labels come first, so no line crosses another.
+    const TOP = 14, ROW = outs[0].item.offsetHeight + 8;
+    const left = side === 'left';
+    const rows = [...outs].sort((p, q) => (left ? p.cx - q.cx : q.cx - p.cx));
+    rows.forEach((o, i) => {
+      o.y = TOP + i * ROW;
+      const mid = o.y + o.item.offsetHeight / 2;
+      if (left) { const end = minCx - PAD; o.right = W - end; paths.push(`M${o.cx},-8 V${mid} H${end + 6}`); }
+      else { const start = maxCx + PAD; o.x = start; paths.push(`M${o.cx},-8 V${mid} H${start - 6}`); }
+    });
+    height = TOP + rows.length * ROW - 8;
+  }
+  rest.style.cssText = `position: relative; display: block; height: ${height}px;`;
+  const svg = document.createElementNS(NS, 'svg');
+  svg.setAttribute('width', W); svg.setAttribute('height', height);
+  svg.setAttribute('style', 'position:absolute;left:0;top:0;overflow:visible');
+  rest.appendChild(svg);
+  for (const o of outs) o.item.style.cssText = `position: absolute; ${o.right === undefined ? `left: ${o.x}` : `right: ${o.right}`}px; top: ${o.y}px; white-space: nowrap;`;
+  for (const d of paths) {
+    const path = document.createElementNS(NS, 'path');
+    for (const [k, v] of Object.entries({ d, fill: 'none', stroke: line, 'stroke-width': 1.5 })) path.setAttribute(k, v);
+    svg.appendChild(path);
+  }
+}
+
+/** 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));
+  host.innerHTML = '';
+  const fills = bars.map((b) => {
+    const label = Object.assign(document.createElement('div'), { className: 'fb-label', innerHTML: b.label });
+    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>`;
+    host.append(label, track);
+    return { bar: track.firstChild, ratio: top > 0 ? Math.max(0, b.value) / top : 0 };
+  });
+  // The longest bar 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 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>';
+
+/** One measure before and after into a <fig-change>: two numbers, each over a bar on one shared scale. */
+export function drawChange(host, spec) {
+  const top = spec.max ?? Math.max(spec.before.value, spec.after.value);
+  const tone = spec.after.tone ?? 'accent';
+  const side = (x, cls) => `<div class="fc-side ${cls}"><span class="fc-when">${esc(x.label)}</span><b class="fc-num">${esc(shown({ ...x, text: String(x.value) }, spec.unit))}</b><div class="fc-bar" style="width:${top > 0 ? (100 * x.value) / top : 0}%"></div></div>`;
+  host.innerHTML = side(spec.before, 'before') + `<div class="fc-arrow">${ARROW}</div>` + side(spec.after, 'after ' + tone);
+}
+
+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') };
+};
+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');
+function span(a, b) {
+  const d = Math.abs(b - a) / 864e5;
+  if (d < 1) return `${num(d * 24)} hours`;
+  return `${num(d)} ${d === 1 ? 'day' : 'days'}`;
+}
+function widest(host, texts, size, weight = 400) {
+  const probe = document.createElement('span');
+  probe.style.cssText = `position:absolute;visibility:hidden;white-space:nowrap;font-size:${size}px;font-weight:${weight}`;
+  host.appendChild(probe);
+  const w = Math.max(...texts.map((t) => { probe.textContent = t; return probe.getBoundingClientRect().width; }));
+  probe.remove();
+  return w;
+}
+function plotInto(host, t, opts) {
+  host.classList.add('chart');
+  host.innerHTML = '';
+  host.appendChild(Plot.plot({ ...opts, style: { background: 'transparent', color: t.muted, fontFamily: t.sans, fontSize: t.small + 'px', overflow: 'visible' } }));
+}
+
+/** Rows that each move from one value to another into a .chart: an arrow per row, its gap labelled above it. */
+export function drawDumbbell(host, spec) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640;
+  const date = typeof spec.rows[0].from === 'string';
+  const rows = spec.rows.map((r) => ({ ...r, a: toX(r.from), b: toX(r.to) }));
+  for (const r of rows) {
+    r.text = r.gap ?? (date ? span(r.a, r.b) : num(Math.abs(r.b - r.a)) + (spec.unit ?? ''));
+    r.mid = date ? new Date((+r.a + +r.b) / 2) : (r.a + r.b) / 2;
+    r.color = t[r.tone ?? 'accent'];
+  }
+  const all = rows.flatMap((r) => [+r.a, +r.b]);
+  const lo = Math.min(...all), hi = Math.max(...all), pad = (hi - lo || 1) * 0.08;
+  const domain = date ? [new Date(lo - pad), new Date(hi + pad)] : [lo - pad, hi + pad];
+  const labelW = widest(host, rows.map((r) => r.label), t.body);
+  plotInto(host, t, {
+    width, height: rows.length * 92 + 50, marginLeft: Math.ceil(labelW) + 28, marginRight: 24, marginTop: 0, marginBottom: 40,
+    x: { domain, ticks: width < 600 ? 4 : 5, label: null, tickFormat: date ? undefined : (d) => num(d) + (spec.unit ?? '') },
+    y: { domain: rows.map((r) => r.label), axis: null, padding: 0.5 },
+    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 }),
+      // 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 }),
+      Plot.dot(rows.filter((r) => r.b < r.a), { x: 'b', y: 'label', symbol: 'triangle2', r: 7.5, dx: 5, fill: 'color', rotate: -90 }),
+      Plot.text(rows, { x: 'mid', y: 'label', text: 'text', dy: -22, fill: t.ink, fontWeight: 600, fontSize: t.small }),
+    ],
+  });
+  // The two ends named once, as a key above the rows.
+  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>`;
+  host.prepend(key);
+}
+
+/** A line over ordered x into a .chart, with one point marked and labelled beside it. */
+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 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 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);
+  // Label to the right of the point when it fits inside the plot there, otherwise to the left.
+  const left0 = Math.ceil(tickW) + 14, plotW = width - left0 - 20;
+  const at = left0 + plotW * ((+mark.x - +pts[0].x) / (+pts[pts.length - 1].x - +pts[0].x));
+  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);
+  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 }),
+      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 }),
+    ],
+  });
+}
+
+/**
+ * Where each record sits: every arrangement of the records over a few small grids is scored, and the best kept.
+ * A score counts references that cross, references that pass over another record, long references, and records drawn
+ * above what they point at (a reference reads upward, to the thing it names). A phone gets at most two columns.
+ */
+export function placeRecords(records, refs, phone) {
+  const n = records.length;
+  const shapes = [];
+  for (let rows = 1; rows <= 3; rows++) for (let cols = 1; cols <= (phone ? 2 : 3); cols++) {
+    if (rows * cols >= n && rows * cols - n < Math.min(rows, cols)) shapes.push([rows, cols]);
+  }
+  const idx = new Map(records.map((r, i) => [r.id, i]));
+  const edges = refs.map((r) => [idx.get(r.from), idx.get(r.to)]);
+  const cross = (a, b, c, d) => {
+    const o = (p, q, r) => Math.sign((q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0]));
+    return o(a, b, c) * o(a, b, d) < 0 && o(c, d, a) * o(c, d, b) < 0;
+  };
+  // A record's cell is about 1.6 times as wide as it is tall, gaps included.
+  const pt = ([r, c]) => [c * 1.6, r];
+  const over = (a, b, cell) => {
+    const [x1, y1] = pt(a), [x2, y2] = pt(b), [cx, cy] = pt(cell);
+    const hw = 0.55, hh = 0.32;
+    for (let t = 0.04; t < 1; t += 0.04) { const x = x1 + (x2 - x1) * t, y = y1 + (y2 - y1) * t; if (Math.abs(x - cx) < hw && Math.abs(y - cy) < hh) return true; }
+    return false;
+  };
+  let best = null;
+  for (const [rows, cols] of shapes) {
+    const cells = [];
+    for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) cells.push([r, c]);
+    const used = new Array(cells.length).fill(false), at = new Array(n);
+    const score = () => {
+      let s = rows * 0.6 + cols * 0.3;
+      const pos = at.map((k) => cells[k]);
+      edges.forEach(([f, t], i) => {
+        const a = pos[f], b = pos[t];
+        const [x1, y1] = pt(a), [x2, y2] = pt(b);
+        s += Math.hypot(x2 - x1, y2 - y1) * 1.2;
+        if (a[0] !== b[0] && a[1] !== b[1]) s += 1.5;
+        if (a[0] < b[0]) s += 3;
+        pos.forEach((p, k) => { if (k !== f && k !== t && over(a, b, p)) s += 12; });
+        for (const [g, u] of edges.slice(i + 1)) if (g !== f && g !== t && u !== f && u !== t && cross(pt(a), pt(b), pt(pos[g]), pt(pos[u]))) s += 8;
+      });
+      // An empty cell in the middle of a row reads as something missing.
+      for (let r = 0; r < rows; r++) for (let c = 1; c < cols - 1; c++) if (!pos.some((p) => p[0] === r && p[1] === c) && pos.some((p) => p[0] === r)) s += 4;
+      return s;
+    };
+    const walk = (i) => {
+      if (i === n) { const s = score(); if (!best || s < best.s - 1e-9) best = { s, rows, cols, pos: at.map((k) => cells[k]) }; return; }
+      for (let k = 0; k < cells.length; k++) if (!used[k]) { used[k] = true; at[i] = k; walk(i + 1); used[k] = false; }
+    };
+    walk(0);
+  }
+  return best;
+}
+
+/** Records and the references between them into the figure: boxes on a grid figkit chose, and <fig-arrow ref> lines. */
+function drawEntities(spec, main) {
+  const phone = main.classList.contains('phone');
+  const { rows, cols, pos } = placeRecords(spec.records, spec.refs, phone);
+  const grid = document.createElement('div');
+  grid.className = 'entities';
+  grid.style.cssText = `grid-template-columns: repeat(${cols}, minmax(0, 1fr)); grid-template-rows: repeat(${rows}, auto);`;
+  spec.records.forEach((r, i) => {
+    const fields = r.fields ?? [];
+    const box = document.createElement('div');
+    box.className = 'node record' + (r.tone ? ' accent' : '');
+    box.id = 'rec-' + r.id;
+    box.style.gridArea = `${pos[i][0] + 1} / ${pos[i][1] + 1}`;
+    box.innerHTML = `<h3>${esc(r.name)}</h3>${fields.length ? `<ul>${fields.map((f) => `<li>${esc(f)}</li>`).join('')}</ul>` : ''}`;
+    grid.appendChild(box);
+  });
+  main.appendChild(grid);
+  for (const ref of spec.refs) {
+    const a = document.createElement('fig-arrow');
+    a.setAttribute('from', 'rec-' + ref.from);
+    a.setAttribute('to', 'rec-' + ref.to);
+    a.setAttribute('ref', ref.count);
+    if (ref.optional) a.setAttribute('dashed', '');
+    main.appendChild(a);
+  }
+}
+
+const HOSTS = { split: 'fig-split', bars: 'fig-bars', 'before-after': 'fig-change', dumbbell: 'div', series: '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>` : ''}`;
+  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: () => {} };
+  }
+  const chart = document.createElement(HOSTS[spec.type]);
+  main.append(header, chart);
+  if (spec.source) {
+    const footer = document.createElement('footer');
+    footer.innerHTML = `<p>${esc(spec.source)}</p>`;
+    main.append(footer);
+  }
+  const draw = () => {
+    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);
+    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);
+  };
+  draw();
+  return { chart, draw };
+}

package/viz/index.js

@@ -0,0 +1,2 @@
+export { parseSpec, Spec, SplitSpec, BarsSpec, TYPES } from './spec.js';
+export { drawSplit, drawBars, drawSpec } from './draw.js';

package/viz/spec.js

@@ -0,0 +1,177 @@
+/* The named visualisations: one Zod schema per type. An agent picks a type and gives data; it never writes markup. */
+import { z } from 'zod';
+
+const TONE = z.enum(['accent', 'second', 'good', 'bad']);
+const label = z.string({ error: 'needs a label' }).trim().min(1, 'needs a label').max(40, 'keep labels to 40 characters');
+const title = z.string({ error: 'needs a title: the one point, stated' }).trim().min(1, 'needs a title: the one point, stated')
+  .refine((t) => t.split(/\s+/).length <= 14, 'keep the title to 14 words');
+const common = {
+  title,
+  note: z.string().trim().max(160, 'keep the note to 160 characters').optional(),
+  unit: z.string().max(8).optional(),
+  source: z.string().trim().max(120).optional(),
+};
+const value = z.number({ error: 'must be a number' }).finite();
+
+/** Parts of a whole, as one bar cut into segments. */
+export const SplitSpec = z.object({
+  type: z.literal('split'),
+  ...common,
+  parts: z.array(z.object({
+    label,
+    value: value.positive('must be more than 0'),
+    tone: TONE.optional(),
+    show: z.string().max(24).optional(),
+  }).strict()).min(2, 'a split needs at least 2 parts').max(8, 'at most 8 parts; group the small ones as "Other"'),
+}).strict();
+
+/** A few numbers compared, one bar each, on an axis from zero. */
+export const BarsSpec = z.object({
+  type: z.literal('bars'),
+  ...common,
+  max: z.number().positive().optional(),
+  bars: z.array(z.object({
+    label,
+    value: value.nonnegative('must be 0 or more'),
+    tone: TONE.optional(),
+    show: z.string().max(24).optional(),
+    note: z.string().trim().max(40).optional(),
+  }).strict()).min(1).max(12, 'at most 12 bars'),
+}).strict()
+  .refine((s) => s.max === undefined || s.bars.every((b) => b.value <= s.max), { message: 'every value must be at most max', path: ['max'] });
+
+const side = z.object({
+  label: z.string({ error: 'needs a label: when it was' }).trim().min(1, 'needs a label: when it was').max(24, 'keep it to 24 characters'),
+  value: value.nonnegative('must be 0 or more'),
+  show: z.string().max(16).optional(),
+}).strict();
+
+/** One measure that changed: the value before and after, side by side on one scale. */
+export const BeforeAfterSpec = z.object({
+  type: z.literal('before-after'),
+  ...common,
+  note: z.string({ error: 'required: what the number counts, e.g. "Share of orders delivered late"' }).trim().min(1).max(80, 'keep the note to 80 characters'),
+  max: z.number().positive().optional(),
+  before: side,
+  after: side.extend({ tone: TONE.optional() }),
+}).strict()
+  .refine((s) => s.max === undefined || (s.before.value <= s.max && s.after.value <= s.max), { message: 'both values must be at most max', path: ['max'] });
+
+const isoDate = z.string().refine((d) => /^\d{4}-\d{2}-\d{2}/.test(d) && !Number.isNaN(Date.parse(d)), 'must be a number or a date like 2026-10-05');
+const point = z.union([z.number().finite(), isoDate], { error: 'must be a number or a date like 2026-10-05' });
+
+/** Each row a move from one value to another, drawn as an arrow, with the gap labelled. */
+export const DumbbellSpec = z.object({
+  type: z.literal('dumbbell'),
+  ...common,
+  fromLabel: z.string({ error: 'required: what the start of each arrow is' }).trim().min(1).max(24),
+  toLabel: z.string({ error: 'required: what the end of each arrow is' }).trim().min(1).max(24),
+  rows: z.array(z.object({
+    label: label.max(24, 'keep row labels to 24 characters'),
+    from: point,
+    to: point,
+    gap: z.string().max(20).optional(),
+    tone: TONE.optional(),
+  }).strict()).min(1).max(8, 'at most 8 rows'),
+}).strict();
+
+/** A line over time (or any ordered x) with one point marked and labelled. */
+export const SeriesSpec = z.object({
+  type: z.literal('series'),
+  ...common,
+  points: z.array(z.object({ x: point, y: value }).strict()).min(3, 'a series needs at least 3 points').max(2000),
+  mark: z.object({ x: point, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }, { error: 'required: the one point to notice, { "x", "label" }' }).strict(),
+  zero: z.boolean().optional(),
+}).strict();
+
+const slug = z.string({ error: 'needs an id, e.g. "order"' }).regex(/^[a-z][a-z0-9-]{0,23}$/, 'ids are short lowercase words, e.g. "order" or "order-line"');
+
+/**
+ * What the things are and which points at which: records, and references from one record to another. A reference is
+ * a pointer one record holds (a foreign key, an id field), never a step in the order work happens.
+ */
+export const EntitiesSpec = z.object({
+  type: z.literal('entities'),
+  title,
+  note: common.note,
+  source: common.source,
+  records: z.array(z.object({
+    id: slug,
+    name: label.max(32, 'keep record names to 32 characters'),
+    table: z.never({ error: 'no table: name the record in words; if the table name matters to the reader, put it in fields' }).optional(),
+    fields: z.array(z.string().trim().min(1).max(36, 'keep each field to 36 characters')).max(4, 'at most 4 fields: the ones that explain the picture').optional(),
+    tone: z.literal('accent', { error: 'tone: only "accent", on the one record to notice' }).optional(),
+  }).strict()).min(2, 'at least 2 records').max(5, 'at most 5 records; more is two figures (the core, then one corner of it), not one'),
+  refs: z.array(z.object({
+    from: slug,
+    to: slug,
+    field: z.never({ error: 'no field: the line is the reference, so its column is not written out' }).optional(),
+    count: z.enum(['many', 'one'], { error: 'count: "many" or "one": how many "from" records can point at one "to" record' }).default('many'),
+    optional: z.boolean().optional(),
+  }).strict()).min(1, 'at least 1 reference').max(8, 'at most 8 references; more is two figures, not a reference left out'),
+}).strict();
+
+export const Spec = z.discriminatedUnion('type', [SplitSpec, BarsSpec, BeforeAfterSpec, DumbbellSpec, SeriesSpec, EntitiesSpec]);
+export const TYPES = { split: SplitSpec, bars: BarsSpec, 'before-after': BeforeAfterSpec, dumbbell: DumbbellSpec, series: SeriesSpec, entities: EntitiesSpec };
+
+const items = (s) => s.parts ?? s.bars ?? s.rows ?? s.records ?? (s.after ? [s.after] : []);
+const kind = (v) => (typeof v === 'number' ? 'number' : 'date');
+
+/** Rules that span fields: x values of one kind, in order, and a mark that is one of the points. */
+function crossChecks(s) {
+  if (s.type === 'dumbbell') {
+    const kinds = new Set(s.rows.flatMap((r) => [kind(r.from), kind(r.to)]));
+    if (kinds.size > 1) return ['rows: use all numbers or all dates, not both'];
+  }
+  if (s.type === 'series') {
+    const kinds = new Set(s.points.map((p) => kind(p.x)));
+    if (kinds.size > 1) return ['points: x values must be all numbers or all dates, not both'];
+    const at = (x) => (typeof x === 'number' ? x : Date.parse(x));
+    for (let i = 1; i < s.points.length; i++) if (at(s.points[i].x) <= at(s.points[i - 1].x)) return [`points[${i}].x: points must be in order of x, each later than the one before`];
+    if (!s.points.some((p) => at(p.x) === at(s.mark.x))) return [`mark.x: must be the x of one of the points, not ${JSON.stringify(s.mark.x)}`];
+  }
+  if (s.type === 'entities') {
+    const ids = s.records.map((r) => r.id);
+    const dup = ids.find((id, i) => ids.indexOf(id) !== i);
+    if (dup) return [`records: two records have the id "${dup}"`];
+    const out = [];
+    const pairs = new Set();
+    s.refs.forEach((r, i) => {
+      for (const end of ['from', 'to']) if (!ids.includes(r[end])) out.push(`refs[${i}].${end}: no record has the id "${r[end]}"; the ids are ${ids.map((x) => `"${x}"`).join(', ')}`);
+      if (r.from === r.to) out.push(`refs[${i}]: a record pointing at itself; say it in its fields instead`);
+      const key = r.from + '>' + r.to;
+      if (pairs.has(key)) out.push(`refs[${i}]: a second reference from "${r.from}" to "${r.to}"; make it one reference`);
+      pairs.add(key);
+    });
+    if (s.records.filter((r) => r.tone).length > 1) out.push('records: accent at most one record, the one to notice');
+    const loose = ids.filter((id) => !s.refs.some((r) => r.from === id || r.to === id));
+    if (loose.length) out.push(`records: ${loose.map((x) => `"${x}"`).join(', ')} ${loose.length === 1 ? 'is' : 'are'} not in any reference; leave ${loose.length === 1 ? 'it' : 'them'} out or add the reference`);
+    return out;
+  }
+  return [];
+}
+
+/**
+ * Checks a spec (an object or JSON text). Returns { ok: true, spec } or { ok: false, problems },
+ * each problem one line naming where it is, e.g. `parts[2].value: must be more than 0`.
+ */
+export function parseSpec(input) {
+  let data = input;
+  if (typeof input === 'string') {
+    try { data = JSON.parse(input); } catch (e) { return { ok: false, problems: [`Not valid JSON: ${e.message}`] }; }
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return { ok: false, problems: ['A spec is a JSON object with a "type"'] };
+  if (!(data.type in TYPES)) return { ok: false, problems: [`type: must be one of ${Object.keys(TYPES).map((t) => `"${t}"`).join(', ')}${data.type === undefined ? '' : `, not ${JSON.stringify(data.type)}`}`] };
+  const r = Spec.safeParse(data);
+  if (!r.success) return { ok: false, problems: r.error.issues.map((i) => `${where(i.path)}${i.message}`) };
+  const cross = crossChecks(r.data);
+  if (cross.length) return { ok: false, problems: cross };
+  const tones = new Set(items(r.data).map((x) => x.tone).filter(Boolean));
+  if (tones.size > 2) return { ok: false, problems: [`tone: use at most two colours, one for what to notice; this uses ${[...tones].join(', ')}`] };
+  return { ok: true, spec: r.data };
+}
+
+function where(path) {
+  if (!path.length) return '';
+  return path.reduce((s, p) => (typeof p === 'number' ? `${s}[${p}]` : s ? `${s}.${String(p)}` : String(p)), '') + ': ';
+}