@liggi/figkit 0.3.0 → 0.5.0

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;
+}

package/viz/sequence.js

@@ -0,0 +1,171 @@
+/* The "sequence" spec drawn: participants across the top, each message a numbered step down the page. */
+const NS = 'http://www.w3.org/2000/svg';
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+
+function svgEl(tag, attrs, parent) {
+  const el = document.createElementNS(NS, tag);
+  for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+  parent.appendChild(el);
+  return el;
+}
+
+/**
+ * Participants side by side in boxes, a line down from each, and the messages in order: a solid arrow for a call, a
+ * dashed one for a reply, a loop for work a participant does itself. Each label sits on the paper above its arrow,
+ * numbered, so prose can say "step 4". Repeated steps sit in a dashed frame named at its top.
+ */
+export function drawSequence(spec, main) {
+  const phone = main.classList.contains('phone');
+  const host = document.createElement('div');
+  host.className = 'sequence';
+  main.appendChild(host);
+  const css = (n) => getComputedStyle(host).getPropertyValue(n).trim();
+  const ink = { line: css('--line'), soft: css('--soft'), accent: css('--accent'), hair: css('--hair'), muted: css('--muted') };
+
+  const lanes = document.createElement('div');
+  lanes.className = 'seq-lanes';
+  host.appendChild(lanes);
+  const svg = document.createElementNS(NS, 'svg');
+  host.prepend(svg);
+  const W = host.clientWidth, n = spec.participants.length;
+  const SEP = phone ? 12 : 24;
+  const boxes = spec.participants.map((p) => {
+    const box = document.createElement('div');
+    box.className = 'node seq-who' + (p.tone ? ' accent' : '');
+    box.id = 'who-' + p.id;
+    box.innerHTML = `<h3>${esc(p.name)}</h3>${p.kind ? `<p>${esc(p.kind)}</p>` : ''}`;
+    lanes.appendChild(box);
+    return box;
+  });
+  // Lanes share the width equally. When a name's longest word will not fit, lanes widen for the names that need it
+  // and narrow for the ones that don't; then the names drop a size; only then do the boxes alternate between two rows.
+  const set = (box, left, width) => Object.assign(box.style, { left: left + 'px', width: width + 'px' });
+  let edge = spec.participants.map((_, i) => (W / n) * i).concat(W);
+  const layout = () => boxes.forEach((b, i) => set(b, edge[i] + SEP / 2, edge[i + 1] - edge[i] - SEP));
+  const over = () => boxes.some((b) => b.scrollWidth > b.clientWidth + 1);
+  const fit = () => {
+    const need = boxes.map((b) => { b.style.width = 'min-content'; return b.offsetWidth + SEP; });
+    const spare = W - need.reduce((a, v) => a + v, 0);
+    if (spare < 0) return false;
+    edge = [0];
+    need.forEach((v) => edge.push(edge[edge.length - 1] + v + spare / n));
+    return true;
+  };
+  layout();
+  let stagger = false;
+  if (over()) {
+    if (!fit()) { lanes.classList.add('tight'); if (!fit()) { edge = spec.participants.map((_, i) => (W / n) * i).concat(W); stagger = n > 2; } }
+    layout();
+    if (stagger) {
+      boxes.forEach((b, i) => {
+        const lo = i > 0 ? (edge[i - 1] + edge[i]) / 2 + SEP / 2 : 0, hi = i < n - 1 ? (edge[i + 1] + edge[i + 2]) / 2 - SEP / 2 : W;
+        set(b, lo, hi - lo);
+      });
+    }
+  }
+  const x = {};
+  spec.participants.forEach((p, i) => { x[p.id] = (edge[i] + edge[i + 1]) / 2; });
+  const L = Math.min(...spec.participants.map((_, i) => edge[i + 1] - edge[i]));
+  const tall = Math.max(...boxes.map((b) => b.offsetHeight));
+  const ROW2 = tall + (phone ? 14 : 18);
+  const bottom = {};
+  boxes.forEach((b, i) => {
+    const down = stagger && i % 2 === 1;
+    Object.assign(b.style, { height: tall + 'px', top: (down ? ROW2 : 0) + 'px' });
+    bottom[spec.participants[i].id] = (down ? ROW2 : 0) + tall;
+  });
+  const top = Math.max(...Object.values(bottom));
+  lanes.style.height = top + 'px';
+  const GAP = phone ? 20 : 24, LIFT = 8, LOOP = phone ? 26 : 32, HEAD = 10;
+  const reps = spec.repeats ?? [];
+  const frames = [];
+  let y = top + (phone ? 26 : 30);
+  const label = (m, i) => {
+    const el = document.createElement('div');
+    el.className = 'seq-msg' + (m.reply ? ' reply' : '') + (m.tone ? ' accent' : '');
+    el.innerHTML = `<span class="seq-n"><span class="seq-ink">${i + 1}</span></span><span class="seq-text"><span class="seq-ink">${esc(m.label)}</span>${m.note ? `<span class="seq-note"><span class="seq-ink">${esc(m.note)}</span></span>` : ''}</span>`;
+    host.appendChild(el);
+    return el;
+  };
+  const place = (el, maxW) => {
+    el.style.maxWidth = Math.max(80, Math.floor(maxW)) + 'px';
+    el.style.left = '0px';
+    return el.offsetWidth;
+  };
+
+  spec.messages.forEach((m, i) => {
+    const rep = reps.find((r) => r.from === i + 1);
+    if (rep) {
+      const tab = document.createElement('div');
+      tab.className = 'seq-frame-label';
+      tab.textContent = rep.label;
+      host.appendChild(tab);
+      // The frame covers only the lanes its steps touch, edge to edge between lines, widened for any label past them.
+      const idx = spec.messages.slice(rep.from - 1, rep.to).flatMap((q) => [q.from, q.to]).map((id) => spec.participants.findIndex((p) => p.id === id));
+      tab.style.top = y + 'px';
+      frames.push({ rep, tab, top: y + tab.offsetHeight / 2, lo: x[spec.participants[Math.min(...idx)].id], hi: x[spec.participants[Math.max(...idx)].id], labels: [] });
+      y += tab.offsetHeight + 10;
+    }
+    const el = label(m, i);
+    const color = m.tone ? ink.accent : m.reply ? ink.soft : ink.line;
+    if (m.from === m.to) {
+      // Work a participant does itself: a loop out to the side of its line, the label beside the loop.
+      const lx = x[m.from];
+      const roomRight = W - (lx + LOOP + 14), roomLeft = lx - LOOP - 14;
+      const right = roomRight >= Math.min(roomLeft, 260) || roomRight >= 200;
+      const ids = spec.participants.map((p) => x[p.id]);
+      const next = right ? Math.min(...ids.filter((v) => v > lx), Infinity) - (lx + LOOP + 14) - 10 : (lx - LOOP - 14) - Math.max(...ids.filter((v) => v < lx), -Infinity) - 10;
+      const w = place(el, Math.min(right ? roomRight : roomLeft, next >= (phone ? 130 : 150) ? next : Infinity));
+      const h = el.offsetHeight;
+      const loopH = Math.max(h, 30);
+      el.style.left = (right ? lx + LOOP + 14 : lx - LOOP - 14 - w) + 'px';
+      el.style.top = y + (loopH - h) / 2 + 'px';
+      const side = right ? 1 : -1, x1 = lx + side * LOOP;
+      svgEl('path', { d: `M${lx},${y} H${x1} V${y + loopH} H${lx + side * (HEAD + 2)}`, fill: 'none', stroke: color, 'stroke-width': 2.25, 'stroke-linejoin': 'round' }, svg);
+      head(lx, y + loopH, -side, color);
+      y += loopH + GAP;
+    } else {
+      const a = x[m.from], b = x[m.to], dir = Math.sign(b - a);
+      // A label starts just inside the arrow's left end, the same for every arrow, and wraps to stay between the
+      // arrow's two lines. Where that is too narrow to read, it reaches at most halfway to the next line out.
+      const lo = Math.min(a, b), hi = Math.max(a, b), MIN = phone ? 150 : 180;
+      const next = Math.min(...Object.values(x).filter((v) => v > hi), Infinity);
+      const inside = hi - lo - 14 >= (phone ? 160 : 140);
+      const reach = inside ? hi - lo - 14 : Math.max(MIN, (next === Infinity ? W : (hi + next) / 2 - 6) - (lo + 6));
+      const w = place(el, Math.min(W, reach));
+      const left = Math.max(0, Math.min(W - w, lo + 6));
+      el.style.left = left + 'px';
+      el.style.top = y + 'px';
+      const ay = y + el.offsetHeight + LIFT;
+      svgEl('line', { x1: a, y1: ay, x2: b - dir * (HEAD + 1), y2: ay, stroke: color, 'stroke-width': 2.25, ...(m.reply ? { 'stroke-dasharray': '7 6' } : {}) }, svg);
+      head(b, ay, dir, color);
+      y = ay + GAP;
+    }
+    for (const f of frames) if (i + 1 >= f.rep.from && i + 1 <= f.rep.to) f.labels.push(el);
+    const open = frames.find((f) => f.rep.to === i + 1);
+    if (open) { open.bottom = y - GAP + 14; y += 14; }
+  });
+  const H = y - GAP + 24;
+  host.style.height = H + 'px';
+  svg.setAttribute('width', W); svg.setAttribute('height', H);
+  // Lines down from each participant and the frames round repeated steps, behind the arrows.
+  const back = document.createElementNS(NS, 'g');
+  svg.prepend(back);
+  // Every frame keeps the same inset outside its first and last lines: the widest any of them needs.
+  let pad = Math.min(L / 2 - 4, 40);
+  for (const f of frames) for (const el of f.labels) pad = Math.max(pad, f.lo - el.offsetLeft + 8, el.offsetLeft + el.offsetWidth + 8 - f.hi);
+  for (const f of frames) {
+    // The same inset outside the first and last lines, wide enough for every label inside.
+    f.left = Math.max(1, f.lo - pad); f.right = Math.min(W - 1, f.hi + pad);
+    // The name starts just past the first line inside the frame, so it covers no line.
+    f.tab.style.left = Math.max(f.left + 14, Math.min(f.lo + 6, f.right - 14 - f.tab.offsetWidth)) + 'px';
+  }
+  for (const f of frames) svgEl('rect', { x: f.left, y: f.top, width: f.right - f.left, height: f.bottom - f.top, rx: 10, fill: 'none', stroke: ink.muted, 'stroke-opacity': 0.55, 'stroke-width': 1.5, 'stroke-dasharray': '6 6' }, back);
+  for (const p of spec.participants) svgEl('line', { x1: x[p.id], y1: bottom[p.id], x2: x[p.id], y2: H, stroke: ink.hair, 'stroke-width': 2 }, back);
+
+  function head(tipX, tipY, dir, color) {
+    const back = tipX - dir * (HEAD + 2);
+    svgEl('path', { d: `M${tipX - dir * 1},${tipY} L${back},${tipY - 6.5} L${back},${tipY + 6.5} Z`, fill: color }, svg);
+  }
+  return host;
+}

