flowfig 0.5.0 → 0.7.0

package/dist/svg.js

@@ -1,34 +1,24 @@
-// The same figure, as one self-contained animated SVG: no scripts, no fonts to fetch, so it plays
-// inside a markdown image on GitHub, GitLab and Notion, where the React player cannot go. It gives
-// up what needs a reader: no hover, no tabs, no pause — every step runs in one loop.
-//
-// It reads the same spec and the same `route()` as the React renderer, so the two cannot drift.
-//
-// Limit: text is measured by character class (src/text.ts) rather than by a browser, so this runs anywhere with plain node.
-// Wrapping is therefore approximate; `flowfig check` uses the same measure, and the player check measures real text.
+// Wrapping is approximate: text is measured by character class, not by a browser.
 import { route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.js';
 import { textWidth, wrap } from './text.js';
-import { checkScene, checkSpec, checkTheme } from './check.js';
+import { checkRendered, planFor } from './check.js';
 export { parseSource, links } from './source.js';
 export { diff, formatDiff } from './diff.js';
-import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, lanePlan, STUB_ROOM, laneBlock, laneEnd, tightCopies, nodeWidth, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, beatMs, STEP_HOLD_MS, playheadItem, dateLabelRaised, labelSpan, outsideLabelRect, } from './model.js';
+import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, STUB_ROOM, laneBlock, laneEnd, tightCopies, nodeWidth, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, labelSpan, outsideLabelRect, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const LINE = CARD_LINE, CARD_SIDE = 8, ROW_GAP = 4;
 const LABEL_LINE = 18, SUB_LINE = 15;
 const FRAME_TOP = 37, FRAME_BOTTOM = 18;
-// The card-on fills are fixed colors that approximate the player's 8% accent tint. The active tint is the player's color-mix.
+// The card-on fills approximate the player's 8 % accent tint.
 const vars = (t, cardOn) => `--accent:${t.accent}; --fg:${t.fg}; --muted:${t.muted}; --bg:${t.bg}; --surface:${t.surface}; --border:${t.border}; --card-on:${cardOn}; --tint:color-mix(in srgb, var(--accent) 10%, var(--surface));`;
