flowfig 0.6.0 → 0.8.0

package/dist/index.js

@@ -10,9 +10,8 @@ export { LIGHT, DARK } from './model.js';
 const DEFAULTS = { ...LIGHT, font: 'inherit' };
 const v = (k) => `var(--fig-${k}, ${DEFAULTS[k]})`;
 const MONO = 'var(--ifm-font-family-monospace, ui-monospace, SFMono-Regular, Menlo, monospace)';
-const NONE = []; // a stable default, so a memo keyed on it does not run every render
-const ACTIVE = 'flowfig-active'; // the box a packet has just reached
-// The active box reads --ff-hop (the tone of the hop that arrived), then --ff-box (the tone of the box), then the accent.
+const NONE = [];
+const ACTIVE = 'flowfig-active';
 const hue = `var(--ff-hop, var(--ff-box, ${v('accent')}))`;
 const glow = `0 0 0 3px color-mix(in srgb, ${hue} 18%, transparent)`;
 const cardBody = (c) => {
@@ -40,20 +39,17 @@ const cardBody = (c) => {
                     fontFamily: r.mono ? MONO : undefined,
                     fontSize: r.mono ? 10.5 : undefined,
                 }, children: [r.text, r.meta != null && _jsxs("span", { style: { color: v('muted') }, children: [" \u00B7 ", r.meta] })] }));
-            // A word-sized tag heads its row so the text keeps the full width; a number or no tag sits inline.
             return (r.tag?.length ?? 0) > 2 ? (_jsxs("div", { children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 5, marginBottom: 1 }, children: [tag, mark] }), text] }, i)) : (_jsxs("div", { style: { display: 'flex', gap: 5, alignItems: 'baseline' }, children: [tag, text, mark] }, i));
         }) }));
 };
 /**
- * The interactive player for one figure: tabs for the steps, play and pause, speed, hover and full screen.
- * Give it a `FlowProps` spec. Use `toSvg` from `flowfig/svg` for a static animated SVG instead.
+ * The interactive player for one figure. Give it a `FlowProps` spec.
+ * Use `toSvg` from `flowfig/svg` for a static animated SVG.
  */
 export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900, autoplay = true, check = false, rail: withRail = false, lanes, timeline, today, }) {
     const tl = timeline && isLanesLayout(layout);
-    // A timeline with no steps of its own walks its dated items in date order, with no tab row.
     const synthetic = tl && !stepsIn.length;
     const steps = useMemo(() => (synthetic ? timelineBeats({ layout, edges, timeline, today }) : stepsIn), [synthetic, layout, edges, timeline, today, stepsIn]);
-    // The width of the timeline area in px: the server draws TL_AXIS_W, and the browser measures the real width after mount.
     const [axisW, setAxisW] = useState(TL_AXIS_W);
     const area = useRef(null);
     const root = useRef(null);
@@ -69,24 +65,19 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
     }, [full]);
     const dots = useRef([]);
     const chips = useRef([]);
-    const bar = useRef(null); // the active tab's progress line
+    const bar = useRef(null);
     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 [holding, setHolding] = useState(false);
+    const [returning, setReturning] = useState(false);
+    const firstLabel = useRef('');
     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 })
