@liggi/figkit 0.4.0 → 0.5.0

package/viz/spec.js

@@ -1,6 +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');
@@ -50,6 +51,11 @@ export const BarsSpec = z.object({
   }).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) => Math.max(b.value, b.high ?? 0) <= s.max), { message: 'every value and every high must be at most max', path: ['max'] });
 
@@ -88,6 +94,31 @@ 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'),
@@ -154,15 +185,15 @@ 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. */
@@ -253,10 +284,14 @@ export const EntitiesSpec = z.object({
 /** 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();
 
-export const Spec = z.discriminatedUnion('type', [SplitSpec, BarsSpec, BeforeAfterSpec, DumbbellSpec, SeriesSpec, EntitiesSpec, GroupsSpec, LinesSpec, PanelsSpec, HeatmapSpec, DotsSpec, ScatterSpec, UnitsSpec, SequenceSpec]);
-export const TYPES = { split: SplitSpec, bars: BarsSpec, '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 };
+/** 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();
+
+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 === 'scatter' ? s.points : s.type === 'dots' ? s.groups : (s.after ? [s.after] : []));
+
+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');
 
 
@@ -306,6 +341,7 @@ function linesChecks(s, at = '') {
 /** 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') {
@@ -340,8 +376,25 @@ 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');

package/viz/states-spec.js

@@ -0,0 +1,161 @@
+/* The "states" spec: the states one thing moves through and the moves between them. spec.js adds it to the union. */
+import { z } from 'zod';
+
+const slug = z.string({ error: 'needs an id, e.g. "open"' }).regex(/^[a-z][a-z0-9-]{0,23}$/, 'ids are short lowercase words, e.g. "open" or "in-review"');
+const text = (max, what, long) => z.string({ error: `needs ${what}` }).trim().min(1, `needs ${what}`).max(max, long);
+const count = z.number({ error: 'a count, a whole number' }).int('a count, a whole number').nonnegative('a count is 0 or more').optional();
+
+/**
+ * One thing's lifecycle: the states it can be in, where it starts, where it can stop, and each move from one state to
+ * another with what makes it happen. A count on a move is how many of the things made that move at least once.
+ */
+export const statesShape = {
+  entry: z.string().trim().min(1).max(28, 'keep the entry label to 28 characters: what starts the lifecycle').optional(),
+  each: z.string().trim().min(1).max(16, 'keep it to 16 characters, a plural noun such as "orders"').optional(),
+  shares: z.boolean().optional(),
+  states: z.array(z.object({
+    id: slug,
+    name: text(24, 'a name', 'keep state names to 24 characters'),
+    note: z.string().trim().min(1).max(32, 'keep the note to 32 characters: one condition or rule').optional(),
+    start: z.literal(true, { error: 'start: true on the one state things begin in, or leave it out' }).optional(),
+    end: z.literal(true, { error: 'end: true on a state things stop in, or leave it out' }).optional(),
+    count,
+    stayed: count,
+    tone: z.literal('accent', { error: 'tone: only "accent", on the one state to notice' }).optional(),
+  }).strict()).min(2, 'at least 2 states; one state is a sentence').max(7, 'at most 7 states; more is two figures (the main path with the side branches merged, then one branch)'),
+  moves: z.array(z.object({
+    from: z.union([slug, z.array(slug).min(2, 'a list of states needs at least 2; give one state as a plain id').max(4, 'at most 4 states in one "from"')], { error: 'from: a state id, or a list of ids for a move every one of them can make' }),
+    to: slug,
+    label: z.string().trim().min(1).max(28, 'keep move labels to 28 characters: what makes the move happen').optional(),
+    count,
+    back: z.string().trim().min(1).max(20, 'keep the back label to 20 characters').optional(),
+    backCount: count,
+    tone: z.literal('accent', { error: 'tone: only "accent", on the moves to notice' }).optional(),
+  }).strict()).min(1, 'at least 1 move').max(10, 'at most 10 moves; more is two figures (the main path, then the exceptions)'),
+};
+
+const list = (ids) => ids.map((x) => `"${x}"`).join(', ');
+const froms = (m) => (Array.isArray(m.from) ? m.from : [m.from]);
+const fmt = (n) => n.toLocaleString('en-GB');
+
+/**
+ * The moves as edges, each forward or a loop back. A depth-first walk from the start, in the order the moves are
+ * written, calls a move a loop when it returns to a state still on the path that reached it. A move's `back` is the
+ * same move the other way, so it is always a loop.
+ */
+export function stateGraph(s) {
+  const edges = [];
+  s.moves.forEach((m, i) => {
+    for (const f of froms(m)) edges.push({ from: f, to: m.to, move: i, list: froms(m).length > 1 });
+    if (m.back) for (const f of froms(m)) edges.push({ from: m.to, to: f, move: i, back: true, list: froms(m).length > 1, loop: true });
+  });
+  const start = s.states.find((x) => x.start)?.id;
+  const seen = new Set(), stack = new Set();
+  const walk = (id) => {
+    seen.add(id); stack.add(id);
+    for (const e of edges) if (e.from === id && !e.back) {
+      if (stack.has(e.to)) e.loop = true;
+      else if (!seen.has(e.to)) walk(e.to);
+    }
+    stack.delete(id);
+  };
+  if (start) walk(start);
+  for (const e of edges) e.loop = !!e.loop;
+  return { edges, start, seen };
+}
+
+/**
+ * How many reached each state: the start's own count, or the counts on the forward moves into it. A loop back brings
+ * things that were already counted, so it adds none.
+ */
+export function reachedCounts(s, edges) {
+  const reached = {};
+  for (const st of s.states) if (st.start) reached[st.id] = st.count;
+  s.moves.forEach((m, i) => {
+    if (m.count == null || edges.some((e) => e.move === i && !e.back && e.loop)) return;
+    reached[m.to] = (reached[m.to] ?? 0) + m.count;
+  });
+  return reached;
+}
+
+/** Rules that span fields: ids that exist, one start, ends with no way out, every state reachable, counts that add up. */
+export function statesChecks(s) {
+  const out = [];
+  const ids = s.states.map((x) => x.id);
+  const dup = ids.find((id, i) => ids.indexOf(id) !== i);
+  if (dup) return [`states: two states have the id "${dup}"`];
+  const byId = Object.fromEntries(s.states.map((x) => [x.id, x]));
+  s.moves.forEach((m, i) => {
+    for (const f of froms(m)) if (!byId[f]) out.push(`moves[${i}].from: no state has the id "${f}"; the ids are ${list(ids)}`);
+    if (!byId[m.to]) out.push(`moves[${i}].to: no state has the id "${m.to}"; the ids are ${list(ids)}`);
+    if (froms(m).includes(m.to)) out.push(`moves[${i}]: a move from "${m.to}" to itself; say it in the state's note instead, e.g. "Restart: review again"`);
+    if (new Set(froms(m)).size !== froms(m).length) out.push(`moves[${i}].from: a state is listed twice`);
+    if (m.backCount != null && !m.back) out.push(`moves[${i}]: backCount without back; back names the move the other way`);
+  });
+  if (out.length) return out;
+  const pairs = new Map();
+  s.moves.forEach((m, i) => froms(m).forEach((f) => {
+    for (const [a, b] of [[f, m.to], ...(m.back ? [[m.to, f]] : [])]) {
+      const key = a + '>' + b;
+      if (pairs.has(key)) out.push(`moves[${i}]: a second move from "${a}" to "${b}" (moves[${pairs.get(key)}] is the first); make it one move with one label`);
+      pairs.set(key, i);
+    }
+  }));
+
+  const starts = s.states.filter((x) => x.start);
+  if (starts.length === 0) out.push('states: mark the state things begin in with "start": true');
+  if (starts.length > 1) out.push(`states: ${list(starts.map((x) => x.id))} ${starts.length === 2 ? 'are both' : 'are all'} marked start; a lifecycle begins in one state, so draw one figure per way in`);
+  for (const st of s.states) if (st.start && st.end) out.push(`states: "${st.id}" is both start and end; nothing moves`);
+  const { edges, seen } = stateGraph(s);
+  for (const st of s.states) {
+    const outs = edges.filter((e) => e.from === st.id);
+    if (st.end && outs.length) out.push(`states: "${st.id}" is an end, but ${outs[0].back ? `moves[${outs[0].move}].back leads out of it` : `moves[${outs[0].move}] leaves it`}; an end has no way out, so drop "end" or the move`);
+    if (!st.end && !outs.length) out.push(`states: nothing leaves "${st.id}"; mark it "end": true if things stop there, or add the move out`);
+    if (starts.length === 1 && !seen.has(st.id)) out.push(`states: "${st.id}" cannot be reached from the start "${starts[0].id}"; add the move into it, or leave it out`);
+  }
+  const accentS = s.states.filter((x) => x.tone).length, accentM = s.moves.filter((m) => m.tone).length;
+  if (accentS > 1) out.push('states: accent at most one state, the one to notice');
+  if (accentS && accentM) out.push('tone: accent one state or some moves, not both');
+  if (accentM && accentM === s.moves.length && s.moves.length > 1) out.push('moves: every move is accented, so none stands out; accent only the moves the title is about');
+  if (out.length) return out;
+
+  // Counts: on every move or none, with what is counted and how many entered.
+  const counted = s.moves.filter((m) => m.count != null).length;
+  for (const st of s.states) if (st.count != null && !st.start) out.push(`states: "${st.id}" has a count; only the start takes one (how many entered), and the counts on the moves say the rest`);
+  if (counted && counted < s.moves.length) out.push(`moves: ${counted} of ${s.moves.length} moves have a count; give every move one or none, since a move without reads as none`);
+  if (s.moves.some((m) => m.back && (m.backCount != null) !== (m.count != null))) out.push('moves: a move with back and a count needs backCount too, and only then');
+  if (!counted && starts[0]?.count != null) out.push(`states: the start "${starts[0].id}" has a count but no move does; give every move its count, or leave the start's out`);
+  for (const st of s.states) if (st.stayed != null && st.end) out.push(`states: "${st.id}" is an end, so everything that reaches it stays; leave out its stayed`);
+  if (!counted && s.states.some((st) => st.stayed != null)) out.push('states: stayed is for counts; give every move a count, or leave stayed out');
+  if (!counted && (s.each || s.shares)) out.push(`${s.shares ? 'shares' : 'each'}: only for counts; give every move a count, or leave it out`);
+  if (counted && !s.each) out.push('each: say what one count is, as a plural noun such as "orders"');
+  if (counted && starts[0]?.count == null) out.push(`states: give the start "${starts[0].id}" a count, how many entered; the moves are counted out of it`);
+  if (out.length) return out;
+  if (!counted) return out;
+
+  const reached = reachedCounts(s, edges);
+  const loopInto = new Set(edges.filter((e) => e.loop).map((e) => e.to));
+  s.moves.forEach((m, i) => {
+    const from = froms(m), base = from.reduce((a, f) => a + (reached[f] ?? 0), 0);
+    if (m.count > base) out.push(`moves[${i}]: ${fmt(m.count)} ${s.each} moved from ${from.length > 1 ? 'those states' : `"${from[0]}"`}, but only ${fmt(base)} reached ${from.length > 1 ? 'them' : 'it'}; a count is how many made the move at least once`);
+    if (m.back && m.backCount > (reached[m.to] ?? 0)) out.push(`moves[${i}].backCount: ${fmt(m.backCount)} moved back from "${m.to}", but only ${fmt(reached[m.to] ?? 0)} reached it`);
+  });
+  // A state nothing loops back into is passed through once, so the moves out of it cannot add up to more than reached it.
+  for (const st of s.states) {
+    if (loopInto.has(st.id) || reached[st.id] == null) continue;
+    const leave = edges.filter((e) => e.from === st.id && !e.list).map((e) => (e.back ? s.moves[e.move].backCount : s.moves[e.move].count)).reduce((a, v) => a + (v ?? 0), 0);
+    if (leave > reached[st.id]) out.push(`states: ${fmt(leave)} ${s.each} leave "${st.id}", but only ${fmt(reached[st.id])} reached it, and nothing loops back into it`);
+  }
+  for (const st of s.states) if (st.stayed != null && st.stayed > (reached[st.id] ?? 0)) out.push(`states: ${fmt(st.stayed)} ${s.each} stayed in "${st.id}", but only ${fmt(reached[st.id] ?? 0)} reached it`);
+  // Each thing ends in one state, so those that stayed and those that reached an end cannot outnumber those that entered.
+  const ended = s.states.reduce((a, st) => a + (st.stayed ?? 0) + (st.end ? reached[st.id] ?? 0 : 0), 0);
+  const entered = starts[0].count;
+  if (ended > entered) out.push(`states: ${fmt(ended)} ${s.each} stayed or reached an end, but only ${fmt(entered)} entered; each ends in one state`);
+  if (s.shares) {
+    s.moves.forEach((m, i) => {
+      const base = froms(m).reduce((a, f) => a + (reached[f] ?? 0), 0);
+      if (base < 10) out.push(`moves[${i}]: a share of ${fmt(base)} ${s.each} reads as more certain than it is; leave shares out and show the counts`);
+    });
+  }
+  return out;
+}

package/viz/states.js

@@ -0,0 +1,203 @@
+/* The "states" spec drawn: the main path down one column, side states beside it, loops back on the left. */
+import { stateGraph, reachedCounts } from './states-spec.js';
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+const fmt = (n) => n.toLocaleString('en-GB');
+const froms = (m) => (Array.isArray(m.from) ? m.from : [m.from]);
+
+/**
+ * Where each state sits. The longest run of forward moves from the start is the main path, one state a row down a
+ * single column, so the lifecycle reads top to bottom. Every other state sits to the right of it, level with the
+ * states it moves to and from. Loops back up the main path run down its left side, in a lane kept for their labels.
+ */
+export function placeStates(spec) {
+  const { edges, start } = stateGraph(spec);
+  const fwd = edges.filter((e) => !e.loop);
+  // A move several states can make (retire, cancel) is an exit beside the path, never a step along it.
+  const path = fwd.filter((e) => !e.list);
+  const rank = { [start]: 0 };
+  for (let k = 0; k < spec.states.length; k++) for (const e of path) if (rank[e.from] != null && (rank[e.to] ?? -1) < rank[e.from] + 1) rank[e.to] = rank[e.from] + 1;
+  const order = spec.states.map((s) => s.id);
+  // The main path ends at the deepest state, an end state when one is that deep, the first written when several are.
+  const deepest = Math.max(...Object.values(rank));
+  for (const e of fwd) if (rank[e.to] == null) rank[e.to] = deepest + 1;
+  const tips = order.filter((id) => rank[id] === deepest);
+  let at = tips.find((id) => spec.states.find((s) => s.id === id).end) ?? tips[0];
+  const main = [at];
+  while (at !== start) {
+    const prev = order.find((id) => rank[id] === rank[at] - 1 && path.some((e) => e.from === id && e.to === at));
+    main.unshift(prev);
+    at = prev;
+  }
+  const cell = {};
+  main.forEach((id, i) => { cell[id] = [i, 0, i]; });
+  const taken = (r, c) => Object.values(cell).some(([a, b, z]) => b === c && r >= a && r <= z);
+  // A state that several main-path states can move to (retire, cancel) sits level with the middle of them, and one
+  // bracket beside them leads to it with one arrow and one label, so no move shares a line with another.
+  const bracket = {};
+  const lists = order.filter((id) => !main.includes(id) && edges.some((e) => e.to === id && e.list && !e.back));
+  for (const id of lists) {
+    const srcs = edges.filter((e) => e.to === id && e.list && !e.back).map((e) => cell[e.from]);
+    if (srcs.some((c) => !c || c[1] !== 0)) continue;
+    const lo = Math.min(...srcs.map((c) => c[0])), hi = Math.max(...srcs.map((c) => c[0]));
+    for (let c = 1; c <= 3; c++) {
+      let free = true;
+      for (let r = lo; r <= hi; r++) if (taken(r, c)) free = false;
+      if (free) { cell[id] = [lo, c, hi]; bracket[id] = [lo, hi]; break; }
+    }
+  }
+  const rest = order.filter((id) => !cell[id]).sort((a, b) => rank[a] - rank[b] || order.indexOf(a) - order.indexOf(b));
+  for (const id of rest) {
+    const near = edges.filter((e) => (e.from === id && cell[e.to]) || (e.to === id && cell[e.from])).map((e) => cell[e.from === id ? e.to : e.from][0]);
+    const want = near.length ? Math.round(near.reduce((a, v) => a + v, 0) / near.length) : Math.min(rank[id], main.length - 1);
+    let best = null;
+    for (let c = 1; c <= 3 && !best; c++) for (const d of [0, 1, -1, 2, -2]) {
+      const r = want + d;
+      if (r >= 0 && r < main.length + 1 && !taken(r, c)) { best = [r, c, r]; break; }
+    }
+    cell[id] = best;
+  }
+  const rows = Math.max(...Object.values(cell).map(([, , z]) => z)) + 1, cols = Math.max(...Object.values(cell).map(([, c]) => c)) + 1;
+  // A loop back up the main column runs on its left; any other move finds its own way.
+  const sides = edges.map((e) => (cell[e.from][1] === 0 && cell[e.to][1] === 0 && cell[e.to][0] < cell[e.from][0] ? 'left' : null));
+  return { cell, rows, cols, edges, sides, main, bracket };
+}
+
+/** States as boxes on a grid figkit chose, the start's dot above the first, and each move a <fig-arrow> with its label. */
+export function drawStates(spec, main) {
+  const phone = main.classList.contains('phone');
+  const { cell, rows, cols, edges, sides, bracket } = placeStates(spec);
+  const reached = spec.moves.some((m) => m.count != null) ? reachedCounts(spec, edges) : null;
+  const share = (n, m) => {
+    if (!spec.shares) return '';
+    const base = froms(m).reduce((a, f) => a + (reached[f] ?? 0), 0);
+    return ` (${Math.round((n / base) * 100)}%)`;
+  };
+  // A move several states make, drawn as one arrow from a bracket beside them.
+  const across = (m) => Array.isArray(m.from) && !!bracket[m.to];
+  const title = (m) => m.label;
+  const lines = (m) => {
+    const out = [];
+    if (m.count != null) out.push(fmt(m.count) + share(m.count, m));
+    if (m.back) out.push(`Back: ${m.back}${m.backCount != null ? ' ' + fmt(m.backCount) : ''}`);
+    return out.join('\n');
+  };
+
+  // The lane on the left is as wide as the widest loop label.
+  const loops = edges.map((e, i) => (sides[i] === 'left' ? e : null)).filter(Boolean);
+  const probe = (m) => {
+    const lab = document.createElement('div');
+    lab.className = 'fig-wire-label';
+    lab.style.cssText = 'position:absolute;visibility:hidden;transform:none';
+    lab.textContent = title(m) ?? '';
+    for (const t of lines(m).split('\n').filter(Boolean)) { const s = document.createElement('span'); s.className = 'fig-wire-sub'; s.textContent = t; lab.appendChild(s); }
+    main.appendChild(lab);
+    const w = lab.offsetWidth;
+    lab.remove();
+    return w;
+  };
+  // A loop's label sits on its line, which runs in the column gap, so the lane only adds what the gap lacks.
+  // The gap beside a bracket holds its label on one line between the bracket and the state it leads to.
+  const into = spec.moves.filter(across).map(probe);
+  const gapX = Math.max(phone ? 64 : 120, ...into.map((w) => w + (phone ? 64 : 84)));
+  const lane = loops.length ? Math.max(8, Math.max(...loops.map((e) => probe(spec.moves[e.move]))) / 2 + 40 - gapX) : 0;
+  const box = phone ? 200 : 250;
+  // The labels on the main column's own arrows, which sit on its line: on a phone the column stays at least as wide.
+  const down = spec.moves.filter((m, i) => edges.some((e, k) => e.move === i && !e.loop && !sides[k] && cell[e.from][1] === 0 && cell[e.to][1] === 0));
+  const downW = Math.min(box, Math.max(0, ...down.map(probe)));
+
+  // On a desktop the figure is only as wide as the picture: the columns, the loop lane, and room for the labels beside
+  // the main column's arrows when nothing sits to its right. A phone keeps the phone width.
+  if (!phone) {
+    const gap = gapX, pad = parseFloat(getComputedStyle(main).paddingLeft) || 44;
+    const right = cols === 1 ? Math.max(0, ...spec.moves.map(probe)) + 40 - box / 2 : 0;
+    const grid = (lane ? lane + gap : 0) + cols * box + (cols - 1) * gap;
+    const need = grid + (cols === 1 ? right : 0);
+    main.style.setProperty('--w', Math.round(Math.min(960, Math.max(640, need + 2 * pad))) + 'px');
+  }
+  const grid = document.createElement('div');
+  grid.className = 'states';
+  grid.style.columnGap = gapX + 'px';
+  grid.style.gridTemplateColumns = [lane ? `${lane}px` : null, ...Array.from({ length: cols }, (_, c) => `minmax(${c === 0 && phone ? downW : 0}px, ${box}px)`)].filter(Boolean).join(' ');
+  grid.style.gridTemplateRows = `auto repeat(${rows}, auto)`;
+  const col0 = lane ? 2 : 1;
+  const dot = document.createElement('div');
+  dot.className = 'node bare st-dot';
+  dot.id = 'st--start';
+  dot.style.gridArea = `1 / ${col0}`;
+  grid.appendChild(dot);
+  for (const s of spec.states) {
+    const el = document.createElement('div');
+    el.className = 'node state' + (s.end ? ' pill' : '') + (bracket[s.id] ? ' mid' : '') + (s.tone ? ' accent' : '');
+    el.id = 'st-' + s.id;
+    el.style.gridArea = `${cell[s.id][0] + 2} / ${cell[s.id][1] + col0} / ${cell[s.id][2] + 3}`;
+    el.innerHTML = `<h3>${esc(s.name)}</h3>${s.note ? `<p>${esc(s.note)}</p>` : ''}${s.stayed != null ? `<p class="st-stayed">${fmt(s.stayed)} went no further</p>` : ''}`;
+    grid.appendChild(el);
+  }
+  for (const [id, [lo, hi]] of Object.entries(bracket)) {
+    const b = document.createElement('div');
+    b.className = 'node bare st-bracket';
+    b.id = 'st--into-' + id;
+    b.style.gridArea = `${lo + 2} / ${col0} / ${hi + 3}`;
+    grid.appendChild(b);
+  }
+  main.appendChild(grid);
+  // A label on the main column wider than its boxes reaches into the gap, so the bracket moves out past it.
+  const brackets = grid.querySelectorAll('.st-bracket');
+  if (brackets.length) {
+    const boxW = grid.querySelector('.state').offsetWidth;
+    const reach = Math.max(0, ...down.map(probe).map((w) => (w - boxW) / 2 + 14));
+    const now = -parseFloat(getComputedStyle(brackets[0]).marginRight);
+    if (reach > now) {
+      for (const b of brackets) b.style.marginRight = -reach + 'px';
+      grid.style.columnGap = gapX + reach - now + 'px';
+    }
+  }
+  const arrow = (from, to, attrs) => {
+    const a = document.createElement('fig-arrow');
+    a.setAttribute('from', from);
+    a.setAttribute('to', to);
+    for (const [k, v] of Object.entries(attrs)) if (v != null && v !== false) a.setAttribute(k, v === true ? '' : v);
+    main.appendChild(a);
+  };
+  const first = spec.states.find((s) => s.start);
+  arrow('st--start', 'st-' + first.id, {
+    label: spec.entry ?? (first.count != null ? `${fmt(first.count)} ${spec.each}` : null),
+    sub: spec.entry && first.count != null ? `${fmt(first.count)} ${spec.each}` : null,
+    'to-side': 'top',
+  });
+  spec.moves.forEach((m, i) => {
+    if (across(m)) {
+      arrow('st--into-' + m.to, 'st-' + m.to, { label: title(m) ?? null, sub: lines(m) || null, accent: !!m.tone, both: !!m.back, 'from-side': 'right', 'to-side': 'left' });
+      return;
+    }
+    const mine = edges.map((e, k) => ({ e, k })).filter(({ e }) => e.move === i && !e.back);
+    // A move several states can make is labelled once, on the arrow from a state level with where it goes, else the
+    // middle one. The others leave low on their state's side and join from above or below, so none shares a line
+    // with another move out of the same state.
+    const level = mine.find(({ e }) => cell[e.from][0] === cell[e.to][0]);
+    const labelled = (level ?? mine[Math.floor((mine.length - 1) / 2)]).e;
+    for (const { e, k } of mine) {
+      let side = sides[k], extra = {};
+      if (mine.length > 1 && cell[e.from][0] !== cell[e.to][0] && cell[e.from][1] < cell[e.to][1]) {
+        const above = cell[e.from][0] < cell[e.to][0];
+        extra = { 'from-side': 'right', 'from-at': above ? 0.85 : 0.15, 'to-side': above ? 'top' : 'bottom' };
+      }
+      // Two moves each way between states side by side: the forward one above, the one back below.
+      if (!side && !Object.keys(extra).length && cell[e.from][0] === cell[e.to][0] && edges.some((o) => o.from === e.to && o.to === e.from)) {
+        const at = e.loop ? 0.68 : 0.32;
+        extra = { 'from-at': at, 'to-at': at };
+      }
+      arrow('st-' + e.from, 'st-' + e.to, {
+        label: e === labelled ? title(m) ?? null : null,
+        sub: e === labelled ? lines(m) || null : null,
+        accent: !!m.tone,
+        both: !!m.back,
+        'from-side': side, 'to-side': side,
+        'from-at': side ? 0.62 : null, 'to-at': side ? 0.38 : null,
+        ...extra,
+      });
+    }
+  });
+  return grid;
+}