package/viz/spec.js

@@ -1,5 +1,7 @@
 /* The named visualisations: one Zod schema per type. An agent picks a type and gives data; it never writes markup. */
 import { z } from 'zod';
+import { sequenceShape, sequenceChecks } from './sequence-spec.js';
+import { statesShape, statesChecks } from './states-spec.js';
 
 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');
@@ -13,6 +15,12 @@ const common = {
   style: z.enum(['report'], { error: 'style: "report" for a light chart that sits in a page, or leave it out' }).optional(),
 };
 const value = z.number({ error: 'must be a number' }).finite();
+/** What the low-to-high ranges are, printed beside a drawn range: required whenever a chart has ranges. */
+const range = z.string().trim().min(1).max(40, 'keep the range description to 40 characters, e.g. "95% interval"').optional();
+const bound = z.number({ error: 'must be a number' }).finite().optional();
+/** The plural noun one counted item is, so a count reads "14 runs" rather than "n = 14". */
+const each = z.string().trim().min(1).max(16, 'keep it to 16 characters, a plural noun such as "runs"').optional();
+const sample = z.number({ error: 'the sample size, a whole number' }).int('the sample size, a whole number').positive('must be more than 0').optional();
 
 /** Parts of a whole, as one bar cut into segments. */
 export const SplitSpec = z.object({
@@ -37,9 +45,19 @@ export const BarsSpec = z.object({
     tone: TONE.optional(),
     show: z.string().max(24).optional(),
     note: z.string().trim().max(40).optional(),
+    low: bound,
+    high: bound,
+    n: sample,
   }).strict()).min(1).max(12, 'at most 12 bars'),
+  range,
+  each,
+  ref: z.object({
+    value: value.nonnegative('must be 0 or more'),
+    label: label.refine((t) => /\p{L}/u.test(t), 'say what the reference is in words, e.g. "Production (ash-prod-27b)", not just a number'),
+    show: z.string().max(24).optional(),
+  }, { error: 'ref: { "value", "label" }, the level every bar is compared with, e.g. production' }).strict().optional(),
 }).strict()
