@liggi/figkit 0.5.0 → 0.6.0

package/examples/charts/map.json

@@ -0,0 +1,269 @@
+{
+  "type": "map",
+  "title": "Every grocery order passes through the order service before stores pick or vans deliver",
+  "subsystems": [
+    {
+      "id": "shop",
+      "name": "Storefront",
+      "kind": "web and mobile"
+    },
+    {
+      "id": "orders",
+      "name": "Orders",
+      "kind": "orders team"
+    },
+    {
+      "id": "stores",
+      "name": "Store fulfilment",
+      "kind": "stores team"
+    },
+    {
+      "id": "delivery",
+      "name": "Delivery",
+      "kind": "logistics team"
+    },
+    {
+      "id": "outside",
+      "name": "Outside services"
+    }
+  ],
+  "parts": [
+    {
+      "id": "web",
+      "name": "Shop website",
+      "kind": "Next.js app",
+      "in": "shop"
+    },
+    {
+      "id": "mobile",
+      "name": "Shop app",
+      "kind": "iOS and Android",
+      "in": "shop"
+    },
+    {
+      "id": "gateway",
+      "name": "API gateway",
+      "kind": "Envoy",
+      "in": "shop"
+    },
+    {
+      "id": "search",
+      "name": "Product search",
+      "kind": "OpenSearch",
+      "in": "shop"
+    },
+    {
+      "id": "basket",
+      "name": "Basket service",
+      "kind": "Go service",
+      "in": "shop"
+    },
+    {
+      "id": "order",
+      "name": "Order service",
+      "kind": "Go service",
+      "in": "orders",
+      "tone": "accent"
+    },
+    {
+      "id": "orderdb",
+      "name": "Orders database",
+      "kind": "Postgres",
+      "in": "orders"
+    },
+    {
+      "id": "payment",
+      "name": "Payment service",
+      "kind": "Go service",
+      "in": "orders"
+    },
+    {
+      "id": "fraud",
+      "name": "Fraud check",
+      "kind": "rules engine",
+      "in": "orders"
+    },
+    {
+      "id": "events",
+      "name": "Order events",
+      "kind": "Kafka topic",
+      "in": "orders"
+    },
+    {
+      "id": "planner",
+      "name": "Picking planner",
+      "kind": "nightly batch",
+      "in": "stores"
+    },
+    {
+      "id": "stock",
+      "name": "Store stock",
+      "kind": "per-store counts",
+      "in": "stores"
+    },
+    {
+      "id": "picker",
+      "name": "Picker app",
+      "kind": "handheld scanner",
+      "in": "stores"
+    },
+    {
+      "id": "subs",
+      "name": "Substitution rules",
+      "kind": "YAML in repo",
+      "in": "stores"
+    },
+    {
+      "id": "slots",
+      "name": "Van slots",
+      "kind": "1-hour windows",
+      "in": "delivery"
+    },
+    {
+      "id": "routes",
+      "name": "Route planner",
+      "kind": "OR-Tools job",
+      "in": "delivery"
+    },
+    {
+      "id": "driver",
+      "name": "Driver app",
+      "kind": "Android",
+      "in": "delivery"
+    },
+    {
+      "id": "tracking",
+      "name": "Live tracking",
+      "kind": "WebSocket service",
+      "in": "delivery"
+    },
+    {
+      "id": "cards",
+      "name": "Card processor",
+      "kind": "Stripe",
+      "in": "outside"
+    },
+    {
+      "id": "sms",
+      "name": "Text messages",
+      "kind": "Twilio",
+      "in": "outside"
+    },
+    {
+      "id": "maps",
+      "name": "Road map data",
+      "kind": "Mapbox",
+      "in": "outside"
+    }
+  ],
+  "links": [
+    {
+      "from": "web",
+      "to": "gateway",
+      "tone": "accent"
+    },
+    {
+      "from": "mobile",
+      "to": "gateway",
+      "tone": "accent"
+    },
+    {
+      "from": "gateway",
+      "to": "search",
+      "label": "queries"
+    },
+    {
+      "from": "gateway",
+      "to": "basket",
+      "tone": "accent"
+    },
+    {
+      "from": "search",
+      "to": "stock"
+    },
+    {
+      "from": "basket",
+      "to": "slots",
+      "label": "books a slot"
+    },
+    {
+      "from": "basket",
+      "to": "order",
+      "label": "checkout",
+      "tone": "accent"
+    },
+    {
+      "from": "order",
+      "to": "payment",
+      "label": "charge"
+    },
+    {
+      "from": "payment",
+      "to": "fraud"
+    },
+    {
+      "from": "payment",
+      "to": "cards"
+    },
+    {
+      "from": "order",
+      "to": "orderdb",
+      "label": "writes"
+    },
+    {
+      "from": "order",
+      "to": "events",
+      "label": "publishes",
+      "tone": "accent"
+    },
+    {
+      "from": "events",
+      "to": "planner",
+      "tone": "accent",
+      "label": "new order"
+    },
+    {
+      "from": "events",
+      "to": "routes",
+      "tone": "accent",
+      "label": "new order"
+    },
+    {
+      "from": "planner",
+      "to": "picker",
+      "label": "pick lists"
+    },
+    {
+      "from": "picker",
+      "to": "stock",
+      "label": "takes off stock"
+    },
+    {
+      "from": "picker",
+      "to": "subs"
+    },
+    {
+      "from": "routes",
+      "to": "maps"
+    },
+    {
+      "from": "routes",
+      "to": "driver",
+      "label": "route stops"
+    },
+    {
+      "from": "driver",
+      "to": "tracking",
+      "label": "location"
+    },
+    {
+      "from": "tracking",
+      "to": "sms",
+      "label": "ETA texts"
+    },
+    {
+      "from": "slots",
+      "to": "routes"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liggi/figkit",
-  "version": "0.5.0",
+  "version": "0.6.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",
@@ -34,6 +34,7 @@
     "agents"
   ],
   "dependencies": {
+    "@dagrejs/dagre": "^3.1.3",
     "@fontsource/geist-mono": "^5.3.0",
     "@fontsource/geist-sans": "^5.3.0",
     "@fontsource/newsreader": "^5.3.0",

package/runtime/fig.css

@@ -313,3 +313,20 @@ fig-bars.has-ref .fb-range.accent { --tone: var(--ink); }
 /* 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; }
+
+/* ---------- map: a whole system, parts in subsystem regions (a spec of type "map"), laid out by dagre and packed by figkit ---------- */
+.fig .map { position: relative; }
+.fig .map > .map-part, .fig .map-region > .map-part { position: absolute; max-width: 260px; min-width: 120px; padding: 10px 14px; gap: 2px; }
+.fig .map-part > h3 { font-size: var(--body); line-height: 1.2; }
+.fig .map-part > p { font-size: var(--small); white-space: nowrap; }
+.fig .map-region { position: absolute; display: block; padding: 0; border: 0; border-radius: 14px; background: color-mix(in srgb, var(--ink) 4%, var(--paper)); box-shadow: inset 0 0 0 1px var(--hair); }
+.fig .map-region > .mp-head { position: absolute; top: 14px; left: 20px; display: flex; flex-direction: column; gap: 2px; white-space: nowrap; }
+.fig .map-region > .mp-head > h2 { font-family: var(--serif); font-size: calc(var(--h) * 1.35); font-weight: 400; line-height: 1.1; color: var(--ink); }
+.fig .map > svg.map-wires { position: absolute; inset: 0; pointer-events: none; overflow: visible; }
+.fig .map .map-label { padding: 0 4px; line-height: 1.25; }
+.fig .map-overview > .map-sub { max-width: 230px; min-width: 150px; }
+.fig .map-sub > ul { list-style: none; margin: 6px 0 0; padding: 0; display: flex; flex-direction: column; gap: 1px; }
+.fig .map-sub > ul li { font-size: var(--small); color: var(--muted); }
+.fig .map-sub > .mp-count { color: var(--soft); }
+/* A map's link label outlined, so a line visibly runs into it rather than stopping short of a floating word. */
+.fig:has(.map) .fig-wire-label { box-shadow: inset 0 0 0 1px var(--hair); }

package/runtime/fig.js

@@ -107,6 +107,11 @@
   function routeOrtho(A, B, obs, arrow, used, W, H) {
     const hard = obs.map((o) => grow(o.r, 3)), soft = obs.map((o) => grow(o.r, M - 1));
     const others = obs.filter((o) => o.el !== A.el && o.el !== B.el).map((o) => grow(o.r, 3));
+    // On a map, a line running along a region's border reads as part of the border, so a step beside one costs more.
+    const borders = [...root().querySelectorAll('.map-region')].map(rectOf);
+    const hugs = (x1, y1, x2, y2) => borders.some((r) => (y1 === y2
+      ? Math.min(Math.abs(y1 - r.y), Math.abs(y1 - r.y - r.h)) < 16 && Math.max(x1, x2) > r.x && Math.min(x1, x2) < r.x + r.w
+      : Math.min(Math.abs(x1 - r.x), Math.abs(x1 - r.x - r.w)) < 16 && Math.max(y1, y2) > r.y && Math.min(y1, y2) < r.y + r.h));
     const clear = (x1, y1, x2, y2) => {
       const seg = { x: Math.min(x1, x2) - 0.5, y: Math.min(y1, y2) - 0.5, w: Math.abs(x2 - x1) + 1, h: Math.abs(y2 - y1) + 1 };
       return !others.some((r) => Math.min(seg.x + seg.w, r.x + r.w) > Math.max(seg.x, r.x) && Math.min(seg.y + seg.h, r.y + r.h) > Math.max(seg.y, r.y));
@@ -144,7 +149,8 @@
     }
     add(xs, 14, 'edge'); add(xs, W - 14, 'edge'); add(ys, 14, 'edge'); add(ys, H - 14, 'edge');
     const pad = parseFloat(getComputedStyle(root()).paddingLeft) || 0;
-    if (pad > 14) { add(xs, pad, 'mid'); add(xs, W - pad, 'mid'); }
+    // A map's regions start at the padding, so a line there would run along their edges.
+    if (pad > 14 && !root().querySelector('.map')) { add(xs, pad, 'mid'); add(xs, W - pad, 'mid'); }
     for (const p of [...pa, ...pb]) { add(xs, p.sx, 'mid'); add(ys, p.sy, 'mid'); add(xs, p.x, 'mid'); add(ys, p.y, 'mid'); }
     const X = [...xs.keys()].sort((a, b) => a - b), Y = [...ys.keys()].sort((a, b) => a - b);
     const NX = X.length, NY = Y.length;
@@ -156,6 +162,8 @@
       for (const r of soft) if (inside(r, x, y)) return 5;
       return 1;
     };
+    // On a map, lines run a long way side by side between regions; closer than 24px apart they cannot be told apart.
+    const near = borders.length ? 24 : 10;
     const usedCost = (x1, y1, x2, y2) => {
       let k = 1, plus = 0;
       const horiz = y1 === y2;
@@ -163,17 +171,19 @@
         const uh = u.y1 === u.y2;
         if (uh === horiz) {
           const off = horiz ? Math.abs(u.y1 - y1) : Math.abs(u.x1 - x1);
-          if (off >= 10) continue;
+          if (off >= near) continue;
           const lo = horiz ? Math.max(Math.min(x1, x2), Math.min(u.x1, u.x2)) : Math.max(Math.min(y1, y2), Math.min(u.y1, u.y2));
           const hi = horiz ? Math.min(Math.max(x1, x2), Math.max(u.x1, u.x2)) : Math.min(Math.max(y1, y2), Math.max(u.y1, u.y2));
-          if (hi - lo <= 0.5) { if (arrow.ref && off < 0.5 && hi - lo > -160 && !bus(u)) plus += 400; continue; }
-          if (off < 0.5 && bus(u)) k = Math.min(k, 0.85); else k = Math.max(k, arrow.ref ? 12 : 4);
+          // Carrying straight on where another line stops reads as that line going on; for the highlighted path, as the path going somewhere it doesn't.
+          if (hi - lo <= 0.5) { if ((arrow.ref || (borders.length && u.tone === 'accent' && arrow.tone !== 'accent')) && off < 0.5 && hi - lo > -160 && !bus(u)) plus += 400; continue; }
+          if (off < 0.5 && bus(u)) k = Math.min(k, 0.85); else k = Math.max(k, arrow.ref || (borders.length && u.tone === 'accent' && arrow.tone !== 'accent') ? 12 : 4);
         } else if (!bus(u)) {
           const cx = horiz ? u.x1 : x1, cy = horiz ? y1 : u.y1;
           // Strictly inside this step, or at its far end: two lines that meet on a grid point cross there too.
           const onMe = horiz ? (cx > Math.min(x1, x2) && cx < Math.max(x1, x2)) || cx === x2 : (cy > Math.min(y1, y2) && cy < Math.max(y1, y2)) || cy === y2;
           const onU = horiz ? cy > Math.min(u.y1, u.y2) && cy < Math.max(u.y1, u.y2) : cx > Math.min(u.x1, u.x2) && cx < Math.max(u.x1, u.x2);
-          if (onMe && onU) plus += arrow.ref ? 1500 : 70;
+          // On a map, a grey line crossing the highlighted path breaks the run the reader follows, so it goes round.
+          if (onMe && onU) plus += arrow.ref ? 1500 : borders.length && u.tone === 'accent' && arrow.tone !== 'accent' ? 900 : 70;
         }
       }
       return [k, plus];
@@ -210,8 +220,9 @@
         const jx = ix + VEC[nd][0], jy = iy + VEC[nd][1];
         if (jx < 0 || jy < 0 || jx >= NX || jy >= NY) continue;
         const x1 = X[ix], y1 = Y[iy], x2 = X[jx], y2 = Y[jy];
-        const m = mult((x1 + x2) / 2, (y1 + y2) / 2);
+        let m = mult((x1 + x2) / 2, (y1 + y2) / 2);
         if (m === Infinity) continue;
+        if (borders.length && hugs(x1, y1, x2, y2)) m *= 3;
         const [k, plus] = usedCost(x1, y1, x2, y2);
         const len = Math.abs(x2 - x1) + Math.abs(y2 - y1);
         const cost = c + len * m * k * (VEC[nd][0] === 0 ? kx[ix] : ky[iy]) + plus + (nd === d ? 0 : BEND);
@@ -367,7 +378,7 @@
       const attrs = { d: pathD, fill: 'none', stroke: color, 'stroke-width': weight, 'stroke-linecap': 'round' };
       if (dash) attrs['stroke-dasharray'] = dash;
       svgEl('path', attrs, svg);
-      fig.wires.push({ from, to, pts, mode, ref });
+      fig.wires.push({ from, to, pts, mode, ref, tone });
 
       const text = ref ? '' : tag.getAttribute('label') ?? tag.textContent.trim();
       if (text) labels.push({ text, sub: tag.getAttribute('sub'), tone, color, pts, at: labelAt, want: tag.getAttribute('label-at'), from, to });
@@ -376,6 +387,49 @@
   }
 
   /** Pairs of drawn lines that cross. Arrows from one box, or into one box, share a trunk, so meeting is not crossing. */
+  /** Pairs of lines that run along each other on the same track, so the eye cannot tell which goes where. */
+  function overlapPairs() {
+    const segs = (fig.wires ?? []).filter((w) => w.mode !== 'curve').flatMap((w) => w.pts.slice(1).map((b, i) => ({ w, a: w.pts[i], b })));
+    const out = [];
+    for (let i = 0; i < segs.length; i++) for (let j = i + 1; j < segs.length; j++) {
+      const s = segs[i], t = segs[j];
+      if (s.w === t.w || s.w.from === t.w.from || s.w.to === t.w.to) continue;
+      const sh = s.a[1] === s.b[1], th = t.a[1] === t.b[1];
+      if (sh !== th) continue;
+      const k = sh ? 1 : 0, q = 1 - k;
+      if (Math.abs(s.a[k] - t.a[k]) >= 3) continue;
+      const lo = Math.max(Math.min(s.a[q], s.b[q]), Math.min(t.a[q], t.b[q])), hi = Math.min(Math.max(s.a[q], s.b[q]), Math.max(t.a[q], t.b[q]));
+      if (hi - lo > 4 && !out.some(([u, w]) => u === s.w && w === t.w)) out.push([s.w, t.w]);
+    }
+    return out;
+  }
+
+  /**
+   * On a map, how the highlighted path reads: grey links crossing it, and each run along it (from a highlighted link
+   * no other highlighted link feeds, to one that feeds none) that doubles back on itself, left then right or down then up.
+   */
+  function accentStats() {
+    const ws = (fig.wires ?? []).filter((w) => w.mode !== 'curve'), hot = ws.filter((w) => w.tone === 'accent');
+    const crossed = crossingPairs().filter(([u, w]) => (u.tone === 'accent') !== (w.tone === 'accent'));
+    const runs = [];
+    const walk = (w, path) => {
+      const next = hot.filter((n) => n.from === w.to && !path.includes(n));
+      if (!next.length) runs.push([...path, w]);
+      for (const n of next) walk(n, [...path, w]);
+    };
+    for (const w of hot) if (!hot.some((u) => u.to === w.from)) walk(w, []);
+    const back = runs.filter((run) => {
+      const seen = new Set();
+      for (const w of run) for (let i = 1; i < w.pts.length; i++) {
+        const dx = w.pts[i][0] - w.pts[i - 1][0], dy = w.pts[i][1] - w.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'));
+    });
+    return { crossed, back, runs, any: hot.length > 0 };
+  }
+
   function crossingPairs() {
     const segs = (fig.wires ?? []).filter((w) => w.mode !== 'curve').flatMap((w) => w.pts.slice(1).map((b, i) => ({ w, a: w.pts[i], b })));
     const out = [];
@@ -460,8 +514,10 @@
   function placeLabels(labels, obs) {
     const R = root(), W = R.offsetWidth, H = R.offsetHeight;
     const placed = [], fails = [];
+    const onLine = !!R.querySelector('.map-region');
+    const heads = [...R.querySelectorAll('.mp-head')].map(rectOf);
     const segsOf = (pts) => pts.slice(1).map((b, i) => ({ a: pts[i], b, len: Math.hypot(b[0] - pts[i][0], b[1] - pts[i][1]) }));
-    const wireHit = (r, skip) => (fig.wires ?? []).some((w) => segsOf(w.pts).some((s) => s !== skip && !(skip && s.a === skip.a && s.b === skip.b)
+    const wireHit = (r, skip, own) => (fig.wires ?? []).some((w) => w.pts !== own && segsOf(w.pts).some((s) => s !== skip && !(skip && s.a === skip.a && s.b === skip.b)
       && Math.min(Math.max(s.a[0], s.b[0]), r.x + r.w) >= Math.max(Math.min(s.a[0], s.b[0]), r.x) && Math.min(Math.max(s.a[1], s.b[1]), r.y + r.h) >= Math.max(Math.min(s.a[1], s.b[1]), r.y)));
     for (const L of labels) {
       const lab = document.createElement('div');
@@ -492,9 +548,15 @@
         for (const seg of segs) {
           const horiz = seg.a[1] === seg.b[1], mid = [(seg.a[0] + seg.b[0]) / 2, (seg.a[1] + seg.b[1]) / 2];
           const real = segsOf(mine ? mine.pts : L.pts).find((s) => s.a[0] === seg.a[0] && s.a[1] === seg.a[1] && s.b[0] === seg.b[0] && s.b[1] === seg.b[1]);
-          for (const t of [0.5, 0.3, 0.7]) {
+          // On a map, many lines run side by side between regions, so a label beside a line reads as naming its
+          // neighbour: there a label sits only on its own line, moved along it until it is clear.
+          // Clear of the line's ends: a little at a bend or the start, more before the arrowhead on the last segment.
+          const half = (horiz ? w : h) / 2, lastSeg = seg.b === L.pts[L.pts.length - 1], lo = half + 8, hi = seg.len - half - (lastSeg ? 26 : 8), slide = [];
+          if (onLine && hi >= lo) for (let d = 0, mid = (lo + hi) / 2; d <= (hi - lo) / 2; d += 4) slide.push((mid - d) / seg.len, (mid + d) / seg.len);
+          for (const t of onLine ? slide : [0.5, 0.3, 0.7]) {
             const c = [seg.a[0] + (seg.b[0] - seg.a[0]) * t, seg.a[1] + (seg.b[1] - seg.a[1]) * t];
-            if (seg.len >= (horiz ? w : h) + 36) cands.push({ c, on: real });
+            if (onLine || seg.len >= (horiz ? w : h) + 36) cands.push({ c, on: real });
+            if (onLine) continue;
             if (horiz) cands.push({ c: [c[0], c[1] - h / 2 - 7] }, { c: [c[0], c[1] + h / 2 + 7] });
             else cands.push({ c: [c[0] + w / 2 + 9, c[1]] }, { c: [c[0] - w / 2 - 9, c[1]] });
           }
@@ -506,11 +568,19 @@
         const r = rectAt(cand.c);
         if (r.x < 8 || r.y < 8 || r.x + r.w > W - 8 || r.y + r.h > H - 8) return false;
         const within = (g) => r.x > g.x + 4 && r.y > g.y + 4 && r.x + r.w < g.x + g.w - 4 && r.y + r.h < g.y + g.h - 4;
-        if (obs.some((o) => (o.el.classList.contains('group') ? overlap(grow(r, 3), o.r) && !within(o.r) : hits({ r: grow(r, 3) }, o)))) return false;
-        if (placed.some((p) => overlap(grow(r, 4), p))) return false;
-        return !wireHit(grow(r, 2), cand.on);
+        // A map's region is a tinted area: a label sits wholly inside it or wholly outside, never across its edge.
+        if (obs.some((o) => (o.el.classList.contains('map-region') ? overlap(grow(r, 8), o.r) && !(r.x > o.r.x + 12 && r.y > o.r.y + 12 && r.x + r.w < o.r.x + o.r.w - 12 && r.y + r.h < o.r.y + o.r.h - 12) : o.el.classList.contains('group') ? overlap(grow(r, 3), o.r) && !within(o.r) : hits({ r: grow(r, 3) }, o)))) return false;
+        if (placed.some((p) => overlap(grow(r, 4), p)) || heads.some((g) => overlap(grow(r, 8), g))) return false;
+        return onLine ? !wireHit(grow(r, 8), null, L.pts) : !wireHit(grow(r, 2), cand.on);
       };
-      const pick = cands.find(free) ?? (fails.push({ from: L.from, to: L.to, w, h }), cands[0]);
+      let pick = cands.find(free);
+      if (!pick) {
+        fails.push({ from: L.from, to: L.to, w, h });
+        lab.dataset.stuck = '1';
+        // With no clear place, the label still goes on its own line, where check() reports it.
+        const long = segsOf(L.pts).sort((p, q) => q.len - p.len)[0];
+        pick = cands[0] ?? { c: [(long.a[0] + long.b[0]) / 2, (long.a[1] + long.b[1]) / 2] };
+      }
       lab.style.left = pick.c[0] + 'px';
       lab.style.top = pick.c[1] + 'px';
       placed.push(rectAt(pick.c));
@@ -666,6 +736,15 @@
       if (reach > 1.02) P.push(`The text of decision ${name(d)} does not fit inside its diamond: shorten it or give the diamond a min-width.`);
     }
 
+    // On a map, a label names the line it sits on: its centre must lie on a segment of its own arrow, clear of the rest.
+    if (R.querySelector('.map-region')) for (const lab of R.querySelectorAll('.fig-wire-label')) {
+      const [from, to] = lab.dataset.arrow.split(' → '), w = (fig.wires ?? []).find((x) => x.from === from && x.to === to);
+      const r = rectOf(lab), cx = r.x + r.w / 2, cy = r.y + r.h / 2;
+      const on = w && w.pts.slice(1).some((b, i) => { const a = w.pts[i]; return Math.abs(a[0] - b[0]) < 0.5 ? Math.abs(cx - a[0]) <= 3 && cy >= Math.min(a[1], b[1]) && cy <= Math.max(a[1], b[1]) : Math.abs(cy - a[1]) <= 3 && cx >= Math.min(a[0], b[0]) && cx <= Math.max(a[0], b[0]); });
+      if (!on) P.push(`The label "${lab.firstChild.textContent}" of arrow ${lab.dataset.arrow} is not on its own line.`);
+      else if (lab.dataset.stuck) P.push(`The label "${lab.firstChild.textContent}" of arrow ${lab.dataset.arrow} has no clear place on its own line: other lines or boxes cover every spot. Drop the label, or shorten it.`);
+    }
+
     // Boxes and labels that collide.
     for (let i = 0; i < obs.length; i++) for (let j = i + 1; j < obs.length; j++) {
       const a = obs[i], b = obs[j];
@@ -690,8 +769,24 @@
         if (hit) P.push(`Arrow ${w.from} → ${w.to} runs through ${name(o.el)}.`);
       }
     }
+    if (R.querySelector('.map')) {
+      const along = overlapPairs().map(([u, w]) => `${u.from} → ${u.to} and ${w.from} → ${w.to}`);
+      if (along.length) P.push(`Links run on top of each other: ${along.join('; ')}. figkit found no arrangement that keeps them apart; leave out a link the question does not need.`);
+    }
     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')
+    // A map of many links crosses some at right angles, which still reads full screen; up to one crossing per 2 links is
+    // allowed and named. Real systems of 24 parts and 30 links cross about 10 times; past 30 parts, 28 times or more.
+    const allowed = R.querySelector('.map') ? Math.floor((fig.wires ?? []).length / 2) : 0;
+    if (R.querySelector('.map')) {
+      // The highlighted path is what the map is about: it reads as one run, and grey links crossing it are named.
+      const st = accentStats(), arrow = (w) => `${w.from} → ${w.to}`;
+      if (st.back.length) P.push(`The highlighted path turns back on itself: ${st.back.map((run) => [run[0].from, ...run.map((w) => w.to)].join(' → ')).join('; ')}. figkit could not lay it out as one run; highlight only the links the question follows, in one direction.`);
+      const grey = [...new Set(st.crossed.map(([u, w]) => (u.tone === 'accent' ? arrow(w) : arrow(u))))];
+      if (grey.length) fig.notes = [...(fig.notes ?? []), `${grey.length} grey link${grey.length === 1 ? ' crosses' : 's cross'} the highlighted path: ${grey.join('; ')}.`];
+    }
+    if (crossings.size && crossings.size <= allowed) fig.notes = [...(fig.notes ?? []), `${crossings.size} crossing${crossings.size === 1 ? '' : 's'} of links (a map of ${(fig.wires ?? []).length} links is allowed ${allowed}): ${[...crossings].join('; ')}.`];
+    else if (crossings.size && R.querySelector('.map')) P.push(`Links cross ${crossings.size} times; a map of ${(fig.wires ?? []).length} links holds at most ${allowed}: ${[...crossings].join('; ')}. Leave out links the question does not need, or move a part to the subsystem it talks to most.`);
+    else 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.`);
@@ -704,6 +799,7 @@
       if (a.el.contains(b.el) || b.el.contains(a.el)) continue;
       // Records share a top edge in their row; their heights follow their fields, which figkit placed, not the author.
       if (a.el.classList.contains('record') && b.el.classList.contains('record')) continue;
+      if (a.el.closest('.map') && b.el.closest('.map')) continue;
       const edges = [['left edges', a.r.x, b.r.x], ['right edges', a.r.x + a.r.w, b.r.x + b.r.w], ['top edges', a.r.y, b.r.y], ['bottom edges', a.r.y + a.r.h, b.r.y + b.r.h]];
       for (const [what, u, v] of edges) { const d = Math.abs(u - v); if (d > 0.75 && d <= 6) near.push(`${name(a.el)} and ${name(b.el)} (${what}, ${d.toFixed(0)}px apart)`); }
     }
@@ -717,7 +813,9 @@
     const nodes = R.querySelectorAll('.node:not(.bare), .decision').length, arrows = (fig.wires ?? []).length;
     // 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 };
+    // A map is many parts laid out by figkit, so it holds what the map spec allows (map-spec.js), not a detail figure's 18.
+    const map = !!R.querySelector('.map');
+    const budget = map ? { words: 320, nodes: 24, arrows: 30 } : 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.`);
@@ -753,10 +851,40 @@
       await Promise.all([...document.images].map((img) => (img.complete ? null : new Promise((res) => { img.onload = img.onerror = res; }))));
       for (const d of root().querySelectorAll('.decision')) { const h = Math.max(...[...d.children].map((k) => k.offsetHeight), 20); d.style.paddingBlock = Math.max(30, Math.round(h * 0.7)) + 'px'; }
       const spec = document.getElementById('figkit-spec');
-      if (spec) window.figkitViz.drawSpec(JSON.parse(spec.textContent), root());
-      else { buildSplits(); buildBars(); }
+      const drawn = spec ? window.figkitViz.drawSpec(JSON.parse(spec.textContent), root()) : (buildSplits(), buildBars(), null);
+      if (drawn?.ready) await drawn.ready;
       for (const job of fig.queue) job();
       await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+      // A map offers a few arrangements of its regions: each is routed, and the one whose arrows cross least is kept.
+      if (fig.mapTry?.length > 1) {
+        let best = null;
+        for (const [i, apply] of fig.mapTry.entries()) {
+          apply();
+          await new Promise((r) => requestAnimationFrame(r));
+          const before = fig.problems.length;
+          const fails = drawArrows().length, crossings = crossingPairs().length + 2 * overlapPairs().length, lost = fig.problems.length - before;
+          // The checks themselves, so an arrangement whose arrows run through labels or boxes loses.
+          const notes = fig.notes;
+          check();
+          const flagged = fig.problems.length - before - lost;
+          fig.problems.length = before;
+          fig.notes = notes;
+          // The highlighted path should read as one run: grey links crossing it, and a run that doubles back, cost most.
+          const st = accentStats();
+          // And, as when the regions were packed, a map read larger on a full screen is better.
+          // With a highlighted path the arrangements differ a lot in size: one read larger on a full screen is better.
+          const read = st.any ? Math.min(1440 / Math.max(root().offsetWidth, 960), 860 / root().offsetHeight) : 1;
+          // Those arrangements are also built for the path rather than packed, so they vary more in what the checks refuse,
+          // and a refused figure is worse than any crossing: there, each problem counts double.
+          const k = st.any ? 2 : 1;
+          // And long detours, which those arrangements make more of, are lines the reader must trace further.
+          const far = st.any ? (fig.wires ?? []).reduce((t, w) => t + w.pts.slice(1).reduce((u, b, j) => u + Math.abs(b[0] - w.pts[j][0]) + Math.abs(b[1] - w.pts[j][1]), 0), 0) / 1000 : 0;
+          const score = crossings + k * (2 * fails + 3 * lost + 4 * flagged) + 3 * st.crossed.length + 8 * st.back.length - 8 * Math.log(read) + far + i * 0.1;
+          if (!best || score < best.score) best = { score, apply };
+        }
+        best.apply();
+        await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+      }
       // A label with no free place opens the gap it needs, then everything is drawn again.
       const tried = new Map();
       for (let i = 0; ; i++) {

package/viz/draw.js

@@ -2,6 +2,7 @@
 import * as Plot from '@observablehq/plot';
 import { drawSequence } from './sequence.js';
 import { drawStates } from './states.js';
+import { drawMap } from './map.js';
 const NS = 'http://www.w3.org/2000/svg';
 const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 
@@ -363,6 +364,18 @@ export function drawSpec(spec, main) {
     if (spec.source) { const footer = document.createElement('footer'); footer.innerHTML = `<p>${esc(spec.source)}</p>`; main.append(footer); }
     return { chart, draw: () => {} };
   }
+  if (spec.type === 'map') {
+    if (main.classList.contains('phone')) {
+      const key = document.createElement('p');
+      key.className = 'read mp-key';
+      key.textContent = 'Each box is a subsystem; numbers count the links between their parts.';
+      header.appendChild(key);
+    }
+    main.append(header);
+    const footer = spec.source ? Object.assign(document.createElement('footer'), { innerHTML: `<p>${esc(spec.source)}</p>` }) : null;
+    const ready = drawMap(spec, main).then((chart) => { if (footer) main.append(footer); return chart; });
+    return { chart: null, draw: () => {}, ready };
+  }
   if (spec.type === 'sequence') {
     main.append(header);
     const chart = drawSequence(spec, main);