@liggi/figkit 0.3.0 → 0.5.0

package/examples/charts/bars-range.json

@@ -0,0 +1,6 @@
+{ "type": "bars", "style": "report", "title": "The new reply check catches more, but the ranges still overlap",
+  "note": "Share of unsafe replies caught, on the same test set", "unit": "%", "max": 100,
+  "range": "likely range (95%)", "each": "replies",
+  "bars": [ { "label": "Current check", "value": 64, "low": 53, "high": 74, "n": 72 },
+            { "label": "New check", "value": 78, "low": 67, "high": 86, "n": 72, "tone": "accent" } ],
+  "source": "Invented example data" }

package/examples/charts/bars-ref.json

@@ -0,0 +1,6 @@
+{ "type": "bars", "title": "Two of the four new layouts beat the current page",
+  "note": "Share of visitors who finished checkout", "unit": "%",
+  "ref": { "label": "Current page", "value": 61 },
+  "bars": [ { "label": "One-page form", "value": 68 }, { "label": "Saved cards first", "value": 64 },
+            { "label": "Address lookup", "value": 60 }, { "label": "Guest by default", "value": 57 } ],
+  "source": "Invented data, for illustration." }

package/examples/charts/dots.json

@@ -0,0 +1,6 @@
+{ "type": "dots", "style": "report", "title": "Most builds finish in four minutes; a few take over ten",
+  "note": "One dot per build: minutes from push to result", "unit": " min", "summary": "median", "zero": true, "each": "builds",
+  "groups": [ { "label": "Main branch", "values": [3.8,4.1,3.6,4.4,3.9,4.0,4.2,3.7,4.6,3.9,4.3,11.8,4.0,3.5,4.1,4.8,3.9,4.2,12.6,4.0,3.8,4.4,4.1,3.7,4.5,3.9,10.4,4.2] },
+              { "label": "Pull requests", "values": [4.9,5.2,4.6,5.8,5.1,4.8,6.2,5.0,5.5,4.7,5.3,5.9,5.0,4.9,6.4,5.2,5.6,4.8,5.1,5.4], "tone": "accent" } ],
+  "mark": { "group": "Main branch", "value": 12.6, "label": "12.6 min, cache miss" },
+  "source": "Invented example data" }

package/examples/charts/estimates.json

@@ -0,0 +1,7 @@
+{ "type": "estimates", "title": "Free delivery lifts orders in two regions; the north's range includes zero",
+  "note": "Change in orders per 100 visitors, free delivery minus paid", "range": "95% interval",
+  "sides": { "below": "Paid better", "above": "Free better" },
+  "rows": [ { "label": "South", "value": 2.4, "low": 1.1, "high": 3.7 },
+            { "label": "Midlands", "value": 1.8, "low": 0.6, "high": 3.0 },
+            { "label": "North", "value": 0.7, "low": -0.9, "high": 2.3 } ],
+  "source": "Invented data, for illustration." }

package/examples/charts/heatmap-signed.json

@@ -0,0 +1,5 @@
+{ "type": "heatmap", "title": "The new menu helped every region except the north",
+  "note": "Change in weekly orders per store after the new menu", "unit": "%",
+  "rows": ["South", "Midlands", "North"], "columns": ["Wk 1", "Wk 2", "Wk 3", "Wk 4"],
+  "values": [ [3.1, 4.4, 5.0, 4.8], [1.2, 2.6, 3.3, 3.9], [-2.4, -3.8, -1.9, -2.7] ],
+  "source": "Invented data, for illustration." }

package/examples/charts/scatter.json