+        ? planLanes({ layout, edges, steps, lanes }, { 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.
     const playingRef = useRef(playing);
     playingRef.current = playing;
     const [rate, setRate] = useState(1);
@@ -95,7 +86,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
     const clock = useRef({ beats: null, elapsed: 0 });
     const [hover, setHover] = useState(null);
     const ids = useMemo(() => edges.map(edgeId), [edges]);
-    // A milestone is a diamond too, so its edges meet the tips.
     const tips = useMemo(() => new Set([
         ...decisions(layout),
         ...(tl
@@ -106,7 +96,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
     ]), [layout, tl, edges, timeline, today]);
     const step = active == null ? null : steps[active];
     const beats = useMemo(() => (step?.flow ?? []).map(toBeat), [step]);
-    // Every content each box's card will ever show. The card is sized to the largest, so text never gets cut and nothing jumps.
     const carded = useMemo(() => {
         const all = new Map();
         for (const b of steps.flatMap((s) => s.flow.map(toBeat)))
@@ -115,30 +104,23 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         return all;
     }, [steps]);
     const cur = beats[beat];
-    // The narration: the latest `say` so far (a beat without one keeps the line before), else the step caption.
     const saidAt = beats.slice(0, beat + 1).findLastIndex((b) => b.say != null);
     const said = saidAt === -1 ? step?.caption : beats[saidAt].say;
-    // Content cards: everything the step has shown so far, latest wins.
     const shown = useMemo(() => Object.assign({}, ...beats.slice(0, beat + 1).map((b) => b.show)), [beats, beat]);
-    // The beat that last changed each card, so only a card whose content just changed animates in.
     const shownAt = useMemo(() => {
         const at = {};
         beats.slice(0, beat + 1).forEach((b, i) => Object.keys(b.show ?? {}).forEach((k) => (at[k] = i)));
         return at;
     }, [beats, beat]);
-    // The rail lays out in node terms, like the SVG, so both renderers draw the same numbers. Its width follows the measured map.
     const figure = useRef(null);
     const [mapW, setMapW] = useState(0);
     const railOnly = withRail === 'only';
     const rail = useMemo(() => (withRail ? layoutRail({ layout, edges, steps, rail: true }, railOnly ? 560 : mapW) : null), [withRail, railOnly, layout, edges, steps, mapW]);
-    // 'only' drops the map, but only when the rail has a hop to draw; a figure never renders empty.
     const noMap = railOnly && rail != null;
-    const jump = useRef(null); // a rail click that asks for a beat of another step
+    const jump = useRef(null);
     const [hoverEdge, setHoverEdge] = useState(null);
-    // With reduced motion the player shows the last beat, so the rail marks every row as done.
     const [still, setStill] = useState(false);
     useEffect(() => setStill(window.matchMedia('(prefers-reduced-motion: reduce)').matches), []);
-    // Boxes with many edges on one side get taller so the edges and their labels have room.
     const minHeight = useMemo(() => {
         const out = {}, inn = {};
         for (const e of edges) {
@@ -150,20 +132,19 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             return n > 2 ? n * 30 : undefined;
         };
     }, [edges]);
-    // Measure every box and redraw the edges whenever anything changes size.
     useEffect(() => {
         const el = root.current, box = outer.current;
         if (!el || !box)
-            return; // no map to measure with rail: 'only'
+            return;
         const measure = () => {
-            // Too wide for its container? Shrink it so the whole figure stays in view. Below half size, scroll instead.
             const scale = Math.max(0.5, Math.min(1, box.clientWidth / el.offsetWidth));
             setFit({ scale, height: el.offsetHeight * scale });
             setMapW(el.offsetWidth);
             if (area.current)
                 setAxisW(area.current.offsetWidth);
             const base = el.getBoundingClientRect();
-            const k = base.width / el.offsetWidth; // the scale currently on screen; rects are measured unscaled
+            // Rects are measured unscaled: k is the scale on screen.
+            const k = base.width / el.offsetWidth;
             const rects = {};
             el.querySelectorAll('[data-fig]').forEach((n) => {
                 const r = n.getBoundingClientRect();
@@ -179,12 +160,10 @@ 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 });
             });
-            // 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))
@@ -195,13 +174,11 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     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
                 ? (() => {
@@ -211,7 +188,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     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();
@@ -248,12 +224,10 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         el.querySelectorAll('[data-fig]').forEach((n) => ro.observe(n));
         return () => ro.disconnect();
     }, [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(() => {
         const el = root.current, box = outer.current;
         const fig = figure.current;
-        // With rail: 'only' there is no map: the figure is the frame and the scene holds only the rail.
         if (!check || !fig || (!noMap && (!el || !box)))
             return;
         const base = (el ?? fig).getBoundingClientRect();
@@ -276,7 +250,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     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));
@@ -289,11 +262,10 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                 }),
             };
         });
-        // 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('*')]
             .filter((t) => !t.children.length &&
             t.textContent?.trim() &&
+            // An SVG <text> has no CSS box, so skip clientWidth.
             (t instanceof SVGElement || t.clientWidth > 0) &&
             !t.closest('[data-fig-tag],[aria-hidden]'))
             .map((t) => parseFloat(getComputedStyle(t).fontSize));
@@ -311,12 +283,10 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             edges: [
                 ...routed.flatMap((r) => {
                     const e = 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, 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) => {
                     const r = row.kind === 'message' ? labels[`rail:${row.n}`] : undefined;
                     if (row.kind !== 'message' || !r)
@@ -345,14 +315,13 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             if (reported.current.has(key))
                 continue;
             reported.current.add(key);
+            // oxlint-disable-next-line no-console
             console.warn(`flowfig check: ${f.severity} ${f.rule}: ${f.message}`);
         }
     }, [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]));
         if (clock.current.beats !== beats) {
-            // A rail click can open another step at a later beat; start the clock at that beat, not at 0.
             const j = jump.current ?? 0;
             jump.current = null;
             clock.current = { beats, elapsed: beats.slice(0, j).reduce((t, b) => t + beatMs(b, speed), 0) };
@@ -366,7 +335,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             return void setBeat(beats.length - 1);
         }
         const ends = beats.reduce((acc, b) => [...acc, (acc.at(-1) ?? 0) + beatMs(b, speed)], []);
