@liggi/figkit 0.5.0 → 0.6.0

package/viz/map-spec.js

@@ -0,0 +1,121 @@
+/* The "map" spec: a whole system, its parts grouped by subsystem and the links between them. spec.js adds it to the union. */
+import { z } from 'zod';
+
+const slug = z.string({ error: 'needs an id, e.g. "queue"' }).regex(/^[a-z][a-z0-9-]{0,31}$/, 'ids are short lowercase words, e.g. "queue" or "canary-gate"');
+const tone = z.literal('accent', { error: 'tone: only "accent", on what the question is about' }).optional();
+
+/** Limits, kept in one place so the guide and the refusals say the same numbers. */
+export const MAP_LIMITS = { parts: 24, minParts: 6, subsystems: 6, perSubsystem: 8, links: 30, accentLinks: 28, sideLinks: 3 };
+
+/**
+ * A system with many parts: each part sits in one subsystem, and each link says one part uses, calls or feeds another.
+ * figkit lays it out; the author only says what exists and what connects.
+ */
+export const mapShape = {
+  subsystems: z.array(z.object({
+    id: slug,
+    name: z.string({ error: 'needs a name' }).trim().min(1, 'needs a name').max(32, 'keep subsystem names to 32 characters'),
+    kind: z.string().trim().min(1).max(36, 'keep the kind to 36 characters: where it lives, e.g. "ash_builder/detectors/"').optional(),
+  }).strict()).min(2, 'at least 2 subsystems; with one, draw a plain figure').max(MAP_LIMITS.subsystems, `at most ${MAP_LIMITS.subsystems} subsystems; more do not read as regions, so merge the small ones or draw two maps`),
+  parts: z.array(z.object({
+    id: slug,
+    name: z.string({ error: 'needs a name' }).trim().min(1, 'needs a name').max(28, 'keep part names to 28 characters'),
+    kind: z.string().trim().min(1).max(32, 'keep the kind to 32 characters: what it is or the file it lives in').optional(),
+    in: slug.optional(),
+    tone,
+  }).strict()).min(MAP_LIMITS.minParts, `at least ${MAP_LIMITS.minParts} parts; fewer is a plain figure of at most 5 boxes`).max(MAP_LIMITS.parts, `at most ${MAP_LIMITS.parts} parts; past that the links tangle even full screen, so draw the subsystems as one map and the busiest subsystem as a second`),
+  links: z.array(z.object({
+    from: slug,
+    to: slug,
+    label: z.string().trim().min(1).max(22, 'keep link labels to 22 characters: a verb or the thing passed, e.g. "writes rows"').optional(),
+    tone,
+  }).strict()).min(1, 'at least 1 link').max(MAP_LIMITS.links, `at most ${MAP_LIMITS.links} links; more cross too often to follow, so leave out links the question does not need and say so in the note`),
+};
+
+const list = (ids) => ids.map((x) => `"${x}"`).join(', ');
+/** The id one or two letters away from a mistyped one, if there is exactly one. */
+function near(id, ids) {
+  const d = (a, b) => {
+    const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+      let prev = row[0]; row[0] = i;
+      for (let j = 1; j <= b.length; j++) { const t = row[j]; row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1)); prev = t; }
+    }
+    return row[b.length];
+  };
+  const close = ids.filter((x) => d(id, x) <= 2);
+  return close.length === 1 ? `; did you mean "${close[0]}"?` : '';
+}
+
+/** Rules that span fields: ids that exist, every part in a subsystem, every part linked, no repeats. */
+export function mapChecks(s) {
+  const out = [];
+  const subIds = s.subsystems.map((x) => x.id), partIds = s.parts.map((x) => x.id);
+  const all = [...subIds, ...partIds];
+  const dup = all.find((id, i) => all.indexOf(id) !== i);
+  if (dup) return [`ids: "${dup}" is used twice; every part and subsystem needs its own id`];
+  const names = s.parts.map((p) => p.name.toLowerCase());
+  const twice = s.parts.find((p, i) => names.indexOf(p.name.toLowerCase()) !== i);
+  if (twice) out.push(`parts: two parts are named "${twice.name}"; name each part so the reader can tell them apart`);
+
+  s.parts.forEach((p, i) => {
+    if (p.in == null) out.push(`parts[${i}]: "${p.id}" is in no subsystem; give it "in", one of ${list(subIds)}. Something outside the system still goes in a subsystem, such as "Outside"`);
+    else if (!subIds.includes(p.in)) out.push(`parts[${i}].in: no subsystem has the id "${p.in}"${partIds.includes(p.in) ? ' (that is a part; parts cannot hold parts)' : ''}; the subsystems are ${list(subIds)}`);
+  });
+  s.links.forEach((l, i) => {
+    for (const end of ['from', 'to']) if (!partIds.includes(l[end])) {
+      out.push(`links[${i}].${end}: no part has the id "${l[end]}"${subIds.includes(l[end]) ? '; that is a subsystem, and links join parts, so name the part inside it' : near(l[end], partIds)}`);
+    }
+  });
+  if (out.length) return out;
+
+  for (const sub of s.subsystems) {
+    const n = s.parts.filter((p) => p.in === sub.id).length;
+    if (n === 0) out.push(`subsystems: "${sub.id}" has no parts; put parts in it with "in": "${sub.id}", or leave it out`);
+    if (n > MAP_LIMITS.perSubsystem) out.push(`subsystems: "${sub.id}" has ${n} parts, more than ${MAP_LIMITS.perSubsystem}; split it in two, or merge parts the question does not need`);
+  }
+  const seen = new Map();
+  s.links.forEach((l, i) => {
+    if (l.from === l.to) out.push(`links[${i}]: "${l.from}" links to itself; say what it does to itself in its kind instead`);
+    const key = l.from + '>' + l.to;
+    if (seen.has(key)) out.push(`links[${i}]: a second link from "${l.from}" to "${l.to}" (links[${seen.get(key)}] is the first); make it one link with one label`);
+    const back = seen.get(l.to + '>' + l.from);
+    if (back != null) out.push(`links[${i}]: "${l.from}" and "${l.to}" link both ways (links[${back}] is the other); keep the one from the part that starts the exchange, the reply is implied`);
+    seen.set(key, i);
+  });
+  const loose = partIds.filter((id) => !s.links.some((l) => l.from === id || l.to === id));
+  if (loose.length) out.push(`parts: ${list(loose)} ${loose.length === 1 ? 'is' : 'are'} in no link; a part with no link says nothing on a map, so link ${loose.length === 1 ? 'it' : 'them'} or leave ${loose.length === 1 ? 'it' : 'them'} out`);
+  const accented = s.parts.filter((p) => p.tone).length + s.links.filter((l) => l.tone).length;
+  if (accented && accented === s.parts.length + s.links.length) out.push('tone: everything is accented, so nothing stands out; accent only what the question is about');
+  if (s.links.some((l) => l.tone)) {
+    // Measured on two real maps: the highlighted path stays one straight run at 28 links, but not at 29 or 30, and not with 4 grey links on one part of it.
+    if (s.links.length > MAP_LIMITS.accentLinks) out.push(`links: ${s.links.length} links with a highlighted path; at most ${MAP_LIMITS.accentLinks}, or figkit cannot keep the path one straight run, so leave out links the question does not need and say so in the note`);
+    const onPath = new Set(s.parts.filter((p) => p.tone).map((p) => p.id));
+    for (const l of s.links) if (l.tone) { onPath.add(l.from); onPath.add(l.to); }
+    for (const id of onPath) {
+      const grey = s.links.filter((l) => !l.tone && (l.from === id || l.to === id));
+      if (grey.length > MAP_LIMITS.sideLinks) out.push(`links: "${id}" is on the highlighted path and has ${grey.length} grey links (${grey.map((l) => `${l.from} → ${l.to}`).join(', ')}); a part on the path holds at most ${MAP_LIMITS.sideLinks}, because the path takes its top and bottom and the grey links must come in from the sides. Leave out the ones the question does not need`);
+    }
+  }
+  if (s.parts.filter((p) => p.tone).length > 8) out.push('parts: more than 8 parts are accented; a map points at one corner of the system, so accent only that corner');
+  return out;
+}
+
+/**
+ * The map with each subsystem as one box: the links between subsystems counted, the links inside one left out.
+ * For the phone layout, where the full map cannot be read.
+ */
+export function collapse(s) {
+  const where = Object.fromEntries(s.parts.map((p) => [p.id, p.in]));
+  const pairs = new Map();
+  for (const l of s.links) {
+    const a = where[l.from], b = where[l.to];
+    if (a === b) continue;
+    const key = a + '>' + b;
+    const e = pairs.get(key) ?? { from: a, to: b, count: 0, tone: undefined };
+    e.count++;
+    if (l.tone) e.tone = 'accent';
+    pairs.set(key, e);
+  }
+  return [...pairs.values()];
+}

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