flowfig 0.4.0 → 0.6.0

package/dist/index.js

@@ -5,7 +5,7 @@ import { route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.js';
 import { textWidth } from './text.js';
 import { checkScene, checkSpec, checkTheme } from './check.js';
-import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, EDGE_OFF, EDGE_ON, LIGHT, TONES, ON_ACCENT, toneFill, toneTint, decisions, edgeId, groupGap, isGroup, isRows, laneColumns, LANE_GAP, LANE_PAD, LANE_ROW_GAP, isLanesLayout, nodes, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, beatMs, STEP_HOLD_MS, playheadItem, dateLabelRaised, } from './model.js';
+import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, EDGE_OFF, EDGE_ON, LIGHT, TONES, ON_ACCENT, toneFill, toneTint, decisions, edgeId, groupGap, isGroup, isRows, lanePlan as planLanes, laneEnd, laneBlock, STUB_ROOM, labelPillW, str, LANE_BLOCK_GAP, LANE_PAD, LANE_ROW_GAP, isLanesLayout, nodes, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, diamondLines, diamondRoom, tightCopies, nodeWidth, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const DEFAULTS = { ...LIGHT, font: 'inherit' };
 const v = (k) => `var(--fig-${k}, ${DEFAULTS[k]})`;
@@ -72,8 +72,18 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
     const bar = useRef(null); // the active tab's progress line
     const [beat, setBeat] = useState(0);
     const [holding, setHolding] = useState(false); // the step hold: a timeline's today line rests at today
+    const [returning, setReturning] = useState(false); // the end of the last hold: the playhead moves back to the loop start
+    const firstLabel = useRef(''); // the playhead date of the first mount, which shows at once; '' before the first render
     const paths = useRef({});
     const [routed, setRouted] = useState([]);
+    // Lane copies that grow because a stub there had no place clear of every edge path (see `tightCopies`).
+    const [extraTall, setExtraTall] = useState(new Set());
+    // Lanes: the shared wrap plan (blocks, gaps, stubs), the same as the SVG at the default 830 px width.
+    const lanePlan = useMemo(() => lanes && !tl && isLanesLayout(layout)
+        ? planLanes({ layout, edges, steps, lanes }, 
+        // A rail sets a least width, as in the SVG.
+        { floor: withRail ? (layoutRail({ layout, edges, steps, rail: true }, 560)?.width ?? 0) : 0 })
+        : null, [lanes, tl, layout, edges, steps, withRail]);
     const [active, setActive] = useState(steps.length ? 0 : null);
     const [playing, setPlaying] = useState(autoplay);
     // The step's clock lives outside React: pausing freezes it, resizing keeps it, only a new step resets it.
@@ -169,13 +179,67 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                 const r = n.getBoundingClientRect();
                 avoid.push({ x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k });
             });
