umlimator 0.15.0 → 0.16.0

package/README.md

@@ -65,7 +65,7 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
 npm install umlimator
 ```
 
-Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.15.0"`. npm 12 refuses git
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.16.0"`. npm 12 refuses git
 dependencies unless the project opts in, so that also needs `allow-git=root` in the `.npmrc` next to `package.json`.
 
 ## Embed
@@ -299,7 +299,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: zintaen/umlimator@v0.15.0
+      - uses: zintaen/umlimator@v0.16.0
         with:
           models: "docs/*.json"   # optional: where the models are (default: every .json that is a map model)
 ```
@@ -394,7 +394,7 @@ umlimator_mcp.py             the MCP server that `umlimator.py mcp` runs
 action.yml                   the diff Action: what a pull request changes in its maps, posted on it
 lib/                         the module (umlimator.js), its types, the default theme, <umlimator-map> and the docs plugins
 engine/                      the page templates the CLI inlines the module into; the upstream renderer and schema
-docs/                        the module's API and the editing design
+docs/                        the module's API and the editing design; docs/diagrams/: the plan for 28 diagram types (not built yet)
 tests/, bench/               tests, benchmark models and results
 icons/                       line icons and the logo manifest (sources and hashes only)
 examples/                    made-up systems: models, host pages and a Node script (live: zintaen.github.io/umlimator)

package/lib/umlimator.js

@@ -340,7 +340,8 @@ const STYLES = `
     .ptabs, .ptablist { flex-wrap: wrap; } .pnav { display: none; } .ptab { padding: 7px 8px; }
     .detail-bullets li { white-space: normal; overflow: visible; }
     .exs { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 10px; }
-    .m-legend, .hint { display: none; }
+    .m-legend, .hint:not(.msg) { display: none; } /* a message shows, as a toast (issue 134) */
+    .hint.msg { left: 12px; right: 12px; bottom: 12px; height: auto; min-height: 28px; padding: 6px 12px; white-space: normal; text-align: center; border: 1px solid var(--um-border); border-radius: 10px; box-shadow: var(--um-shadow); }
   }
   /* render()'s pieces (#99), laid out as the page lays them out: the views list left of the map (☰ or O), the details under
      it, the legend and the hint line over it; while a story is told, the legend gives way to its caption bar */
@@ -566,6 +567,9 @@ const noteOf = x => NOTATIONS.includes(x) ? x : null;
 function cardLook(n, notation, hint, ports) {
   const sh = shapeOf(n, notation); if (sh === 'box') return null;
   const S = SHAPE[sh], L = { ...n, sh, S, portTop: ports ? Math.min(ports.L, ports.R) : Infinity, portL: ports ? ports.L : Infinity }, tabs = mapTabs(n), spans = []; let tx = n.x + 12;
+  // a step keeps 16 px above the highest line into the left side (svgOf): where that is above a person's or robot's shoulder,
+  // the shoulder comes up under it, 5 px below its middle (it floated 4 px above the shoulder)
+  if (n.step && S.head && L.portL - 16 < S.tabY(L)) L.portTop = Math.min(L.portTop, Math.max(n.y, L.portL - 16) + 6);
   tabs.forEach(t => { spans.push([tx, tx + t.w]); tx += t.w + 4; });
   L.tabEnd = tabs.length ? tx - 2 : 0;
   const right = []; if (hint) right.push([n.x + n.w - 44, n.x + n.w - 8]);
@@ -857,6 +861,9 @@ const mapNodeW = n => {
 function layoutGraph(dg, map) {
   let g = layoutPass(dg, map, null);
   if (g.room) { const g2 = layoutPass(dg, map, g.room, true); g2.ms.probe = g.ms.probe; g = g2; }
+  // a label with no room where it fits: the view laid out again with room for it, kept with fewer issues and labels cut short
+  if (g.labelRoom) { const g2 = layoutPass(dg, map, g.labelRoom, true), cut = h => h.edges.filter(e => (e.label || e.step != null) && (!e.lbl || e.lbl.short)).length;
+    delete g.labelRoom; if (routeAudit(g2, '').length + cut(g2) < routeAudit(g, '').length + cut(g)) g = g2; }
   // two lines that still cross: one takes another side, and the view is laid out so once more, kept if it has fewer issues. A
   // line that closes a loop leaves its source on the far side, out round the map as a loop under the boxes does, and still comes
   // in on its target's near side (clinic's reminder, from the SMS gateway under Patient records, crossed the line into Patient
@@ -868,11 +875,49 @@ function layoutGraph(dg, map) {
   pairs.forEach(p => p.forEach(e => { if (e.back && !e.fixed && !e.fromSide) out.set(e.from + '>' + e.to, ['fromSide', far[e.fs]]); }));
   pairs.forEach(p => { const e = p.filter(e => !e.back && !e.fixed && !e.toSide && /[LR]/.test(e.ts) && dy(e)).sort((a, b) => Math.abs(dy(b)) - Math.abs(dy(a)))[0];
     if (e && !p.some(o => out.has(o.from + '>' + o.to))) out.set(e.from + '>' + e.to, ['toSide', dy(e) > 0 ? 'bottom' : 'top']); });
-  if (!out.size) return g;
-  const g2 = layoutGraph({ ...dg, flipped: true, edges: dg.edges.map(e => out.has(e.from + '>' + e.to) ? { ...e, [out.get(e.from + '>' + e.to)[0]]: out.get(e.from + '>' + e.to)[1] } : e) }, map);
-  return routeAudit(g2, '').length < routeAudit(g, '').length ? g2 : g;
+  let best = g, bestDg = dg, n = pairs.length ? routeAudit(g, '').length : 0;
+  const attempt = d => { const h = layoutGraph({ ...d, flipped: true }, map), k = routeAudit(h, '').length; if (k < n) { best = h; bestDg = d; n = k; } };
+  if (out.size) attempt({ ...dg, edges: dg.edges.map(e => out.has(e.from + '>' + e.to) ? { ...e, [out.get(e.from + '>' + e.to)[0]]: out.get(e.from + '>' + e.to)[1] } : e) });
+  // two lines that still cross where neither can take another side without crossing the other (two cards that each feed the
+  // same two cards, as web and admin feed kit and api-client in r15's monorepo, issue 111): one of them goes round the outside,
+  // out its source's far side and into its target's top (bottom) from beyond. Of the first two crossing pairs, the lines from
+  // two cards that both feed both their targets are tried first, then the pairs' own lines, each on its own (on the layout kept so far,
+  // and on the first), and the best layout kept. ponytail: up to four layouts more, on views of up to 30 cards; r19/plain takes
+  // about four times as long for them, and gains nothing
+  const r2 = [], left = n && best !== g ? routeAudit(best, '', null, r2).flatMap((s, k) => s.endsWith(' cross') ? [r2[k]] : []) : pairs;
+  const feeds = (s, t) => best.edges.some(o => o.s === s && o.t === t), both = ([a, b]) => { const k = a.t !== b.t && best.edges.filter(o => [a.t, b.t].includes(o.t) && feeds(o.s, a.t) && feeds(o.s, b.t)); return k && k.length >= 4 ? k : []; };
+  const round = [...new Set([...left.slice(0, 2).flatMap(both), ...left.slice(0, 2).flat()])].filter(e => !e.back && !e.fixed && !e.fromSide && !e.toSide && /[LR]/.test(e.fs) && /[LR]/.test(e.ts));
+  let tries = 4;
+  round.forEach(e => { const side = { fromSide: e.fs === 'R' ? 'left' : 'right', toSide: dy(e) >= 0 ? 'top' : 'bottom' };
+    [...new Set([bestDg, dg])].forEach(d => { if (n && tries-- > 0) attempt({ ...d, edges: d.edges.map(x => x.from === e.from && x.to === e.to ? { ...x, ...side } : x) }); }); });
+  // fan-in (issue 149): lines into a card that six or more lines come into still cross. One line of such a pair at a time, of
+  // the first pair first, goes round the outside (out its source's far side, or into its target's), or its target moves to
+  // the foot of its column; a layout with fewer such crossings and no more issues is kept, and the search goes on from it; the
+  // view keeps the one found only when it has fewer issues than at the start.
+  // r19's logger: boxed 5 → 1, plain 6 → 3. ponytail: 14 layouts more at most, on views of up to 30 cards; a crossing-aware
+  // placement would reach plain's last ones (search beside db)
+  const fan = {}; best.edges.forEach(e => { if (!e.back) fan[e.to] = (fan[e.to] || 0) + 1; });
+  if (map && dg.fan && !dg.quick && !dg.flipped && dg.nodes.length <= 30 && Object.values(fan).some(k => k >= 6)) {
+    const audit = h => { const r = [], is = routeAudit(h, '', null, r), hot = r.filter((p, k) => / (cross|share a line)$/.test(is[k]) && p.some(e => fan[e.to] >= 6));
+      return { hot, n: is.length }; };
+    const far = { L: 'right', R: 'left', T: 'bottom', B: 'top' }, tried = new Set(), start = audit(best), g0 = [best, bestDg], lined = new Set(dg.edges.flatMap(e => [e.from, e.to]));
+    let cur = start, left = 14;
+    const ways = e => [['fromSide', far[e.fs]], ['toSide', far[e.ts]], ['foot', e.to]].map(([k, s]) => {
+      if (k !== 'foot') return !e[k] && s && { key: e.from + '>' + e.to + k, d: { ...bestDg, edges: bestDg.edges.map(x => x.from === e.from && x.to === e.to ? { ...x, [k]: s } : x) } };
+      const nodes = bestDg.nodes.map(n => ({ ...n })), me = nodes.find(n => n.id === s), col = nodes.filter(n => n !== me && n.col === me.col), rows = col.filter(n => lined.has(n.id)).map(n => n.row);
+      if (!rows.length || me.row > Math.max(...rows)) return null; const r = Math.max(...rows) + 1;
+      col.forEach(n => { if (!lined.has(n.id) && n.row > r - 1) n.row++; }); me.row = r; // cards with no line stay under it
+      return { key: 'foot ' + s, d: { ...bestDg, nodes } }; });
+    for (let more = true; more && cur.hot.length && left > 0;) { more = false;
+      for (const e of [...new Set(cur.hot.flat())]) { if (more || e.back || e.fixed) continue;
+        for (const w of ways(e)) { if (more || left <= 0 || !w || tried.has(w.key)) continue; tried.add(w.key); left--;
+          const h = layoutGraph({ ...w.d, flipped: true }, map), a = audit(h);
+          if (a.n <= cur.n && (a.hot.length < cur.hot.length || a.hot.length === cur.hot.length && a.n < cur.n)) { best = h; bestDg = w.d; cur = a; more = true; } } } }
+    if (cur.n >= start.n) [best, bestDg] = g0; // kept only with fewer issues
+  }
+  return best;
 }
-function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row: px } }; last: lay out with it, find no more
+function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row: px } } (lx, ly: a label's, past the boxes'); last: lay out with it, find no more
   const __ms = { t: performance.now() }, t0 = __ms.t;
   const CG = dg.gap ? dg.gap : map ? (dg.mainSteps && !dg.containers ? 38 : 66) : CG0, RG = dg.rgap ? dg.rgap : map ? 44 : RG0; // family borders also need clearance between columns
   const NH = dg.nodeH || 64, pitch = NH + RG;