-  .refine((s) => s.max === undefined || s.bars.every((b) => b.value <= s.max), { message: 'every value must be at most max', path: ['max'] });
+  .refine((s) => s.max === undefined || s.bars.every((b) => Math.max(b.value, b.high ?? 0) <= s.max), { message: 'every value and every high 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'),
@@ -76,11 +94,38 @@ export const DumbbellSpec = z.object({
   }).strict()).min(1).max(8, 'at most 8 rows'),
 }).strict();
 
+/**
+ * Signed estimates with their ranges around a zero line, one row each (a forest plot): a gap, a change or a correlation,
+ * and how sure it is. Colour is not chosen by the author: a row is coloured when its range clears zero, grey when not.
+ */
+export const EstimatesSpec = z.object({
+  type: z.literal('estimates'),
+  ...common,
+  note: z.string({ error: 'required: what each number is and which way round, e.g. "Gap in points, matched minus not matched"' }).trim().min(1).max(160, 'keep the note to 160 characters'),
+  range: z.string({ error: 'required: what the ranges are, e.g. "95% interval"' }).trim().min(1).max(40, 'keep the range description to 40 characters, e.g. "95% interval"'),
+  sides: z.object({
+    below: label.max(28, 'keep it to 28 characters'),
+    above: label.max(28, 'keep it to 28 characters'),
+  }, { error: 'sides: { "below", "above" }, what a value under and over zero means, e.g. "Control better"' }).strict().optional(),
+  better: z.enum(['higher', 'lower'], { error: 'better: "higher" or "lower", when one direction is good; rows clear of zero then read as good or bad' }).optional(),
+  rows: z.array(z.object({
+    label: label.max(32, 'keep row labels to 32 characters'),
+    value,
+    low: z.number({ error: 'every estimate needs its range: "low" and "high". A number with no range is a "bars" chart' }).finite(),
+    high: z.number({ error: 'every estimate needs its range: "low" and "high". A number with no range is a "bars" chart' }).finite(),
+    tone: z.never({ error: 'no tone: figkit colours a row whose range clears zero and greys one whose range includes it, so the colour cannot claim more than the range' }).optional(),
+    n: sample,
+  }).strict()).min(1).max(12, 'at most 12 rows; more is two figures'),
+  each,
+}).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),
+  points: z.array(z.object({ x: point, y: value, low: bound, high: bound }).strict()).min(3, 'a series needs at least 3 points').max(2000),
+  range,
+  ref: z.object({ y: value, label: z.string().trim().min(1).max(32, 'keep the reference label to 32 characters') }, { error: 'ref: { "y", "label" }, a level to compare the line with' }).strict().optional(),
   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();