-            setRouted(route(edges.map((e, i) => ({
+            // A timeline elbow keeps clear of the bars and milestones it does not connect, as in the SVG.
+            if (tl)
+                for (const n of nodes(layout))
+                    if (rects[n.id])
+                        avoid.push({ ...rects[n.id], box: true });
+            // Wrapped lanes: an edge between two blocks is two stubs with pills, clear of the boxes and the lane labels.
+            const stubs = lanePlan?.stubs ?? new Map();
+            if (stubs.size) {
+                for (const n of nodes(layout))
+                    if (rects[n.id])
+                        avoid.push(rects[n.id]);
+                el.querySelectorAll('[data-fig-gutter]').forEach((n) => {
+                    const r = n.getBoundingClientRect();
+                    avoid.push({ x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k });
+                });
+            }
+            // A wrapped lane end routes to the band of its block (`data-fig-copy`), as in the SVG.
+            const bands = {};
+            el.querySelectorAll('[data-fig-copy]').forEach((n) => {
+                const r = n.getBoundingClientRect();
+                bands[n.dataset.figCopy] = { x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k };
+            });
+            // A stub pill stays in the lanes, right of the gutter, as in the SVG.
+            const blockRects = [...el.querySelectorAll('[data-fig-block]')].map((n) => n.getBoundingClientRect());
+            const pillArea = stubs.size && blockRects.length
+                ? (() => {
+                    const [x0, y0] = [Math.min(...blockRects.map((r) => r.left)), Math.min(...blockRects.map((r) => r.top))];
+                    const [x1, y1] = [Math.max(...blockRects.map((r) => r.right)), Math.max(...blockRects.map((r) => r.bottom))];
+                    const x = (x0 - base.left) / k + lanePlan.gutter;
+                    return { x, y: (y0 - base.top) / k, w: (x1 - base.left) / k - x, h: (y1 - y0) / k };
+                })()
+                : undefined;
+            // The band of an edge end, in the block of that end, as in the SVG.
+            const laneBands = {};
+            el.querySelectorAll('[data-fig-band]').forEach((n) => {
+                const r = n.getBoundingClientRect();
+                laneBands[n.dataset.figBand] = { x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k };
+            });
+            const bandOf = (eid, id, j) => {
+                const li = layout.children.findIndex((l) => isGroup(l) && (l.id === id || l.children.some((b) => b.id === id)));
+                return laneBands[`${li}@${lanePlan?.ends.get(eid)?.[j]}`];
+            };
+            const end = (eid, id, start) => lanePlan ? laneEnd(lanePlan, eid, id, start, (lane, b) => bands[`${lane}@${b}`], rects) : id;
+            const next = route(edges.map((e, i) => ({
                 id: ids[i],
-                from: e.from,
-                to: e.to,
-                around: e.around,
+                from: end(ids[i], e.from, true),
+                to: end(ids[i], e.to, false),
+                around: e.around ?? (lanePlan?.around.has(ids[i]) ? 'below' : undefined),
                 ...(tl && { sides: ['r', 'l'], elbow: true }),
-            })), rects, tips, avoid));
+                ...(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 || lanePlan) && e.label != null && { labelW: labelPillW(str(e.label)) }),
+            })), rects, tips, avoid, pillArea, lanePlan ? { bands: Object.values(laneBands), boxes: nodes(layout).flatMap((n) => (rects[n.id] ? [rects[n.id]] : [])) } : undefined);
+            setRouted(next);
+            if (lanePlan) {
+                const more = [...tightCopies(layout.children, lanePlan.ends, edges, next)].filter((k) => !lanePlan.tall.has(k) && !extraTall.has(k));
+                if (more.length)
+                    setExtraTall(new Set([...extraTall, ...more]));
+            }
         };
         measure();
         const ro = new ResizeObserver(measure);
@@ -183,7 +247,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         ro.observe(box);
         el.querySelectorAll('[data-fig]').forEach((n) => ro.observe(n));
         return () => ro.disconnect();