@@ -960,6 +1005,8 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
     Object.entries(wantX).forEach(([k, v]) => { extraX[k] = (extraX[k] || 0) + v; }); Object.entries(wantY).forEach(([k, v]) => { extraY[k] = (extraY[k] || 0) + v; });
     place();
   }
+  // a label's room comes on top of what keeps the boxes apart
+  if (room && (room.lx || room.ly)) { for (const [k, o] of [['lx', extraX], ['ly', extraY]]) Object.entries(room[k] || {}).forEach(([g, v]) => { o[g] = (o[g] || 0) + v; }); place(); }
   // decorations hanging on a node's top/bottom border (kind tab, step badge, ⤢ badge, author name tag):
   // ports keep off them, routes and labels treat the name tag as an obstacle
   if (map) nodes.forEach(n => {
@@ -1007,20 +1054,25 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
   const segHitsRect = (a, b, r) => { const x1 = Math.min(a[0], b[0]), x2 = Math.max(a[0], b[0]), y1 = Math.min(a[1], b[1]), y2 = Math.max(a[1], b[1]); return x2 > r.x && x1 < r.x + r.w && y2 > r.y && y1 < r.y + r.h; };
   const through = (pts, e) => nodes.find(n => n !== e.s && n !== e.t && segsOf(pts).some(([a, b]) => segHitsRect(a, b, { x: n.x + 2, y: n.y + 2, w: n.w - 4, h: n.h - 4 }))); // a card it does not join
   // fixed edges arrive with their route already drawn (the hub comb); the router works around them
-  // a loop back out of a family runs under the frames: out the source's right side, down past every
-  // frame and card it would cut through, left along the bottom, and up into the target's bottom
+  // a loop back out of a family runs under the frames: out the source's right side, down past every frame and card it
+  // would cut through, left along the bottom, and up the gap right of its target into its near side, the lowest port
+  // there (issue 128); where that would cut through a card, up into the target's bottom, as before. Loops into one target
+  // nest: the outer comes up nearer the card, into the lower port.
   const inFam = n => families.filter(f => n.x >= f.x && n.x + n.w <= f.x + f.w && n.y >= f.y && n.y + n.h <= f.y + f.h);
-  edges.filter(e => map && e.back && !e.fixed && (inFam(e.s).length || inFam(e.t).length)).forEach((e, k) => {
+  const unders = edges.filter(e => map && e.back && !e.fixed && (inFam(e.s).length || inFam(e.t).length));
+  unders.forEach((e, k) => {
     // the source's other outgoing wires keep its middle port; the loop leaves lower down
     const { s, t } = e, sy = s.y + s.h / 2 + (edges.some(o => o !== e && o.from === s.id && !o.back) ? s.h / 4 : 0);
     const xr = Math.max(s.x + s.w + 22, ...inFam(s).map(f => f.x + f.w + 14)) + k * 10;
     const tx = t.tag ? Math.max(t.x + 12, (t.x + t.tag.x - 2) / 2) : t.x + t.w / 2, ty = t.y + t.h + (t.kids || t.opens ? 8 : 0);
-    const span = nodes.filter(n => n.x < xr && n.x + n.w > tx), yb = Math.max(...[...inFam(s), ...inFam(t)].map(f => f.y + f.h), ...span.map(n => n.y + n.h + (n.tag ? 22 : 8))) + 24 + k * 10;
-    const pts = [[s.x + s.w, sy], [xr, sy], [xr, yb], [tx, yb], [tx, ty]];
-    if (!through(pts, e)) { e.fixed = pts; e.under = true; } // one that would cut through a card is left to the router
+    const xn = t.x + t.w + 16 + 10 * unders.slice(k + 1).filter(o => o.t === t).length, near = xn < xr;
+    const span = nodes.filter(n => n.x < xr && n.x + n.w > (near ? xn : tx)), yb = Math.max(...[...inFam(s), ...inFam(t)].map(f => f.y + f.h), ...span.map(n => n.y + n.h + (n.tag ? 22 : 8))) + 24 + k * 10;
+    const pts = [[s.x + s.w, sy], [xr, sy], [xr, yb]], up = [[xn, yb], [xn, t.y + t.h / 2], [t.x + t.w, t.y + t.h / 2]], bottom = [[tx, yb], [tx, ty]];
+    if (near && !through([...pts, ...up], e)) { e.fixed = [...pts, ...up]; e.under = k + 1; }
+    else if (!through([...pts, ...bottom], e)) { e.fixed = [...pts, ...bottom]; e.under = true; } // one that would cut through a card is left to the router
   });
   const free = edges.filter(e => !e.fixed);
-  edges.filter(e => e.fixed).forEach(e => { e.pts = e.fixed; e.p1 = e.pts[0]; e.p2 = e.pts[e.pts.length - 1]; e.fs = 'R'; e.ts = e.under ? 'B' : 'L'; e.stubs = []; e.how = e.under ? 'under' : 'comb'; });
+  edges.filter(e => e.fixed).forEach(e => { e.pts = e.fixed; e.p1 = e.pts[0]; e.p2 = e.pts[e.pts.length - 1]; e.fs = 'R'; e.ts = e.under > 0 ? 'R' : e.under ? 'B' : 'L'; e.stubs = []; e.how = e.under ? 'under' : 'comb'; });
   const sides = {};
   const pushSide = (n, side, e, other) => ((sides[n.id + '|' + side] ||= []).push({ e, other, n }));
   free.forEach(e => {
@@ -1052,6 +1104,7 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
     });
   });
   free.forEach(e => { pushSide(e.s, e.fs, e, e.t); pushSide(e.t, e.ts, e, e.s); });
+  edges.filter(e => e.under > 0).forEach(e => pushSide(e.t, 'R', e, e.s)); // a loop under the boxes takes its port with the side's other lines
   const portAt = (it, side, p) => { if (it.n === it.e.s && it.e.fs === side) it.e.p1 = p; else it.e.p2 = p; };
   Object.entries(sides).sort(([, a], [, b]) => !!a[0].n.box - !!b[0].n.box).forEach(([key, list]) => { // cards first: a box's port lines up with them
     const side = key.split('|').pop(), vertical = side === 'L' || side === 'R';
@@ -1077,7 +1130,7 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
     // nearer takes the higher port, since the farther one's line passes under it (b10/overview's Reports 7 took the port
     // under Billing 1's, whose line ran below Reports, and had no way in but round the map)
     const lean = it => Math.atan2(it.other.y + it.other.h / 2 - my, Math.abs(it.other.x + it.other.w / 2 - mx));
-    list.sort((a, b) => vertical ? (a.other.y - b.other.y) || (lean(a) - lean(b)) || ((side === 'R' ? -1 : 1) * (a.other.x - b.other.x)) : turn(a) - turn(b));
+    list.sort((a, b) => vertical ? ((a.e.under || 0) - (b.e.under || 0)) || (a.other.y - b.other.y) || (lean(a) - lean(b)) || ((side === 'R' ? -1 : 1) * (a.other.x - b.other.x)) : turn(a) - turn(b));
     const sp = vertical ? null : sideSpan(n, side);
     const len = vertical ? n.h : sp ? sp[1] - sp[0] : n.w, mid = sp ? (sp[0] + sp[1]) / 2 : n.x + n.w / 2;
     const gap = Math.min(vertical ? 16 : 26, (len * 0.84) / Math.max(1, list.length)), cy = n.y + n.h / 2;
@@ -1088,6 +1141,7 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
       portAt(it, side, p);
     });
   });