-        const total = ends.at(-1) + STEP_HOLD_MS; // The figure holds on the last beat before the next step.
+        const total = ends.at(-1) + STEP_HOLD_MS;
         let raf = 0, last = performance.now(), shownBeat = -1;
         const tick = (now) => {
             if (playingRef.current)
@@ -387,7 +356,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             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 f = Math.min(1, (t - start) / speed);
             const eased = f < 0.5 ? 2 * f * f : 1 - (-2 * f + 2) ** 2 / 2;
             const hops = t < ends.at(-1) ? beats[i].hops : [];
             gs.forEach((g, j) => {
@@ -413,14 +382,12 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     c.style.opacity = hops[j].data == null ? '0' : '1';
                 }
             });
-            // A box is active from the packet arrival to the end of the step hold. The tick toggles the class and skips React.
             const arrived = new Map();
             if (f >= 1)
                 for (const h of beats[i].hops) {
                     const to = h.back ? edgeOf[h.edge]?.from : edgeOf[h.edge]?.to;
                     arrived.set(to, arrived.get(to) ?? (h.tone && TONES[h.tone]));
                 }
-            // A focused box turns active at the beat start; in a timeline, when the today line arrives.
             if (t - start >= (tl ? 400 * BASE_RATE : 0))
                 for (const id of beats[i].focus ?? [])
                     if (!arrived.has(id))
@@ -437,8 +404,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                 if (on === n.classList.contains(ACTIVE))
                     return;
                 if (!on)
-                    return void n.classList.remove(ACTIVE); // the transition fades the box
-                // The box turns active at once: no transition while the class arrives.
+                    return void n.classList.remove(ACTIVE);
                 const keep = n.style.transition;
                 n.style.transition = 'none';
                 n.classList.add(ACTIVE);
@@ -455,8 +421,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             cs.forEach((c) => c && (c.style.opacity = '0'));
         };
     }, [beats, routed, noMap, speed, steps.length]);
-    // What to light up: the step's edges and their ends, or whatever touches the hovered box.
-    // A step lights the trail so far: every edge its beats have crossed, and every box it has filled.
     const trail = beats.slice(0, beat + 1).flatMap((b) => b.hops.map((h) => h.edge));
     const hoverEdgeIdx = hoverEdge == null ? -1 : ids.indexOf(hoverEdge);
     const litEdges = new Set(hoverEdge ? [hoverEdge] : hover ? ids.filter((id, i) => edges[i].from === hover || edges[i].to === hover) : trail);
@@ -469,7 +433,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         if (litEdges.has(ids[i]))
             litNodes.add(e.from).add(e.to);
     });