-    }, [edges, ids, layout, tips, noMap, lanes, tl, axisW]);
+    }, [edges, ids, layout, tips, noMap, lanes, tl, axisW, lanePlan, extraTall]);
     // The same rules as `flowfig check`, on what the browser actually drew: real fonts, real wrapping. Each fault prints once.
     const reported = useRef(new Set());
     useEffect(() => {
@@ -201,16 +265,30 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         const boxIds = new Set(nodes(layout).map((n) => n.id));
         const boxes = [...(el ?? fig).querySelectorAll('[data-fig]')]
             .filter((n) => boxIds.has(n.dataset.fig))
-            .map((n) => ({
-            id: n.dataset.fig,
-            rect: rel(n),
-            texts: [...n.querySelectorAll('*')]
-                .filter((t) => !t.children.length && t.textContent?.trim() && t.clientWidth > 0 && !t.closest('[aria-hidden]'))
-                .map((t) => {
-                const fontSize = parseFloat(getComputedStyle(t).fontSize);
-                return { text: t.textContent, fontSize, room: t.clientWidth, need: t.scrollWidth };
-            }),
-        }));
+            .map((n) => {
+            const rect = rel(n);
+            return {
+                id: n.dataset.fig,
+                rect,
+                texts: [...n.querySelectorAll('*')]
+                    .filter((t) => !t.children.length && t.textContent?.trim() && t.clientWidth > 0 && !t.closest('[aria-hidden]'))
+                    .map((t) => {
+                    const fontSize = parseFloat(getComputedStyle(t).fontSize);
+                    if (!n.dataset.diamond)
+                        return { text: t.textContent, fontSize, room: t.clientWidth, need: t.scrollWidth };
+                    // A diamond gives a line the width of its outline at the far edge of the line, and the line is as wide as its text.
+                    const [r, range] = [rel(t), document.createRange()];
+                    range.selectNodeContents(t);
+                    const far = Math.max(Math.abs(r.y - rect.y - rect.h / 2), Math.abs(r.y + r.h - rect.y - rect.h / 2));
+                    return {
+                        text: t.textContent,
+                        fontSize,
+                        room: diamondRoom(rect.w, rect.h, far),
+                        need: range.getBoundingClientRect().width / k,
+                    };
+                }),
+            };
+        });
         // Every visible leaf text counts, as in the SVG scene; the 9 px tag pills do not.
         // The rail is a sibling of the map, so the rail queries start at the figure. An SVG <text> has no CSS box, so it skips clientWidth.
         const fonts = [...fig.querySelectorAll('*')]
@@ -220,13 +298,23 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             !t.closest('[data-fig-tag],[aria-hidden]'))
             .map((t) => parseFloat(getComputedStyle(t).fontSize));
         const labels = Object.fromEntries([...fig.querySelectorAll('[data-fig-label]')].map((n) => [n.dataset.figLabel, rel(n)]));
+        const lanesIn = el ? [...el.querySelectorAll('[data-fig-band]')] : [];
         const scene = {
             width: Math.max(el?.offsetWidth ?? 0, rail?.width ?? 0),
             boxes,
+            ...(lanePlan?.stubs.size && {
+                lanes: lanesIn.map((n) => ({
+                    id: str(layout.children[Number(n.dataset.figBand.split('@')[0])].label),
+                    rect: rel(n),
+                })),
+            }),
             edges: [
-                ...routed.map((r) => {
+                ...routed.flatMap((r) => {
                     const e = edges[ids.indexOf(r.id)];
-                    return { id: r.id, from: e.from, to: e.to, curve: r.curve, label: labels[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, j) => ({ id: r.id, from: e.from, to: e.to, curve: r.curve, pts, label: labels[`${r.id}:${j}`] }));
+                    return [{ id: r.id, from: e.from, to: e.to, curve: r.curve, label: labels[r.id], ...(tl && { behind: true }) }];
                 }),
                 // A rail pill is a label for label-overlap; its curve is a point at the pill center, so it can cross no box.
                 ...(rail?.rows ?? []).flatMap((row) => {
@@ -259,7 +347,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             reported.current.add(key);
             console.warn(`flowfig check: ${f.severity} ${f.rule}: ${f.message}`);
         }
-    }, [check, routed, layout, edges, steps, ids, theme, rail, noMap]);
+    }, [check, routed, layout, edges, steps, ids, theme, rail, noMap, lanePlan]);
     // Play the step's beats: each moves its packets (and their data cards) along its edges, then the next step starts.
     useEffect(() => {
         const gs = dots.current, cs = chips.current, edgeOf = Object.fromEntries(edges.map((e, i) => [ids[i], e]));
@@ -297,6 +385,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             if (i !== shownBeat)
                 setBeat((shownBeat = i));
             setHolding(t >= ends.at(-1));
+            setReturning(active === steps.length - 1 && t >= total - 400 * BASE_RATE);
             const start = i ? ends[i - 1] : 0;
             const f = Math.min(1, (t - start) / speed); // the packet crosses in `speed`; the hold gives the rest
             const eased = f < 0.5 ? 2 * f * f : 1 - (-2 * f + 2) ** 2 / 2;
@@ -434,11 +523,52 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         if (timelineFig && item === layout) {
             const lanesList = layout.children;
             // The playhead follows the latest dated focus in the step, and rests at the last date before one and in the hold.
-            const focused = holding || still ? undefined : playheadItem(timelineFig.items, beats, beat);
+            // In the last 400 ms of the loop it moves back to the loop start, so the next loop starts in place, as in the SVG.
+            const focused = still
+                ? undefined
+                : returning
+                    ? loopStartItem(timelineFig.items, steps)
+                    : holding
+                        ? undefined
+                        : playheadItem(timelineFig.items, beats, beat);
             const home = timelineFig.last ?? 0;
             const at = focused ? focused.x + (focused.milestone ? focused.w / 2 : 0) : home;
             const dateText = focused ? focused.date : timelineFig.lastDate;
             const rowsPx = timelineFig.rows.map((r) => r * TL_BAR_H + (r - 1) * TL_ROW_GAP + LANE_PAD * 2);
+            // The today line and the playhead line sit behind the bars (before them, at the bars' z-index); their labels sit on top.
+            // The playhead label waits for the line, except on the first mount, where the line starts in place.
+            if (firstLabel.current === '')
+                firstLabel.current = dateText;
+            else if (firstLabel.current !== dateText)
+                firstLabel.current = null;
+            const marks = (front) => timelineFig.last != null && (_jsxs("div", { style: { gridColumn: '2 / 4', gridRow: '1 / -1', position: 'relative', zIndex: front ? 2 : 1, pointerEvents: 'none' }, children: [timelineFig.today != null && (_jsx("div", { "data-fig-today": front ? undefined : '', style: { position: 'absolute', left: timelineFig.today, top: 12, bottom: 0, width: 0 }, children: front ? (_jsx("span", { style: {
+                                position: 'absolute',
+                                right: 3,
+                                top: -1,
+                                fontSize: 11,
+                                lineHeight: '11px',
+                                fontWeight: 600,
+                                color: v('accent'),
+                            }, children: "today" })) : (_jsx("div", { style: { position: 'absolute', top: 0, bottom: 0, borderLeft: `1px dashed ${v('accent')}`, opacity: 0.6 } })) })), _jsx("div", { "data-fig-playhead": front ? undefined : '', style: {
+                            position: 'absolute',
+                            left: 0,
+                            top: 12,
+                            bottom: 0,
+                            width: front ? 0 : 1.5,
+                            background: front ? undefined : v('accent'),
+                            transform: `translateX(${at}px)`,
+                            transition: still ? 'none' : 'transform .4s linear',
+                        }, children: front && (_jsx("span", { style: {
+                                position: 'absolute',
+                                left: 3,
+                                top: dateLabelRaised(at, timelineFig.today, textWidth(dateText, 11), textWidth('today', 11)) ? -13 : -1,
+                                fontSize: 11,
+                                lineHeight: '11px',
+                                fontWeight: 600,
+                                whiteSpace: 'nowrap',
+                                color: v('accent'),
+                                animation: still || firstLabel.current === dateText ? undefined : 'flowfig-label .4s step-end',
+                            }, children: dateText }, dateText)) })] }));
             return (_jsxs("div", { style: {
                     display: 'grid',
                     gridTemplateColumns: `max-content minmax(${TL_AXIS_W}px, 1fr) 18px`,
@@ -446,7 +576,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     gridTemplateRows: `${TL_AXIS_H - LANE_ROW_GAP}px ${rowsPx.map((h) => h + 'px').join(' ')}`,
                     rowGap: LANE_ROW_GAP,
                     position: 'relative',
-                }, children: [_jsxs("div", { "data-fig-axis": "", style: { gridColumn: '2 / 4', gridRow: 1, position: 'relative', height: TL_AXIS_H, alignSelf: 'start' }, children: [_jsx("div", { style: { position: 'absolute', left: 0, right: 0, top: TL_AXIS_H - 1, height: 1, background: v('border') } }), timelineFig.ticks.map((k) => (_jsxs(Fragment, { children: [_jsx("div", { style: { position: 'absolute', left: k.x, top: TL_AXIS_H - 5, width: 1, height: 4, background: v('border') } }), _jsx("div", { style: { position: 'absolute', left: k.x + 3, top: 0, fontSize: 11, lineHeight: '13px', color: v('muted') }, children: k.label })] }, k.x)))] }), lanesList.map((lane, li) => {
+                }, children: [marks(false), _jsxs("div", { "data-fig-axis": "", style: { gridColumn: '2 / 4', gridRow: 1, position: 'relative', height: TL_AXIS_H, alignSelf: 'start' }, children: [_jsx("div", { style: { position: 'absolute', left: 0, right: 0, top: TL_AXIS_H - 1, height: 1, background: v('border') } }), timelineFig.ticks.map((k) => (_jsxs(Fragment, { children: [_jsx("div", { style: { position: 'absolute', left: k.x, top: TL_AXIS_H - 5, width: 1, height: 4, background: v('border') } }), _jsx("div", { style: { position: 'absolute', left: k.x + 3, top: 0, fontSize: 11, lineHeight: '13px', color: v('muted') }, children: k.label })] }, k.x)))] }), lanesList.map((lane, li) => {
                         const lit = lane.id != null && litNodes.has(lane.id);
                         return (_jsxs(Fragment, { children: [_jsx("div", { "data-fig": lane.id, "data-fig-lane": "", style: {
                                         gridColumn: '1 / -1',
@@ -471,75 +601,63 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                     }, children: lane.label }), _jsx("div", { ref: li === 0 ? area : undefined, style: { gridColumn: 2, gridRow: li + 2, position: 'relative', zIndex: 1 }, children: timelineFig.items
                                         .filter((it) => it.track === li)
                                         .map((it) => renderBar(lane.children.find((k) => k.id === it.id), it)) })] }, lane.id ?? String(lane.label)));
-                    }), timelineFig.last != null && (_jsxs("div", { style: { gridColumn: '2 / 4', gridRow: '1 / -1', position: 'relative', zIndex: 2, pointerEvents: 'none' }, children: [timelineFig.today != null && (_jsxs("div", { "data-fig-today": "", style: { position: 'absolute', left: timelineFig.today, top: 12, bottom: 0, width: 0 }, children: [_jsx("div", { style: { position: 'absolute', top: 0, bottom: 0, borderLeft: `1px dashed ${v('accent')}`, opacity: 0.6 } }), _jsx("span", { style: {
-                                            position: 'absolute',
-                                            right: 3,
-                                            top: -1,
-                                            fontSize: 11,
-                                            lineHeight: '11px',
-                                            fontWeight: 600,
-                                            color: v('accent'),
-                                        }, children: "today" })] })), _jsx("div", { "data-fig-playhead": "", style: {
-                                    position: 'absolute',
-                                    left: 0,
-                                    top: 12,
-                                    bottom: 0,
-                                    width: 1.5,
-                                    background: v('accent'),
-                                    transform: `translateX(${at}px)`,
-                                    transition: still ? 'none' : 'transform .4s linear',
-                                }, children: _jsx("span", { style: {
-                                        position: 'absolute',
-                                        left: 3,
-                                        top: dateLabelRaised(at, timelineFig.today, textWidth(dateText, 11), textWidth('today', 11)) ? -13 : -1,
-                                        fontSize: 11,
-                                        lineHeight: '11px',
-                                        fontWeight: 600,
-                                        whiteSpace: 'nowrap',
-                                        color: v('accent'),
-                                        animation: still ? undefined : 'flowfig-label .4s step-end',
-                                    }, children: dateText }, dateText) })] }))] }));
+                    }), marks(true)] }));
         }
         if (lanes && item === layout && isLanesLayout(layout)) {
-            const cols = laneColumns({ layout, edges, steps, lanes });
+            const { cols, starts, gaps, lead, blocks, gutter, tall } = lanePlan;
             const n = Math.max(0, ...cols.values()) + 1;
-            return (_jsx("div", { style: {
-                    display: 'grid',
-                    gridTemplateColumns: `max-content repeat(${n}, max-content)`,
-                    columnGap: 0,
-                    rowGap: LANE_ROW_GAP,
-                    position: 'relative',
-                }, children: layout.children.map((lane, li) => {
-                    const lit = lane.id != null && litNodes.has(lane.id);
-                    return (_jsxs(Fragment, { children: [_jsx("div", { "data-fig": lane.id, "data-fig-lane": "", style: {
-                                    gridColumn: '1 / -1',
-                                    gridRow: li + 1,
-                                    background: v('surface'),
-                                    border: `1px solid ${lit ? v('accent') : v('border')}`,
-                                    boxShadow: lit ? glow : undefined,
-                                    transition: 'border-color .25s, box-shadow .25s',
-                                    borderRadius: 14,
-                                    zIndex: 0,
-                                } }), _jsx("div", { style: {
-                                    gridColumn: 1,
-                                    gridRow: li + 1,
-                                    alignSelf: 'center',
-                                    zIndex: 1,
-                                    padding: '0 18px',
-                                    fontSize: 12,
-                                    fontWeight: 600,
-                                    letterSpacing: '.04em',
-                                    textTransform: 'uppercase',
-                                    color: v('muted'),
-                                }, children: lane.label }), lane.children.map((b) => (_jsx("div", { style: {
-                                    gridColumn: cols.get(b.id) + 2,
-                                    gridRow: li + 1,
-                                    alignSelf: 'center',
-                                    zIndex: 1,
-                                    // The last time column keeps the frame side, as in the SVG.
-                                    padding: `${LANE_PAD}px ${cols.get(b.id) === n - 1 ? 18 : LANE_GAP}px ${LANE_PAD}px 0`,
-                                }, children: renderItem(b, 1) }, b.id)))] }, lane.id ?? String(lane.label)));
-                }) }));
+            const count = blocks.length;
+            // One grid per block of `per` time columns, as in the SVG. A wrapped block shows only the lanes with a box in it.
+            const grid = (bk) => {
+                const m = starts[bk + 1] - starts[bk];
+                const inBlock = (b) => laneBlock(starts, cols.get(b.id)) === bk;
+                const shown = layout.children.filter((lane) => count < 2 || lane.children.some(inBlock));
+                return (_jsx("div", { "data-fig-block": bk, style: {
+                        display: 'grid',
+                        // A wrapped block stretches to the widest block, so all bands share one width.
+                        // Every block has the gutter of the plan, so the labels and the columns line up as in the SVG.
+                        gridTemplateColumns: `${gutter}px repeat(${m}, max-content)${count > 1 ? ' 1fr' : ''}`,
+                        // An empty lane keeps the SVG's least band height: a 38 px label line plus the lane padding.
+                        gridAutoRows: `minmax(${38 + LANE_PAD * 2}px, auto)`,
+                        columnGap: 0,
+                        rowGap: LANE_ROW_GAP,
+                        position: 'relative',
+                    }, children: shown.map((lane, li) => {
+                        const lit = lane.id != null && litNodes.has(lane.id);
+                        return (_jsxs(Fragment, { children: [_jsx("div", { "data-fig": lane.id, "data-fig-copy": lane.id != null ? `${lane.id}@${bk}` : undefined, "data-fig-band": `${layout.children.indexOf(lane)}@${bk}`, "data-fig-lane": "", style: {
+                                        gridColumn: '1 / -1',
+                                        gridRow: li + 1,
+                                        background: v('surface'),
+                                        border: `1px solid ${lit ? v('accent') : v('border')}`,
+                                        boxShadow: lit ? glow : undefined,
+                                        transition: 'border-color .25s, box-shadow .25s',
+                                        borderRadius: 14,
+                                        zIndex: 0,
+                                    } }), _jsx("div", { "data-fig-gutter": "", style: {
+                                        gridColumn: 1,
+                                        gridRow: li + 1,
+                                        alignSelf: 'center',
+                                        zIndex: 1,
+                                        padding: '0 18px',
+                                        whiteSpace: 'nowrap',
+                                        fontSize: 12,
+                                        fontWeight: 600,
+                                        letterSpacing: '.04em',
+                                        textTransform: 'uppercase',
+                                        color: v('muted'),
+                                    }, children: lane.label }), lane.children.filter(inBlock).map((b) => (_jsx("div", { style: {
+                                        gridColumn: cols.get(b.id) - starts[bk] + 2,
+                                        gridRow: li + 1,
+                                        alignSelf: 'center',
+                                        zIndex: 1,
+                                        // The space after each column and before a block's first column comes from the plan, as in the SVG.
+                                        padding: `${LANE_PAD}px ${gaps[cols.get(b.id)]}px ${LANE_PAD + (tall.has(`${layout.children.indexOf(lane)}@${bk}`) || extraTall.has(`${layout.children.indexOf(lane)}@${bk}`) ? STUB_ROOM : 0)}px ${cols.get(b.id) === starts[bk] ? lead[bk] : 0}px`,
+                                    }, children: renderItem(b, 1) }, b.id)))] }, lane.id ?? String(lane.label)));
+                    }) }, bk));
+            };
+            if (count < 2)
+                return grid(blocks[0]);
+            return _jsx("div", { style: { display: 'flex', flexDirection: 'column', gap: LANE_BLOCK_GAP }, children: blocks.map(grid) });
         }
         if (isGroup(item)) {
             const lit = item.id != null && litNodes.has(item.id);
@@ -578,14 +696,16 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         const diamond = item.shape === 'decision';
         const store = item.shape === 'store';
         const card = carded.has(item.id);
+        // The sub of a diamond wraps as in the SVG, one div per line, so a line stays inside the outline.
+        const dl = diamond && !card ? diamondLines(item, nodeWidth(item, false) + 70) : null;
         const bt = item.tone && TONES[item.tone];
         return (_jsxs("div", { "data-fig": item.id, "data-diamond": diamond || undefined, onMouseEnter: () => setHover(item.id), onMouseLeave: () => setHover(null), style: {
                 position: 'relative',
                 isolation: 'isolate',
                 minWidth: 100,
-                maxWidth: card ? undefined : 190,
-                width: item.width ?? (card ? CARD_WIDTH : undefined),
-                minHeight: minHeight(item.id),
+                maxWidth: card || diamond ? undefined : 190,
+                width: diamond ? nodeWidth(item, card) + 70 : (item.width ?? (card ? CARD_WIDTH : undefined)),
+                minHeight: dl ? Math.max(dl.h, (minHeight(item.id) ?? 0) + 24) : minHeight(item.id),
                 boxSizing: 'border-box',
                 display: 'flex',
                 flexDirection: 'column',
@@ -637,7 +757,9 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                 border: `1.5px solid ${bt ?? v('accent')}`,
                                 background: `radial-gradient(circle, ${bt ?? v('accent')} 0 4px, transparent 4.5px)`,
                             }),
-                    } })), _jsx("div", { children: item.label }), item.sub != null && _jsx("div", { style: { fontSize: 12, fontWeight: 400, color: v('muted'), marginTop: 2 }, children: item.sub }), card && (_jsxs("div", { style: {
+                    } })), _jsx("div", { children: item.label }), dl
+                    ? dl.subs.map((l, i) => (_jsx("div", { style: { fontSize: 12, fontWeight: 400, color: v('muted'), lineHeight: '15px', whiteSpace: 'nowrap' }, children: l.text }, i)))
+                    : item.sub != null && _jsx("div", { style: { fontSize: 12, fontWeight: 400, color: v('muted'), marginTop: 2 }, children: item.sub }), card && (_jsxs("div", { style: {
                         marginTop: 8,
                         padding: '6px 8px',
                         minHeight: item.lines != null ? item.lines * CARD_LINE + CARD_PAD * 2 + 1 : undefined,
@@ -710,8 +832,11 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                 transformOrigin: 'top left',
                                 padding: 4,
                                 // room for edges that arc over or under the boxes
-                                paddingTop: edges.some((e) => e.around === 'above') ? 44 : 4,
-                                paddingBottom: edges.some((e) => e.around === 'below') ? 44 : 4,
+                                // A stub does not arc.
+                                paddingTop: edges.some((e, i) => e.around === 'above' && !lanePlan?.stubs.has(ids[i])) ? 44 : 4,
+                                paddingBottom: edges.some((e, i) => (e.around === 'below' || (!e.around && lanePlan?.around.has(ids[i]))) && !lanePlan?.stubs.has(ids[i]))
+                                    ? 44
+                                    : 4,
                             }, children: [renderItem(layout, 0), _jsxs("svg", { style: {
                                         position: 'absolute',
                                         inset: 0,
@@ -725,9 +850,18 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                             const on = litEdges.has(r.id);
                                             const tone = hopTone(r.id);
                                             const hidden = !on && edges[ids.indexOf(r.id)].quiet;
-                                            return (_jsx("path", { ref: (p) => {
+                                            const look = (d, key, guides = false) => (_jsx("path", { ref: guides
+                                                    ? (p) => {
+                                                        paths.current[r.id] = p;
+                                                    }
+                                                    : undefined, d: d, fill: "none", stroke: on ? (tone ?? v('accent')) : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeOpacity: hidden ? 0 : focus && !on ? 0.35 : 1, markerEnd: hidden ? undefined : `url(#fig-arrow-${on ? 'on' : 'off'})`, style: { transition: 'stroke .25s, stroke-opacity .25s' } }, key));
+                                            const guide = (_jsx("path", { ref: (p) => {
                                                     paths.current[r.id] = p;
-                                                }, d: r.d, fill: "none", stroke: on ? (tone ?? v('accent')) : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeOpacity: hidden ? 0 : focus && !on ? 0.35 : 1, markerEnd: hidden ? undefined : `url(#fig-arrow-${on ? 'on' : 'off'})`, style: { transition: 'stroke .25s, stroke-opacity .25s' } }, r.id));
+                                                }, d: r.d, fill: "none", stroke: "none" }, r.id));
+                                            // A cross-block edge draws its two stubs; its full path only guides the packet, which jumps between the blocks.
+                                            if (r.stub)
+                                                return [...r.stub.parts.map((d, j) => look(d, `${r.id}:${j}`)), guide];
+                                            return look(r.d, r.id, true);
                                         }), Array.from({ length: Math.max(1, ...beats.map((b) => b.hops.length)) }, (_, j) => (_jsxs("g", { ref: (g) => {
                                                 dots.current[j] = g;
                                             }, style: { opacity: 0, color: v('accent') }, children: [_jsx("circle", { r: 10, fill: "currentColor", opacity: 0.2 }), _jsx("circle", { r: 4.5, fill: "currentColor" })] }, j)))] }), Array.from({ length: Math.max(1, ...beats.map((b) => b.hops.length)) }, (_, j) => (_jsx("div", { ref: (c) => {
@@ -749,16 +883,26 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                         color: ON_ACCENT,
                                         boxShadow: '0 4px 14px rgba(0,0,0,.18)',
                                         transition: 'opacity .2s',
-                                    }, children: cur?.hops[j]?.data }, j))), routed.map((r) => {
+                                    }, children: cur?.hops[j]?.data }, j))), routed.flatMap((r) => {
                                     const e = edges[ids.indexOf(r.id)];
-                                    if (e.label == null || tl)
-                                        return null;
+                                    const texts = r.stub && lanePlan?.stubs.get(r.id);
+                                    if (!texts && (e.label == null || tl))
+                                        return [];
                                     const on = litEdges.has(r.id);
                                     const tone = hopTone(r.id);
-                                    return (_jsx("div", { "data-fig-label": r.id, style: {
+                                    // A cross-block edge has two pills, one per stub, in place of its label.
+                                    const pills = texts
+                                        ? r.stub.pills.map((p, j) => ({
+                                            key: `${r.id}:${j}`,
+                                            x: p.x + p.w / 2,
+                                            y: p.y + p.h / 2,
+                                            text: (j === 0 && r.stub.short ? texts[2] : texts[j]),
+                                        }))
+                                        : [{ key: r.id, x: r.mid.x, y: r.mid.y, text: e.label }];
+                                    return pills.map((p) => (_jsx("div", { "data-fig-label": p.key, style: {
                                             position: 'absolute',
-                                            left: r.mid.x,
-                                            top: r.mid.y,
+                                            left: p.x,
+                                            top: p.y,
                                             transform: 'translate(-50%, -50%)',
                                             fontSize: 11,
                                             lineHeight: '16px',
@@ -772,7 +916,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                             opacity: !on && e.quiet ? 0 : focus && !on ? 0.6 : 1,
                                             fontFamily: MONO,
                                             transition: 'background .25s, color .25s, opacity .25s',
-                                        }, children: e.label }, r.id));
+                                        }, children: p.text }, p.key)));
                                 })] }) }) }) })), rail && (_jsxs("svg", { viewBox: `0 0 ${rail.width} ${rail.height}`, style: {
                     display: 'block',
                     width: '100%',

package/dist/init.js

@@ -1,7 +1,7 @@
 // `flowfig init`: write flowfig instructions for the coding agents of a repo. Pure functions where possible, so the tests need no TTY.
 import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import { createInterface } from 'node:readline';
 import { AGENT_TEXT, SKILL_DESCRIPTION } from './guide.js';
 import { runPicker } from './picker.js';
@@ -136,7 +136,10 @@ export function registerMcp(a, old) {
 /** `✓ ` before a finished write. */
 const mark = (status) => (/^(created|updated|unchanged)$/.test(status) ? '✓ ' : '');
 /** The path to show: relative to the repo folder, or `~` for the home folder. */
-const shown = (path, base, global) => (global ? `~/${relative(base, path)}` : relative(base, path));
+const shown = (path, base, global) => {
+    const rel = relative(base, path).split(sep).join('/'); // the output uses / on every system
+    return global ? `~/${rel}` : rel;
+};
 const HINT = 'run with -y or --agents <ids>';
 /** Run `flowfig init`. Returns the exit code. */
 export async function runInit(argv) {

package/dist/mcp.js

@@ -100,7 +100,7 @@ function run(name, args) {
         if (name === 'check' || errors)
             return ok(lines.join('\n'), errors);
         const out = String(args.out);
-        const svg = svgWithSpec(props);
+        const svg = svgWithSpec(props, opts);
         try {
             mkdirSync(dirname(out), { recursive: true });
             writeFileSync(out, svg);