umlimator 0.12.0 → 0.12.1

package/README.md

@@ -44,7 +44,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.12.0"`. npm 12 refuses git
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.12.1"`. 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
@@ -140,7 +140,7 @@ python3 umlimator.py diff --base origin/main --out diff/              # every mo
 python3 umlimator.py drift model.json traffic.json --out drift.html   # drawn vs. seen (a Jaeger or Tempo dependency list)
 python3 umlimator.py timelapse model.json --out history.html          # the model's versions in git history, on a slider
 python3 umlimator.py check page.html --expand                          # also each view with each stacked card unfolded
-python3 umlimator.py record bike-share.html --story ride --out ride.png   # bike-share's story as an animated PNG, a frame per step
+python3 umlimator.py record bike-share.html --story ride --out ride.png   # bike-share's story as an animated PNG, its tours riding
 ```
 
 `check` also reports each rule the model breaks, and then exits 1.
@@ -170,7 +170,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: zintaen/umlimator@v0.12.0
+      - uses: zintaen/umlimator@v0.12.1
         with:
           models: "docs/*.json"   # optional: where the models are (default: every .json that is a map model)
 ```

package/lib/umlimator.d.ts

@@ -143,8 +143,9 @@ export interface Handle {
   on<K extends keyof Events>(type: K, fn: (e: Events[K]) => void): () => void;
   /** Unfolds a stacked card of the view shown into a box in place (#71): its inner view's own cards inside, this view's
    *  lines to it moved onto them, the rest of the picture in its order. In this handle only, never in the model; kept per
-   *  view across update(). False when it can't: no loaded inner view, nothing of its own inside, a numbered (sequence)
-   *  view in or opened, an editable map. No expand event: that is for gestures. */
+   *  view across update(). A numbered (sequence) inner view keeps its run order: numbers, loops back, lanes (#82). False
+   *  when it can't: no loaded inner view, nothing of its own inside, a card on a numbered view, an editable map. No
+   *  expand event: that is for gestures. */
   expand(id: string): boolean;
   /** Folds an unfolded card back (and anything unfolded inside it). False when it was not unfolded. */
   collapse(id: string): boolean;
@@ -195,8 +196,9 @@ export interface StoryPlayer {
 
 /** A mark on a card. tone: a palette name (--um-<tone>), drawn as a ring; badge: a tab after the card's own; level: 0 to 1. */
 export interface CardMark { tone?: string; badge?: Badge; pulse?: boolean; level?: number }
-/** A mark on a line. speed: its flow's speed, as a factor (0 stops it); tone: a glow under it; label: a pill under its own;
- *  dash: drawn dashed; level: 0 to 1. A drawn line that stands for several edges takes the strongest of their marks. */
+/** A mark on a line. speed: its flow's speed, as a factor (0 stops it); tone: a glow under it; label: a pill under its own,
+ *  or along the line where it covers nothing (with no room, in the line's tooltip and name instead); dash: drawn dashed;
+ *  level: 0 to 1. A drawn line that stands for several edges takes the strongest of their marks. */
 export interface LineMark { tone?: string; speed?: number; pulse?: boolean; label?: string; level?: number; dash?: boolean }
 /** A layer of marks: cards by node id, lines by edge id ("<from>-><to>#<n>" for an edge without one, as Refs name it).
  *  dim: what the layer doesn't name fades. */
@@ -222,7 +224,8 @@ export function render(container: HTMLElement, model: MapModel, options?: Render
 export interface History { readonly model: MapModel; readonly canUndo: boolean; readonly canRedo: boolean; push(m: MapModel): MapModel; undo(): MapModel; redo(): MapModel }
 export function history(model: MapModel, limit?: number): History;
 /** expand: cards of the view unfolded in place (#71), as handle.expand() draws them; the geometry's `unfolded` lists those
- *  that did (one inside another after it), and its `families` the boxes they became (`unfolds`: the inner view). */
+ *  that did (one inside another after it), and its `families` the boxes they became (`unfolds`: the inner view). A
+ *  numbered inner view's numbers are its lines' and cards' `step`, and its lanes are boxes with `lane: true` (#82). */
 export function layout(model: MapModel, viewId: string, options?: { repair?: boolean; measure?: (text: string, px: number) => number; expand?: string[] }): Geometry & { unfolded?: string[] };
 /** A model's own problem. path says where: "views[2].nodeIds[4]". Errors draw as holes or not at all (missing,
  *  repeated or dangling ids, a box inside itself); warnings draw other than they say (an unknown kind, weight or side,

package/lib/umlimator.js

@@ -264,6 +264,7 @@ const SIGIL = {
 const CHG = { added: ['green', 'NEW'], new: ['green', 'NEW'], modified: ['amber', 'CHANGED'], changed: ['amber', 'CHANGED'], removed: ['rose', 'REMOVED'], planned: ['cyan', 'PLANNED'] };
 const NW = 168, CG0 = 84, RG0 = 44;
 const pillW = (label, sub, max = 440) => Math.max(sansW(fit(label, 10.5, max), 10.5, .92), sub ? sansW(fit(sub, 9.5, max), 9.5, .92) : 0) + 18; // a line's label, and its sublabel under it (#44)
+const stepW = s => String(s).length > 2 ? Math.max(16, sansW(String(s), 9.5, .9) + 8) : 16; // a line's step mark: a 16 px circle, or a pill for a number such as 4.1 (#82)
 // Text width. Without a measurer: a monospace estimate (font-independent, so layouts are the same on every machine;
 // the bench and layout() in Node use it). render() sets measureText to the host's own font while it lays out a view.
 let measureText = null;
@@ -483,10 +484,10 @@ const mapTabs = (n, c) => { const tw = t => t.toUpperCase().length * 6.4 + 10, b
   const t = n.k === 'm-public' ? 'PUBLIC' : n.k === 'm-ext' ? 'EXTERNAL' : n.k === 'm-lane' ? 'LANE' : ''; return t ? [{ text: t, fill: c, w: tw(t) }] : []; };
 const mapNodeW = n => {
   const px = n.emphasis ? 15 : 13;
-  const sub = n.sub || n.sublabel || '';
+  const sub = n.sub || n.sublabel || '', chips = (n.verbs || []).reduce((a, v) => a + textW(v, 9.5) + 14, -4); // its chips as svgOf draws them: each verb and 10 px, 4 px apart (#84)
   return Math.min(n.emphasis ? 205 : 386, Math.max(n.emphasis ? 146 : 138,
     Math.ceil(textW(n.label, px) + 70), badgesOf(n).length ? Math.ceil(badgesOf(n).reduce((a, b) => a + b.text.length * 6.4 + 10, 0) + (badgesOf(n).length - 1) * 4 + 120) : 0,
-    Math.min(386, Math.ceil(textW(sub, 10) + 70))));
+    Math.min(386, Math.ceil(Math.max(textW(sub, 10), chips) + 70))));
 };
 /* Geometry: node boxes, ports, orthogonal routes, label slots. A view with lines the router found no route for is laid
    out once more, with room where those lines need it (#40); a view whose lines all route keeps its geometry. */
@@ -523,8 +524,11 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
       return c ? [...(c.nodeIds || []), ...(dg.containers || []).filter(k => k.parent === b).flatMap(k => inBox(k.id, seen))] : []; };
     const near = (b, other) => { const cs = inBox(b).map(i => colOf[i]).filter(c => c != null); if (other == null || !cs.length) return null;
       const lo = Math.min(...cs), hi = Math.max(...cs); return other < lo ? lo : other > hi ? hi : null; };
+    // an unfolded numbered view's lane is a box in its box (#82): a line to a card in one, or to that box, crosses two borders.
+    // ponytail: lanes only; an inner view's own nested boxes have the same 12 px less, but room for them moves views drawn today
+    const inLane = id => (dg.containers || []).some(f => f.lane && (f.parent === id || (f.nodeIds || []).includes(id)));
     (dg.edges || []).forEach(e => { const p = colOf[e.from] ?? near(e.from, colOf[e.to]), q = colOf[e.to] ?? near(e.to, colOf[e.from]); if (p == null || q == null || !e.label || Math.abs(p - q) !== 1) return;
-      const c = Math.min(p, q), w = pillW(e.label, e.sublabel) + (e.step != null ? 20 : 0), box = boxOf(e.from) !== boxOf(e.to) || !(e.from in colOf) || !(e.to in colOf) ? 48 : 0;
+      const c = Math.min(p, q), w = pillW(e.label, e.sublabel) + (e.step != null ? stepW(e.step) + 4 : 0), box = boxOf(e.from) !== boxOf(e.to) || !(e.from in colOf) || !(e.to in colOf) ? 48 + ([e.from, e.to].some(inLane) ? 12 : 0) : 0;
       gapAfter[c] = Math.max(gapAfter[c] || 0, w + 54 + box);
       [e.from, e.to].forEach(id => { const k = c + '|' + id, t = sum[k] ||= { w: -6, box: 0 }; t.w += w + 6; t.box = Math.max(t.box, box); gapAfter[c] = Math.max(gapAfter[c], t.w + 54 + t.box); }); }); }
   const extraX = { ...(room || {}).x }, extraY = { ...(room || {}).y }; // more room after a column (row): for lines with no route, and where a box would touch another box (below)
@@ -820,7 +824,9 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
       hpop(); const k = pk, cell = k >> 2, dir = k & 3, i = (cell / ny) | 0, j = cell - i * ny;
       if (pd > dist[k] + (hx[i] + hy[j])) continue;
       const d = dist[k];
-      if (cell === t0) { best = k; if (dir === dEnd) break; continue; }
+      // in head-on if it can; else the cheapest way in, the first found (it kept the last, the dearest: a top-to-top line on
+      // the top row ran past its card and back, #80)
+      if (cell === t0) { if (dir === dEnd) { best = k; break; } if (best < 0) best = k; continue; }
       const xi = X[i], yj = Y[j];
       for (let nd = 0; nd < 4; nd++) {
         if ((nd ^ 1) === dir && ((nd >> 1) === (dir >> 1))) continue; // no reversal
@@ -863,7 +869,7 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
     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));
     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 ? (text ? 20 : 22) : 0) : textW(text, 10) + 12, hgt = map ? (two ? 32 : 20) : 18;