-/** What a card actually holds: rows, or its text. Only text survives outside React. */
 const content = (c) => (isRows(c) ? c : str(c));
 const esc = (s) => s.replace(/[<>&"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' })[c]);
 const n2 = (v) => Math.round(v * 10) / 10;
-// Keyframe times are fractions of a loop that can last a minute: one decimal would round a 0.7 s hop away, and the packet would jump.
+// Four decimals: one decimal rounds a 0.7 s hop away and the packet jumps.
 const n4 = (v) => Math.round(v * 10000) / 10000;
 const pct = (v) => Math.round(v * 10000) / 100 + '%';
-/** A tag pill. The tag is drawn in bold capitals with letter spacing, so the width counts both. */
 const pillW = (tag) => textWidth(tag.toUpperCase(), 9) + tag.length * 0.27 + 8;
-/** A card's rows, wrapped for `width`, with the height they need. */
 function layoutCard(c, width) {
     const inner = width - CARD_SIDE * 2;
     if (c == null)
@@ -39,7 +29,6 @@ function layoutCard(c, width) {
         return { rows: [{ row: { text: body }, heads: false, lines, room: inner }], height: lines.length * LINE + CARD_PAD * 2 };
     }
     const rows = body.map((row) => {
-        // A word-sized tag heads its row so the text keeps the full width; a number or no tag sits inline.
         const heads = (row.tag?.length ?? 0) > 2;
         const tagW = row.tag && !heads ? pillW(row.tag) + 5 : 0;
         const markW = row.mark && !heads ? textWidth(str(row.mark), 11) + 6 : 0;
@@ -68,8 +57,6 @@ function size(item, s) {
     const inner = item.direction === 'column' ? { w: across, h: along } : { w: along, h: across };
     return item.label != null ? { w: inner.w + FRAME_SIDE * 2, h: inner.h + FRAME_TOP + FRAME_BOTTOM } : inner;
 }
-/** Swimlanes: the bands span the width, the label sits in a left gutter, and a box sits at its time column. Columns past
- * the plan wrap into blocks under the first. A block holds only the lanes with a box in it; all bands share one width. */
 function placeLanes(fig, x, y, s, out) {
     const lanes = fig.layout.children;
     const { cols, starts, gaps, lead, blocks } = s.plan;
@@ -87,7 +74,6 @@ function placeLanes(fig, x, y, s, out) {
                 .slice(0, c - starts[k])
                 .reduce((a, w, i) => a + w + gaps[starts[k] + i], 0));
     });
-    // A figure with no box has no column: its band keeps the frame side on the right.
     const width = Math.max(...blocks.map((k) => {
         const ws = colsOf(k);
         return (gutter +
@@ -104,7 +90,6 @@ function placeLanes(fig, x, y, s, out) {
             ly += LANE_BLOCK_GAP - LANE_ROW_GAP;
         for (const lane of lanes) {
             const kids = lane.children.filter((b) => laneBlock(starts, cols.get(b.id)) === bk).map((b) => ({ b, ...size(b, s) }));
-            // A wrapped block draws only its own lanes; one block draws every lane, an empty one too.
             if (blocks.length > 1 && !kids.length)
                 continue;
             const inner = Math.max(LABEL_LINE + 20, ...kids.map((k) => k.h));
@@ -117,7 +102,6 @@ function placeLanes(fig, x, y, s, out) {
     });
     out[topAt].h = ly - LANE_ROW_GAP - y;
 }
-/** A timeline: the axis strip on top, one band per track, and the bars and milestones at the shared layout x. */
 function placeTimeline(fig, x, y, out) {
     const lanes = fig.layout.children;
     const gutter = gutterOf(lanes);
@@ -178,24 +162,18 @@ function place(item, x, y, s, out) {
     }
 }
 const SYSTEM_FONT = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
-/**
- * The SVG string, and the scene it drew. The scene lets `flowfig check` test the same layout the SVG uses.
- * The scene is for tools, and its shape may change. Use `toSvg` if you only need the SVG.
- */
+/** The SVG string and the scene it drew. The scene shape may change; use `toSvg` for the SVG only. */
 export function render(fig, opts = {}) {
     const speed = (opts.speed ?? fig.speed ?? 900) / 1000 / BASE_RATE;
     const pad = opts.padding ?? 24;
     const tl = fig.timeline && isLanesLayout(fig.layout) ? timelineLayout(fig, TL_AXIS_W) : null;
-    // A timeline with no steps of its own walks its dated items in date order.
     const synthetic = tl != null && !fig.steps?.length;
     const steps = synthetic ? timelineBeats(fig) : (fig.steps ?? []);
     const beats = steps.map((s) => s.flow.map(toBeat));
-    // Every content a box will ever show, so its card can be sized to the biggest one up front.
     const cards = new Map();
     for (const b of beats.flat())
         for (const [id, c] of Object.entries(b.show ?? {}))
             cards.set(id, [...(cards.get(id) ?? []), c]);
-    // Boxes with many edges on one side get taller so the edges and their labels have room.
     const out = {}, inn = {};
     for (const e of fig.edges) {
         out[e.from] = (out[e.from] ?? 0) + 1;
@@ -210,14 +188,13 @@ export function render(fig, opts = {}) {
     const plan = lanes ? planFor(fig, opts) : null;
     const sizes = { cards, cardH, minH, gap: (g) => groupGap(g, fig.edges), fig, plan, tall: new Set(plan?.tall) };
     for (const [id, contents] of cards) {
-        const width = CARD_WIDTH; // refined below once the node's own width is known
+        const width = CARD_WIDTH;
         const widths = [width];
         cardH.set(id, Math.max(LINE + CARD_PAD * 2, ...contents.map((c) => layoutCard(c, Math.min(...widths) - 20).height)));
     }
     const placed = [];
     place(fig.layout, pad, pad, sizes, placed);
     let nodes = placed.filter((p) => !isGroup(p.item));
-    // A node's own width can differ from CARD_WIDTH (`width` in the spec), so re-measure once placed.
     for (const p of nodes) {
         if (!cards.has(p.item.id))
             continue;
@@ -227,11 +204,9 @@ export function render(fig, opts = {}) {
     const rects = {};
     const tips = new Set(placed.filter((p) => !isGroup(p.item) && (p.item.shape === 'decision' || p.tl?.milestone)).map((p) => p.item.id));
     const ids = fig.edges.map(edgeId);
-    // Wrapped lanes: an edge between two blocks is two stubs with pills, clear of the boxes and the lane gutters.
     const stubs = plan?.stubs ?? new Map();
     const gutter = plan ? gutterOf(fig.layout.children) : 0;
     const band = (id, k) => placed.find((p) => p.lane && p.item.id === id && p.block === k);
-    // The band of an edge end, in the block of that end: the band of the box's lane, or of the lane itself.
     const laneGroups = fig.layout.children;
     const bandOf = (eid, id, k) => {
         const block = plan?.ends.get(eid)?.[k];
@@ -239,7 +214,6 @@ export function render(fig, opts = {}) {
         return placed.find((p) => p.lane && p.item === lane && p.block === block);
     };
     const end = (eid, id, start) => (plan ? laneEnd(plan, eid, id, start, band, rects) : id);
-    // Place and route. A stub end with no place clear of every edge path makes its lane copy taller, then both run again.
     const go = () => {
         placed.length = 0;
         place(fig.layout, pad, pad, sizes, placed);
@@ -253,12 +227,13 @@ export function render(fig, opts = {}) {
             around: e.around ?? (plan?.around.has(ids[i]) ? 'below' : undefined),
             ...(tl && { sides: ['r', 'l'], elbow: true }),
             ...(stubs.has(ids[i]) && { stub: stubs.get(ids[i]).map(labelPillW), bands: [bandOf(ids[i], e.from, 0), bandOf(ids[i], e.to, 1)] }),
-            ...(stubs.size && e.label != null && { labelW: labelPillW(str(e.label)) }),
+            ...((stubs.size || lanes) && e.label != null && { labelW: labelPillW(str(e.label)) }),
         })), rects, tips, stubs.size
             ? placed.flatMap((p) => (!isGroup(p.item) ? [p] : p.lane ? [{ x: p.x, y: p.y, w: gutter, h: p.h }] : []))
-            : placed.filter((p) => p.tl && !p.tl.labelInside).map((p) => outsideLabelRect(p, str(p.item.label))), 
-        // A stub pill stays in the lanes, right of the gutter.
-        stubs.size ? { x: placed[0].x + gutter, y: placed[0].y, w: placed[0].w - gutter, h: placed[0].h } : undefined);
+            : [
+                ...placed.filter((p) => p.tl && !p.tl.labelInside).map((p) => outsideLabelRect(p, str(p.item.label))),
+                ...placed.filter((p) => p.tl).map((p) => ({ x: p.x, y: p.y, w: p.w, h: p.h, box: true })),
+            ], stubs.size ? { x: placed[0].x + gutter, y: placed[0].y, w: placed[0].w - gutter, h: placed[0].h } : undefined, lanes ? { bands: placed.filter((p) => p.lane), boxes: placed.filter((p) => !isGroup(p.item)) } : undefined);
     };
     let routed = go();
     for (let pass = 0; plan && pass < 3; pass++) {
@@ -270,11 +245,9 @@ export function render(fig, opts = {}) {
     }
     nodes = placed.filter((p) => !isGroup(p.item));
     const byId = Object.fromEntries(routed.map((r) => [r.id, r]));
-    // What this layout drew, in scene form. Tags are left out of minFont: short bold capitals, not reading text.
     const fonts = [14, ...(steps.length ? [13.5] : [])];
     const sceneBoxes = nodes.map((p) => {
         if (p.tl) {
-            // A label inside the bar has the bar as room; a label beside the bar has the space to the next item of its row, or to the band edge.
             const label = str(p.item.label);
             const mine = tl.items.find((i) => i.id === p.item.id);
             const next = tl.items.filter((i) => i.track === mine.track && i.row === mine.row && i.x > mine.x).map((i) => p.x - mine.x + i.x - 8);
@@ -306,7 +279,6 @@ export function render(fig, opts = {}) {
     });
     if (placed.some((p) => isGroup(p.item) && p.item.label != null))
         fonts.push(11);
-    // The timeline: every beat of every step, in order, with the player's hold at the end of each step.
     const segs = [];
     const hops = [];
     const edgeOf = Object.fromEntries(fig.edges.map((e, i) => [ids[i], e]));
@@ -337,7 +309,6 @@ export function render(fig, opts = {}) {
         });
     });
     const total = t || 1;
-    // What the figure shows during each segment, matching the React player exactly.
     const shownAt = segs.map(({ si, bi }) => Object.assign({}, ...beats[si].slice(0, bi + 1).map((b) => b.show)));
     const litEdges = segs.map(({ si, bi }) => new Set(beats[si].slice(0, bi + 1).flatMap((b) => b.hops.map((h) => h.edge))));
     const litNodes = segs.map((seg, i) => {
@@ -357,10 +328,19 @@ export function render(fig, opts = {}) {
         const said = beats[si].slice(0, bi + 1).findLastIndex((b) => b.say != null);
         return str(said === -1 ? steps[si].caption : beats[si][said].say);
     });
-    // One class per on/off pattern over the segments, so 30 boxes share a handful of keyframes.
     const css = [];
     const seen = new Map();
-    /** The class that switches this element between `onCss` and `offCss` as the loop plays. */
+    const runs = (values) => {
+        const out = [];
+        for (let i = 0; i < segs.length;) {
+            let j = i;
+            while (j + 1 < segs.length && values[j + 1] === values[i])
+                j++;
+            out.push(`${pct(segs[i].t0 / total)},${pct(segs[j].t1 / total - 0.0001)} { ${values[i]} }`);
+            i = j + 1;
+        }
+        return out.join(' ');
+    };
     const anim = (on, onCss, offCss, prefix) => {
         if (!segs.length || on.every((x) => !x))
             return '';
@@ -368,17 +348,16 @@ export function render(fig, opts = {}) {
         if (!seen.has(key)) {
             const name = `a${seen.size}`;
             seen.set(key, name);
-            const frames = segs.map((s, i) => `${pct(s.t0 / total)},${pct(s.t1 / total - 0.0001)} { ${on[i] ? onCss : offCss} }`).join(' ');
+            const frames = runs(on.map((x) => (x ? onCss : offCss)));
             css.push(`@keyframes ${name} { ${frames} }\n.${name} { animation: ${name} ${n2(total)}s infinite step-end; }`);
         }
         return seen.get(key);
     };
-    /** One `class` attribute from the static classes and the animated one — two would be invalid XML. */
+    // One class attribute only: two would be invalid XML.
     const cls = (...names) => {
         const list = names.filter(Boolean).join(' ');
         return list ? ` class="${list}"` : '';
     };
-    /** Like `anim`, for a property that takes a different value in each segment (a row that moves as phases fold). */
     const frames = (values, prefix, base = values[0]) => {
         if (!segs.length || values.every((v) => v === base))
             return '';
@@ -386,20 +365,14 @@ export function render(fig, opts = {}) {
         if (!seen.has(key)) {
             const name = `a${seen.size}`;
             seen.set(key, name);
-            const kf = segs.map((s, i) => `${pct(s.t0 / total)},${pct(s.t1 / total - 0.0001)} { ${values[i]} }`).join(' ');
+            const kf = runs(values);
             css.push(`@keyframes ${name} { ${kf} }\n.${name} { animation: ${name} ${n2(total)}s infinite step-end; }`);
         }
         return seen.get(key);
     };
-    /**
-     * The look of one box over the loop: off, trail (visited) or active (the packet arrived, until the segment ends).
-     * A segment ends at the beat end, or after the step hold for the last beat.
-     * Each frame holds one look. The gap before the frame that follows an active frame gives the FADE.
-     * FADE is in timeline seconds, which are wall seconds.
-     */
+    // FADE and RAMP are wall seconds; the player matches them in ms.
     const FADE = 0.4;
-    const RAMP = 0.4; // the today line moves in 400 ms, in wall seconds like FADE
-    // A box tone is a permanent state: a 1 px border and a light tint in the off and trail looks. The active look uses the hop tone, else the box tone.
+    const RAMP = 0.4;
     const looks = (look, boxTone, hopTone) => {
         const tint = boxTone ? toneTint(boxTone, 'var(--bg)') : 'var(--bg)';
         if (look === 'off')
@@ -411,13 +384,21 @@ export function render(fig, opts = {}) {
             ? [toneTint(c, 'var(--surface)', 10), c, 2, `drop-shadow(0 0 4px ${c})`]
             : ['var(--tint)', 'var(--accent)', 2, 'drop-shadow(0 0 4px var(--accent))'];
     };
+    const hopsAt = new Map();
+    for (const h of hops) {
+        const k = `${h.si}:${h.bi}:${h.dest}`;
+        const list = hopsAt.get(k);
+        if (list)
+            list.push(h);
+        else
+            hopsAt.set(k, [h]);
+    }
     const boxAnim = (id, shape, boxTone) => {
         const pieces = [];
         segs.forEach((s, i) => {
             if (!litNodes[i].has(id))
                 return void pieces.push({ a: s.t0, b: s.t1, look: 'off' });
-            const here = hops.filter((h) => h.dest === id && h.si === s.si && h.bi === s.bi);
-            // A focused box turns active at the beat start; in a timeline, when the today line arrives.
+            const here = hopsAt.get(`${s.si}:${s.bi}:${id}`) ?? [];
             const focused = beats[s.si][s.bi].focus?.includes(id);
             const arrive = Math.min(...here.map((h) => h.t1), focused ? Math.min(s.t0 + (tl ? RAMP : 0), s.t1) : s.t1, s.t1);
             if (arrive > s.t0)
@@ -427,18 +408,23 @@ export function render(fig, opts = {}) {
         });
         if (!pieces.length || pieces.every((q) => q.look === 'off'))
             return '';
-        // The last frame is active: the fade ends at 100 %, so the loop wraps with no jump.
         const end = pieces.at(-1);
         if (end.look === 'active') {
             end.b -= FADE;
             pieces.push({ a: end.b, b: end.b + FADE, look: pieces[0].look, hop: pieces[0].hop, ramp: FADE - 0.0002 * total });
         }
-        const kf = pieces.map((q, k) => {
+        const merged = [];
+        pieces.forEach((q, k) => {
             const ramp = q.ramp ?? (q.look !== 'active' && pieces[k - 1]?.look === 'active' ? Math.min(FADE, (q.b - q.a) / 2) : 0);
             const [fill, stroke, width, filter] = looks(q.look, boxTone, q.hop);
             const css = `${shape ? `fill: ${fill}; ` : ''}stroke: ${stroke}; stroke-width: ${width}${shape ? `; filter: ${filter}` : ''}`;
-            return `${pct((q.a + ramp) / total)},${pct(q.b / total - 0.0001)} { ${css} }`;
+            const last = merged.at(-1);
+            if (last?.css === css)
+                last.b = q.b;
+            else
+                merged.push({ a: q.a + ramp, b: q.b, css });
         });
+        const kf = merged.map((f) => `${pct(f.a / total)},${pct(f.b / total - 0.0001)} { ${f.css} }`);
         const key = (shape ? 'B' : 'R') + kf.join(' ');
         if (!seen.has(key)) {
             const name = `a${seen.size}`;
@@ -491,7 +477,6 @@ export function render(fig, opts = {}) {
             : item.sub
                 ? `<text x="${n2(cx)}" y="${n2(labelY + SUB_LINE)}" class="sub">${esc(str(item.sub))}</text>`
                 : '';
-        // The mark sits in the gap beside the box, so it changes no size and adds nothing to the scene.
         const dot = bt ?? 'var(--accent)';
         const my = n2(p.y + p.h / 2);
         const mark = item.mark === 'start'
@@ -501,7 +486,6 @@ export function render(fig, opts = {}) {
                 : '';
         return shape + label + sub + mark + (contents ? card(p, cardTop, contents) : '');
     });
-    /** The dashed content card: one group per content it will ever hold, each visible on its own beats. */
     function card(p, top, contents) {
         const id = p.item.id;
         const x = p.x + 10, w = p.w - 20, h = cardH.get(id);
@@ -509,7 +493,6 @@ export function render(fig, opts = {}) {
         const box = `<rect x="${n2(x)}" y="${n2(top)}" width="${n2(w)}" height="${n2(h)}" rx="6" fill="var(--surface)" stroke="var(--border)" stroke-dasharray="3 3"` +
             cls(anim(filled, 'stroke: var(--accent); fill: var(--card-on)', 'stroke: var(--border); fill: var(--surface)', 'c')) +
             `/>`;
-        // Every distinct content gets a layer; the segments decide which one is showing.
         const layers = contents
             .map((c, ci) => {
             const on = segs.map((_, i) => contents.indexOf(shownAt[i][id]) === ci);
@@ -524,7 +507,6 @@ export function render(fig, opts = {}) {
             : '';
         return box + layers + dash;
     }
-    /** One card's rows: a colored tag pill, the text, its muted meta, and the mark on the right. */
     function rows(c, x, top, w) {
         const { rows } = layoutCard(c, w);
         let y = top + CARD_PAD;
@@ -561,22 +543,18 @@ export function render(fig, opts = {}) {
         const on = segs.map((_, i) => litEdges[i].has(r.id));
         const hidden = e.quiet && !on.every(Boolean);
         const shown = hidden ? cls(anim(on, 'opacity: 1', 'opacity: 0', 'q')) : '';
-        // A toned hop colors its edge for its own beat only; the trail after it is the accent.
         const tone = segs.map(({ si, bi }) => (beats[si][bi].hops.find((h) => h.edge === r.id && h.tone)?.tone ?? undefined));
         const col = tone.map((x) => (x ? TONES[x] : 'var(--accent)'));
         const off = `stroke: var(--muted); stroke-width: ${EDGE_OFF}`;
-        // With no tone the map and the rail share one keyframe (same key); a toned edge needs its own values.
         const toned = tone.some(Boolean);
         const lit = cls(toned
             ? frames(on.map((x, i) => (x ? `stroke: ${col[i]}; stroke-width: ${EDGE_ON}` : off)), 'e', off)
             : anim(on, `stroke: var(--accent); stroke-width: ${EDGE_ON}`, off, 'e'));
-        // A cross-block edge draws its two stubs; its full path only guides the packet, so the packet jumps between the blocks.
         const path = r.stub
             ? r.stub.parts
                 .map((d) => `<path d="${d}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`)
                 .join('') + `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="none"/>`
             : `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`;
-        // A quiet edge is only drawn while a step uses it, so wrap the whole thing rather than the stroke.
         const pill = (x, y, lw, text) => `<rect x="${n2(x - lw / 2)}" y="${n2(y - 9)}" width="${n2(lw)}" height="18" rx="9" fill="var(--bg)" stroke="var(--border)"` +
             cls(toned
                 ? frames(on.map((x, i) => x ? `fill: ${tone[i] ? toneFill(col[i]) : col[i]}; stroke: ${col[i]}` : 'fill: var(--bg); stroke: var(--border)'), 'l', 'fill: var(--bg); stroke: var(--border)')
@@ -596,8 +574,6 @@ export function render(fig, opts = {}) {
         }
         return hidden ? `<g opacity="0"${shown}>${path}${label}</g>` : path + label;
     });
-    // A packet per hop: it waits offstage, crosses its edge in `speed`, rests at the end of the edge to the end of its beat, then leaves. Any `data`
-    // rides above it in a chip, which is how the figure says what is moving.
     const packets = hops.map((h, i) => {
         const t0 = h.t0 / total, t1 = h.t1 / total, tEnd = h.tEnd / total;
         const name = `p${i}`;
@@ -618,8 +594,7 @@ export function render(fig, opts = {}) {
             `<animateMotion dur="${n2(total)}s" repeatCount="indefinite" keyTimes="0;${n4(t0)};${n4(t1)};1" keyPoints="${h.back ? '1;1;0;0' : '0;0;1;1'}" calcMode="linear">` +
             `<mpath href="#p-${esc(h.edge)}" xlink:href="#p-${esc(h.edge)}"/></animateMotion></g>`);
     });
-    // The timeline axis under the boxes, the fixed today marker and the moving playhead over them.
-    let axisSvg = '', todaySvg = '';
+    let axisSvg = '', lineSvg = '', todaySvg = '';
     if (tl) {
         const top = placed[0];
         const x0 = top.x + gutterOf(fig.layout.children);
@@ -632,38 +607,40 @@ export function render(fig, opts = {}) {
                     `<text x="${n2(x0 + k.x + 3)}" y="${n2(top.y + 10)}" class="tick">${esc(k.label)}</text>`)
                     .join('');
         const bottom = n2(top.y + top.h);
-        // The today marker is fixed at the figure's `today`.
         if (tl.today != null) {
             const tx = x0 + tl.today;
-            todaySvg =
-                `<path d="M ${n2(tx)} ${n2(top.y + 12)} V ${bottom}" stroke="var(--accent)" stroke-opacity="0.6" stroke-width="1" stroke-dasharray="3 3"/>` +
-                    `<text x="${n2(tx - 3)}" y="${n2(top.y + 22)}" text-anchor="end" class="today">today</text>`;
+            lineSvg = `<path d="M ${n2(tx)} ${n2(top.y + 12)} V ${bottom}" stroke="var(--accent)" stroke-opacity="0.6" stroke-width="1" stroke-dasharray="3 3"/>`;
+            todaySvg = `<text x="${n2(tx - 3)}" y="${n2(top.y + 22)}" text-anchor="end" class="today">today</text>`;
         }
-        // The playhead moves to the start of each beat's item, then to the last date in the step hold.
         if (tl.last != null && segs.length) {
             const home = tl.last;
             const startOf = new Map(tl.items.map((i) => [i.id, i.x + (i.milestone ? i.w / 2 : 0)]));
             const dateOf = new Map(tl.items.map((i) => [i.id, i.date]));
             const hold = STEP_HOLD_MS / 1000 / BASE_RATE;
-            const pts = [[0, home]];
-            const dates = []; // the label date in each time span
-            let at = home;
+            const first = loopStartItem(tl.items, steps);
+            const start = first ? startOf.get(first.id) : home;
+            const pts = [[0, start]];
+            const dates = [];
+            let at = start;
             segs.forEach((s, i) => {
                 const item = playheadItem(tl.items, beats[s.si], s.bi);
                 const to = item ? startOf.get(item.id) : home;
                 const date = item ? dateOf.get(item.id) : tl.lastDate;
                 const last = i === segs.length - 1 || segs[i + 1].si !== s.si;
-                const end = last ? s.t1 - hold : s.t1; // the step hold starts here
+                const end = last ? s.t1 - hold : s.t1;
                 pts.push([s.t0, at], [Math.min(s.t0 + RAMP, end), to], [end, to]);
-                const [la, lb] = labelSpan(s.t0, end, RAMP);
+                const [la, lb] = i === 0 && to === start ? [s.t0, end] : labelSpan(s.t0, end, RAMP);
                 if (la < lb)
                     dates.push({ a: la, b: lb, d: date, x: to });
                 at = to;
                 if (last) {
-                    pts.push([Math.min(end + RAMP, s.t1), home], [s.t1, home]);
-                    const [ha, hb] = labelSpan(end, s.t1, RAMP);
+                    const back = i === segs.length - 1 ? Math.max(end + RAMP, s.t1 - RAMP) : s.t1;
+                    pts.push([Math.min(end + RAMP, s.t1), home], [back, home]);
+                    const [ha, hb] = labelSpan(end, back, RAMP);
                     if (ha < hb)
                         dates.push({ a: ha, b: hb, d: tl.lastDate, x: home });
+                    if (back < s.t1)
+                        pts.push([s.t1, start]);
                     at = home;
                 }
             });
@@ -678,36 +655,32 @@ export function render(fig, opts = {}) {
                 if (!seen.has(key)) {
                     const nm = `a${seen.size}`;
                     seen.set(key, nm);
-                    // Each span ends with a hidden frame: the label stays off while the line moves.
                     const fr = dates
                         .map((x) => `${pct(x.a / total)},${pct(x.b / total - 0.0001)} { opacity: ${x.d === d ? 1 : 0} } ${pct(x.b / total)} { opacity: 0 }`)
                         .join(' ');
                     css.push(`@keyframes ${nm} { ${fr} }\n.${nm} { animation: ${nm} ${n2(total)}s infinite step-end; }`);
                 }
-                // A label that would meet "today" moves to the tick row.
                 const raised = dateLabelRaised(dates.find((x) => x.d === d).x, tl.today, textWidth(d, 11), textWidth('today', 11));
                 return `<text x="${n2(lx + 3)}" y="${n2(top.y + (raised ? 10 : 22))}" opacity="0"${cls('today', seen.get(key))}>${esc(d)}</text>`;
             });
-            todaySvg += `<g${cls(name)}><path d="M ${n2(lx)} ${n2(top.y + 12)} V ${bottom}" stroke="var(--accent)" stroke-width="1.5"/>${labels.join('')}</g>`;
+            lineSvg += `<g${cls(name)}><path d="M ${n2(lx)} ${n2(top.y + 12)} V ${bottom}" stroke="var(--accent)" stroke-width="1.5"/></g>`;
+            todaySvg += `<g${cls(name)}>${labels.join('')}</g>`;
         }
     }
     const bounds = placed[0];
-    const arcs = fig.edges.some((e, i) => (e.around || plan?.around.has(ids[i])) && !stubs.has(ids[i])); // a stub does not arc
+    const arcs = fig.edges.some((e, i) => (e.around || plan?.around.has(ids[i])) && !stubs.has(ids[i]));
     const capLines = [...new Set(captions)].flatMap((c) => wrap(c, Math.max(560, bounds.w), 13.5).length);
     const mapW = Math.max(bounds.w + pad * 2, 560);
-    // `rail: 'only'` drops the map, but only when the rail has a hop to draw; a figure never renders empty.
     const rail = fig.rail ? layoutRail(fig, fig.rail === 'only' ? 560 : mapW) : null;
     const only = fig.rail === 'only' && rail != null;
-    // With the rail, the rail shows the step label, so the caption holds the narration only.
     const capTop = rail ? 20 : 26;
     const capH = steps.length ? capTop + 4 + Math.max(0, ...capLines) * 20 : 0;
     const W = only ? Math.max(560, rail.width) : Math.max(mapW, rail?.width ?? 0);
     const mapH = only ? 0 : bounds.h + pad * 2 + (arcs ? 44 : 0);
-    const top = only ? pad : mapH + RAIL.gap; // the rail's top
+    const top = only ? pad : mapH + RAIL.gap;
     const H = only ? pad + rail.height + capH : mapH + (rail ? RAIL.gap + rail.height : 0) + capH;
     const shift = (W - (bounds.w + pad * 2)) / 2;
     const railX = rail ? (W - rail.width) / 2 : 0;
-    // The step label and its narration, both switching with the beats.
     const labels = rail || synthetic
         ? []
         : steps.map((_, si) => {
@@ -721,23 +694,19 @@ export function render(fig, opts = {}) {
             lines.map((l, li) => `<text x="${n2(W / 2)}" y="${n2(H - capH + capTop + 16 + li * 20)}" class="caption">${esc(l)}</text>`).join('') +
             `</g>`);
     });
-    // The rail: lifelines under the map. Every part reuses a map part: the frame for a band, the edge-label pill for a payload, the card
-    // tag for `async`, the filled card for a parallel group. So the rail adds no color and no font size.
     const railSvg = !rail
         ? ''
         : (() => {
             const parts = [];
-            const cols = rail.head - RAIL.cols / 2 + 4; // the column-label baseline
+            const cols = rail.head - RAIL.cols / 2 + 4;
             for (const b of rail.bands)
                 parts.push(`<rect x="${n2(b.rect.x)}" y="${n2(top + b.rect.y)}" width="${n2(b.rect.w)}" height="${n2(b.rect.h)}" rx="10" fill="var(--surface)" stroke="var(--border)"/>` +
                     `<text x="${n2(b.rect.x + 10)}" y="${n2(top + b.rect.y + 14)}" class="frame">${esc(b.label.toUpperCase())}</text>`);
             for (const c of rail.columns)
                 parts.push(`<text x="${n2(c.x)}" y="${n2(top + cols)}" class="railcol">${esc(c.label)}</text>`);
-            // Where each row sits in each segment: it moves when another phase opens, and hides while its phase is folded.
             const at = (i) => segs.map((s) => railState(rail, s.si)[i]);
             const base = (i) => railState(rail, 0)[i].y;
             const moveRow = (i) => frames(at(i).map((st) => `transform: translateY(${n2(st.y - base(i))}px); opacity: ${st.shown ? 1 : 0}`), 'm');
-            // The lifelines run through the message rows only, so a phase header reads as one clear divider.
             rail.rows.forEach((row, i) => {
                 if (row.kind !== 'message')
                     return;
@@ -755,8 +724,7 @@ export function render(fig, opts = {}) {
                 if (row.kind === 'phase') {
                     const folded = segs.map((s) => rail.folds && s.si !== row.step);
                     const rule = (x1) => `<path d="M ${n2(x1)} ${n2(y + 15)} H ${n2(row.line.end)}" stroke="var(--border)"/>`;
-                    // One counter per beat of this phase, on this row, so it moves with the row. A parallel beat counts its first message.
-                    const first = new Map(); // beat -> the n of its first message
+                    const first = new Map();
                     for (const r of rail.rows)
                         if (r.kind === 'message' && r.step === row.step && !first.has(r.beat))
                             first.set(r.beat, r.n);
@@ -780,7 +748,6 @@ export function render(fig, opts = {}) {
                 const col = row.tone ? TONES[row.tone] : 'var(--accent)';
                 const lit = anim(now, `stroke: ${col}; stroke-width: ${EDGE_ON}`, `stroke: var(--muted); stroke-width: ${EDGE_OFF}`, row.tone ? 'e' + col : 'e');
                 const tagW = ASYNC_TAG_W;
-                // The tag sits on the tail side of the pill, so it never hides the arrowhead.
                 const tagX = !row.pill ? (x1 + x2) / 2 - tagW / 2 : x2 > x1 ? row.pill.x - tagW - 4 : row.pill.x + row.pill.w + 4;
                 const tag = row.async
                     ? `<rect x="${n2(tagX)}" y="${n2(ly - 6)}" width="${n2(tagW)}" height="12" rx="4" fill="var(--bg)"/>` +
@@ -831,7 +798,7 @@ ${only
         ? ''
         : `<g transform="translate(${n2(shift)} ${arcs ? 44 : 0})">
 ${axisSvg}
-${tl ? boxes.filter((b, i) => b && isGroup(placed[i].item)).join('\n') : ''}
+${tl ? boxes.filter((b, i) => b && isGroup(placed[i].item)).join('\n') : ''}${lineSvg && `\n${lineSvg}`}
 ${tl ? edgeSvg.join('\n') : ''}
 ${boxes.filter((b, i) => b && !(tl && isGroup(placed[i].item))).join('\n')}
 ${tl ? '' : edgeSvg.join('\n')}
@@ -851,16 +818,22 @@ ${said.join('\n')}
         edges: [
             ...(only ? [] : routed).flatMap((r) => {
                 const e = fig.edges[ids.indexOf(r.id)];
-                // A cross-block edge is two scene edges: each stub with its pill.
                 if (r.stub)
                     return r.stub.pts.map((pts, k) => ({ id: r.id, from: e.from, to: e.to, curve: r.curve, pts, label: r.stub.pills[k] }));
-                return [{ id: r.id, from: e.from, to: e.to, curve: r.curve, label: labelRects[r.id], ...(tl && { behind: true }) }];
+                return [
+                    {
+                        id: r.id,
+                        from: e.from,
+                        to: e.to,
+                        curve: r.curve,
+                        label: labelRects[r.id],
+                        ...(tl && { behind: true, elbow: r.elbow }),
+                    },
+                ];
             }),
-            // Each rail payload is a label too, in its own open-phase position, so label-overlap covers the rail.
             ...(rail?.rows ?? []).flatMap((row, i) => {
                 if (row.kind !== 'message')
                     return [];
-                // Scene coordinates are the map's layout coordinates: the page minus the map's translate(shift, arcs).
                 const dx = only ? railX : railX - shift, dy = only ? top : top - (arcs ? 44 : 0);
                 const y = dy + railState(rail, row.step)[i].y + RAIL.row / 2;
                 const [x1, x2] = [dx + rail.columns[row.from].x, dx + rail.columns[row.to].x];
@@ -878,30 +851,17 @@ ${said.join('\n')}
             }),
         ],
         minFont: Math.min(...fonts),
-        ...(stubs.size && {
+        ...(lanes && {
             lanes: placed.filter((p) => p.lane).map((p) => ({ id: str(p.item.label), rect: { x: p.x, y: p.y, w: p.w, h: p.h } })),
         }),
     };
     return { svg, scene };
 }
-/** The lanes wrap plan at the width and text size of `opts`, or null if the figure does not draw as lanes. A rail sets a least width. */
-function planFor(fig, opts) {
-    if (fig.timeline || !fig.lanes || !isLanesLayout(fig.layout))
-        return null;
-    const floor = fig.rail ? (layoutRail(fig, 560)?.width ?? 0) : 0;
-    return lanePlan(fig, { width: opts.width, minText: opts.minText, padding: opts.padding ?? 24, floor });
-}
 /** One self-contained animated SVG string for the figure. Needs no React and no browser. */
 export function toSvg(fig, opts = {}) {
     return render(fig, opts).svg;
 }
-/** Every fault `flowfig check` knows about, for this figure as the SVG lays it out. A `Finding` has a `rule` name, a `severity`, the ids it names and a message. */
+/** Every fault `flowfig check` knows about, for this figure as the SVG lays it out. */
 export function check(fig, opts = {}) {
-    const lost = (planFor(fig, opts)?.lost ?? []).map((id) => ({
-        rule: 'lane-end-block',
-        severity: 'warning',
-        ids: [id],
-        message: `edge "${id}" ends at a lane that no block on its side shows; the edge uses the nearest block`,
-    }));
-    return [...checkSpec(fig), ...checkScene(render(fig, opts).scene, opts), ...lost, ...checkTheme({ ...fig.theme, ...opts.theme })];
+    return checkRendered(fig, opts, render(fig, opts).scene);
 }

package/dist/text.d.ts

@@ -1,4 +1,2 @@
-/** The width of `s` in px at `fontSize`. */
 export declare function textWidth(s: string, fontSize: number, mono?: boolean): number;
-/** Break a string into lines that fit `width`, keeping the newlines it already has. */
 export declare function wrap(s: string, width: number, fontSize: number, mono?: boolean): string[];

package/dist/text.js

@@ -1,17 +1,14 @@
-// Text width without a browser: the SVG layout and `flowfig check` both run in plain node. Each character counts by its class in
-// the system sans-serif stack. Monospace is exact at 0.6em. The React player measures real text instead.
+// Estimated widths: no browser here. The React player measures real text.
 const FULL = /[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]|\p{Extended_Pictographic}/u;
 const NARROW = /[ilj.,:;'|!()[\]ftrI ]/;
 const WIDE = /[WMmw@%]/;
 const TALL = /[A-Z0-9#&?]/;
-/** The width of `s` in px at `fontSize`. */
 export function textWidth(s, fontSize, mono = false) {
     let em = 0;
     for (const ch of s)
         em += FULL.test(ch) ? 1 : mono ? 0.6 : WIDE.test(ch) ? 0.85 : NARROW.test(ch) ? 0.3 : TALL.test(ch) ? 0.64 : 0.53;
     return em * fontSize;
 }
-/** Break a string into lines that fit `width`, keeping the newlines it already has. */
 export function wrap(s, width, fontSize, mono = false) {
     const out = [];
     for (const para of s.split('\n')) {

package/dist/verify.d.ts

@@ -1,7 +1,7 @@
 import type { FlowProps } from './model.ts';
 import type { Finding } from './scene.ts';
 export { parseSource, headingSlug, owners, links, type Link } from './source.ts';
-/** The links against the files under `root`. A path outside the root is a missing file: the figure names the repo, not the disk. */
+/** The links against the files under `root`. A path outside `root` counts as a missing file. */
 export declare function verify(fig: FlowProps, { root }?: {
     root?: string;
 }): Finding[];