flowfig 0.4.0 → 0.6.0

package/dist/svg.js

@@ -8,15 +8,15 @@
 // Wrapping is therefore approximate; `flowfig check` uses the same measure, and the player check measures real text.
 import { route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.js';
-import { textWidth } from './text.js';
+import { textWidth, wrap } from './text.js';
 import { checkScene, checkSpec, checkTheme } 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, laneColumns, LANE_GAP, LANE_PAD, LANE_ROW_GAP, 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, 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, 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, NODE_MIN_W = 100, NODE_MAX_W = 190;
-const FRAME_TOP = 37, FRAME_SIDE = 18, FRAME_BOTTOM = 18;
+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.
 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. */
@@ -26,25 +26,6 @@ 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.
 const n4 = (v) => Math.round(v * 10000) / 10000;
 const pct = (v) => Math.round(v * 10000) / 100 + '%';
-/** Break a string into lines that fit `width`, keeping the newlines it already has. */
-function wrap(s, width, fontSize, mono = false) {
-    const out = [];
-    for (const para of s.split('\n')) {
-        let line = '';
-        for (const word of para.split(' ')) {
-            if (!line)
-                line = word;
-            else if (textWidth(line + ' ' + word, fontSize, mono) <= width)
-                line += ' ' + word;
-            else {
-                out.push(line);
-                line = word;
-            }
-        }
-        out.push(line);
-    }
-    return out;
-}
 /** 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. */
@@ -69,23 +50,16 @@ function layoutCard(c, width) {
     const height = rows.reduce((h, r) => h + (r.heads ? LINE : 0) + r.lines.length * LINE, 0) + ROW_GAP * Math.max(0, rows.length - 1) + CARD_PAD * 2;
     return { rows, height };
 }
-function nodeWidth(item, carded) {
-    if (item.width != null)
-        return item.width;
-    if (carded)
-        return CARD_WIDTH;
-    const label = textWidth(str(item.label), 14) + 32;
-    const sub = textWidth(str(item.sub), 12) + 32;
-    return Math.min(NODE_MAX_W, Math.max(NODE_MIN_W, label, sub));
-}
 function size(item, s) {
     if (!isGroup(item)) {
         const contents = s.cards.get(item.id);
-        const w = nodeWidth(item, contents != null);
+        const w = nodeWidth(item, contents != null) + (item.shape === 'decision' ? 70 : 0);
         const top = item.shape === 'store' ? 24 : 10;
         const card = contents ? 8 + s.cardH.get(item.id) : 0;
         const h = Math.max(top + LABEL_LINE + (item.sub ? SUB_LINE : 0) + card + 10, s.minH(item.id));
-        return item.shape === 'decision' ? { w: w + 70, h: h + 24 } : { w, h };
+        if (item.shape !== 'decision')
+            return { w, h };
+        return { w, h: contents ? h + 24 : Math.max(diamondLines(item, w).h, s.minH(item.id) + 24) };
     }
     const kids = item.children.map((c) => size(c, s));
     const gap = s.gap(item);
@@ -94,33 +68,55 @@ 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. */
+/** 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 = laneColumns(fig);
+    const { cols, starts, gaps, lead, blocks } = s.plan;
     const colW = Array.from({ length: Math.max(-1, ...cols.values()) + 1 }, () => 0);
     for (const lane of lanes)
         for (const b of lane.children)
             colW[cols.get(b.id)] = Math.max(colW[cols.get(b.id)], size(b, s).w);
     const gutter = gutterOf(lanes);
-    const colX = colW.map((_, c) => gutter + colW.slice(0, c).reduce((a, w) => a + w + LANE_GAP, 0));
-    const width = gutter + colW.reduce((a, w) => a + w, 0) + LANE_GAP * Math.max(0, colW.length - 1) + FRAME_SIDE;
+    const colsOf = (k) => colW.slice(starts[k], starts[k + 1]);
+    const colX = colW.map((_, c) => {
+        const k = laneBlock(starts, c);
+        return (gutter +
+            lead[k] +
+            colsOf(k)
+                .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 +
+            lead[k] +
+            ws.reduce((a, w) => a + w, 0) +
+            gaps.slice(starts[k], starts[k] + ws.length - 1).reduce((a, g) => a + g, 0) +
+            (gaps[starts[k] + ws.length - 1] ?? FRAME_SIDE));
+    }));
     const topAt = out.length;
     out.push({ x, y, w: width, h: 0, item: fig.layout });
     let ly = y;
-    for (const lane of lanes) {
-        const kids = lane.children.map((b) => ({ b, ...size(b, s) }));
-        const inner = Math.max(LABEL_LINE + 20, ...kids.map((k) => k.h));
-        const h = inner + LANE_PAD * 2;
-        out.push({ x, y: ly, w: width, h, item: lane, lane: true });
-        for (const k of kids)
-            out.push({ x: x + colX[cols.get(k.b.id)], y: ly + LANE_PAD + (inner - k.h) / 2, w: k.w, h: k.h, item: k.b });
-        ly += h + LANE_ROW_GAP;
-    }
+    blocks.forEach((bk, i) => {
+        if (i)
+            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));
+            const h = inner + LANE_PAD * 2 + (s.tall.has(`${lanes.indexOf(lane)}@${bk}`) ? STUB_ROOM : 0);
+            out.push({ x, y: ly, w: width, h, item: lane, lane: true, block: bk });
+            for (const k of kids)
+                out.push({ x: x + colX[cols.get(k.b.id)], y: ly + LANE_PAD + (inner - k.h) / 2, w: k.w, h: k.h, item: k.b });
+            ly += h + LANE_ROW_GAP;
+        }
+    });
     out[topAt].h = ly - LANE_ROW_GAP - y;
 }
-/** The width of the label gutter of lanes and of a timeline: the widest track label plus the frame sides. */
-const gutterOf = (lanes) => Math.max(0, ...lanes.map((l) => textWidth(str(l.label).toUpperCase(), 12))) + FRAME_SIDE * 2;
 /** 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;
@@ -210,7 +206,9 @@ export function render(fig, opts = {}) {
         return n > 2 ? n * 30 : 0;
     };
     const cardH = new Map();
-    const sizes = { cards, cardH, minH, gap: (g) => groupGap(g, fig.edges), fig };
+    const lanes = !tl && fig.lanes && isLanesLayout(fig.layout);
+    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 widths = [width];
@@ -218,7 +216,7 @@ export function render(fig, opts = {}) {
     }
     const placed = [];
     place(fig.layout, pad, pad, sizes, placed);
-    const nodes = placed.filter((p) => !isGroup(p.item));
+    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))
@@ -226,21 +224,55 @@ export function render(fig, opts = {}) {
         const inner = p.w - 20;
         cardH.set(p.item.id, Math.max(...cards.get(p.item.id).map((c) => layoutCard(c, inner).height), LINE + CARD_PAD * 2));
     }
-    placed.length = 0;
-    place(fig.layout, pad, pad, sizes, placed);
     const rects = {};
-    for (const p of placed)
-        if (p.item.id)
-            rects[p.item.id] = p;
     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);
-    const routed = route(fig.edges.map((e, i) => ({
-        id: ids[i],
-        from: e.from,
-        to: e.to,
-        around: e.around,
-        ...(tl && { sides: ['r', 'l'], elbow: true }),
-    })), rects, tips, placed.filter((p) => p.tl && !p.tl.labelInside).map((p) => outsideLabelRect(p, str(p.item.label))));
+    // 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];
+        const lane = laneGroups.find((l) => l.id === id || l.children.some((b) => b.id === id));
+        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);
+        for (const p of placed)
+            if (p.item.id)
+                rects[p.item.id] = p;
+        return route(fig.edges.map((e, i) => ({
+            id: ids[i],
+            from: end(ids[i], e.from, true),
+            to: end(ids[i], e.to, false),
+            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 || 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 timeline elbow keeps clear of the bars and milestones it does not connect.
+                ...placed.filter((p) => p.tl).map((p) => ({ x: p.x, y: p.y, w: p.w, h: p.h, box: true })),
+            ], 
+        // 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, 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++) {
+        const more = [...tightCopies(laneGroups, plan.ends, fig.edges, routed)].filter((k) => !sizes.tall.has(k));
+        if (!more.length)
+            break;
+        more.forEach((k) => sizes.tall.add(k));
+        routed = go();
+    }
+    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] : [])];
@@ -255,12 +287,18 @@ export function render(fig, opts = {}) {
             fonts.push(13);
             return { id: p.item.id, rect: { x: p.x, y: p.y, w: p.w, h: p.h }, texts: [{ text: label, fontSize: 13, room }] };
         }
-        const room = (p.item.shape === 'decision' ? p.w - 70 : p.w) - 16;
-        const texts = [{ text: str(p.item.label), fontSize: 14, room }];
-        if (p.item.sub) {
-            texts.push({ text: str(p.item.sub), fontSize: 12, room });
+        const dia = p.item.shape === 'decision' && !cards.has(p.item.id);
+        const dl = dia ? diamondLines(p.item, p.w) : null;
+        const room = (far) => diamondRoom(p.w, p.h, far);
+        const flat = (p.item.shape === 'decision' ? p.w - 70 : p.w) - 16;
+        const texts = [{ text: str(p.item.label), fontSize: 14, room: dl ? room(dl.label.far) : flat }];
+        if (dl)
+            for (const l of dl.subs)
+                texts.push({ text: l.text, fontSize: 12, room: room(l.far) });
+        else if (p.item.sub)
+            texts.push({ text: str(p.item.sub), fontSize: 12, room: flat });
+        if (p.item.sub)
             fonts.push(12);
-        }
         for (const c of cards.get(p.item.id) ?? [])
             for (const r of layoutCard(c, p.w - 20).rows) {
                 const fontSize = r.row.mono ? 10.5 : 11;
@@ -443,7 +481,8 @@ export function render(fig, opts = {}) {
         const cx = p.x + p.w / 2;
         const contents = cards.get(item.id);
         const cardTop = p.y + p.h - 10 - (contents ? cardH.get(item.id) : 0);
-        const labelY = item.shape === 'store' ? p.y + 24 + 13 : contents ? p.y + 10 + 13 : p.y + p.h / 2 + (item.sub ? -2 : 5);
+        const dl = item.shape === 'decision' && !contents ? diamondLines(item, p.w) : null;
+        const labelY = item.shape === 'store' ? p.y + 24 + 13 : contents ? p.y + 10 + 13 : p.y + p.h / 2 + (dl ? dl.label.dy : item.sub ? -2 : 5);
         const shape = item.shape === 'decision'
             ? `<polygon points="${n2(cx)},${n2(p.y)} ${n2(p.x + p.w)},${n2(p.y + p.h / 2)} ${n2(cx)},${n2(p.y + p.h)} ${n2(p.x)},${n2(p.y + p.h / 2)}" fill="${fill0}" stroke="${stroke0}"${stroke}/>`
             : item.shape === 'store'
@@ -451,7 +490,11 @@ export function render(fig, opts = {}) {
                     `<path d="M${n2(p.x)} ${n2(p.y + 12)} a ${n2(p.w / 2)} 12 0 0 0 ${n2(p.w)} 0" fill="none" stroke="${stroke0}"${rim}/>`
                 : `<rect x="${n2(p.x)}" y="${n2(p.y)}" width="${n2(p.w)}" height="${n2(p.h)}" rx="10" fill="${fill0}" stroke="${stroke0}"${stroke}/>`;
         const label = `<text x="${n2(cx)}" y="${n2(labelY)}" class="label">${esc(str(item.label))}</text>`;
-        const sub = item.sub ? `<text x="${n2(cx)}" y="${n2(labelY + SUB_LINE)}" class="sub">${esc(str(item.sub))}</text>` : '';
+        const sub = dl
+            ? dl.subs.map((l) => `<text x="${n2(cx)}" y="${n2(p.y + p.h / 2 + l.dy)}" class="sub">${esc(l.text)}</text>`).join('')
+            : 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);
@@ -531,20 +574,30 @@ export function render(fig, opts = {}) {
         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'));
-        const path = `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`;
+        // 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 label = e.label == null || tl
-            ? ''
-            : (() => {
-                const lw = labelPillW(str(e.label));
-                labelRects[r.id] = { x: r.mid.x - lw / 2, y: r.mid.y - 9, w: lw, h: 18 };
-                fonts.push(11);
-                return (`<rect x="${n2(r.mid.x - lw / 2)}" y="${n2(r.mid.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)')
-                        : anim(on, 'fill: var(--accent); stroke: var(--accent)', 'fill: var(--bg); stroke: var(--border)', 'l')) +
-                    `/><text x="${n2(r.mid.x)}" y="${n2(r.mid.y + 4)}"${cls('edgelabel', anim(on, `fill: ${ON_ACCENT}`, 'fill: var(--muted)', 'x'))}>${esc(str(e.label))}</text>`);
-            })();
+        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)')
+                : anim(on, 'fill: var(--accent); stroke: var(--accent)', 'fill: var(--bg); stroke: var(--border)', 'l')) +
+            `/><text x="${n2(x)}" y="${n2(y + 4)}"${cls('edgelabel', anim(on, `fill: ${ON_ACCENT}`, 'fill: var(--muted)', 'x'))}>${esc(text)}</text>`;
+        let label = '';
+        if (r.stub) {
+            fonts.push(11);
+            const texts = stubs.get(r.id);
+            label = r.stub.pills.map((p, k) => pill(p.x + p.w / 2, p.y + 9, p.w, k === 0 && r.stub.short ? texts[2] : texts[k])).join('');
+        }
+        else if (e.label != null && !tl) {
+            const lw = labelPillW(str(e.label));
+            labelRects[r.id] = { x: r.mid.x - lw / 2, y: r.mid.y - 9, w: lw, h: 18 };
+            fonts.push(11);
+            label = pill(r.mid.x, r.mid.y, lw, str(e.label));
+        }
         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`
@@ -569,8 +622,8 @@ 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 = '';
+    // The timeline axis, the fixed today marker and the moving playhead. Their lines sit behind the bars, their labels on top.
+    let axisSvg = '', lineSvg = '', todaySvg = '';
     if (tl) {
         const top = placed[0];
         const x0 = top.x + gutterOf(fig.layout.children);
@@ -586,19 +639,21 @@ export function render(fig, opts = {}) {
         // 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.
+        // The playhead moves to the start of each beat's item, then to the last date in the step hold. The loop starts with
+        // the playhead at the first beat's item, so the first frame shows the first beat; the last hold moves it back there.
         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 first = loopStartItem(tl.items, steps);
+            const start = first ? startOf.get(first.id) : home;
+            const pts = [[0, start]];
             const dates = []; // the label date in each time span
-            let at = home;
+            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;
@@ -606,15 +661,20 @@ export function render(fig, opts = {}) {
                 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
                 pts.push([s.t0, at], [Math.min(s.t0 + RAMP, end), to], [end, to]);
-                const [la, lb] = labelSpan(s.t0, end, RAMP);
+                // The label waits for the line, except at the loop start, where the line is already in place.
+                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);
+                    // The last hold of the loop ends with the move back to the loop start.
+                    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;
                 }
             });
@@ -639,11 +699,12 @@ export function render(fig, opts = {}) {
                 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) => e.around);
+    const arcs = fig.edges.some((e, i) => (e.around || plan?.around.has(ids[i])) && !stubs.has(ids[i])); // a stub does not arc
     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.
@@ -782,7 +843,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')}
@@ -800,9 +861,22 @@ ${said.join('\n')}
         width: n2(W),
         boxes: only ? [] : sceneBoxes,
         edges: [
-            ...(only ? [] : routed).map((r) => {
+            ...(only ? [] : routed).flatMap((r) => {
                 const e = fig.edges[ids.indexOf(r.id)];
-                return { id: r.id, from: e.from, to: e.to, curve: r.curve, label: labelRects[r.id], ...(tl && { behind: true }) };
+                // 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] }));
+                // A timeline edge is drawn behind, but `check` still tests its elbow against the boxes it does not connect.
+                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) => {
@@ -826,14 +900,30 @@ ${said.join('\n')}
             }),
         ],
         minFont: Math.min(...fonts),
+        ...(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. */
 export function check(fig, opts = {}) {
-    return [...checkSpec(fig), ...checkScene(render(fig, opts).scene, opts), ...checkTheme({ ...fig.theme, ...opts.theme })];
+    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 })];
 }