+  edges.filter(e => e.under > 0).forEach(e => { const P = e.fixed; e.pts = e.fixed = [...P.slice(0, 4), [P[3][0], e.p2[1]], e.p2]; });
   const C = map ? 16 : 12, STUB = dg.mainSteps ? C : C + 6, SEP = 10, BEND = map ? 60 : 26, CROSS = 900; // maps: 16 px clear of other nodes, few bends
   const OUT = { R: [1, 0], L: [-1, 0], T: [0, -1], B: [0, 1] };
   const nodeRects = nodes.map(n => ({ x: n.x, y: n.y, w: n.w, h: n.h }));
@@ -1255,11 +1309,12 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
   }
   // labels: on the edge's own segment, in free space — never across another route, node, or label
   const placed = [];
-  function placeLabel(e) {
-    if (!e.label && e.step == null) return;
-    const full = map ? fit(e.label || '', 10.5, e.under ? 320 : 440) : fit((e.step != null ? e.step + ' · ' : '') + (e.label || ''), 10, 150);
-    const sub = map && e.label && e.sublabel ? fit(e.sublabel, 9.5, e.under ? 320 : 440) : ''; // a second, smaller line under the label (#44)
-    const tries = [full]; if (e.step != null && e.label && !dg.abs) tries.push(map ? '' : String(e.step));
+  // every spot on e's line where a label of this text fits, best first, at pass 0 (strict), 1 (strict, but it may touch a box
+  // border) or 2 (relaxed)
+  const subOf = (e, text) => map && text && e.sublabel ? fit(e.sublabel, 9.5, e.under ? 320 : 440) : ''; // a second, smaller line under the label (#44)
+  const sizeOf = (e, text, sub = subOf(e, text)) => { const two = !!(text && sub), pill = map && e.step != null;
+    return { two, w: map ? (text ? pillW(text, two && sub) : 0) + (pill ? stepW(e.step) + (text ? 4 : 6) : 0) : textW(text, 10) + 12, hgt: map ? (two ? 32 : 20) : 18 }; };
+  function* fits(e, text, pass) { const relax = pass === 2, sub = subOf(e, text);
     const segs = segsOf(e.pts).map((s, i) => ({ a: s[0], b: s[1], i, l: Math.hypot(s[1][0] - s[0][0], s[1][1] - s[0][1]), h: s[0][1] === s[1][1] }));
     const order = [...segs].sort((p, q) => (q.h - p.h) * 40 + (q.l - p.l));
     // the strict spots along a segment: the middle, a third and a fifth of the way, then those just clear of each card's stub room,
@@ -1270,25 +1325,43 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
         ...[...routed.filter(r => r !== e).map(r => r.pts), e.pts].flatMap(P => segsOf(P).map(([p, q]) => ({ x: Math.min(p[0], q[0]), y: Math.min(p[1], q[1]), w: Math.abs(q[0] - p[0]), h: Math.abs(q[1] - p[1]) })))];
       return [.5, .32, .68, .2, .8, ...rs.map(span).filter(s => s[1 - v][0] < mid + across && s[1 - v][1] > mid - across).flatMap(s => [s[v][0] - half, s[v][1] + half])
         .map(u => (u - lo) / len).filter(f => f >= 0 && f <= 1).sort((p, q) => Math.abs(p - .5) - Math.abs(q - .5))]; };