@@ -0,0 +1,6 @@
+{ "type": "scatter", "style": "report", "title": "Bigger pull requests wait longer for review",
+  "note": "One dot per merged pull request", "x": { "label": "Lines changed", "log": true }, "y": { "label": "Time to first review", "time": "hours", "zero": true },
+  "points": [ {"x":12,"y":1.5},{"x":30,"y":2.1},{"x":8,"y":0.6},{"x":45,"y":3.2},{"x":120,"y":5.5},{"x":260,"y":9.1},{"x":75,"y":2.8},
+              {"x":18,"y":1.1},{"x":540,"y":22.0,"label":"Search rewrite","tone":"accent"},{"x":95,"y":6.0},{"x":160,"y":4.2},{"x":22,"y":3.9},
+              {"x":64,"y":2.2},{"x":310,"y":12.5},{"x":40,"y":1.8},{"x":5,"y":0.4},{"x":210,"y":7.7},{"x":880,"y":30.5},{"x":15,"y":0.9},{"x":130,"y":3.6} ],
+  "source": "Invented example data" }

package/examples/charts/sequence.json

@@ -0,0 +1,67 @@
+{
+  "type": "sequence",
+  "title": "The shopper has an order number before the receipt is sent",
+  "participants": [
+    {
+      "id": "app",
+      "name": "Shop app",
+      "kind": "browser"
+    },
+    {
+      "id": "api",
+      "name": "Checkout API"
+    },
+    {
+      "id": "pay",
+      "name": "Card processor"
+    },
+    {
+      "id": "mail",
+      "name": "Email queue"
+    }
+  ],
+  "messages": [
+    {
+      "from": "app",
+      "to": "api",
+      "label": "Place order"
+    },
+    {
+      "from": "api",
+      "to": "api",
+      "label": "Check stock and price"
+    },
+    {
+      "from": "api",
+      "to": "pay",
+      "label": "Charge the card",
+      "tone": "accent"
+    },
+    {
+      "from": "pay",
+      "to": "api",
+      "label": "Approved or declined",
+      "reply": true,
+      "tone": "accent"
+    },
+    {
+      "from": "api",
+      "to": "app",
+      "label": "Order number",
+      "reply": true
+    },
+    {
+      "from": "api",
+      "to": "mail",
+      "label": "Send the receipt",
+      "note": "within a minute"
+    }
+  ],
+  "repeats": [
+    {
+      "from": 3,
+      "to": 4,
+      "label": "Up to 3 tries"
+    }
+  ]
+}

package/examples/charts/series-range.json

@@ -0,0 +1,6 @@
+{ "type": "series", "style": "report", "title": "The weekly pass rate dipped in week 6, beyond its usual range",
+  "note": "Share of test runs that passed, each week", "unit": "%", "zero": false, "range": "likely range (95%)",
+  "points": [ {"x":1,"y":91,"low":86,"high":94}, {"x":2,"y":93,"low":88,"high":96}, {"x":3,"y":90,"low":85,"high":94},
+              {"x":4,"y":92,"low":87,"high":95}, {"x":5,"y":91,"low":86,"high":95}, {"x":6,"y":79,"low":72,"high":85},
+              {"x":7,"y":89,"low":84,"high":93}, {"x":8,"y":92,"low":87,"high":95} ],
+  "mark": { "x": 6, "label": "79%, week 6" }, "source": "Invented example data" }

package/examples/charts/states.json

@@ -0,0 +1,71 @@
+{
+  "type": "states",
+  "title": "An order waits after a declined card until a new card is added",
+  "entry": "Shopper checks out",
+  "states": [
+    {
+      "id": "waiting",
+      "name": "Awaiting payment",
+      "start": true
+    },
+    {
+      "id": "declined",
+      "name": "Card declined",
+      "note": "Shopper emailed",
+      "tone": "accent"
+    },
+    {
+      "id": "paid",
+      "name": "Paid"
+    },
+    {
+      "id": "packed",
+      "name": "Packed"
+    },
+    {
+      "id": "shipped",
+      "name": "Shipped",
+      "end": true
+    },
+    {
+      "id": "cancelled",
+      "name": "Cancelled",
+      "end": true
+    }
+  ],
+  "moves": [
+    {
+      "from": "waiting",
+      "to": "paid",
+      "label": "Charge succeeds"
+    },
+    {
+      "from": "waiting",
+      "to": "declined",
+      "label": "Charge fails"
+    },
+    {
+      "from": "declined",
+      "to": "waiting",
+      "label": "New card added"
+    },
+    {
+      "from": "paid",
+      "to": "packed",
+      "label": "Warehouse picks"
+    },
+    {
+      "from": "packed",
+      "to": "shipped",
+      "label": "Carrier collects"
+    },
+    {
+      "from": [
+        "paid",
+        "packed"
+      ],
+      "to": "cancelled",
+      "label": "Shopper cancels"
+    }
+  ]
+}