-    // A toned hop colors its edge for its own beat only; the trail after it is the accent.
     const hopTone = (edge) => {
         const t = cur?.hops.find((h) => h.edge === edge && h.tone)?.tone;
         return t && TONES[t];
@@ -488,7 +451,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
     const focus = hover != null || hoverEdge != null || step != null;
     const vars = Object.fromEntries(Object.entries(theme ?? {}).map(([k, val]) => [`--fig-${k}`, val]));
     const timelineFig = useMemo(() => (tl ? timelineLayout({ layout, edges, timeline, today }, axisW) : null), [tl, layout, edges, timeline, today, axisW]);
-    // A bar or a milestone of a timeline: placed by the shared layout, with the look of a box.
     const renderBar = (n, it) => {
         const lit = litNodes.has(n.id);
         const bt = n.tone && TONES[n.tone];
@@ -522,8 +484,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
     const renderItem = (item, depth) => {
         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.
-            // 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
@@ -535,8 +495,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             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)
@@ -572,7 +530,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             return (_jsxs("div", { style: {
                     display: 'grid',
                     gridTemplateColumns: `max-content minmax(${TL_AXIS_W}px, 1fr) 18px`,
-                    // The axis strip sits over the gap above the first band, as in the SVG.
                     gridTemplateRows: `${TL_AXIS_H - LANE_ROW_GAP}px ${rowsPx.map((h) => h + 'px').join(' ')}`,
                     rowGap: LANE_ROW_GAP,
                     position: 'relative',
@@ -605,19 +562,14 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         }
         if (lanes && item === layout && isLanesLayout(layout)) {
             const { cols, starts, gaps, lead, blocks, gutter, tall } = lanePlan;
-            const n = Math.max(0, ...cols.values()) + 1;
             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,
@@ -650,7 +602,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                         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));
@@ -696,7 +647,6 @@ 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: {
@@ -812,7 +762,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     width: 28,
                     height: 28,
                 }, children: _jsx(Icon, { d: full ? 'M4 4l8 8M12 4l-8 8' : 'M9 3h4v4M7 13H3V9M13 3L9 7M3 13l4-4' }) }), _jsx("style", { children: '@keyframes flowfig-label{from{opacity:0}to{opacity:0}}@keyframes flowfig-in{from{opacity:0;transform:translateY(3px)}to{opacity:1;transform:none}}' +
-                    // The active box has a 2 px border, a tint and a glow. The padding shrinks by 1 px. The box size stays the same, so the edges keep their route.
+                    // The 2 px active border takes 1 px of padding, so the box size stays.
                     `.${ACTIVE}:not([data-diamond]){--ff-b:1px;border-width:2px!important;background:color-mix(in srgb, ${hue} 10%, ${v('surface')})!important;box-shadow:${glow}!important;border-color:${hue}!important}` +
                     `.${ACTIVE} polygon{fill:color-mix(in srgb, ${hue} 10%, ${v('surface')});stroke:${hue};stroke-width:2px}` }), !noMap && (_jsx(_Fragment, { children: _jsx("div", { style: {
                         margin: full ? '-48px -24px 0' : '-20px -16px 0',
@@ -831,8 +781,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                 transform: fit.scale < 1 ? `scale(${fit.scale})` : undefined,
                                 transformOrigin: 'top left',
                                 padding: 4,
-                                // room for edges that arc over or under the boxes
-                                // 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
@@ -844,7 +792,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                         height: '100%',
                                         overflow: 'visible',
                                         pointerEvents: 'none',
-                                        // A timeline dependency runs under the bars (z-index 1) and over the bands (0).
                                         zIndex: tl ? 0 : undefined,
                                     }, children: [_jsx("defs", { children: ['off', 'on'].map((k) => (_jsx("marker", { id: `fig-arrow-${k}`, viewBox: "0 0 10 10", refX: "9", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse", children: _jsx("path", { d: "M 0 1 L 9 5 L 0 9 z", fill: "context-stroke" }) }, k))) }), routed.map((r) => {
                                             const on = litEdges.has(r.id);
@@ -858,7 +805,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                             const guide = (_jsx("path", { ref: (p) => {
                                                     paths.current[r.id] = p;
                                                 }, 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);
@@ -890,7 +836,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                         return [];
                                     const on = litEdges.has(r.id);
                                     const tone = hopTone(r.id);
-                                    // 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}`,
@@ -927,7 +872,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     fontFamily: v('font'),
                 }, children: [rail.bands.map((b) => (_jsxs("g", { children: [_jsx("rect", { x: b.rect.x, y: b.rect.y, width: b.rect.w, height: b.rect.h, rx: 10, fill: v('surface'), stroke: v('border') }), _jsx("text", { x: b.rect.x + 10, y: b.rect.y + 14, fill: v('muted'), fontSize: 11, fontWeight: 600, letterSpacing: ".04em", children: b.label.toUpperCase() })] }, b.id))), rail.columns.map((c) => (_jsx("text", { x: c.x, y: rail.head - RAIL.cols / 2 + 4, fill: v('fg'), fontSize: 12, fontWeight: 500, textAnchor: "middle", children: c.label }, c.id))), (() => {
                         const st = railState(rail, active ?? 0);
-                        // The lifelines run through the message rows only, so a phase header reads as one clear divider.
                         const lines = rail.rows.flatMap((row, i) => row.kind === 'message' && st[i].shown ? rail.columns.map((c) => `M ${c.x} ${st[i].y} V ${st[i].y + RAIL.row}`) : []);
                         return _jsx("path", { d: lines.join(' '), stroke: v('border'), strokeDasharray: "2 3" });
                     })(), (() => {
@@ -958,7 +902,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                             return (_jsxs("g", { "data-rail-row": row.n, "data-state": state, opacity: state === 'next' && !on ? 0.45 : 1, style: { cursor: 'pointer' }, onClick: () => goTo(row.step, row.beat), onMouseEnter: () => setHoverEdge(row.edge), onMouseLeave: () => setHoverEdge(null), children: [g && g.rows[0] === i && (_jsx("rect", { x: groupBox(rail, g).x, y: y + groupBox(rail, g).y, width: groupBox(rail, g).w, height: groupBox(rail, g).h, rx: 6, fill: `color-mix(in srgb, ${v('accent')} 8%, ${v('bg')})`, stroke: v('accent'), strokeDasharray: "3 3" })), _jsx("path", { d: `M ${x1} ${ly} H ${x2}`, fill: "none", stroke: on ? (tone ?? v('accent')) : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeDasharray: row.async ? '4 3' : undefined, markerEnd: "url(#flowfig-rail-arrow)" }), row.async &&
                                         (() => {
                                             const tagW = ASYNC_TAG_W;
-                                            // The tag sits on the tail side of the pill, so it never hides the arrowhead.
                                             const tx = !row.pill ? (x1 + x2) / 2 - tagW / 2 : x2 > x1 ? row.pill.x - tagW - 4 : row.pill.x + row.pill.w + 4;
                                             return (_jsxs(_Fragment, { children: [_jsx("rect", { x: tx, y: ly - 6, width: tagW, height: 12, rx: 4, fill: v('bg') }), _jsx("rect", { x: tx, y: ly - 6, width: tagW, height: 12, rx: 4, fill: TONES.gray, fillOpacity: 0.15 }), _jsx("text", { x: tx + tagW / 2, y: ly + 3, fill: TONES.gray, fontSize: 9, fontWeight: 600, letterSpacing: ".03em", textAnchor: "middle", "data-fig-tag": true, children: "ASYNC" })] }));
                                         })(), row.pill && (_jsxs("g", { "data-fig-label": `rail:${row.n}`, children: [_jsx("rect", { x: row.pill.x, y: ly - 9, width: row.pill.w, height: 18, rx: 9, fill: on ? (tone ? toneFill(tone) : v('accent')) : v('bg'), stroke: on ? (tone ?? v('accent')) : v('border') }), _jsx("text", { x: row.pill.x + row.pill.w / 2, y: ly + 4, fill: on ? ON_ACCENT : v('muted'), fontSize: 11, fontFamily: MONO, textAnchor: "middle", children: row.text })] }))] }, `m${i}`));
@@ -973,7 +916,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                 }, children: steps.map((s, i) => {
                                     const on = active === i;
                                     return (_jsxs("button", { type: "button", role: "tab", "aria-selected": on, onClick: () => {
-                                            clock.current.elapsed = 0; // replay from the start, even when it is already the active step
+                                            clock.current.elapsed = 0;
                                             setActive(i);
                                             setPlaying(true);
                                             setBeat(0);
@@ -1022,7 +965,6 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                             animation: 'flowfig-in .35s ease-out',
                         }, children: said }, `${active}-${saidAt}`))] }))] }));
 }
-/** A 16px stroke icon drawn from one SVG path. */
 function Icon({ d, fill = false }) {
     return (_jsx("svg", { width: 14, height: 14, viewBox: "0 0 16 16", fill: fill ? 'currentColor' : 'none', stroke: "currentColor", strokeWidth: 1.6, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true, children: _jsx("path", { d: d }) }));
 }

package/dist/init.d.ts

@@ -1,25 +1,18 @@
 type Agent = {
     id: string;
     name: string;
-    /** Paths whose presence means the repo uses the agent. A trailing `/` means a directory. */
     marks: string[];
-    /** The file init writes, relative to the repo. */
     file: string;
-    /** `section` edits a file the user owns; `whole` owns the file. */
     kind: 'section' | 'whole';
-    /** Text before the marked block in a whole file. */
     head?: string;
     note?: string;
-    /** The MCP config file the agent reads, and the top-level key that holds the servers. `type` adds `"type": "stdio"`. */
     mcp?: {
         file: string;
         key: 'mcpServers' | 'servers';
         type?: true;
         global?: string;
     };
-    /** Shown in place of the MCP file when init cannot write the config. */
     mcpNote?: string;
-    /** A second file, a marked section in a file the user owns. Written only in a repo run, never with `--global`. */
     also?: {
         file: string;
         text: string;
@@ -30,16 +23,13 @@ export declare const MCP_ENTRY: {
     args: string[];
 };
 export declare const AGENTS: Agent[];
-/** The ids of the agents that the repo at `dir` already uses. */
 export declare const detect: (dir: string) => string[];
-/** Toggle the agents named by numbers ("1 3" or "1,3"). A number out of range and other text are ignored. */
+/** Toggle the agents named by numbers ("1 3" or "1,3"). Ignore bad input. */
 export declare function toggle(input: string, selected: Set<string>, count: number): Set<string>;
-/** The picker screen. */
 export declare function renderList(selected: Set<string>, detected: string[], dir: string): string;
-/** The new file text, or `undefined` if the file belongs to the user and init must leave it. `old` is `undefined` for a missing file. */
+/** The new file text, or `undefined` if the user owns the file. */
 export declare function place(a: Agent, old: string | undefined): string | undefined;
-/** The MCP file with the flowfig entry merged in, or `undefined` when the file is not a JSON object that can hold it. */
+/** The MCP file with the flowfig entry, or `undefined` if the file cannot hold it. */
 export declare function registerMcp(a: Agent, old: string | undefined): string | undefined;
-/** Run `flowfig init`. Returns the exit code. */
 export declare function runInit(argv: string[]): Promise<number>;
 export {};

package/dist/init.js

@@ -1,4 +1,3 @@
-// `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, sep } from 'node:path';
@@ -65,20 +64,20 @@ export const AGENTS = [
         mcp: { file: '.kiro/settings/mcp.json', key: 'mcpServers', global: '.kiro/settings/mcp.json' },
     },
 ];
-/** The ids of the agents that the repo at `dir` already uses. */
 export const detect = (dir) => AGENTS.filter((a) => a.marks.some((m) => existsSync(join(dir, m)))).map((a) => a.id);
-/** Toggle the agents named by numbers ("1 3" or "1,3"). A number out of range and other text are ignored. */
+/** Toggle the agents named by numbers ("1 3" or "1,3"). Ignore bad input. */
 export function toggle(input, selected, count) {
     const next = new Set(selected);
     for (const t of input.split(/[\s,]+/)) {
         const n = /^\d+$/.test(t) ? Number(t) : 0;
         const id = n >= 1 && n <= count ? AGENTS[n - 1].id : undefined;
-        if (id)
-            next.has(id) ? next.delete(id) : next.add(id);
+        if (id && next.has(id))
+            next.delete(id);
+        else if (id)
+            next.add(id);
     }
     return next;
 }
-/** The picker screen. */
 export function renderList(selected, detected, dir) {
     const rows = AGENTS.map((a, i) => {
         const found = detected.includes(a.id) ? `(${a.marks.find((m) => existsSync(join(dir, m)))} found)` : '';
@@ -93,25 +92,25 @@ export function renderList(selected, detected, dir) {
     ].join('\n');
 }
 const block = (text = AGENT_TEXT) => `${START}\n${text.trimEnd()}\n${END}\n`;
-/** The new file text, or `undefined` if the file belongs to the user and init must leave it. `old` is `undefined` for a missing file. */
+/** The new file text, or `undefined` if the user owns the file. */
 export function place(a, old) {
     const mine = block();
     if (a.kind === 'whole')
         return old === undefined || old.includes(START) ? `${a.head ?? ''}${mine}` : undefined;
     return section(old, mine);
 }
-/** `old` with the marked block `mine` added or replaced. `undefined` if the block is open. */
 function section(old, mine) {
     if (old === undefined)
         return mine;
     const s = old.indexOf(START), e = old.indexOf(END, s);
+    // An open block: the next run would eat the text after START.
     if (s !== -1 && e === -1)
-        return undefined; // an open block: the next run would eat the text after START
+        return undefined;
     if (s !== -1)
         return old.slice(0, s) + mine.trimEnd() + old.slice(e + END.length);
     return old + (old.endsWith('\n\n') ? '' : old.endsWith('\n') ? '\n' : '\n\n') + mine;
 }
-/** The MCP file with the flowfig entry merged in, or `undefined` when the file is not a JSON object that can hold it. */
+/** The MCP file with the flowfig entry, or `undefined` if the file cannot hold it. */
 export function registerMcp(a, old) {
     if (!a.mcp)
         return undefined;
@@ -127,21 +126,19 @@ export function registerMcp(a, old) {
     const servers = json[a.mcp.key] ?? {};
     if (typeof servers !== 'object' || servers === null || Array.isArray(servers))
         return undefined;
+    // Keep the entry: the user may have pinned a version.
     if ('flowfig' in servers)
-        return old; // the user may have pinned a version or set env: keep the entry
+        return old;
     const entry = a.mcp.type ? { ...MCP_ENTRY, type: 'stdio' } : MCP_ENTRY;
     json[a.mcp.key] = { ...servers, flowfig: entry };
     return JSON.stringify(json, null, 2) + '\n';
 }
-/** `✓ ` 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) => {
-    const rel = relative(base, path).split(sep).join('/'); // the output uses / on every system
+    const rel = relative(base, path).split(sep).join('/');
     return global ? `~/${rel}` : rel;
 };
 const HINT = 'run with -y or --agents <ids>';
-/** Run `flowfig init`. Returns the exit code. */
 export async function runInit(argv) {
     const args = [...argv];
     const flag = (n, ...alias) => [n, ...alias].some((x) => args.includes(x) && args.splice(args.indexOf(x), 1).length > 0);
@@ -248,8 +245,7 @@ export async function runInit(argv) {
                 mcpStatus = `would ${mcpStatus === 'created' ? 'create' : 'update'}`;
             else {
                 mkdirSync(dirname(mcpPath), { recursive: true });
-                // Same-folder temp file, then rename: a crash or a parallel write cannot leave half a file (~/.claude.json holds user settings).
-                // Resolve a symlink first, so the rename replaces the target and not the link. Copy the old mode to the new file.
+                // Rename a temp file over the symlink target, so a crash leaves no half file.
                 const real = existsSync(mcpPath) ? realpathSync(mcpPath) : mcpPath;
                 const tmp = `${real}.${process.pid}.tmp`;
                 try {
@@ -274,7 +270,6 @@ function fail(message) {
     console.error(message);
     return 2;
 }
-/** Ask on the terminal. Returns the chosen ids, or `undefined` if the user quits. */
 async function pick(start, detected, dir) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const ask = (q) => new Promise((res) => (rl.once('close', () => res(undefined)), rl.question(q, res)));

package/dist/load.d.ts

@@ -1,12 +1,10 @@
 import { type FlowProps } from './model.ts';
 import { type Finding, type SvgOptions } from './svg.ts';
-/** The spec JSON inside an SVG this package wrote. */
 export declare function specOf(svg: string, name: string): string;
 /** A spec from a `.json` or SVG path, or an object (`{ props }` or the props). Every error message starts with the name. */
 export declare function loadSpec(input: string | object, name?: string): FlowProps;
 /** The SVG with its spec in `<metadata>`: an SVG is then its own source. `]]>` would close the CDATA early, so it is escaped. */
-export declare function svgWithSpec(props: FlowProps, opts?: SvgOptions): string;
-/** Errors first, then by rule name. `strict` makes every warning an error. */
+export declare function svgWithSpec(props: FlowProps, opts?: SvgOptions, svg?: string): string;
 export declare function sortFindings(findings: Finding[], strict: boolean): Finding[];
 /** One line per finding, the counts line (unless `withCounts` is false), and the `figure:` line. No color: the CLI adds it. */
 export declare function reportLines(props: FlowProps, findings: Finding[], withCounts?: boolean): string[];

package/dist/load.js

@@ -1,10 +1,8 @@
-// What the CLI and the MCP server share: read a spec, write an SVG that carries its spec, and print the check lines.
 import { readFileSync } from 'node:fs';
 import { counts } from './model.js';
 import { toSvg } from './svg.js';
 const SPEC_OPEN = '<metadata id="figure-spec"><![CDATA[';
 const SPEC_CLOSE = ']]></metadata>';
-/** The spec JSON inside an SVG this package wrote. */
 export function specOf(svg, name) {
     const at = svg.indexOf(SPEC_OPEN);
     if (at === -1)
@@ -36,11 +34,10 @@ export function loadSpec(input, name = typeof input === 'string' ? input : 'spec
     return props;
 }
 /** The SVG with its spec in `<metadata>`: an SVG is then its own source. `]]>` would close the CDATA early, so it is escaped. */
-export function svgWithSpec(props, opts = {}) {
+export function svgWithSpec(props, opts = {}, svg = toSvg(props, opts)) {
     const spec = JSON.stringify({ props }).replaceAll(']]>', ']]\\u003e');
-    return toSvg(props, opts).replace(/(<svg[^>]*>\n?)/, (tag) => `${tag}${SPEC_OPEN}${spec}${SPEC_CLOSE}\n`);
+    return svg.replace(/(<svg[^>]*>\n?)/, (tag) => `${tag}${SPEC_OPEN}${spec}${SPEC_CLOSE}\n`);
 }
-/** Errors first, then by rule name. `strict` makes every warning an error. */
 export function sortFindings(findings, strict) {
     return findings
         .map((f) => (strict ? { ...f, severity: 'error' } : f))

package/dist/mcp.d.ts

@@ -133,7 +133,6 @@ export declare const TOOLS: ({
         required: string[];
     };
 })[];
-/** One JSON-RPC message in, one response out; `undefined` for a notification. Pure, so the tests call it directly. */
+/** Returns `undefined` for a notification. */
 export declare function handle(message: unknown): Response | undefined;
-/** Read one message per line from `input`, write one response per line to `output`. Returns when `input` ends. */
 export declare function serve(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): Promise<void>;