package/dist/text.d.ts

@@ -1,2 +1,4 @@
 /** 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

@@ -11,3 +11,22 @@ export function textWidth(s, fontSize, mono = false) {
         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')) {
+        let line = '';
+        for (const word of para.split(' ')) {
+            if (!line)
+                line = word;
+            else if (textWidth(line + ' ' + word, fontSize, mono) <= width)
+                line += ' ' + word;
+            else {
+                out.push(line);
+                line = word;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}

package/dist/verify.js

@@ -1,6 +1,6 @@
 // `flowfig verify`: checks that the code a link names is still there. The link parsing lives in source.ts, which has no Node import.
 import { readFileSync, statSync } from 'node:fs';
-import { isAbsolute, relative, resolve } from 'node:path';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { headingSlug, links } from './source.js';
 export { parseSource, headingSlug, owners, links } from './source.js';
 const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -28,7 +28,7 @@ export function verify(fig, { root = process.cwd() } = {}) {
     for (const l of all) {
         const full = resolve(root, l.path);
         const rel = relative(root, full);
-        const outside = isAbsolute(l.path) || rel === '..' || rel.startsWith('../');
+        const outside = isAbsolute(l.path) || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
         if (!files.has(full))
             files.set(full, outside ? null : read(full));
         const text = files.get(full);

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** The package version, for the MCP `serverInfo`. The release list bumps it with package.json. */
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.6.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** The package version, for the MCP `serverInfo`. The release list bumps it with package.json. */
-export const VERSION = '0.4.0';
+export const VERSION = '0.6.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowfig",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Your coding agent draws animated diagrams from your code, and flowfig checks them. One animated SVG for a GitHub README, PR or issue, and a React player. Set up Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf and Kiro with npx flowfig init.",
   "license": "MIT",
   "repository": {