@liggi/figkit 0.4.0 → 0.6.0

package/viz/map.js

@@ -0,0 +1,513 @@
+/* The "map" spec drawn: parts in labelled subsystem regions packed into rows; on a phone, one box per subsystem. */
+import dagre from '@dagrejs/dagre';
+import { collapse } from './map-spec.js';
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+/** The widest a map may be drawn (GUIDE.md: a detail figure widens to 1560px at most). */
+const MAX_W = 1560;
+/** A desktop screen the map is opened full screen on: the arrangement read largest there is preferred. */
+const SCREEN = { w: 1440, h: 860 };
+/** Space between regions: a lane for the links between subsystems and their labels. */
+const GAP = { desk: 104, phone: 64 };
+const PAD = { x: 22, bottom: 22 };
+/** A lane round the outside of the regions, for links that leave a region and come back in elsewhere. */
+const LANE = 32;
+/** How far beside a part the highlighted path runs when it steps around another part: figkit's clearance from a box. */
+const LANE_OFF = 16;
+/** How many of the arrangements built around a highlighted path are routed for real. */
+const SPINE_TRIES = 40;
+
+/** The boxes, regions and links to lay out: the full map, or on a phone one box per subsystem. */
+function graphOf(spec, phone) {
+  if (!phone) {
+    return {
+      groups: spec.subsystems,
+      nodes: spec.parts.map((p) => ({ id: p.id, group: p.in, tone: p.tone, html: `<h3>${esc(p.name)}</h3>${p.kind ? `<p>${esc(p.kind)}</p>` : ''}` })),
+      edges: spec.links.map((l) => ({ from: l.from, to: l.to, label: l.label, tone: l.tone })),
+    };
+  }
+  return {
+    groups: [],
+    nodes: spec.subsystems.map((g) => {
+      const parts = spec.parts.filter((p) => p.in === g.id);
+      return {
+        id: g.id, tone: parts.some((p) => p.tone) ? 'accent' : undefined, sub: true,
+        html: `<h3>${esc(g.name)}</h3><ul>${parts.map((p) => `<li${p.tone ? ' class="t-accent"' : ''}>${esc(p.name)}</li>`).join('')}</ul>`,
+      };
+    }),
+    edges: collapse(spec).map((e) => ({ from: e.from, to: e.to, label: String(e.count), tone: e.tone })),
+  };
+}
+
+/**
+ * The parts of one region placed in layers by dagre, across (RIGHT) or down (DOWN), with room kept between layers for
+ * the labels. Returns the region's inner size and each part's top-left corner.
+ */
+function layoutRegion(children, edges, dir) {
+  const g = new dagre.graphlib.Graph({ multigraph: true });
+  g.setGraph({ rankdir: dir === 'RIGHT' ? 'LR' : 'TB', nodesep: 28, ranksep: 56, edgesep: 14, marginx: 0, marginy: 0 });
+  g.setDefaultEdgeLabel(() => ({}));
+  for (const c of children) g.setNode(c.id, { width: c.width, height: c.height });
+  // A highlighted link pulls hard, so the highlighted path runs straight through the region.
+  for (const e of edges) g.setEdge(e.from, e.to, { width: e.label?.width ?? 0, height: e.label?.height ?? 0, labelpos: 'c', weight: e.tone ? 12 : 1 }, e.id);
+  dagre.layout(g);
+  const placed = children.map((c) => { const n = g.node(c.id); return { id: c.id, width: c.width, height: c.height, x: n.x - c.width / 2, y: n.y - c.height / 2 }; });
+  const x0 = Math.min(...placed.map((c) => c.x)), y0 = Math.min(...placed.map((c) => c.y));
+  for (const c of placed) { c.x -= x0; c.y -= y0; }
+  return { children: placed, width: Math.max(...placed.map((c) => c.x + c.width)), height: Math.max(...placed.map((c) => c.y + c.height)) };
+}
+
+/**
+ * The runs along the highlighted links: from a highlighted link no other highlighted link feeds, to one that feeds none.
+ * Each run is the list of its links.
+ */
+function runsOf(edges) {
+  const hot = edges.filter((e) => e.tone), runs = [];
+  const walk = (e, path) => {
+    const next = hot.filter((n) => n.from === e.to && !path.includes(n));
+    if (!next.length) runs.push([...path, e]);
+    for (const n of next) walk(n, [...path, e]);
+  };
+  for (const e of hot) if (!hot.some((u) => u.to === e.from)) walk(e, []);
+  return runs;
+}
+
+/** Whether a run through these points doubles back: goes left and right, or down and up, by more than a step. */
+function doublesBack(pts) {
+  const seen = new Set();
+  for (let i = 1; i < pts.length; i++) {
+    const dx = pts[i][0] - pts[i - 1][0], dy = pts[i][1] - pts[i - 1][1];
+    if (Math.abs(dx) >= 40) seen.add(dx > 0 ? 'r' : 'l');
+    if (Math.abs(dy) >= 40) seen.add(dy > 0 ? 'd' : 'u');
+  }
+  return (seen.has('r') && seen.has('l')) || (seen.has('d') && seen.has('u'));
+}
+
+function permutations(n) {
+  const out = [], a = [...Array(n).keys()];
+  const walk = (k) => {
+    if (k === n) { out.push([...a]); return; }
+    for (let i = k; i < n; i++) { [a[k], a[i]] = [a[i], a[k]]; walk(k + 1); [a[k], a[i]] = [a[i], a[k]]; }
+  };
+  walk(0);
+  return out;
+}
+
+/**
+ * Where each region goes: regions in rows, left to right, the rows top to bottom. Every order and every way of
+ * breaking it into rows is tried. An arrangement costs more for links that must go round another region, for long
+ * links, and for links that run back up or to the left; on a desktop it also costs more the smaller it reads on a
+ * full screen. Each region may be laid out across or down, whichever arrangement is cheaper.
+ */
+function pack(items, links, { maxW, gap, extra, phone, hotRuns = [] }) {
+  const n = items.length;
+  const keep = [];
+  // Every mix of regions laid out across and down.
+  const options = phone ? [items.map(() => 0)] : Array.from({ length: 1 << n }, (_, m) => items.map((_, i) => (m >> i) & 1));
+  for (const choice of options) {
+    const dims = items.map((it, i) => it.dims[choice[i]]);
+    for (const perm of permutations(n)) {
+      for (let mask = 0; mask < 1 << (n - 1); mask++) {
+        const rect = new Array(n);
+        let x = 0, y = 0, rowH = 0, W = 0;
+        perm.forEach((k, j) => {
+          if (j > 0 && mask & (1 << (j - 1))) { y += rowH + gap; x = 0; rowH = 0; }
+          rect[k] = { x, y, w: dims[k].w, h: dims[k].h };
+          x += dims[k].w + gap; rowH = Math.max(rowH, dims[k].h); W = Math.max(W, x - gap);
+        });
+        const H = y + rowH;
+        let cost = W > maxW ? 1000 + W / 100 : 0;
+        for (const { a, b, count } of links) {
+          const A = rect[a], B = rect[b];
+          const dx = Math.max(0, A.x - (B.x + B.w), B.x - (A.x + A.w)), dy = Math.max(0, A.y - (B.y + B.h), B.y - (A.y + A.h));
+          const ca = [A.x + A.w / 2, A.y + A.h / 2], cb = [B.x + B.w / 2, B.y + B.h / 2];
+          const between = rect.some((r, k) => k !== a && k !== b && segHits(ca, cb, r));
+          const back = cb[1] < A.y - 1 || (Math.abs(A.y - B.y) < 1 && cb[0] < ca[0]);
+          cost += count * ((dx + dy) / 500 + (between ? 1.2 : 0) + (back ? (phone ? 1.5 : 0.25) : 0));
+        }
+        // The highlighted path, subsystem to subsystem, should keep one way across the map, never turn back.
+        for (const run of hotRuns) if (doublesBack(run.map((k) => [rect[k].x + rect[k].w / 2, rect[k].y + rect[k].h / 2]))) cost += 3;
+        const read = Math.min(SCREEN.w / Math.max(W + extra.w, 960), SCREEN.h / (H + extra.h));
+        cost += phone ? H / 2000 : -8 * Math.log(read);
+        if (keep.length < 60 || cost < keep[keep.length - 1].cost) {
+          keep.push({ cost, rect, W, H, choice });
+          keep.sort((p, q) => p.cost - q.cost);
+          if (keep.length > 60) keep.pop();
+        }
+      }
+    }
+  }
+  return keep;
+}
+
+/**
+ * The cheapest arrangement once the parts themselves are placed: each candidate is tried with each region mirrored
+ * (down a region laid out across, across one laid out down, so links still run the same way), and costs more for
+ * every pair of links whose straight lines cross and every link whose line passes through a part it does not join.
+ * Returns them all, cheapest first.
+ */
+function refine(cands, items, edges, partsOf) {
+  const all = [];
+  const n = items.length;
+  const runs = runsOf(edges);
+  for (const c of cands) {
+    for (let flip = 0; flip < 1 << n; flip++) {
+      const at = {}, rects = [];
+      items.forEach((it, k) => {
+        const r = c.rect[k];
+        for (const p of partsOf(k, c.choice[k], (flip >> k) & 1)) {
+          at[p.id] = [r.x + p.x + p.w / 2, r.y + p.y + p.h / 2];
+          rects.push({ id: p.id, x: r.x + p.x, y: r.y + p.y, w: p.w, h: p.h });
+        }
+      });
+      const segs = edges.map((e) => [at[e.from], at[e.to], e]);
+      let cost = c.cost;
+      for (let i = 0; i < segs.length; i++) {
+        const [p, q, e] = segs[i];
+        for (let j = i + 1; j < segs.length; j++) {
+          const [u, v, f] = segs[j];
+          if (e.from === f.from || e.from === f.to || e.to === f.from || e.to === f.to) continue;
+          if (crosses(p, q, u, v)) cost += !e.tone !== !f.tone ? 4 : 1;
+        }
+        for (const r of rects) if (r.id !== e.from && r.id !== e.to && segHits(p, q, r)) cost += 0.5;
+      }
+      // A highlighted run that doubles back is what the layout must avoid most.
+      for (const run of runs) if (doublesBack([at[run[0].from], ...run.map((e) => at[e.to])])) cost += 8;
+      all.push({ ...c, cost, flip });
+    }
+  }
+  return all.sort((p, q) => p.cost - q.cost);
+}
+
+/**
+ * Arrangements built around the highlighted path. The subsystems it passes through are placed one after another in the
+ * order the path reaches them, top to bottom (each laid out down) or left to right (each laid out across), and moved
+ * so the part the path enters lines up with the part it left: the path runs as one straight line, and steps aside only
+ * where it forks. The other subsystems go on either side of it, or after its end, wherever their links are shortest and
+ * cross the path least. Returns them cheapest first, in the form refine() returns; none when nothing is highlighted, or
+ * when the path goes back to a subsystem it has left.
+ */
+function spine(items, edges, partsOf, owner, { maxW, gap, extra }) {
+  const hot = edges.filter((e) => e.tone);
+  if (!hot.length) return [];
+  const n = items.length;
+  const step = hot.map((e) => [owner(e.from), owner(e.to), e]).filter(([a, b]) => a !== b);
+  const on = new Set(hot.flatMap((e) => [owner(e.from), owner(e.to)]));
+  // Each of the path's subsystems at the step it is reached, counting the highlighted links between subsystems.
+  const level = new Map([...on].map((k) => [k, 0]));
+  for (let i = 0; i <= on.size; i++) {
+    let moved = false;
+    for (const [a, b] of step) if (level.get(b) < level.get(a) + 1) { level.set(b, level.get(a) + 1); moved = true; }
+    if (moved && i === on.size) return [];
+  }
+  const levels = [];
+  for (const [k, l] of level) (levels[l] ??= []).push(k);
+  if (levels.some((l) => !l)) return [];
+  const rest = [...Array(n).keys()].filter((k) => !on.has(k));
+  const spineK = [...on];
+  const runs = runsOf(edges);
+  const out = [];
+  const seen = new Set();
+  const keep = (c) => {
+    // The same placement reached another way (a mirror that moves nothing) is kept once.
+    const key = c.key;
+    if (seen.has(key)) return;
+    seen.add(key);
+    if (out.length < 80 || c.cost < out[out.length - 1].cost) { out.push(c); out.sort((a, b) => a.cost - b.cost); if (out.length > 80) out.pop(); }
+  };
+
+  // Worked in the path's own frame: "along" is the way the path runs, "across" the other way. Down: along is y.
+  for (const down of [true, false]) {
+    const sw = (r) => (down ? r : { x: r.y, y: r.x, w: r.h, h: r.w });
+    const pathChoice = down ? 1 : 0;
+    // Where the path forks, the subsystems side by side in every order.
+    let orders = [[]];
+    for (const lv of levels) orders = orders.flatMap((o) => permutations(lv.length).map((pm) => [...o, pm.map((i) => lv[i])])).slice(0, 24);
+    for (const order of orders)
+    for (let flipMask = 0; flipMask < 1 << spineK.length; flipMask++) {
+      const flipOf = (k) => (spineK.includes(k) ? (flipMask >> spineK.indexOf(k)) & 1 : 0);
+      const inset = new Array(n).fill(0);
+      // A part in the path's subsystem, in that frame, relative to the subsystem's corner.
+      const local = (k, choice, flip) => Object.fromEntries(partsOf(k, choice, flip, inset[k]).map((p) => [p.id, sw(p)]));
+      const size = (k, choice) => sw({ x: 0, y: 0, w: items[k].dims[choice].w + inset[k], h: items[k].dims[choice].h });
+      const rect = new Array(n), at = {};
+      const put = (k, choice, flip, x, y) => {
+        const d = size(k, choice);
+        rect[k] = { x, y, w: d.w, h: d.h };
+        for (const [id, p] of Object.entries(local(k, choice, flip))) at[id] = { x: x + p.x, y: y + p.y, w: p.w, h: p.h };
+      };
+      // Where a line may run into (or out of) a part along the path without crossing another part of its subsystem or
+      // its heading: straight in at the middle ("c"), or in a lane just to its left ("l") or right ("r"), entering from
+      // the side. Each as an offset across from the subsystem's corner, freest first.
+      const lanes = (k, choice, flip, id, into) => {
+        const ps = local(k, choice, flip), me = ps[id], d = size(k, choice);
+        const head = sw({ x: PAD.x, y: 0, w: items[k].headW, h: items[k].dims[choice].top - 8 });
+        const others = [...Object.entries(ps).filter(([q]) => q !== id).map(([, r]) => r), head];
+        const y0 = into ? -1 : me.y + me.h, y1 = into ? me.y : d.h + 1;
+        const free = (x) => !others.some((r) => r.x < x + 14 && r.x + r.w > x - 14 && r.y < y1 && r.y + r.h > y0);
+        // A part near the subsystem's edge steps out into the gap beside the subsystem, not along its border.
+        const l = me.x < 64 ? -gap / 2 : me.x - LANE_OFF, r = d.w - me.x - me.w < 64 ? d.w + gap / 2 : me.x + me.w + LANE_OFF;
+        return [['c', me.x + me.w / 2], ['l', l], ['r', r]].filter(([, x]) => free(x));
+      };
+      let y = 0;
+      const entered = {};
+      for (const lv of order) {
+        const into = lv.map((k) => step.find(([a, b]) => b === k && rect[a]));
+        // Laid out down, a line coming in from above would cross the subsystem's heading at its top left: the parts
+        // move right until a line straight down the middle clears it.
+        if (down) lv.forEach((k, i) => {
+          if (!into[i]) return;
+          const dst = local(k, pathChoice, flipOf(k))[into[i][2].to];
+          const need = Math.max(0, PAD.x + items[k].headW + 16 - (dst.x + dst.w / 2));
+          const before = inset[k];
+          inset[k] = need;
+          if (!lanes(k, pathChoice, flipOf(k), into[i][2].to, true).some(([s]) => s === 'c')) inset[k] = before;
+        });
+        // Out of the part above and into the part here: straight down if both are clear, else stepping aside through a
+        // lane, never out to one side and back in from the other, which would turn the path back on itself.
+        const xs = lv.map((k, i) => {
+          if (!into[i]) return null;
+          const [a, , e] = into[i], src = at[e.from];
+          // A part entered from one side is left by the other side or the bottom, so the path keeps going one way.
+          const outs = lanes(a, pathChoice, flipOf(a), e.from, false).filter(([s]) => s === 'c' || s !== entered[e.from]).map(([s, x]) => [s, x + rect[a].x]);
+          const ins = lanes(k, pathChoice, flipOf(k), e.to, true);
+          const rank = ([so], [si]) => (so === 'c' ? 0 : 1) + (si === 'c' ? 0 : 1);
+          const pairs = outs.flatMap((o) => ins.filter((n) => !(o[0] !== 'c' && n[0] === o[0])).map((n) => [o, n])).sort((p, q) => rank(...p) - rank(...q));
+          if (!pairs.length) return src.x + src.w / 2 - (local(k, pathChoice, flipOf(k))[e.to].x + local(k, pathChoice, flipOf(k))[e.to].w / 2);
+          const [[, ox], [si, ix]] = pairs[0];
+          entered[e.to] = si;
+          return ox - ix;
+        });
+        const h = Math.max(...lv.map((k) => size(k, pathChoice).h));
+        if (lv.length === 1) put(lv[0], pathChoice, flipOf(lv[0]), xs[0] ?? 0, y);
+        else {
+          // Where the path forks into several subsystems, they sit side by side, centred on where it came from.
+          const ws = lv.map((k) => size(k, pathChoice).w), total = ws.reduce((a, b) => a + b, 0) + gap * (lv.length - 1);
+          const known = lv.map((k, i) => (xs[i] == null ? null : xs[i] + ws[i] / 2)).filter((v) => v != null);
+          const mid = known.length ? known.reduce((a, b) => a + b, 0) / known.length : total / 2;
+          let x = mid - total / 2;
+          lv.forEach((k, i) => { put(k, pathChoice, flipOf(k), x, y); x += ws[i] + gap; });
+        }
+        y += h + gap;
+      }
+      const sx0 = Math.min(...spineK.map((k) => rect[k].x)), sx1 = Math.max(...spineK.map((k) => rect[k].x + rect[k].w));
+      const sy1 = y - gap;
+      // Each other subsystem: before the path (0), after it (1) or past its end (2), laid out across or down.
+      const options = 3 ** rest.length * 2 ** rest.length;
+      for (let o = 0; o < options; o++) {
+        let m = o;
+        const side = rest.map(() => { const v = m % 3; m = Math.floor(m / 3); return v; });
+        const choice = rest.map(() => { const v = m % 2; m >>= 1; return v; });
+        const sorted = [[], [], []];
+        rest.forEach((k, i) => sorted[side[i]].push(i));
+        // Each column in every order: the subsystem its links pull highest need not be the best one on top.
+        for (const p0 of permutations(sorted[0].length)) for (const p1 of permutations(sorted[1].length)) {
+        const R = rect.slice(), A = { ...at };
+        const placeRest = (i, x, yy) => {
+          const k = rest[i], d = size(k, choice[i]);
+          R[k] = { x, y: yy, w: d.w, h: d.h };
+          for (const [id, p] of Object.entries(local(k, choice[i], 0))) A[id] = { x: x + p.x, y: yy + p.y, w: p.w, h: p.h };
+        };
+        const cols = [p0.map((j) => sorted[0][j]), p1.map((j) => sorted[1][j]), sorted[2]];
+        // Beside the path, a subsystem sits level with the path's parts it links to.
+        const pull = (i) => {
+          const k = rest[i], ys = edges.filter((e) => (owner(e.from) === k) !== (owner(e.to) === k) && on.has(owner(owner(e.from) === k ? e.to : e.from)))
+            .map((e) => { const p = at[owner(e.from) === k ? e.to : e.from]; return p.y + p.h / 2; });
+          return ys.length ? ys.reduce((a, b) => a + b, 0) / ys.length : sy1;
+        };
+        for (const c of [0, 1]) {
+          // The gap beside the path widens with the links that cross it, so their lines and labels stay apart.
+          const ks = new Set(cols[c].map((i) => rest[i]));
+          const through = edges.filter((e) => ks.has(owner(e.from)) !== ks.has(owner(e.to))).length;
+          const cgap = gap + Math.max(0, through - 4) * 14;
+          let cy = 0;
+          const wmax = Math.max(0, ...cols[c].map((i) => size(rest[i], choice[i]).w));
+          for (const i of cols[c]) {
+            const d = size(rest[i], choice[i]);
+            const yy = Math.max(0, cy, Math.min(pull(i) - d.h / 2, sy1 - d.h));
+            placeRest(i, c === 0 ? sx0 - cgap - (wmax + d.w) / 2 : sx1 + cgap + (wmax - d.w) / 2, yy);
+            cy = yy + d.h + gap;
+          }
+        }
+        let bx = Math.min(sx0, ...cols[0].map((i) => R[rest[i]].x));
+        const below = Math.max(sy1, ...[0, 1].flatMap((c) => cols[c].map((i) => R[rest[i]].y + R[rest[i]].h))) + gap;
+        for (const i of cols[2]) { placeRest(i, bx, below); bx += size(rest[i], choice[i]).w + gap; }
+        // Back to the page's frame, starting at 0, 0.
+        const real = R.map(sw), x0 = Math.min(...real.map((r) => r.x)), y0 = Math.min(...real.map((r) => r.y));
+        const fin = real.map((r) => ({ ...r, x: r.x - x0, y: r.y - y0 }));
+        if (fin.some((r, i) => fin.some((q, j) => j > i && r.x < q.x + q.w + gap / 2 && q.x < r.x + r.w + gap / 2 && r.y < q.y + q.h + gap / 2 && q.y < r.y + r.h + gap / 2))) continue;
+        const W = Math.max(...fin.map((r) => r.x + r.w)), H = Math.max(...fin.map((r) => r.y + r.h));
+        const P = Object.fromEntries(Object.entries(A).map(([id, r]) => { const q = sw(r); return [id, { x: q.x - x0, y: q.y - y0, w: q.w, h: q.h }]; }));
+        const c = (id) => [P[id].x + P[id].w / 2, P[id].y + P[id].h / 2];
+        let cost = W > maxW ? 1000 + W / 100 : 0;
+        cost += -8 * Math.log(Math.min(SCREEN.w / Math.max(W + extra.w, 960), SCREEN.h / (H + extra.h)));
+        const segs = edges.map((e) => [c(e.from), c(e.to), e]);
+        for (let i = 0; i < segs.length; i++) {
+          const [p, q, e] = segs[i];
+          cost += (Math.abs(p[0] - q[0]) + Math.abs(p[1] - q[1])) / 500;
+          for (let j = i + 1; j < segs.length; j++) {
+            const [u, v, f] = segs[j];
+            if (e.from === f.from || e.from === f.to || e.to === f.from || e.to === f.to) continue;
+            if (crosses(p, q, u, v)) cost += !e.tone !== !f.tone ? 4 : 1;
+          }
+          for (const id in P) if (id !== e.from && id !== e.to && segHits(p, q, P[id])) cost += 0.5;
+        }
+        for (const run of runs) if (doublesBack([c(run[0].from), ...run.map((e) => c(e.to))])) cost += 8;
+        const ch = items.map((_, k) => (on.has(k) ? pathChoice : choice[rest.indexOf(k)]));
+        keep({ key: Object.keys(P).sort().map((id) => c(id).map(Math.round).join(',')).join(' '), cost, rect: fin, W, H, choice: ch, flip: spineK.reduce((f, k) => f | (flipOf(k) << k), 0), inset: inset.slice() });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function crosses(a, b, c, d) {
+  const o = (p, q, r) => Math.sign((q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0]));
+  return o(a, b, c) * o(a, b, d) < 0 && o(c, d, a) * o(c, d, b) < 0;
+}
+
+/** Whether the line from p to q passes through rectangle r (Liang–Barsky clipping). */
+function segHits(p, q, r) {
+  const dx = q[0] - p[0], dy = q[1] - p[1];
+  let t0 = 0, t1 = 1;
+  for (const [pp, qq] of [[-dx, p[0] - r.x], [dx, r.x + r.w - p[0]], [-dy, p[1] - r.y], [dy, r.y + r.h - p[1]]]) {
+    if (pp === 0) { if (qq <= 0) return false; continue; }
+    const t = qq / pp;
+    if (pp < 0) t0 = Math.max(t0, t); else t1 = Math.min(t1, t);
+    if (t0 >= t1) return false;
+  }
+  return true;
+}
+
+/**
+ * Lays the map out and draws it. Each box is measured in the page first. dagre lays out the parts inside each
+ * subsystem, across and down; figkit then packs the subsystems into rows that fit the figure, and its own router draws
+ * every link around the boxes, as for any figure, so the checks on arrows and labels apply unchanged.
+ */
+export async function drawMap(spec, main) {
+  const phone = main.classList.contains('phone');
+  const { groups, nodes, edges } = graphOf(spec, phone);
+  const pad = parseFloat(getComputedStyle(main).paddingLeft) || 48;
+  const wrap = document.createElement('div');
+  wrap.className = 'map' + (phone ? ' map-overview' : '');
+  main.appendChild(wrap);
+
+  const box = {};
+  for (const n of nodes) {
+    const el = document.createElement('div');
+    el.className = 'node map-part' + (n.sub ? ' map-sub' : '') + (n.tone ? ' accent' : '');
+    el.id = 'mp-' + n.id;
+    el.innerHTML = n.html;
+    wrap.appendChild(el);
+    box[n.id] = el;
+  }
+  const region = {};
+  for (const g of groups) {
+    const el = document.createElement('div');
+    el.className = 'group map-region';
+    el.id = 'mp-' + g.id;
+    el.innerHTML = `<div class="mp-head"><h2>${esc(g.name)}</h2>${g.kind ? `<span class="tag">${esc(g.kind)}</span>` : ''}</div>`;
+    wrap.appendChild(el);
+    region[g.id] = el;
+  }
+  // A label measured as figkit draws it, so the layout keeps room for it between the layers of a region.
+  const probe = (text) => {
+    const el = document.createElement('div');
+    el.className = 'fig-wire-label';
+    el.style.visibility = 'hidden';
+    el.textContent = text;
+    wrap.appendChild(el);
+    const r = el.getBoundingClientRect();
+    el.remove();
+    return { width: Math.ceil(r.width), height: Math.ceil(r.height) };
+  };
+  await new Promise((r) => requestAnimationFrame(r));
+  // Fractional widths rounded down would wrap the text again once the box is given that width.
+  const size = (el) => { const r = el.getBoundingClientRect(); return { width: Math.ceil(r.width) + 1, height: Math.ceil(r.height) }; };
+  const sizes = Object.fromEntries(nodes.map((n) => [n.id, size(box[n.id])]));
+
+  // Each region laid out on its own, across and down; on a phone each subsystem is one box and needs no layout.
+  const items = [];
+  if (phone) for (const n of nodes) items.push({ id: n.id, dims: [{ w: sizes[n.id].width, h: sizes[n.id].height }] });
+  for (const g of groups) {
+    const head = size(region[g.id].querySelector('.mp-head'));
+    const mine = nodes.filter((n) => n.group === g.id);
+    const ids = new Set(mine.map((n) => n.id));
+    const inner = edges.map((e, i) => ({ e, i })).filter(({ e }) => ids.has(e.from) && ids.has(e.to));
+    const dims = [];
+    for (const dir of ['RIGHT', 'DOWN']) {
+      const out = layoutRegion(mine.map((n) => ({ id: n.id, ...sizes[n.id] })), inner.map(({ e, i }) => ({ id: 'e' + i, from: e.from, to: e.to, tone: e.tone, label: e.label ? probe(e.label) : null })), dir);
+      const top = head.height + 30;
+      dims.push({ w: Math.max(out.width + 2 * PAD.x, head.width + 2 * PAD.x), h: out.height + top + PAD.bottom, top, out });
+    }
+    items.push({ id: g.id, dims, headW: head.width });
+  }
+
+  const index = Object.fromEntries(items.map((it, i) => [it.id, i]));
+  const owner = (id) => index[phone ? id : nodes.find((n) => n.id === id).group];
+  const counts = new Map();
+  for (const e of edges) {
+    const a = owner(e.from), b = owner(e.to);
+    if (a === b) continue;
+    const key = a + ',' + b;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const links = [...counts].map(([k, count]) => { const [a, b] = k.split(',').map(Number); return { a, b, count }; });
+  const header = main.querySelector(':scope > header');
+  const gap = phone ? GAP.phone : GAP.desk;
+  const inner = phone ? (parseFloat(getComputedStyle(main).width) || 560) - 2 * pad : MAX_W - 2 * pad - 2 * LANE;
+  // Each highlighted run as the subsystems it passes through, in order.
+  const hotRuns = runsOf(edges).map((run) => [owner(run[0].from), ...run.map((e) => owner(e.to))].filter((k, i, a) => i === 0 || a[i - 1] !== k)).filter((r) => r.length > 2);
+  const cands = pack(items, links, { maxW: inner, gap, extra: { w: 2 * pad, h: (header ? header.offsetHeight + 28 : 0) + 2 * pad }, phone, hotRuns });
+  // Each part's box within its region, for a region laid out across (0) or down (1), mirrored or not.
+  const partsOf = (k, choice, flip, inset = 0) => {
+    const it = items[k];
+    if (phone) return [{ id: it.id, x: 0, y: 0, w: it.dims[0].w, h: it.dims[0].h }];
+    const d = it.dims[choice];
+    // A region wider than its parts (for its heading) centres them.
+    const shift = Math.max(0, (d.w - (d.out.width + 2 * PAD.x)) / 2);
+    return d.out.children.map((c) => ({
+      id: c.id, w: c.width, h: c.height,
+      x: PAD.x + shift + inset + (flip && choice === 1 ? d.out.width - c.x - c.width : c.x),
+      y: d.top + (flip && choice === 0 ? d.out.height - c.y - c.height : c.y),
+    }));
+  };
+  // With a highlighted path, the arrangements built around it are tried first; the packed ones stay as a fallback.
+  const around = phone ? [] : spine(items, edges, partsOf, owner, { maxW: inner, gap, extra: { w: 2 * pad, h: (header ? header.offsetHeight + 28 : 0) + 2 * pad } });
+  const ranked = [...around.slice(0, SPINE_TRIES), ...refine(cands, items, edges, partsOf)];
+
+  // Regions, and the parts inside each at the place the layout gave them; on a phone the boxes themselves.
+  const apply = (best) => {
+    const place = (el, x, y, w, h) => Object.assign(el.style, { left: x + 'px', top: y + 'px', ...(w ? { width: w + 'px', height: h + 'px' } : {}) });
+    const offsetX = phone ? Math.max(0, (inner - best.W) / 2) : 0;
+    items.forEach((it, k) => {
+      const r = best.rect[k];
+      if (phone) { place(box[it.id], r.x + offsetX, r.y); return; }
+      // A region shorter than its row keeps its own height; its parts are centred across its width.
+      place(region[it.id], r.x + LANE, r.y, r.w, r.h);
+      for (const p of partsOf(k, best.choice[k], (best.flip >> k) & 1, best.inset?.[k] ?? 0)) { region[it.id].appendChild(box[p.id]); place(box[p.id], p.x, p.y, p.w, p.h); }
+    });
+    wrap.style.width = (phone ? inner : best.W + 2 * LANE) + 'px';
+    wrap.style.height = best.H + 'px';
+    if (!phone) main.style.setProperty('--w', Math.round(Math.max(960, best.W + 2 * LANE + 2 * pad)) + 'px');
+
+  };
+  // The few cheapest arrangements are routed for real by fig.js, which keeps the one whose arrows cross least.
+  const per = new Map();
+  const tries = ranked.filter((c) => { const k = per.get(c.rect) ?? 0; per.set(c.rect, k + 1); return k < (phone ? 1 : 4); }).slice(0, phone ? 12 : 32 + around.slice(0, SPINE_TRIES).length);
+  window.fig.mapTry = tries.map((c) => () => apply(c));
+  apply(ranked[0]);
+
+  // Every link is an ordinary figkit arrow, routed around the boxes and regions with its label placed clear of them.
+  // The highlighted links are routed first, so they take the straightest way and the grey links go around them.
+  for (const e of [...edges.filter((x) => x.tone), ...edges.filter((x) => !x.tone)]) {
+    const a = document.createElement('fig-arrow');
+    a.setAttribute('from', 'mp-' + e.from);
+    a.setAttribute('to', 'mp-' + e.to);
+    if (e.label) a.setAttribute('label', e.label);
+    if (e.tone) a.setAttribute('accent', '');
+    main.appendChild(a);
+  }
+  return wrap;
+}

package/viz/spec.js

@@ -1,6 +1,8 @@
 /* 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';
+import { mapShape, mapChecks } from './map-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 +52,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 +95,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 +186,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 +285,17 @@ 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();
+
+/** A whole system: parts grouped by subsystem and the links between them, laid out by figkit. */
+export const MapSpec = z.object({ type: z.literal('map'), title, note: common.note, source: common.source, style: common.style, ...mapShape }).strict();
+
+export const Spec = z.discriminatedUnion('type', [SplitSpec, BarsSpec, EstimatesSpec, BeforeAfterSpec, DumbbellSpec, SeriesSpec, EntitiesSpec, GroupsSpec, LinesSpec, PanelsSpec, HeatmapSpec, DotsSpec, ScatterSpec, UnitsSpec, SequenceSpec, StatesSpec, MapSpec]);
+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, map: MapSpec };
 
-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] : s.type === 'map' ? [...s.parts, ...s.links] : 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 +345,8 @@ 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 === 'map') return mapChecks(s);
   if (s.type === 'groups') return groupsChecks(s);
   if (s.type === 'lines') return linesChecks(s);
   if (s.type === 'panels') {
@@ -340,8 +381,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');