@@ -107,7 +152,7 @@ const groupsData = {
 export const GroupsSpec = z.object({ type: z.literal('groups'), ...common, ...groupsData }).strict();
 
 /** Two or three lines on one axis, each named at its end; one is the line to notice. */
-const linePoint = z.object({ x: point, y: value }).strict();
+const linePoint = z.object({ x: point, y: value, low: bound, high: bound }).strict();
 const linesData = {
   series: z.array(z.object({
     label: seriesName,
@@ -116,6 +161,7 @@ const linesData = {
   accent: z.string({ error: 'required: the label of the line to notice' }),
   mark: z.object({ x: point, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }).strict().optional(),
   zero: z.boolean().optional(),
+  range,
   xTicks: z.array(z.object({ x: point, label: z.string().trim().min(1).max(12, 'keep tick labels to 12 characters') }).strict()).min(2).max(8, 'at most 8 ticks').optional(),
 };
 export const LinesSpec = z.object({ type: z.literal('lines'), ...common, ...linesData }).strict();
@@ -129,6 +175,7 @@ export const PanelsSpec = z.object({
   accent: z.union([z.string(), groupsData.accent]),
   max: z.number().positive().optional(),
   zero: z.boolean().optional(),
+  range,
   xTicks: linesData.xTicks,
   panels: z.array(z.object({
     label: label.max(32, 'keep panel labels to 32 characters'),
@@ -138,15 +185,72 @@ export const PanelsSpec = z.object({
 }).strict();
 
 /** A grid of values coloured from pale to strong: where something is high or low across two dimensions. */
-const axisLabel = z.union([z.string().trim().min(1).max(16, 'keep row and column labels to 16 characters'), z.number().finite()]);
+const axisLabel = z.union([z.string().trim().min(1).max(16, 'keep column labels to 16 characters'), z.number().finite()]);
 export const HeatmapSpec = z.object({
   type: z.literal('heatmap'),
   ...common,
   note: z.string({ error: 'required: what the colour counts, e.g. "People active per hour"' }).trim().min(1).max(160, 'keep the note to 160 characters'),
-  rows: z.array(axisLabel).min(2).max(12, 'at most 12 rows'),
+  rows: z.array(z.union([z.string().trim().min(1).max(28, 'keep row labels to 28 characters'), z.number().finite()])).min(2).max(12, 'at most 12 rows'),
   columns: z.array(axisLabel).min(2).max(31, 'at most 31 columns'),
   values: z.array(z.array(value)),
-  mark: z.object({ row: axisLabel, column: axisLabel, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }).strict().optional(),
+  mark: z.object({ row: z.union([z.string(), z.number()]), column: axisLabel, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }).strict().optional(),
+}).strict();
+
+/** Every value as a dot: one row per group, the dots stacked where they would overlap, so none hides another. */
+export const DotsSpec = z.object({
+  type: z.literal('dots'),
+  ...common,
+  note: z.string({ error: 'required: what each dot is and what it measures, e.g. "One dot per run: minutes to finish"' }).trim().min(1).max(160, 'keep the note to 160 characters'),
+  groups: z.array(z.object({
+    label: label.max(28, 'keep group labels to 28 characters'),
+    values: z.array(value).min(1).max(300, 'at most 300 dots in a group; more is a distribution, not dots to look at one by one'),
+    tone: TONE.optional(),
+  }).strict()).min(1).max(6, 'at most 6 groups'),
+  each,
+  summary: z.enum(['median', 'mean'], { error: 'summary: "median" or "mean", drawn as a line across each group' }).optional(),
+  mark: z.object({ group: z.string(), value, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }).strict().optional(),
+  zero: z.boolean().optional(),
+  max: z.number().finite().optional(),
+}).strict();
+
+/** Two measures against each other, a dot per thing measured. Both axes say what they measure. */
+const axis = z.object({
+  label: z.string({ error: 'required: what this axis measures' }).trim().min(1, 'required: what this axis measures').max(40, 'keep axis labels to 40 characters'),
+  unit: z.string().max(8).optional(),
+  log: z.boolean().optional(),
+  zero: z.boolean().optional(),
+  time: z.enum(['seconds', 'minutes', 'hours', 'days'], { error: 'time: "seconds", "minutes", "hours" or "days", the unit the values are in; ticks then read 1 min, 1 h, 1 day' }).optional(),
+}, { error: 'required: { "label" } saying what this axis measures' }).strict();
+export const ScatterSpec = z.object({
+  type: z.literal('scatter'),
+  title: common.title,
+  note: z.string({ error: 'required: what each dot is, e.g. "One dot per merged pull request"' }).trim().min(1).max(160, 'keep the note to 160 characters'),
+  source: common.source,
+  style: common.style,
+  x: axis,
+  y: axis,
+  medians: z.boolean().optional(),
+  points: z.array(z.object({
+    x: value, y: value,
+    label: z.string().trim().min(1).max(32, 'keep point labels to 32 characters').optional(),
+    tone: TONE.optional(),
+  }).strict()).min(3, 'at least 3 points').max(1000, 'at most 1000 points'),
+}).strict();
+
+/** A small count made concrete: one square per thing counted, the ones that matter filled. */
+export const UnitsSpec = z.object({
+  type: z.literal('units'),
+  title: common.title,
+  note: common.note,
+  source: common.source,
+  style: common.style,
+  total: z.number({ error: 'how many things there are, a whole number' }).int('a whole number; units are things, not fractions').min(2).max(100, 'at most 100 units; more cannot be counted by eye, so use a "split" bar of the shares'),
+  parts: z.array(z.object({
+    label: label.max(32, 'keep part labels to 32 characters'),
+    count: z.number({ error: 'a whole number' }).int('a whole number; units are things, not fractions').positive('more than 0'),
+    tone: TONE.optional(),
+  }).strict()).min(1).max(3, 'at most 3 filled parts; the rest are the empty squares'),
+  rest: label.max(32, 'keep the rest label to 32 characters'),
 }).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"');
@@ -177,13 +281,37 @@ export const EntitiesSpec = z.object({
   }).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, GroupsSpec, LinesSpec, PanelsSpec, HeatmapSpec]);
-export const TYPES = { split: SplitSpec, bars: BarsSpec, 'before-after': BeforeAfterSpec, dumbbell: DumbbellSpec, series: SeriesSpec, entities: EntitiesSpec, groups: GroupsSpec, lines: LinesSpec, panels: PanelsSpec, heatmap: HeatmapSpec };
+/** Who calls whom, in order: participants side by side and numbered messages between them. */
+export const SequenceSpec = z.object({ type: z.literal('sequence'), title, note: common.note, source: common.source, style: common.style, ...sequenceShape }).strict();
+
+/** The states one thing moves through and the moves between them, with optional counts on the moves. */
+export const StatesSpec = z.object({ type: z.literal('states'), title, note: common.note, source: common.source, style: common.style, ...statesShape }).strict();
 
-const items = (s) => s.parts ?? s.bars ?? s.rows ?? s.records ?? (s.after ? [s.after] : []);
+export const Spec = z.discriminatedUnion('type', [SplitSpec, BarsSpec, EstimatesSpec, BeforeAfterSpec, DumbbellSpec, SeriesSpec, EntitiesSpec, GroupsSpec, LinesSpec, PanelsSpec, HeatmapSpec, DotsSpec, ScatterSpec, UnitsSpec, SequenceSpec, StatesSpec]);
+export const TYPES = { split: SplitSpec, bars: BarsSpec, estimates: EstimatesSpec, 'before-after': BeforeAfterSpec, dumbbell: DumbbellSpec, series: SeriesSpec, entities: EntitiesSpec, groups: GroupsSpec, lines: LinesSpec, panels: PanelsSpec, heatmap: HeatmapSpec, dots: DotsSpec, scatter: ScatterSpec, units: UnitsSpec, sequence: SequenceSpec, states: StatesSpec };
+
+
+const items = (s) => s.parts ?? s.bars ?? s.rows ?? s.records ?? s.messages ?? (s.type === 'states' ? [...s.states, ...s.moves] : null) ?? (s.type === 'scatter' ? s.points : s.type === 'dots' ? s.groups : (s.after ? [s.after] : []));
 const kind = (v) => (typeof v === 'number' ? 'number' : 'date');
 
 
+/**
+ * Ranges: a low and a high together, around their value, on every item or none (a value with no range among ones
+ * with ranges reads as certain), and said what they are. `of` gives each item's value.
+ */
+function rangeChecks(items, of, desc, at) {
+  const out = [];
+  const has = items.map((x) => x.low !== undefined || x.high !== undefined);
+  items.forEach((x, i) => {
+    if (has[i] && (x.low === undefined || x.high === undefined)) out.push(`${at}[${i}]: a range needs both "low" and "high"`);
+    else if (has[i] && !(x.low <= of(x) && of(x) <= x.high)) out.push(`${at}[${i}]: the range ${x.low} to ${x.high} does not contain its value ${of(x)}; low ≤ value ≤ high`);
+  });
+  if (has.some(Boolean) && !has.every(Boolean)) out.push(`${at}: give every item a range or none; one without reads as certain`);
+  if (has.some(Boolean) && !desc) out.push('range: required with ranges: say what they are, e.g. "95% interval" or "lowest to highest run"');
+  if (!has.some(Boolean) && desc) out.push('range: there are no ranges to describe; give items "low" and "high", or leave "range" out');
+  return out;
+}
+
 function groupsChecks(s, at = '') {
   const out = [];
   s.groups.forEach((g, i) => { if (g.values.length !== s.series.length) out.push(`${at}groups[${i}].values: one value per series, ${s.series.length}, not ${g.values.length}`); });
@@ -203,11 +331,17 @@ function linesChecks(s, at = '') {
   if (new Set(names).size < names.length) out.push(`${at}series: two lines have the same label`);
   if (!names.includes(s.accent)) out.push(`accent: must be the label of one of the lines, ${names.map((x) => `"${x}"`).join(', ')}`);
   if (s.mark) { const line = s.series.find((l) => l.label === s.accent); if (line && !line.points.some((p) => t(p.x) === t(s.mark.x))) out.push(`mark.x: must be the x of one of the points on the "${s.accent}" line`); }
+  const ranged = s.series.filter((l) => l.points.some((p) => p.low !== undefined || p.high !== undefined));
+  s.series.forEach((l, i) => { if (ranged.includes(l)) out.push(...rangeChecks(l.points, (p) => p.y, s.range ?? 'given', `${at}series[${i}].points`)); });
+  if (!ranged.length && s.range) out.push('range: there are no ranges to describe; give points "low" and "high", or leave "range" out');
+  if (ranged.length && !s.range) out.push('range: required with ranges: say what they are, e.g. "95% interval"');
   return out;
 }
 
 /** 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 === 'sequence') return sequenceChecks(s);
+  if (s.type === 'states') return statesChecks(s);
   if (s.type === 'groups') return groupsChecks(s);
   if (s.type === 'lines') return linesChecks(s);
   if (s.type === 'panels') {
@@ -223,7 +357,7 @@ function crossChecks(s) {
       } else {
         if (!p.series || p.groups) { out.push(`${at}: a lines panel has "series" and no "groups"`); return; }
         if (typeof s.accent !== 'string') { out.push('accent: the label of the line to notice, the same in every panel'); return; }
-        out.push(...linesChecks({ series: p.series, accent: s.accent }, at));
+        out.push(...linesChecks({ series: p.series, accent: s.accent, range: s.range }, at));
         const names = (q) => q.series.map((l) => l.label).join('|');
         if (names(p) !== names(s.panels[0])) out.push(`${at}series: every panel has the same lines, in the same order, so a line is one colour throughout`);
       }
@@ -242,7 +376,64 @@ function crossChecks(s) {
     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 === 'estimates') {
+    const out = [];
+    s.rows.forEach((r, i) => {
+      if (!(r.low <= r.value && r.value <= r.high)) out.push(`rows[${i}]: the range ${r.low} to ${r.high} does not contain its value ${r.value}; low ≤ value ≤ high`);
+      else if (r.low === r.high) out.push(`rows[${i}]: a range from ${r.low} to ${r.high} says the number is exact; give its real range, or draw a "bars" chart`);
+    });
+    const names = s.rows.map((r) => r.label);
+    if (new Set(names).size < names.length) out.push('rows: two rows have the same label');
+    const ns = s.rows.map((r) => r.n !== undefined);
+    if (ns.some(Boolean) && !ns.every(Boolean)) out.push('rows: give every row an "n" or none');
+    return out;
+  }
+  if (s.type === 'bars') {
+    const out = rangeChecks(s.bars, (b) => b.value, s.range, 'bars');
+    if (s.ref) {
+      if (!s.note) out.push('note: required with ref: say what the number is ("AshIndex score, higher is better"), so the reference value means something');
+      s.bars.forEach((b, i) => { if (b.tone) out.push(`bars[${i}].tone: with a ref, figkit colours the bars above it and greys the rest; leave tone out`); });
+      if (s.max !== undefined && s.ref.value > s.max) out.push('ref.value: must be at most max');
+    }
+    s.bars.forEach((b, i) => { if (b.low !== undefined && b.low < 0) out.push(`bars[${i}].low: bars start at zero, so the range cannot go below it`); });
+    const ns = s.bars.map((b) => b.n !== undefined);
+    if (ns.some(Boolean) && !ns.every(Boolean)) out.push('bars: give every bar an "n" or none');
+    s.bars.forEach((b, i) => { if (b.n !== undefined && b.show === undefined && s.unit === '%' && b.n < 10) out.push(`bars[${i}].n: a percentage of ${b.n} things says more than it knows; show it as a count with "show", e.g. "${Math.round((b.value / 100) * b.n)} of ${b.n}", or draw a "units" chart`); });
+    return out;
+  }
+  if (s.type === 'dots') {
+    const out = [];
+    const names = s.groups.map((g) => g.label);
+    if (new Set(names).size < names.length) out.push('groups: two groups have the same label');
+    if (s.groups.reduce((a, g) => a + g.values.length, 0) > 600) out.push('groups: at most 600 dots in all');
+    if (s.mark) {
+      const g = s.groups.find((x) => x.label === s.mark.group);
+      if (!g) out.push(`mark.group: must be one of ${names.map((x) => `"${x}"`).join(', ')}`);
+      else if (!g.values.includes(s.mark.value)) out.push(`mark.value: must be one of the values in "${g.label}"`);
+    }
+    if (s.max !== undefined && s.groups.some((g) => g.values.some((v) => v > s.max))) out.push('max: every value must be at most max');
+    if (s.zero && s.groups.some((g) => g.values.some((v) => v < 0))) out.push('zero: an axis from zero cannot show values below it');
+    return out;
+  }
+  if (s.type === 'scatter') {
+    const out = [];
+    for (const k of ['x', 'y']) {
+      if (s[k].log && s.points.some((p) => p[k] <= 0)) out.push(`${k}.log: a log axis needs every ${k} above 0`);
+      if (s[k].log && s[k].zero) out.push(`${k}: a log axis has no zero; leave out "zero"`);
+    }
+    if (s.points.filter((p) => p.label).length > 5) out.push('points: label at most 5 points; the title is about one or two');
+    for (const k of ['x', 'y']) if (s[k].time && s[k].unit) out.push(`${k}: a time axis writes its own units (1 min, 1 h); leave out "unit"`);
+    return out;
+  }
+  if (s.type === 'units') {
+    const filled = s.parts.reduce((a, p) => a + p.count, 0);
+    if (filled > s.total) return [`parts: the counts add up to ${filled}, more than the total of ${s.total}`];
+    if (filled === s.total) return [`parts: the counts fill all ${s.total}; "rest" names the empty squares, so at least one must be left. For all of them, say so in the title`];
+    return [];
+  }
   if (s.type === 'series') {
+    const ranged = rangeChecks(s.points, (p) => p.y, s.range, 'points');
+    if (ranged.length) return ranged;
     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));