+      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;
@@ -876,7 +882,7 @@ function layoutPass(dg, map, room, last) { // room: { x: { col: px }, y: { row:
           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, short: text !== full }; return;
+          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;
         }
       }
     }
@@ -1151,7 +1157,7 @@ return I && I.src ? `<rect x="${x - M * 3 / 28}" y="${y - M * 3 / 28}" width="${
       let vx = 0; const chips = [], maxW = third ? sw : n.w - 24; // on a third line they keep to the text's column, clear of the mark
       for (let i = 0; i < verbs.length; i++) {
         const wv = textW(verbs[i], 9.5) + 10, rest = verbs.length - i - 1, more = rest ? textW('+' + rest, 9.5) + 10 : 0;
-        if (vx + wv + (rest ? more + 4 : 0) > maxW && i) { chips.push(['+' + (verbs.length - i), textW('+' + (verbs.length - i), 9.5) + 10, true]); break; }
+        if (vx + wv + (rest ? more + 4 : 0) > maxW) { chips.push(['+' + (verbs.length - i), textW('+' + (verbs.length - i), 9.5) + 10, true]); break; } // the first too: a verb wider than any card is "+N" (#84)
         chips.push([verbs[i], wv]); vx += wv + 4;
       }
       const total = chips.reduce((a, c2) => a + c2[1], 0) + (chips.length - 1) * 4;
@@ -1182,8 +1188,9 @@ return I && I.src ? `<rect x="${x - M * 3 / 28}" y="${y - M * 3 / 28}" width="${
     if (!e.lbl) return;
     const L = e.lbl;
     if (map) {
-      const st = L.step != null ? `<circle cx="${L.x + 11}" cy="${L.y + L.h / 2}" r="8" class="e-step"/><text x="${L.x + 11}" y="${L.y + L.h / 2 + 3.3}" text-anchor="middle" class="e-step-tx">${esc(L.step)}</text>` : '';
-      const ax = L.step != null ? L.x + 23 : L.x + L.w / 2, an = L.step != null ? '' : 'text-anchor="middle"';
+      const sw = L.sw || 16, cy = L.y + L.h / 2; // the step mark: a circle, or a pill as wide as a longer number (#82)
+      const st = L.step != null ? `${sw > 16 ? `<rect x="${L.x + 3}" y="${cy - 8}" width="${sw}" height="16" rx="8" class="e-step"/>` : `<circle cx="${L.x + 11}" cy="${cy}" r="8" class="e-step"/>`}<text x="${L.x + 3 + sw / 2}" y="${cy + 3.3}" text-anchor="middle" class="e-step-tx">${esc(L.step)}</text>` : '';
+      const ax = L.step != null ? L.x + 7 + sw : L.x + L.w / 2, an = L.step != null ? '' : 'text-anchor="middle"';
       const tx = L.text ? `<text x="${ax}" y="${L.y + 14}" ${an} class="e-label" data-t="el" data-o="${esc(e.from)}>${esc(e.to)}">${esc(L.text)}</text>` : '';
       const sb = L.sub ? `<text x="${ax}" y="${L.y + 26}" ${an} class="e-sub" data-t="el" data-o="${esc(e.from)}>${esc(e.to)}">${esc(L.sub)}</text>` : '';
       s += `<g class="e-lab${L.tag ? ' ctag' : ''}${e.wk ? ' w-' + e.wk : ''}" data-i="${i}"><rect x="${L.x}" y="${L.y}" width="${L.w}" height="${L.h}" rx="${Math.min(L.h / 2, 10)}" class="e-lbg"/>${st}${tx}${sb}</g>`;
@@ -1447,6 +1454,8 @@ function auditSvg(svg, geo, where) {
       nodes.forEach(n => { if (n !== own && hit(a.b, R(n), -1)) issues.push(`${where}: text "${a.txt}" overlaps node "${n.label}"`); });
     }
   });