-    for (const pass of (map ? [0, 1, 2] : [0])) for (const text of tries) { const relax = pass === 2; // 0 strict, 1 strict but may touch a box border, 2 relaxed
-      const two = !!(text && sub), pill = map && e.step != null, w = map ? (text ? pillW(text, two && sub) : 0) + (pill ? stepW(e.step) + (text ? 4 : 6) : 0) : textW(text, 10) + 12, hgt = map ? (two ? 32 : 20) : 18;
-      for (const sg of order) {
-        if (!relax && sg.h && sg.l < w + 10) continue;
-        if (!relax && !sg.h && sg.l < hgt + 14) continue;
-        for (const f of (relax ? [.5, .32, .68, .2, .8, .1, .9, .42, .58, .26, .74, .05, .95] : spots(sg, w, hgt))) {
-          const lx = sg.a[0] + (sg.b[0] - sg.a[0]) * f, ly = sg.a[1] + (sg.b[1] - sg.a[1]) * f;
-          const box = { x: lx - w / 2, y: ly - hgt / 2, w, h: hgt };
-          const grow = { x: box.x - 3, y: box.y - 3, w: box.w + 6, h: box.h + 6 };
-          if (nodeRects.some(r => hit(relax ? { x: r.x, y: r.y - 10, w: r.w, h: r.h + 10 } : { x: r.x - STUB - 4, y: r.y - STUB - 4, w: r.w + 2 * STUB + 8, h: r.h + 2 * STUB + 8 }, box))) continue; // keep port stubs free
-          if (tagRects.some(r => hit(r, grow))) continue;
-          if (placed.some(r => (pass === 0 || !r.band) && hit(r, grow))) continue;
-          if (!relax && routed.some(r => r !== e && segsOf(r.pts).some(([a, b]) => segHitsRect(a, b, grow)))) continue;
-          if (!relax && segs.some(s2 => s2.i !== sg.i && segHitsRect(s2.a, s2.b, box))) continue;
-          placed.push(box); reserved.push(grow); e.lbl = { ...box, text, ...(two ? { sub } : {}), step: map ? e.step : null, ...(pill ? { sw: stepW(e.step) } : {}), short: text !== full }; return;
-        }
+    const { two, w, hgt } = sizeOf(e, text, sub), pill = map && e.step != null;
+    for (const sg of order) {
+      if (!relax && sg.h && sg.l < w + 10) continue;
+      if (!relax && !sg.h && sg.l < hgt + 14) continue;
+      for (const f of (relax ? [.5, .32, .68, .2, .8, .1, .9, .42, .58, .26, .74, .05, .95] : spots(sg, w, hgt))) {
+        const lx = sg.a[0] + (sg.b[0] - sg.a[0]) * f, ly = sg.a[1] + (sg.b[1] - sg.a[1]) * f;
+        const box = { x: lx - w / 2, y: ly - hgt / 2, w, h: hgt };
+        const grow = { x: box.x - 3, y: box.y - 3, w: box.w + 6, h: box.h + 6 };
+        if (nodeRects.some(r => hit(relax ? { x: r.x, y: r.y - 10, w: r.w, h: r.h + 10 } : { x: r.x - STUB - 4, y: r.y - STUB - 4, w: r.w + 2 * STUB + 8, h: r.h + 2 * STUB + 8 }, box))) continue; // keep port stubs free
+        if (tagRects.some(r => hit(r, grow))) continue;
+        if (placed.some(r => (pass === 0 || !r.band) && hit(r, grow))) continue;
+        if (!relax && routed.some(r => r !== e && segsOf(r.pts).some(([a, b]) => segHitsRect(a, b, grow)))) continue;
+        if (!relax && segs.some(s2 => s2.i !== sg.i && segHitsRect(s2.a, s2.b, box))) continue;
+        yield { box, grow, lbl: { ...box, text, ...(two ? { sub } : {}), step: map ? e.step : null, ...(pill ? { sw: stepW(e.step) } : {}) } };
       }
     }
   }
+  const put = (e, s, full) => { placed.push(s.box); reserved.push(s.grow); e.lbl = { ...s.lbl, short: s.lbl.text !== full }; };
+  const unput = e => { const L = e.lbl, same = m => r => r.x === L.x - m && r.y === L.y - m && r.w === L.w + 2 * m && r.h === L.h + 2 * m;
+    const p = placed.findIndex(same(0)), q = reserved.findIndex(same(3)); if (p >= 0) placed.splice(p, 1); if (q >= 0) reserved.splice(q, 1); e.lbl = null; };
+  const fullOf = e => map ? fit(e.label || '', 10.5, e.under ? 320 : 440) : fit((e.step != null ? e.step + ' · ' : '') + (e.label || ''), 10, 150);
+  function placeLabel(e) {
+    if (!e.label && e.step == null) return;
+    const full = fullOf(e);
+    const tries = [full]; if (e.step != null && e.label && !dg.abs) tries.push(map ? '' : String(e.step));
+    const first = (x, text, pass) => fits(x, text, pass).next().value;
+    let s = first(e, full, 0); if (s) return put(e, s, full);
+    // a label whose spots are all taken by a label placed before it: that label moves to each of its other spots in turn, until
+    // this one fits too. Both centred on their lines, the labels of two lines that leave a card side by side (16 px apart, too
+    // close to stack) left the second no room, and it fell back to its step (assistant's "a draft", by a jog of 16 px)
+    if (map) for (const o of routed) { if (o === e || !o.lbl || o.lbl.short || o.fixed) continue;
+      const was = o.lbl, back = () => put(o, { box: { x: was.x, y: was.y, w: was.w, h: was.h }, grow: { x: was.x - 3, y: was.y - 3, w: was.w + 6, h: was.h + 6 }, lbl: was }, was.text);
+      unput(o); if (!first(e, full, 0)) { back(); continue; } // e finds no spot even without it
+      for (const so of fits(o, was.text, 0)) { put(o, so, was.text); if ((s = first(e, full, 0))) return put(e, s, full); unput(o); }
+      back(); }
+    for (const pass of (map ? [0, 1, 2] : [0])) for (const text of tries) if ((pass || text !== full) && (s = first(e, text, pass))) return put(e, s, full);
+  }
   let stats = {};
   free.forEach(e => { // every port's stub is reserved before routing starts
     const st = [e.p1[0] + OUT[e.fs][0] * STUB, e.p1[1] + OUT[e.fs][1] * STUB], en = [e.p2[0] + OUT[e.ts][0] * STUB, e.p2[1] + OUT[e.ts][1] * STUB];
@@ -1318,10 +1391,16 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
     const nearFirst = e => { const d = e.p1[ax] - e.p2[ax]; return d > 0 ? -e.p2[ax] : d < 0 ? e.p2[ax] - 1e6 : 1e7; };
     const slots = list.map(e => order.indexOf(e)).sort((a, b) => a - b), turns = [...list].sort((a, b) => nearFirst(a) - nearFirst(b));
     slots.forEach((at, i) => { order[at] = turns[i]; }); });
+  // fan-in (issue 111): lines into a card that six or more lines come into go first, in that order, so they take the tracks by
+  // the card and the rest go round them (r19's logger has seven; its lines crossed the ones routed before them).
+  // ponytail: six fits the bench (five made d24's hub worse); a fan-in card's own layout row is what is left
+  const fan = {}, hot = e => fan[e.t.id] >= 6; free.forEach(e => { fan[e.t.id] = (fan[e.t.id] || 0) + 1; });
+  order = [...order.filter(hot), ...order.filter(e => !hot(e))];
   let bad = runRouting(order);
   // rip-up and reroute: an edge that had to cross goes first next time; keep the best attempt (not when the view is laid
-  // out again with room: that layout's tries seldom gained anything, and they cost a third of its time)
-  for (let tries = 0; bad && !last && tries < 4; tries++) {
+  // out again with room for lines: that layout's tries seldom gained anything, and they cost a third of its time; with room for
+  // a label it tries, as the layout it may replace did)
+  for (let tries = 0; bad && (!last || room.lx) && tries < 4; tries++) {
     const stuck = order.filter(e => e.how !== 'grid');
     const next = [...stuck, ...order.filter(e => e.how === 'grid')];
     const snap = order.map(e => [e, e.pts, e.lbl, e.how]), snapStats = stats, snapR = [routed.slice(), reserved.slice(), placed.slice()];
@@ -1419,6 +1498,22 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
   if (!dg.quick) free.filter(e => e.how === 'fallback').forEach(e => { ripUp(e); e.pts = gridRoute(e, 2, 320) || gridRoute(e, 2, 0) || e.pts; e.lbl = null; routed.push(e); placeLabel(e); });
   if (!dg.quick) edges.forEach(e => { const n = through(e.pts, e); if (n) warn(`the line for edge ${edgeRefIds(e).join(' / ') || e.from + '->' + e.to} runs through card "${n.id}", which it does not join: no route found around it`); });
   __ms.repair = performance.now() - __ms.t; delete __ms.t;
+  // a label on a box's border, cut to its step or with no spot asks for room where it is: the column gap it sits in widens by
+  // the label's width, else the row gap by its height and 14 px; a label in neither, or with no spot, the gap its line's longest
+  // run crosses, a column's first. layoutGraph lays the view out again with it, and keeps that layout if it is better
+  let labelRoom = null;
+  const tight = !last && !dg.quick && map && !dg.abs ? free.filter(e => (e.label || e.step != null) && (!e.lbl || e.lbl.short || families.some(f => onBorder(e.lbl, f)))) : [];
+  if (tight.length) {
+    const cs = Object.keys(colX).map(Number), rs = nodes.map(n => n.row), r0 = Math.floor(Math.min(...rs)), r1 = Math.ceil(Math.max(...rs)), need = { x: {}, y: {} };
+    const gaps = [...cs.filter(c => colX[c + 1] != null).map(c => ['x', c, colX[c] + (colW[c] || NW), colX[c + 1]]),
+      ...Array.from({ length: Math.max(0, r1 - r0) }, (_, k) => ['y', r0 + k, rowY(r0 + k) + NH, rowY(r0 + k + 1)])];
+    tight.forEach(e => { const { w, hgt: h } = sizeOf(e, fullOf(e)), L = e.lbl, c = L && { x: L.x + L.w / 2, y: L.y + L.h / 2 };
+      let best = c && ['x', 'y'].map(k => gaps.find(([gk, g, p, q]) => gk === k && c[k] >= p && c[k] <= q)).find(Boolean);
+      if (!best) segsOf(e.pts).forEach(([a, b]) => { const k = a[1] === b[1] ? 'x' : 'y', i = k === 'x' ? 0 : 1, lo = Math.min(a[i], b[i]), hi = Math.max(a[i], b[i]);
+        gaps.forEach(([gk, g, p, q]) => { const run = Math.min(hi, q) - Math.max(lo, p); if (gk === k && run > 0 && (!best || (k === 'x') > (best[0] === 'x') || ((k === 'x') === (best[0] === 'x') && run > best[2]))) best = [k, g, run]; }); });
+      if (best) need[best[0]][best[1]] = (need[best[0]][best[1]] || 0) + (best[0] === 'x' ? w : h + 14); });
+    if (Object.keys(need.x).length + Object.keys(need.y).length) labelRoom = { ...room, lx: need.x, ly: need.y };
+  }
   const groups = (dg.groups || []).map(g => {
     const ms = (g.nodes || []).map(i => byId[i]).filter(Boolean);
     if (!ms.length) return null;
@@ -1430,7 +1525,7 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
   const ys = [...families.flatMap(f => [f.y,f.y+f.h]), ...(dg.lanes || []).flatMap(l => [l.y, l.y + l.h]), ...nodes.flatMap(n => [n.y - 14, n.y + n.h + (n.tag ? 18 : 8)]), ...groups.flatMap(g => [g.y, g.y2]), ...edges.flatMap(e => e.pts.map(p => p[1])), ...placed.flatMap(p => [p.y, p.y + p.h])];
   intake.forEach(b => { xs.push(b.cx - b.r - 8 - textW(b.label || '', 10.5), b.cx + b.r); ys.push(b.cy - b.r, b.cy + b.r); });
   const M = 36, minX = Math.min(...xs) - M, minY = Math.min(...ys) - M;
-  return { ms: __ms, stats, nodes, edges, subAndChips: !!dg.subAndChips, groups, families, intake, tour: dg.tour || null, byId, map, hub: dg.hub || null, lanes: dg.lanes || [], blocks: dg.blocks || [], bounds: { x: minX, y: minY, w: Math.max(...xs) - minX + M, h: Math.max(...ys) - minY + M } };
+  return { ms: __ms, ...(labelRoom ? { labelRoom } : {}), stats, nodes, edges, subAndChips: !!dg.subAndChips, groups, families, intake, tour: dg.tour || null, byId, map, hub: dg.hub || null, lanes: dg.lanes || [], blocks: dg.blocks || [], bounds: { x: minX, y: minY, w: Math.max(...xs) - minX + M, h: Math.max(...ys) - minY + M } };
 }
 
 let svgSeq = 0;
@@ -1787,6 +1882,9 @@ class Camera {
 // an issue's message, and what it is about (the cards, lines and boxes it names) when the caller keeps a list of that: check()
 // turns those into Refs; the page's check reads only the messages
 const teller = (issues, refs) => (message, ...about) => { issues.push(message); if (refs) refs.push(about); };
+// a label's box L across one of box f's borders
+const onBorder = (L, f) => { const xin = L.x + L.w > f.x && L.x < f.x + f.w, yin = L.y + L.h > f.y && L.y < f.y + f.h;
+  return (xin && [f.y, f.y + f.h].some(u => L.y < u && L.y + L.h > u)) || (yin && [f.x, f.x + f.w].some(u => L.x < u && L.x + L.w > u)); };
 // a detour: a route 2.5 times longer than the straight distance between its ends, or than 100 px; [its length, that distance]
 const detour = pts => { const len = pts.slice(1).reduce((a, p, k) => a + Math.abs(p[0] - pts[k][0]) + Math.abs(p[1] - pts[k][1]), 0);
   const d = Math.hypot(pts[pts.length - 1][0] - pts[0][0], pts[pts.length - 1][1] - pts[0][1]); return len > 2.5 * Math.max(d, 100) ? [len, d] : null; };
@@ -1864,8 +1962,7 @@ function routeAudit(geo, where, only, refs) { // only: a set of edges; counts ju
     geo.edges.forEach((e,i) => { if (segs[i].some(([a,b]) => { const v = a[0] === b[0], c = v ? a[0] : a[1], p = v ? [a[1], b[1]] : [a[0], b[0]];
       const lo = Math.max(Math.min(...p), v ? f.y : f.x), hi = Math.min(Math.max(...p), v ? f.y + f.h : f.x + f.w);
       return hi - lo > 40 && (v ? [f.x, f.x + f.w] : [f.y, f.y + f.h]).some(u => Math.abs(c - u) < 8); })) say(`${where}: edge ${name(e)} runs along the border of family "${f.label}"`, e, f); });
-    geo.edges.forEach(e => { const L = e.lbl; if (!L) return; const xin = L.x + L.w > f.x && L.x < f.x + f.w, yin = L.y + L.h > f.y && L.y < f.y + f.h;
-      if ((xin && [f.y, f.y + f.h].some(u => L.y < u && L.y + L.h > u)) || (yin && [f.x, f.x + f.w].some(u => L.x < u && L.x + L.w > u))) say(`${where}: label "${L.text || L.step}" sits on the border of family "${f.label}"`, e, f); });
+    geo.edges.forEach(e => { const L = e.lbl; if (L && onBorder(L, f)) say(`${where}: label "${L.text || L.step}" sits on the border of family "${f.label}"`, e, f); });
   });
   return issues;
 }
@@ -1880,6 +1977,8 @@ function overlapIssues(geo, where, refs) {
 }
 function leaveIssues(geo, where, refs) {
   const issues = [], say = teller(issues, refs);
+  // a numbered line's label with no room on it: only its step shows, its words in the line's title and the details only
+  if (geo.map) geo.edges.forEach(e => { if (e.label && e.lbl && e.lbl.short) say(`${where}: label "${e.label}" has no room on edge ${e.s.label}→${e.t.label}: only its step ${e.lbl.step} shows`, e); });
   if (geo.map) geo.edges.forEach(e => { const L = e.lbl; if (!L || (!e.label && L.step == null) || !e.pts) return; // a label, or a step's mark, must leave some of its own line visible
     const c = [L.x + L.w / 2, L.y + L.h / 2], P = e.pts; let s = 0, at = null, half = 0, tot = 0;
     for (let i = 0; i + 1 < P.length; i++) { const a = P[i], b = P[i + 1], len = Math.abs(b[0] - a[0]) + Math.abs(b[1] - a[1]);
@@ -2192,9 +2291,12 @@ function mapContext(model, opts = {}) {
     for (const o of [{ pull: true }, { packed: true }, { pull: true, packed: true }]) { const p = flowPos(vid, o), k = JSON.stringify(p); if (!seen.has(k)) { seen.add(k); ways.push(p); } }
     if (ways.length < 2) return first;
     let best = first, score = Infinity;
-    ways.forEach(p => { const g = buildGeo(vid, p), s = scoreGeo(g); if (s < score - 0.5) { score = s; best = p; drawn[vid] = { pos: p, g }; } }); // as it will be drawn: with port repair
+    scouting = true; ways.forEach(p => { const g = buildGeo(vid, p), s = scoreGeo(g); if (s < score - 0.5) { score = s; best = p; drawn[vid] = { pos: p, g }; } }); scouting = false; // as it will be drawn: with port repair
+    if (fanIn(vid)) delete drawn[vid];
     return best;
   }
+  let scouting = false;
+  const fanIn = vid => { const k = {}; return viewEdges(V[vid] || {}).some(e => e.from !== e.to && (k[e.to] = (k[e.to] || 0) + 1) >= 6); };
   const drawn = {}; // the way bestFlow kept, routed already: the view's next buildGeo takes it once instead of routing it again
   function flowPos(vid, o = {}) {
     const v = V[vid], lp = loopsOf(v), fwd = lp.edges.filter((e, k) => !lp.back.has(k) && e.from !== e.to);
@@ -2280,7 +2382,7 @@ function mapContext(model, opts = {}) {
     const stepIds = v.stepIds || ids;
     const dg = { nodeH: mainSteps ? 82 : v.subAndChips ? 80 : 64, subAndChips: !!v.subAndChips, mainSteps, containers: v.containers, nodes: ids.map(i => { const n = nodeIn(i, vid), step = mainSteps && stepIds.includes(i); return { ...n, sub: n.sub || n.sublabel, emphasis: !!step || !!n.emphasis, step: step ? stepIds.indexOf(i) + 1 : (v.cardSteps || {})[i] || null, verbs: step ? [] : n.verbs, kids: kidCount(i, vid), opens: !!opensOf(i, vid), col: (pos[i] || [0, 0])[0], row: (pos[i] || [0, 0])[1] }; }),
       edges: prepEdges(vid, edges, P.backKeys) };
-    dg.authors = D.authors; dg.repair = repair; dg.intake = v.intake; dg.tour = v.tour; dg.gap = v.gap; dg.rgap = v.rgap; dg.quick = quick;
+    dg.authors = D.authors; dg.fan = !scouting; dg.repair = repair; dg.intake = v.intake; dg.tour = v.tour; dg.gap = v.gap; dg.rgap = v.rgap; dg.quick = quick;
     return layoutGraph(dg, true);
   }
   function hubGeo(vid, P, edges, repair, quick) {
@@ -2909,7 +3011,7 @@ export function render(container, model, options = {}) {
           <button data-z="up" title="Up one level (Esc)" aria-label="Up one level">↑</button><span class="sep"></span>
           <button data-z="out" title="Zoom out (−)" aria-label="Zoom out">−</button><button data-z="fit" class="pct" title="Fit to screen (0)">100%</button><button data-z="in" title="Zoom in (+)" aria-label="Zoom in">+</button><span class="sep"></span>
           <button data-z="one" title="Actual size (1)">1:1</button><button data-z="flow" title="Animate flow direction (F)" aria-label="Animate flow">≋</button>${E && E.add ? '<span class="sep"></span><button data-z="add" title="Add a card (N, or Alt + double-click)" aria-label="Add a card">＋</button>' : ''}<span class="depth" title="Reading depth follows zoom">READ</span>
-        </div>`}</div></div>${!framed ? '' : (options.legend ? '<div class="m-legend"></div>' : '') + (options.hints ? `<div class="hint" role="status" aria-live="polite">${hintHTML('', ctrlWheel)}</div>` : '') + '</div>'
+        </div>`}</div></div>${!framed ? '' : (options.legend ? '<div class="m-legend"></div>' : '') + (options.hints ? `<div class="hint">${hintHTML('', ctrlWheel)}</div>` : '') + '</div>'
           + (options.details ? '<aside class="panel" aria-label="Node details" hidden></aside>' : '') + '</div>'
           + (options.nav ? '<button class="ibtn um-navbtn" title="Views (O)" aria-label="Toggle the views list" aria-expanded="false">☰</button><aside class="outline" aria-label="Views"></aside>' : '') + '</div>'}`;
   const stage = root.querySelector('.stage'), q = s => root.querySelector(s);
@@ -2951,7 +3053,9 @@ export function render(container, model, options = {}) {
   const status = t => P.status ? P.status(t) : tell && tell(t);
   const wide = P.wide || (() => (cam ? cam.size()[0] : stage.clientWidth) > 820);
 
-  const upOf = () => (P.upTarget ? P.upTarget() : (ctx.V[cur] || {}).parent) || null;
+  // the views the reader walked through, the one shown last: up goes back along them, then to the model's parent (issue 137)
+  let trail = [];
+  const upOf = () => (P.upTarget ? P.upTarget() : trail.length > 1 ? trail[trail.length - 2] : (ctx.V[cur] || {}).parent) || null;
   const nodeRef = id => ({ type: 'node', id, view: cur });
   const copyRef = r => r && { ...r, ...(Array.isArray(r.ids) ? { ids: [...r.ids] } : {}) }; // a host gets copies: the map's Refs stay its own
   const picked = () => sel ? [...more.map(nodeRef), copyRef(sel)] : []; // every selected thing, the latest last (more: other selected cards)
@@ -2979,6 +3083,7 @@ export function render(container, model, options = {}) {
     const back = focusOf();
     cancelGesture(!!v && vid === cur); // a new picture: a drag or a line under way stops; a name field stays over its card if the view draws it still
     cur = v ? vid : null; if (v) ctx.planOf(vid);
+    if (v) { trail = trail.filter(id => ctx.V[id]); if (!trail.includes(vid)) trail = [vid]; } // the first view, or after an update() took the walk's views away
     stage.querySelectorAll('svg.map-svg, .empty-view').forEach(s => s.remove());
     if (!v || !(v.nodeIds || []).some(i => ctx.N[i])) { // a view with nothing in it, or a model with no views, gets a friendly card, not a blank canvas
       geo = { nodes: [], edges: [], groups: [], lanes: [], families: [], byId: {}, stats: {}, bounds: { x: 0, y: 0, w: 400, h: 300 } };
@@ -3181,6 +3286,7 @@ export function render(container, model, options = {}) {
         const mode = modeOf(vid);
         delete asked[prev]; // an unfold asked for on the view left is not waited for (#71)
         if (P.onNavigate) P.onNavigate(vid, prev, mode);
+        const at = trail.indexOf(vid); trail = at >= 0 ? trail.slice(0, at + 1) : trail.length === 1 && vid === (ctx.V[prev] || {}).parent ? [vid] : [...trail, vid];
         mount(vid); emitSel(); left = false;
         const fitS = startView(), back = mode === 'out' ? geo.nodes.find(n => ctx.childOf(n.id, cur) === prev) : null;
         if (prev && !still()) {
@@ -3669,7 +3775,7 @@ export function render(container, model, options = {}) {
       return; }
     if (!ctx.V[cur]) { // the view shown is gone: the root, or the empty card of a model with no views
       const from = cur; mount(ctx.rootId ?? null); cam.set(startView()); cam.touched = false; emitSel(); if (cur) emit('viewchange', { view: cur, from }); return; }
-    if (ctx.geoCache[cur] && keys[cur] === ctx.viewKey(cur) && ctx.geoCache[cur].shapes === noteFor(cur)) { if (lensId != null) { relens(); drawMarks(); } if (pc) pc.chrome(); return; } // this view's picture did not change (its lens or the views may have)
+    if (ctx.geoCache[cur] && keys[cur] === ctx.viewKey(cur) && ctx.geoCache[cur].shapes === noteFor(cur)) { if (lensId != null) { relens(); drawMarks(); } if (pc) pc.chrome(); if (P.onMount) P.onMount(inner); return; } // this view's picture did not change (its lens or the views may have; the page reads the new model, issue 133)
     const keep = sel, keepMore = more, touched = cam.touched, prev = [geo, svg];
     mount(cur);
     if (touched) cam.set({}); else cam.set(startView());
@@ -4327,7 +4433,7 @@ export function mountPage(container, model, options = {}) {
       <span class="mbrand"><i></i><span>${esc(D.title || 'Map')}</span></span>
       <nav class="crumbs" id="m-crumbs" aria-label="Breadcrumb"></nav>
       <button class="findbtn" id="m-find" type="button" aria-label="Search nodes and views (${modK})"><span aria-hidden="true">⌕</span><span class="ft">Find a node or view…</span><span class="kbd">${modK}</span></button>
-      <button class="ibtn" id="m-theme" title="Light / dark" aria-label="Toggle theme">◐</button><button class="ibtn txt" id="m-shapes" type="button" title="Card shapes: box, c4 or uml">⬡<span class="lbl"></span></button>${(D.stories || []).length ? `
+      <button class="ibtn" id="m-theme" title="Light / dark" aria-label="Dark theme" aria-pressed="false">◐</button><button class="ibtn txt" id="m-shapes" type="button" title="Card shapes: box, c4 or uml">⬡<span class="lbl"></span></button>${(D.stories || []).length ? `
       <div class="menu"><button class="ibtn txt" id="m-stories" aria-haspopup="true" aria-expanded="false" title="Stories: walk-throughs of this map">▶<span class="lbl"> Stories</span></button>
         <div class="menu-pop" id="m-stories-pop" hidden>${D.stories.map(s => `<button data-story="${esc(s && s.id)}">${esc((s && (s.title || s.id)) || '')}</button>`).join('')}</div></div>` : ''}${arrOf(D.lenses).some(l => l && l.id) ? `
       <div class="menu"><button class="ibtn txt" id="m-lenses" aria-haspopup="true" aria-expanded="false" title="Lenses: ways to look at this map">◎<span class="lbl"> Lenses</span></button>
@@ -4344,7 +4450,7 @@ export function mountPage(container, model, options = {}) {
         <div class="ghosts" id="m-ghosts" aria-hidden="true">${ghost}</div>
         <div class="vpill" id="m-vpill"></div>
         <div class="m-legend" id="m-legend"></div>
-        <div class="hint" id="m-hint" role="status" aria-live="polite">${HINT}</div>
+        <div class="hint" id="m-hint">${HINT}</div>
       </div>
       <aside class="panel" id="m-panel" aria-label="Node details" hidden></aside>
     </div>
@@ -4385,7 +4491,7 @@ export function mountPage(container, model, options = {}) {
   const setTree = pc.setTree;
 
   /* the link (0.14.0): one place writes it, from what the map shows: its view, card, story step and lens, and the reader
-     copy, theme, check and shot the page was opened with (the theme as it is now, after ◐ too). A new view is a new entry,
+     copy and theme the page was opened with (the theme as it is now, after ◐ too). A new view is a new entry,
      written once the move lands; anything else rewrites the entry. Nothing is written while a link is being followed */
   function write(push = false) {
     if (!X || linking || handle.destroyed) return;
@@ -4394,7 +4500,7 @@ export function mountPage(container, model, options = {}) {
     if (lensOn) p.set('lens', lensOn); // the lens on the map (#94)
     if (X.override()) p.set('shapes', X.override()); // the notation a reader or the link picked (0.15.0)
     if (Q.get('theme')) p.set('theme', document.documentElement.dataset.theme || Q.get('theme'));
-    ['reader', 'check', 'shot'].forEach(k => Q.get(k) && p.set(k, Q.get(k)));
+    if (Q.get('reader')) p.set('reader', Q.get('reader')); // check, shot and still describe one run: never in the link a reader shares (issue 136)
     const h = '#' + p.toString();
     if (location.hash !== h) window.history[push ? 'pushState' : 'replaceState'](null, '', h); // window's: history() is this module's undo helper
   }
@@ -4459,7 +4565,9 @@ export function mountPage(container, model, options = {}) {
   let narrow = innerWidth <= 820;
   addEventListener('resize', () => { const n = innerWidth <= 820; if (n && !narrow) setTree(false); narrow = n; }, { signal });
   $('m-help').addEventListener('click', () => toggleHelp());
-  $('m-theme').addEventListener('click', () => { toggleTheme(); write(); }); // a link that names the theme names the one shown
+  const themed = () => $('m-theme').setAttribute('aria-pressed', (document.documentElement.dataset.theme || (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')) === 'dark'); // ◐ says which theme is on (issue 135)
+  themed(); matchMedia('(prefers-color-scheme: dark)').addEventListener('change', themed, { signal }); // the system's theme, when the page sets none
+  $('m-theme').addEventListener('click', () => { toggleTheme(); themed(); write(); }); // a link that names the theme names the one shown
   $('m-pause').addEventListener('click', e => { paused = !paused; const b = e.currentTarget, l = paused ? 'Play' : 'Pause'; X.pause(paused); b.setAttribute('aria-pressed', paused); b.title = l; b.setAttribute('aria-label', l); b.textContent = paused ? '▶' : '❚❚'; });
   $('m-export-pop').addEventListener('click', e => { const x = e.target.closest('[data-x]')?.dataset.x; if (!x) return; openMenu(null); exportView(x); });
 
@@ -4528,9 +4636,9 @@ export function mountPage(container, model, options = {}) {
   }
   const recordSoon = () => { if (rec && !handle.story) { clearTimeout(rec.t); rec.t = setTimeout(() => rec && !handle.story && rec.take(), 650); } }; // once the camera has landed; not a story's steps
 
-  /* ⌘K command box: nodes and views, Enter jumps */
-  const nodeIdx = nodes.map(n => ({ n, hay: [n.label, n.id, (n.verbs || []).join(' '), n.what, n.kind, n.author, ((D.authors || {})[n.author] || {}).name, n.origin].join(' ').toLowerCase() }));
-  const viewIdx = views.map(v => ({ v, hay: [v.title, v.id, v.caption].join(' ').toLowerCase() }));
+  /* ⌘K command box: nodes and views, Enter jumps. Indexed from the model shown, as an update() leaves it (issue 133) */
+  const nodeIdx = () => nodes.map(n => ({ n, hay: [n.label, n.id, (n.verbs || []).join(' '), n.what, n.kind, n.author, ((D.authors || {})[n.author] || {}).name, n.origin].join(' ').toLowerCase() }));
+  const viewIdx = () => views.map(v => ({ v, hay: [v.title, v.id, v.caption].join(' ').toLowerCase() }));
   const pal = $('m-pal'), q = $('m-q'), res = $('m-res');
   let hits = [], hi = 0;
   const mark = (s, words) => { let out = esc(s); words.filter(w => w.length > 1).forEach(w => { out = out.replace(new RegExp('(' + w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ')', 'ig'), '<mark>$1</mark>'); }); return out; };
@@ -4541,8 +4649,8 @@ export function mountPage(container, model, options = {}) {
       hits = [...kidsOf(cur), ...views.filter(v => v.id !== cur && !kidsOf(cur).includes(v))].slice(0, 8).map(v => ({ t: 'v', v }));
     } else {
       const starts = s => String(s || '').toLowerCase().startsWith(qs) ? 0 : 1;
-      const ns = nodeIdx.filter(x => words.every(w => x.hay.includes(w))).sort((a, b) => starts(a.n.label) - starts(b.n.label) || (geo.byId[b.n.id] ? 1 : 0) - (geo.byId[a.n.id] ? 1 : 0)).slice(0, 7).map(x => ({ t: 'n', n: x.n }));
-      const vs = viewIdx.filter(x => words.every(w => x.hay.includes(w))).slice(0, 5).map(x => ({ t: 'v', v: x.v }));
+      const ns = nodeIdx().filter(x => words.every(w => x.hay.includes(w))).sort((a, b) => starts(a.n.label) - starts(b.n.label) || (geo.byId[b.n.id] ? 1 : 0) - (geo.byId[a.n.id] ? 1 : 0)).slice(0, 7).map(x => ({ t: 'n', n: x.n }));
+      const vs = viewIdx().filter(x => words.every(w => x.hay.includes(w))).slice(0, 5).map(x => ({ t: 'v', v: x.v }));
       hits = [...ns, ...vs];
     }
     hi = Math.min(hi, Math.max(0, hits.length - 1));
@@ -4825,7 +4933,9 @@ function printDoc(X, model, Q) {
 const shortT = t => String(t || '').split(' · ')[0];
 const hintHTML = (keys, ctrl) => typeof matchMedia === 'function' && matchMedia('(hover: none)').matches ? '<span>pinch = zoom</span><span>drag = move</span><span>tap = details</span>'
   : `<span>${ctrl ? 'Ctrl + scroll' : 'scroll'} = zoom</span><span>drag = move</span><span>double-click ⤢ = open</span>${keys ? `<span>${keys} = search</span><span>? = keys</span>` : ''}`; // keys: the page's search key; ctrl: wheel 'ctrl'
-function hinter(el, html) { let t; return (s, ms = 1800) => { el.textContent = s; el.classList.add('msg'); clearTimeout(t); t = setTimeout(() => { el.innerHTML = html; el.classList.remove('msg'); }, ms); }; }
+function hinter(el, html) { // messages are said in a live region of their own, apart from the key hints (issue 134)
+  let t; const live = document.createElement('div'); live.className = 'um-live'; live.setAttribute('role', 'status'); live.setAttribute('aria-live', 'polite'); el.after(live);
+  return (s, ms = 1800) => { el.textContent = live.textContent = s; el.classList.add('msg'); clearTimeout(t); t = setTimeout(() => { el.innerHTML = html; el.classList.remove('msg'); }, ms); }; }
 
 // Pull concise points from captured prose; retain wording and keep the full point in its tooltip. A point is a sentence
 // or a clause; one longer than a line (160 characters) is cut in two, but a short sentence stays whole (#97).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umlimator",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Embeddable, layered architecture maps: layout, orthogonal routing and an interactive canvas in one ES module.",
   "keywords": ["architecture", "diagram", "c4", "map", "svg", "layout", "orthogonal-routing", "drill-down"],
   "homepage": "https://zintaen.github.io/umlimator/",