package/examples/charts/units.json

@@ -0,0 +1,4 @@
+{ "type": "units", "style": "report", "title": "11 of the 29 flagged days were real problems",
+  "note": "One square per day the monitor flagged in October", "total": 29,
+  "parts": [ { "label": "real problems", "count": 11 } ], "rest": "false alarms",
+  "source": "Invented example data" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liggi/figkit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Explanatory figures for agents and people: write a little HTML or a chart spec, get a laid-out PNG and a list of what is wrong with it.",
   "license": "MIT",
   "type": "module",

package/runtime/fig.css

@@ -218,3 +218,98 @@ fig-bars .fb-sub { font-weight: 400; color: var(--soft); font-size: var(--small)
 .fig .hm-key { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; font-size: var(--small); color: var(--muted); margin: 0 0 12px; }
 .fig .hm-key i { display: inline-block; width: 160px; height: 14px; border-radius: 3px; }
 .fig.phone .hm-key i { width: 84px; }
+
+/* ---------- sequence: who calls whom, in order (a spec of type "sequence") ---------- */
+.fig .sequence { position: relative; }
+.fig .sequence > svg { position: absolute; left: 0; top: 0; overflow: visible; }
+.fig .seq-lanes { position: relative; }
+.fig .seq-who { position: absolute; }
+.fig .seq-who { text-align: center; align-items: center; justify-content: center; }
+.fig.phone .seq-who { padding: 10px 8px; }
+.fig.phone .seq-who > h3 { font-size: var(--body); }
+/* The paper shows only behind the words themselves, line by line, so a line passing a label stops just at its text. */
+.fig .seq-msg { position: absolute; box-sizing: border-box; width: max-content; display: flex; gap: 10px; align-items: baseline; padding: 1px 6px; }
+.fig .seq-ink { background: var(--paper); box-decoration-break: clone; -webkit-box-decoration-break: clone; padding: 1px 0; }
+.fig .seq-n { font-size: var(--small); font-variant-numeric: tabular-nums; color: var(--soft); flex: 0 0 auto; min-width: 2ch; text-align: right; }
+.fig .seq-text { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.fig .seq-note { font-size: var(--small); color: var(--muted); }
+.fig .seq-msg.reply .seq-text { color: var(--muted); }
+.fig .seq-msg.accent .seq-text, .fig .seq-msg.accent .seq-n { color: var(--accent); }
+.fig .seq-msg.accent .seq-text { font-weight: 600; }
+.fig .seq-msg.accent .seq-note { font-weight: 400; }
+.fig .seq-frame-label { position: absolute; white-space: nowrap; background: var(--paper); padding: 0 8px; font-size: var(--small); font-weight: 600; color: var(--muted); }
+.fig .seq-lanes.tight .seq-who { padding: 8px 4px; }
+.fig .seq-lanes.tight .seq-who > h3 { font-size: var(--small); }
+
+/* ranges: what they are, said once under the reading line; on bars a line with end caps across the bar's end */
+.fig .range-key { display: flex; flex-wrap: wrap; column-gap: 28px; row-gap: 6px; margin: 2px 0 0; font-size: var(--small); color: var(--muted); }
+.fig .range-key > span { display: inline-flex; align-items: center; gap: 10px; }
+.fig .range-key i { flex: 0 0 auto; }
+.fig .range-key i.dash { width: 34px; height: 0; border-top: 2px dashed var(--ink); }
+.fig .range-key i.whisker { position: relative; width: 34px; height: 14px; border-left: 2px solid var(--ink); border-right: 2px solid var(--ink); }
+.fig .range-key i.whisker::after { content: ''; position: absolute; left: 0; right: 0; top: 6px; border-top: 2px solid var(--ink); }
+.fig .range-key i.median { width: 34px; height: 4px; border-radius: 2px; }
+.fig .range-key i.band { width: 34px; height: 14px; border-radius: 2px; background: var(--fill); opacity: .45; }
+fig-bars .fb-track { position: relative; }
+fig-bars .fb-range { --tone: var(--ink); position: absolute; top: 50%; height: 12px; margin-top: -6px; border-left: 2px solid var(--tone); border-right: 2px solid var(--tone); pointer-events: none; }
+fig-bars .fb-range::after { content: ''; position: absolute; left: 0; right: 0; top: 4.5px; border-top: 3px solid var(--tone); }
+fig-bars .fb-bar.dim { opacity: .4; }
+fig-bars .fb-val .fb-sub + .fb-sub { margin-left: 10px; }
+fig-bars .fb-label .fb-n { display: block; font-size: var(--small); color: var(--soft); }
+
+/* dots: the count of a single group, above its dots */
+.fig .dots-n { margin: 0 0 4px; font-size: var(--small); color: var(--muted); }
+
+/* units: one square per thing counted */
+.fig .units { display: flex; flex-direction: column; gap: 22px; }
+.fig .un-grid { display: grid; }
+.fig .un-grid i { width: var(--un); height: var(--un); border-radius: 4px; }
+.fig .un-grid i.empty, .fig .un-key i.empty { background: var(--hair); }
+.fig .un-key { display: flex; flex-wrap: wrap; column-gap: 28px; row-gap: 8px; font-size: var(--body); color: var(--muted); }
+.fig .un-key span { display: inline-flex; align-items: center; gap: 8px; }
+.fig .un-key i { width: 18px; height: 18px; border-radius: 3px; display: inline-block; }
+.fig .un-key b { color: var(--ink); font-weight: 600; font-variant-numeric: tabular-nums; }
+
+/* bars on a phone: the name and count above each bar, so the bar and its range get the full width */
+.fig.phone fig-bars { grid-template-columns: minmax(0, 1fr); row-gap: 4px; }
+.fig.phone fig-bars .fb-label { margin-top: 10px; }
+.fig.phone fig-bars .fb-label .fb-n { display: inline; margin-left: 8px; }
+
+/* estimates: signed values with ranges around a zero line; what each side of zero means under the axis */
+.fig .estimates { position: relative; }
+
+.fig .range-key i.est-dot { width: 14px; height: 14px; border-radius: 50%; border: 2.5px solid; box-sizing: border-box; }
+.fig .est-sides { position: relative; height: calc(var(--small) * 1.4); margin-top: -6px; font-size: var(--small); color: var(--muted); }
+.fig .est-sides span { position: absolute; top: 0; white-space: nowrap; }
+
+/* bars with a reference: its own first row in the second colour, and a dashed line from its end through the rest */
+fig-bars.has-ref { position: relative; }
+fig-bars .fb-label.ref { color: var(--second); }
+fig-bars .fb-refline { position: absolute; width: 0; border-left: 2px dashed var(--second); pointer-events: none; }
+.fig .range-key i.swatch { width: 18px; height: 14px; border-radius: 2px; background: var(--accent); }
+fig-bars.has-ref .fb-label.ref + .fb-track .fb-bar { opacity: .55; }
+/* on a phone the names sit above the bars, so the reference line stops at each name rather than crossing it */
+.fig.phone fig-bars.has-ref .fb-label { position: relative; z-index: 1; justify-self: start; background: var(--paper); padding-right: 8px; }
+.fig .hm-key i.hm-signed { position: relative; margin-bottom: calc(var(--small) * 1.3); }
+.fig .hm-key i.hm-signed b { font-style: normal; position: absolute; top: 100%; transform: translateX(-50%); font-weight: 400; color: var(--muted); padding-top: 2px; line-height: 1; }
+.fig .hm-key i.hm-signed b::before { content: ''; position: absolute; left: 50%; top: -14px; height: 14px; border-left: 2px solid var(--paper); }
+fig-bars.has-ref .fb-val:not(.lead) { color: var(--muted); }
+/* Against a reference, a bar that clears it is solid accent (a faded orange reads as brown on dark); its range is drawn in ink on top. */
+fig-bars.has-ref .fb-bar.dim.accent { opacity: 1; }
+fig-bars.has-ref .fb-range.accent { --tone: var(--ink); }
+
+/* ---------- states: what one thing moves through (a spec of type "states") ---------- */
+.fig .states { display: grid; column-gap: 120px; row-gap: 76px; align-items: stretch; justify-content: start; }
+.fig.phone .states { column-gap: 64px; row-gap: 68px; }
+.fig.phone .state { padding: 12px 10px; }
+.fig.phone .state > h3 { font-size: var(--body); }
+.fig .state { text-align: center; align-items: center; justify-content: center; justify-self: stretch; }
+.fig .state > p { margin-top: 4px; }
+.fig .state > .st-stayed { color: var(--ink); }
+.fig .node.bare.st-dot { width: 22px; height: 22px; padding: 0; border-radius: 50%; background: var(--line); justify-self: center; align-self: center; }
+.fig .fig-wire-label .fig-wire-sub { display: block; font-weight: 400; font-variant-numeric: tabular-nums; }
+.fig .st-key { font-size: var(--small); }
+.fig .state.mid { align-self: center; }
+/* the bracket beside the states that share one move, which leads to it with one arrow */
+.fig .node.bare.st-bracket { justify-self: end; width: 14px; margin-right: -30px; padding: 0; border: 1.5px solid var(--line); border-left: 0; border-radius: 0 4px 4px 0; background: none; }
+.fig.phone .node.bare.st-bracket { margin-right: -24px; width: 10px; }

package/runtime/fig.js

@@ -42,7 +42,7 @@
   function obstacles() {
     const out = [];
     const solid = [...root().querySelectorAll(SOLID)].filter(visible);
-    for (const el of solid) if (!el.classList.contains('bare')) out.push({ el, r: rectOf(el) });
+    for (const el of solid) if (!el.classList.contains('bare') || el.classList.contains('st-bracket')) out.push({ el, r: rectOf(el) });
     const walker = document.createTreeWalker(root(), NodeFilter.SHOW_TEXT);
     const seen = new Set();
     for (let n = walker.nextNode(); n; n = walker.nextNode()) {
@@ -370,7 +370,7 @@
       fig.wires.push({ from, to, pts, mode, ref });
 
       const text = ref ? '' : tag.getAttribute('label') ?? tag.textContent.trim();
-      if (text) labels.push({ text, tone, color, pts, at: labelAt, want: tag.getAttribute('label-at'), from, to });
+      if (text) labels.push({ text, sub: tag.getAttribute('sub'), tone, color, pts, at: labelAt, want: tag.getAttribute('label-at'), from, to });
     }
     return placeLabels(labels, obs);
   }
@@ -467,6 +467,8 @@
       const lab = document.createElement('div');
       lab.className = 'fig-wire-label';
       lab.textContent = L.text;
+      // Further lines under the label, such as a count: one span each.
+      for (const t of (L.sub ?? '').split('\n').filter(Boolean)) { const e = document.createElement('span'); e.className = 'fig-wire-sub'; e.textContent = t; lab.appendChild(e); }
       if (L.tone !== 'line') lab.style.color = L.color;
       lab.dataset.arrow = `${L.from} → ${L.to}`;
       R.appendChild(lab);
@@ -553,10 +555,66 @@
   });
 
   // ---------- checks ----------
+  /** The colour as [r, g, b, a] (0–255, alpha 0–1), or null when it is not a plain colour (none, a gradient, a pattern). */
+  function rgba(c) {
+    const m = /^rgba?\(([\d.]+),\s*([\d.]+),\s*([\d.]+)(?:,\s*([\d.]+))?\)$/.exec((c || '').trim());
+    if (m) return [+m[1], +m[2], +m[3], m[4] === undefined ? 1 : +m[4]];
+    const s = /^color\(srgb ([\d.e-]+) ([\d.e-]+) ([\d.e-]+)(?: \/ ([\d.]+))?\)$/.exec((c || '').trim());
+    return s ? [+s[1] * 255, +s[2] * 255, +s[3] * 255, s[4] === undefined ? 1 : +s[4]] : null;
+  }
+  const lumOf = ([r, g, b]) => [r, g, b].map((v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; }).reduce((s, v, i) => s + v * [0.2126, 0.7152, 0.0722][i], 0);
+  const over = (top, under) => [0, 1, 2].map((i) => top[i] * top[3] + under[i] * (1 - top[3])).concat(1);
+  function opacityOf(el) { let o = 1; for (let x = el; x && x !== document.documentElement; x = x.parentElement) o *= parseFloat(getComputedStyle(x).opacity); return o; }
+  /** The colour an element paints over its own area, with its opacity, or undefined when it paints nothing there. */
+  function paintOf(el) {
+    const cs = getComputedStyle(el);
+    if (el instanceof SVGElement) {
+      if (!/^(rect|path|circle|ellipse|polygon)$/.test(el.tagName)) return undefined;
+      if (cs.fill === 'none') return undefined;
+      const c = rgba(cs.fill);
+      return c ? [c[0], c[1], c[2], c[3] * parseFloat(cs.fillOpacity) * opacityOf(el)] : null;
+    }
+    if (cs.backgroundImage !== 'none') return null;
+    const c = rgba(cs.backgroundColor);
+    if (!c) return null;
+    return c[3] === 0 ? undefined : [c[0], c[1], c[2], c[3] * opacityOf(el)];
+  }
+  /** Contrast between a text element and what lies under its middle, as a WCAG ratio; null when it cannot be told. */
+  function contrastOf(el) {
+    const b = el.getBoundingClientRect();
+    if (b.top < 0 || b.bottom > innerHeight || b.left < 0 || b.right > innerWidth) el.scrollIntoView({ block: 'center', inline: 'center' });
+    const r = el.tagName === 'text' ? el.getBoundingClientRect() : (() => { const t = textRect(el), o = R0(); return { x: t.x + o.x, y: t.y + o.y, width: t.w, height: t.h }; })();
+    const stack = document.elementsFromPoint(r.x + r.width / 2, r.y + r.height / 2);
+    let i = stack.findIndex((x) => x === el || x.contains(el));
+    if (i < 0) return null;
+    if (el.tagName === 'text') i++;
+    const layers = [];
+    for (; i < stack.length; i++) {
+      const p = paintOf(stack[i]);
+      if (p === null) return null;
+      if (p === undefined) continue;
+      layers.push(p);
+      if (p[3] >= 0.99) break;
+    }
+    let bg = [255, 255, 255, 1];
+    for (const l of layers.reverse()) bg = over(l, bg);
+    const cs = getComputedStyle(el);
+    const fg = rgba(el.tagName === 'text' ? cs.fill : cs.color);
+    if (!fg) return null;
+    const ink = over([fg[0], fg[1], fg[2], fg[3] * opacityOf(el)], bg);
+    const la = lumOf(ink), lb = lumOf(bg);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+  }
+  const R0 = () => { const b = root().getBoundingClientRect(); return { x: b.x, y: b.y }; };
+
   function check() {
     const R = root(), P = fig.problems;
     const W = R.offsetWidth, H = R.offsetHeight;
     const detail = R.classList.contains('detail');
+    // A phone layout is 560px wide (fig.css); opening gaps for labels can widen it past that.
+    const phoneW = R.classList.contains('phone') ? 560 : 0;
+    const wide = Math.max(W, R.scrollWidth, R.getBoundingClientRect().width);
+    if (phoneW && wide > phoneW + 1) P.push(`The figure is ${Math.round(wide)}px wide on a phone, wider than ${phoneW}px; shorten the widest labels.`);
     const minText = detail ? 13 : 15;
     const obs = obstacles();
 
@@ -567,6 +625,22 @@
       for (const b of marks.slice(i + 1)) if (overlap(a.r, b.r) && !a.e.contains(b.e) && !b.e.contains(a.e)) P.push(`Chart labels overlap: "${a.e.textContent.trim()}" and "${b.e.textContent.trim()}".`);
     }
 
+    // Chart labels over dots: a label drawn across a dot hides the value it sits on.
+    const dots = [...R.querySelectorAll('.chart svg circle')].filter(visible).map(rectOf).map((r) => grow(r, -1.5));
+    for (const a of marks) {
+      const hit = dots.filter((d) => overlap(grow(a.r, -1), d)).length;
+      if (hit) P.push(`Chart label covers ${hit === 1 ? 'a dot' : hit + ' dots'}: "${a.e.textContent.trim()}".`);
+    }
+
+    // Text that cannot be read against what is drawn behind it, such as white numbers on a pale cell.
+    for (const e of [...R.querySelectorAll('*')].filter((x) => !x.closest('svg') || x.tagName === 'text')) {
+      if (e.tagName !== 'text' && ![...e.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim())) continue;
+      if (!e.textContent.trim() || !visible(e) || e.matches('script, style')) continue;
+      const ratio = contrastOf(e);
+      if (ratio !== null && ratio < 3) P.push(`Text cannot be read against what is behind it: "${e.textContent.trim().replace(/\s+/g, ' ')}" (contrast ${ratio.toFixed(1)} to 1; it needs 3).`);
+    }
+    window.scrollTo(0, 0);
+
     // Text: too small, cut off, or past its box.
     const small = [];
     for (const o of obs.flatMap((b) => (b.text ? [b.el] : [...b.el.querySelectorAll('*')].filter((e) => [...e.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim()))))) {
@@ -619,6 +693,7 @@
     const crossings = new Set(crossingPairs().map(([u, w]) => `${u.from} → ${u.to} and ${w.from} → ${w.to}`));
     if (crossings.size) P.push(R.querySelector('.entities')
       ? `References cross: ${[...crossings].join('; ')}. Split the records over two figures; do not leave a reference out.`
+      : R.querySelector('.states') ? `Moves cross: ${[...crossings].join('; ')}. figkit could not lay them out apart; draw the side branch as a second figure.`
       : `Arrows cross: ${[...crossings].join('; ')}. Reorder the boxes so they do not, or drop an arrow.`);
 
     // Neighbours that almost line up.
@@ -640,7 +715,9 @@
     const outside = R.querySelector('.panels') ? [...R.children].filter((c) => !c.matches('script, style') && !c.querySelector('.panels') && !c.matches('.panels')).map((c) => c.innerText).join(' ') : null;
     const words = (panelText !== null ? outside + ' ' + panelText : R.innerText).split(/\s+/).filter(Boolean).length;
     const nodes = R.querySelectorAll('.node:not(.bare), .decision').length, arrows = (fig.wires ?? []).length;
-    const budget = detail ? { words: 190, nodes: 18, arrows: 18 } : { words: 70, nodes: 5, arrows: 8 };
+    // A states picture reads down one path of short names, so it holds up to 7 states (see the states spec).
+    const states = !!R.querySelector('.states');
+    const budget = detail ? { words: 190, nodes: 18, arrows: 18 } : states ? { words: 90, nodes: 7, arrows: 12 } : { words: 70, nodes: 5, arrows: 8 };
     if (words > budget.words) P.push(`${words} words; a ${detail ? 'detail' : 'glance'} figure holds about ${budget.words}. Cut sentences that explain, and keep labels.`);
     if (nodes > budget.nodes) P.push(`${nodes} boxes; more than ${budget.nodes} stops reading as one picture. ${detail ? 'Split it into two figures or merge boxes.' : 'Split it into two or three figures in a row (what exists, one case through it, what changes), or merge boxes.'}`);
     if (arrows > budget.arrows) P.push(`${arrows} arrows; more than ${budget.arrows} tangles. Show the main path and drop the rest.`);

package/viz/build.mjs

@@ -4,7 +4,7 @@ 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 SOURCES = [...fs.readdirSync(path.join(HOME, 'viz')).filter((f) => f.endsWith('.js')).map((f) => 'viz/' + f), '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);