+  svg.querySelectorAll('rect.verb-chip').forEach(r => { const own = geo.byId[r.closest('[data-id]').dataset.id], x = +r.getAttribute('x'); // a chip's pill, not only its text (#84)
+    if (own && (x < own.x + 1 || x + +r.getAttribute('width') > own.x + own.w - 1)) issues.push(`${where}: chip "${r.nextElementSibling.textContent}" overflows node "${own.label}"`); });
   issues.push(...routeAudit(geo, where), ...leaveIssues(geo, where));
   const els = T.filter(a => a.t === 'el');
   for (let i = 0; i < els.length; i++) for (let j = i + 1; j < els.length; j++) if (hit(els[i].b, els[j].b, -1)) issues.push(`${where}: edge labels "${els[i].txt}" and "${els[j].txt}" overlap`);
@@ -1784,7 +1793,7 @@ function mapContext(model, opts = {}) {
     const ready = drawn[vid]; delete drawn[vid]; if (ready && !override && ready.pos === pos && repair === (v.repair !== false) && !quick) return ready.g;
     const mainSteps = v.mainSteps || v.render === 'process';
     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 : 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] }; }),
+    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;
     return layoutGraph(dg, true);
@@ -1902,20 +1911,26 @@ function mapContext(model, opts = {}) {
      same way round, or, with none, ends on the box's border; the inner view's other lines to neighbours are not added. The
      box is the inner view's own cards in their own order, at the card's place: later columns move right by its width, and
      the cards under it in its column move down by its height, so the rest of the picture keeps its places (a hub view, which
-     has no columns, is laid out again). The inner view's boxes that hold its own cards come along inside. Neither in nor of
-     a numbered (sequence) view: its run order, numbers and lanes, would move or be lost; that one opens. */
+     has no columns, is laid out again). The inner view's boxes that hold its own cards come along inside, and a numbered
+     (sequence) view's run order: its numbers, its loops back and its lanes (#82). Not in a numbered view: its own steps
+     would be numbered again; that card opens. */
+  // the inner view's own cards: those this view shows neither as cards nor as boxes (a card unfolded here already is one, #98)
+  const ownOf = (v, C, nid) => (C.nodeIds || []).filter(i => N[i] && i !== nid && !(v.nodeIds || []).includes(i) && !(v.containers || []).some(b => b && b.id === i));
   const unfoldable = (nid, vid) => { const v = V[vid], ids = (v && v.nodeIds) || [], c = ids.includes(nid) && N[nid] && v.render !== 'sequence' ? childOf(nid, vid) : null;
-    if (!c || c === vid || V[c].render === 'sequence' || chain(vid).includes(c) || (v.containers || []).some(b => b && b.id === nid)) return null;
-    return (V[c].nodeIds || []).some(i => N[i] && i !== nid && !ids.includes(i)) ? c : null; };
+    if (!c || c === vid || chain(vid).includes(c) || (v.containers || []).some(b => b && b.id === nid)) return null;
+    return ownOf(v, V[c], nid).length ? c : null; };
   function unfold(vid, nid) {
     const v = V[vid], c = unfoldable(nid, vid); if (!c) return false;
-    const C = V[c], outer = (v.nodeIds || []).filter(i => N[i]), inner = (C.nodeIds || []).filter(i => N[i] && i !== nid && !outer.includes(i));
+    const C = V[c], outer = (v.nodeIds || []).filter(i => N[i]), inner = ownOf(v, C, nid);
     const n0 = nodeIn(nid, vid), holder = (v.containers || []).filter(b => b && (b.nodeIds || []).includes(nid)).pop();
     const boxes = (v.containers || []).filter(b => b && b.id).map(b => ({ ...b, nodeIds: (b.nodeIds || []).filter(i => i !== nid) }));
     const taken = new Set([...outer, ...inner, ...boxes.map(b => b.id)]);
     const cb = (C.containers || []).filter(b => b && b.id && !taken.has(b.id) && (b.nodeIds || []).some(i => inner.includes(i))), kept = new Set(cb.map(b => b.id));
     const above = b => { let p = b.parent; for (let k = 0; p != null && !kept.has(p) && k < 64; k++) p = ((C.containers || []).find(x => x && x.id === p) || {}).parent; return kept.has(p) ? p : nid; };
-    const own = cb.map(b => ({ ...b, nodeIds: b.nodeIds.filter(i => inner.includes(i)), parent: above(b) })), boxed = new Set(own.flatMap(b => b.nodeIds));
+    // a numbered view drawn around one card (a hub) brings its lanes, boxed as it draws them, in their order (#82)
+    const hp = C.render === 'sequence' && planOf(c).hub ? planOf(c) : null;
+    const lanes = hp && hp.boxed ? hp.lanes.map((L, j) => ({ id: `${nid}:lane${j + 1}`, label: L.title, lane: true, nodeIds: L.ids.filter(i => inner.includes(i)), parent: nid })).filter(b => b.nodeIds.length) : [];
+    const own = [...cb.map(b => ({ ...b, nodeIds: b.nodeIds.filter(i => inner.includes(i)), parent: above(b) })), ...lanes], boxed = new Set(own.flatMap(b => b.nodeIds));
     const box = { id: nid, label: n0.label || nid, nodeIds: inner.filter(i => !boxed.has(i)), unfolds: c, ...(holder ? { parent: holder.id } : {}), ...(badgesOf(n0).length ? { badges: badgesOf(n0) } : {}) };
     const isIn = id => inner.includes(id) || kept.has(id), mine = viewEdges(v);
     const to = new Set(mine.filter(e => e.to === nid).map(e => e.from)), from = new Set(mine.filter(e => e.from === nid).map(e => e.to)); // this view's neighbours of the card
@@ -1924,6 +1939,16 @@ function mapContext(model, opts = {}) {
     const ends = (a, out) => [...new Set(theirs.filter(e => out ? isIn(e.from) && e.to === a : e.from === a && isIn(e.to)).map(e => out ? e.from : e.to))].join();
     const split = new Set([...to].filter(a => from.has(a) && (ends(a, true) || ends(a, false)) && (ends(a, true) !== ends(a, false) || ends(a, true).includes(','))));
     theirs = theirs.filter(e => !split.has(isIn(e.from) ? e.to : e.from));
+    /* a numbered view's run order comes along (#82): its lines keep their numbers, and a step back stays a loop back. A step
+       between the card itself and a card inside has no line (the card is the box), and a hub's steps show on the cards they
+       reach, as the numbered view draws them: those numbers go on that card inside. On a numbered card (a process view's
+       step, or one an unfolded numbered view numbered) they go under its number: step 4's are 4.1, 4.2 */
+    const tags = {}, onCard = e => e.from === nid ? e.to : e.to === nid ? e.from : hp && e.from === hp.hub ? e.to : null;
+    const sid = v.stepIds || outer, at = (v.mainSteps || v.render === 'process') && sid.includes(nid) ? sid.indexOf(nid) + 1 : (v.cardSteps || {})[nid];
+    const num = j => /^\d+(\.\d+)*$/.test(String(at ?? '')) ? `${at}.${j + 1}` : j + 1; // a card with several numbers (2·3) holds no one step
+    if (C.render === 'sequence') { const lq = loopsOf(C);
+      lq.edges.forEach((e, j) => { const o = onCard(e); if (inner.includes(o)) (tags[o] ||= []).push(num(j)); });
+      theirs = theirs.map(e => { const j = lq.edges.indexOf(e); return { ...e, ...(inner.includes(onCard(e)) ? {} : { step: num(j) }), ...(lq.back.has(j) ? { loop: true } : {}) }; }); }
     const exact = new Set(theirs.flatMap(e => isIn(e.from) === isIn(e.to) ? [] : isIn(e.to) ? [e.from + '>'] : ['>' + e.to])); // neighbours the inner view joins to a card inside
     const k = (v.nodeIds || []).indexOf(nid), grid = !planOf(vid).hub;
     const pos = grid ? (v.layout ? fillLayout(vid, v.layout) : (layoutCache[vid] ||= autoPos(vid))) : null;
@@ -1933,6 +1958,7 @@ function mapContext(model, opts = {}) {
     if (v.mainSteps || v.render === 'process') v.stepIds = v.stepIds || outer; // the steps keep their numbers; the cards inside are not steps
     if (Array.isArray(v.intake)) v.intake = v.intake.filter(s => s && s.to !== nid);
     if (+C.gap > (v.gap || 66)) v.gap = +C.gap; if (+C.rgap > (v.rgap || 44)) v.rgap = +C.rgap; // the room the inner view's lines were given
+    Object.entries(tags).forEach(([i, s]) => { (v.cardSteps ||= {})[i] = s.length > 2 ? s[0] + '+' : s.join('·'); }); // as hubGeo's stepTxt; buildGeo draws them
     delete v.layout; delete planCache[vid]; delete layoutCache[vid]; delete drawn[vid];
     if (!grid) return true; // a hub view has no columns to keep: laid out again, with its boxes
     /* the box's slots: the inner view's own cards in its columns, or in this view's reading order, and in its rows packed,
@@ -1950,7 +1976,11 @@ function mapContext(model, opts = {}) {
     // with another, or not at all
     const inBox = (id, seen = new Set()) => seen.has(id) ? [] : (seen.add(id), [...((boxes.find(x => x.id === id) || {}).nodeIds || []), ...boxes.filter(k => k.parent === id).flatMap(k => inBox(k.id, seen))]);
     const xBoxes = new Set(); for (let b = holder, k = 0; b && k < 64; k++, b = boxes.find(x => x.id === b.parent)) xBoxes.add(b.id); // the boxes the card is in
-    const ip0 = C.layout ? fillLayout(c, C.layout) : (layoutCache[c] ||= autoPos(c)), lp = loopsOf(v), rk = Object.fromEntries(inner.map(i => [i, 0]));
+    // a hub's slots, as it draws them: the hub, then its lanes' columns in order (#82). ponytail: rows in each column's order,
+    // not level with the part before as hubGeo lines them up; do that if a lane of several columns reads badly
+    const hs = hp && { [hp.hub]: [0, 0] };
+    if (hs) hp.lanes.flatMap(L => L.cols).map(col => col.filter(i => inner.includes(i))).filter(col => col.length).forEach((col, j) => col.forEach((i, r) => { hs[i] = [j + 1, r]; }));
+    const ip0 = hs || (C.layout ? fillLayout(c, C.layout) : (layoutCache[c] ||= autoPos(c))), lp = loopsOf(v), rk = Object.fromEntries(inner.map(i => [i, 0]));
     const fwd = lp.edges.filter((e, j) => !lp.back.has(j) && e.from !== e.to && inner.includes(e.from) && inner.includes(e.to));
     for (let it = 0; it < inner.length; it++) fwd.forEach(e => { if (rk[e.to] < rk[e.from] + 1) rk[e.to] = rk[e.from] + 1; });
     const one = own.length || v.nodeIds.length > 30; // its boxes' room to keep, or too big to route seven times: its own slots only
@@ -2988,6 +3018,7 @@ export function render(container, model, options = {}) {
     s.querySelectorAll('.node[opacity], .edge-g[opacity], .e-lab[opacity]').forEach(x => x.removeAttribute('opacity'));
     s.querySelectorAll('.edge[style], .flowline[style]').forEach(x => x.removeAttribute('style'));
     s.querySelectorAll('.node[aria-description]').forEach(x => x.removeAttribute('aria-description'));
+    s.querySelectorAll('[data-was]').forEach(x => { if (x.tagName === 'title') x.textContent = x.getAttribute('data-was'); else x.setAttribute('aria-label', x.getAttribute('data-was')); x.removeAttribute('data-was'); });
     if (s === svg) stage.classList.toggle('um-lit', [...layers.values()].some(L => L.dim));
     if (!layers.size) return;
     const tone = t => 'var(--um-' + String(t || 'accent').replace(/[^\w-]/g, '') + ')', op = m => m.level < 1 ? ` opacity="${m.level}"` : '';
@@ -3000,6 +3031,9 @@ export function render(container, model, options = {}) {
       const x = mapTabs(n).reduce((a, t) => a + t.w + 4, n.x + 12), w = b.text.toUpperCase().length * 6.4 + 10;
       over += `<g class="um-tab"${op(m)}><rect x="${x}" y="${n.y - 8}" width="${w}" height="15" rx="4" fill="${toneOf(b)}"/><text x="${x + w / 2}" y="${n.y + 3}" text-anchor="middle" class="tab-tx">${esc(b.text)}</text></g>`;
       el.setAttribute('aria-description', b.text); });
+    const heads = (g.families || []).flatMap(f => [{ x: f.x + 8, y: f.y + 3, w: String(f.label || f.id).length * 6.6 + 8, h: 22 }, // a box's title, 11 px mono
+      ...(f.tabs || []).map(t => ({ x: t.x, y: f.y - 8, w: t.w, h: 16 }))]); // and its tabs
+    const pills = [], free = r => !g.nodes.some(n => hit(r, n, 8) || (n.tag && hit(r, n.tag, 2))) && !heads.some(h => hit(r, h, 2)) && !g.edges.some(o => o.lbl && hit(r, o.lbl, 2)) && !pills.some(p => hit(r, p, 2));
     g.edges.forEach((e, i) => { const m = markOf(L => strongest(edgeRefIds(e).map(x => (L.edges || {})[x]))), eg = s.querySelector(`.edge-g[data-i="${i}"]`); if (!m || !eg) return;
       const path = eg.querySelector('.edge'), flow = eg.querySelector('.flowline');
       if (m.level < 1) [eg, s.querySelector(`.e-lab[data-i="${i}"]`)].forEach(x => x && x.setAttribute('opacity', m.level));
@@ -3007,10 +3041,19 @@ export function render(container, model, options = {}) {
       if (m.dash) path.setAttribute('style', 'stroke-dasharray: 7 5');
       if (m.speed != null && flow) flow.setAttribute('style', +m.speed > 0 ? `animation-duration: ${(2.4 / m.speed).toFixed(2)}s` : 'animation: none; opacity: 0');
       if (m.label == null || m.label === '') return;
-      // ponytail: the label sits under the line's own (else on its longest run) with no room kept for it, so it may cover a neighbour's
-      const t = String(m.label), w = sansW(t, 10, .92) + 14, L = e.lbl, [a, b] = L ? [] : longest(e.pts);
-      const x = L ? L.x + L.w / 2 : (a[0] + b[0]) / 2, y = L ? L.y + L.h + 2 : (a[1] + b[1]) / 2 - 8;
-      over += `<g class="um-lab"${op(m)}><rect x="${x - w / 2}" y="${y}" width="${w}" height="16" rx="8"${m.tone ? ` style="stroke: ${tone(m.tone)}"` : ''}/><text x="${x}" y="${y + 11.5}" text-anchor="middle">${esc(t)}</text></g>`; });
+      // the pill takes the first place that covers no card, box title or tab, line label or pill before it (#81): under the
+      // line's own label (else on its longest run), then a few places along the line. The view is not laid out again for
+      // it, so with no room at any, its text goes in the line's tooltip and accessible name instead
+      // ponytail: six places, and another line may lie under one; scan along the line if too few find room
+      const t = String(m.label), w = sansW(t, 10, .92) + 14, L = e.lbl, [a, b] = longest(e.pts), len = lenOf(e.pts);
+      const box = [L ? [L.x + L.w / 2, L.y + L.h + 10] : [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2], ...[.5, .3, .7, .15, .85].map(f => along(e.pts, f * len))]
+        .map(([x, y]) => ({ x: x - w / 2, y: y - 8, w, h: 16 })).find(free);
+      if (!box) { const tt = eg.querySelector(':scope > title'), key = s.querySelector(`.line-key[data-i="${i}"]`);
+        if (tt) { tt.setAttribute('data-was', tt.textContent); tt.textContent += '\n' + t; }
+        if (key) { key.setAttribute('data-was', key.getAttribute('aria-label')); key.setAttribute('aria-label', key.getAttribute('aria-label') + ', ' + t); }
+        return; }
+      pills.push(box);
+      over += `<g class="um-lab"${op(m)}><rect x="${box.x}" y="${box.y}" width="${w}" height="16" rx="8"${m.tone ? ` style="stroke: ${tone(m.tone)}"` : ''}/><text x="${box.x + w / 2}" y="${box.y + 11.5}" text-anchor="middle">${esc(t)}</text></g>`; });
     const cardsG = s.querySelector('.nodes');
     if (under && cardsG) cardsG.insertAdjacentHTML('beforebegin', `<g class="um-rings" aria-hidden="true">${under}</g>`);
     if (over) s.insertAdjacentHTML('beforeend', `<g class="um-marks" aria-hidden="true">${over}</g>`);
@@ -3056,10 +3099,15 @@ export function render(container, model, options = {}) {
       const prev = legs[legs.length - 1], n = geo.byId[ids[k]];
       const pts = prev && prev.to === ids[k] ? [prev.pts[prev.pts.length - 1], [n.x + n.w / 2, n.y + n.h / 2], ...r.pts] : r.pts;
       legs.push({ pts, to: ids[k + 1], len: lenOf(pts) }); }
-    if (!legs.length || reducedMotion()) return Promise.resolve(legs.length > 0);
+    if (!legs.length || (reducedMotion() && P.tourAt == null)) return Promise.resolve(legs.length > 0);
     const speed = Math.max(20, +o.speed || 240); // map units a second
     svg.insertAdjacentHTML('beforeend', '<g class="um-trip" aria-hidden="true"><circle r="5.5" class="tour-dot"/></g>');
     const g = svg.lastElementChild, dot = g.firstElementChild; let leg = 0, base = 0;
+    if (P.tourAt != null) { // the page's #shot=1&at=<0 to 1>: the dot held that far along the ride, a frame for umlimator.py record (#83)
+      let d = clamp01(P.tourAt) * legs.reduce((s, l) => s + l.len, 0); while (leg < legs.length - 1 && d > legs[leg].len) d -= legs[leg++].len;
+      const [x, y] = along(legs[leg].pts, d); dot.setAttribute('cx', x); dot.setAttribute('cy', y);
+      trip = { raf: 0, dot: g, end() {} }; return Promise.resolve(true);
+    }
     return new Promise(res => { startTrip(ms => { const d = ms * speed / 1000;
       while (leg < legs.length && d - base >= legs[leg].len) { base += legs[leg].len; flash(legs[leg].to); leg++; }
       if (leg >= legs.length) return false;
@@ -3443,11 +3491,12 @@ export function mountPage(container, model, options = {}) {
   }
   const setTree = on => { document.body.classList.toggle('tree-open', on); $('m-outline').setAttribute('aria-expanded', on); };
 
-  // Pull concise points from captured prose; retain wording and keep the full point in its tooltip.
+  // 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).
   function detailBullets(body) {
     const normalized = String(body || '').replace(/^\s*(?:[-*]|\d+[.)])\s+/gm, '').replace(/\n+/g, ' ').trim();
     let parts = normalized.split(/(?<=[.!?])\s+(?=[A-Z`/])|;\s+|\s+[·|]\s+/).filter(Boolean);
-    while (parts.length < 2 || parts.some(p => p.length > 160) && parts.length < 4) {
+    while (parts.some(p => p.length > 160) && parts.length < 4) {
       const index = parts.reduce((best, p, i) => p.length > (parts[best] || '').length ? i : best, 0), value = parts[index];
       if (!value || value.length < 8) break;
       const separators = [...value.matchAll(/:\s+|,\s+|\s+(?=then\b|with\b|before\b|after\b|once\b|to\b|and\b|or\b|during\b|by\b|whose\b|outside\b|on\b|for\b|as\b|whenever\b|into\b|in\b|from\b|when\b|includes\b|typed\b)/g)].map(m => m.index + m[0].length);
@@ -3748,7 +3797,7 @@ export function mountPage(container, model, options = {}) {
     view: v0, minimap: true, flow: flowPref ? flowPref === '1' : undefined,
     on: { story: ({ story: id, step }) => { told = step == null ? null : { id, step }; app.classList.toggle('story', !!told); if (X) setHash(true); } }, // from the first draw: a link may open a story (#69)
     _page: {
-      instant: options.instant, defer: !INSTANT, tour: !Q.get('still'), openHint: !Q.get('reader'), kinds: true, status,
+      instant: options.instant, defer: !INSTANT, tour: !Q.get('still'), openHint: !Q.get('reader'), kinds: true, status, tourAt: Q.get('shot') ? Q.get('at') : null,
       wide: () => innerWidth > 820,
       upTarget: () => stack.length > 1 ? stack[stack.length - 2] : (V[cur] || {}).parent,
       inset: () => { const top = Math.max(58, 26 + $('m-vpill').offsetHeight); if (innerWidth <= 820) return { t: top, r: 12, b: 12, l: 12 }; const lg = $('m-legend'), on = lg && !lg.hidden; // the legend box sits bottom left

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umlimator",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "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/",