flowfig 0.1.0 → 0.3.0

package/dist/index.js

@@ -4,12 +4,15 @@ import { useEffect, useMemo, useRef, useState } from 'react';
 import { route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.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, decisions, edgeId, groupGap, isGroup, isRows, nodes, toBeat, } 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, nodes, toBeat, beatMs, STEP_HOLD_MS, } from './model.js';
 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 glow = `0 0 0 3px color-mix(in srgb, ${v('accent')} 18%, transparent)`;
+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 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) => {
     if (c == null)
         return '—';
@@ -203,6 +206,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                     return [
                         {
                             id: `rail:${row.n}`,
+                            step: row.step,
                             from: rail.columns[row.from].id,
                             to: rail.columns[row.to].id,
                             curve: [c, c, c, c],
@@ -227,12 +231,12 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
     }, [check, routed, layout, edges, steps, ids, theme, rail, noMap]);
     // 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;
+        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 + (b.ms ?? speed), 0) };
+            clock.current = { beats, elapsed: beats.slice(0, j).reduce((t, b) => t + beatMs(b, speed), 0) };
             setBeat(j);
         }
         if (!beats.length || (!noMap && !routed.length))
@@ -242,8 +246,8 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                 bar.current.style.transform = 'none';
             return void setBeat(beats.length - 1);
         }
-        const ends = beats.reduce((acc, b) => [...acc, (acc.at(-1) ?? 0) + (b.ms ?? speed)], []);
-        const total = ends.at(-1) + speed * 1.5; // hold on the last beat before moving on
+        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.
         let raf = 0, last = performance.now(), shownBeat = -1;
         const tick = (now) => {
             if (playingRef.current)
@@ -262,7 +266,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
             if (i !== shownBeat)
                 setBeat((shownBeat = i));
             const start = i ? ends[i - 1] : 0;
-            const f = Math.min(1, (t - start) / ((beats[i].ms ?? speed) * 0.8)); // arrive a little early, rest at the end
+            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;
             const hops = t < ends.at(-1) ? beats[i].hops : [];
             gs.forEach((g, j) => {
@@ -276,20 +280,51 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                     return;
                 }
                 const pt = p.getPointAtLength((hops[j].back ? 1 - eased : eased) * p.getTotalLength());
+                const tone = hops[j].tone && TONES[hops[j].tone];
                 if (g) {
                     g.setAttribute('transform', `translate(${pt.x} ${pt.y})`);
                     g.style.opacity = '1';
+                    g.style.color = tone ?? v('accent');
                 }
                 if (c) {
+                    c.style.background = tone ? toneFill(tone) : v('accent');
                     c.style.transform = `translate(${pt.x}px, ${pt.y}px) translate(-50%, calc(-100% - 12px))`;
                     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]));
+                }
+            root.current?.querySelectorAll('[data-fig]').forEach((n) => {
+                const on = arrived.has(n.dataset.fig ?? '');
+                if (on) {
+                    const tone = arrived.get(n.dataset.fig);
+                    if (tone)
+                        n.style.setProperty('--ff-hop', tone);
+                    else
+                        n.style.removeProperty('--ff-hop');
+                }
+                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.
+                const keep = n.style.transition;
+                n.style.transition = 'none';
+                n.classList.add(ACTIVE);
+                void n.offsetWidth;
+                n.style.transition = keep;
+            });
             raf = requestAnimationFrame(tick);
         };
         raf = requestAnimationFrame(tick);
         return () => {
             cancelAnimationFrame(raf);
+            root.current?.querySelectorAll(`.${ACTIVE}`).forEach((n) => n.classList.remove(ACTIVE));
             gs.forEach((g) => g && (g.style.opacity = '0'));
             cs.forEach((c) => c && (c.style.opacity = '0'));
         };
@@ -308,10 +343,15 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
         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];
+    };
     const goTo = (step, b) => {
         setPlaying(true);
         if (step === active) {
-            clock.current.elapsed = beats.slice(0, b).reduce((t, x) => t + (x.ms ?? speed), 0);
+            clock.current.elapsed = beats.slice(0, b).reduce((t, x) => t + beatMs(x, speed), 0);
             setBeat(b);
         }
         else {
@@ -359,7 +399,8 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
         const diamond = item.shape === 'decision';
         const store = item.shape === 'store';
         const card = carded.has(item.id);
-        return (_jsxs("div", { "data-fig": item.id, onMouseEnter: () => setHover(item.id), onMouseLeave: () => setHover(null), style: {
+        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,
@@ -370,17 +411,20 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                 display: 'flex',
                 flexDirection: 'column',
                 justifyContent: 'center',
-                padding: diamond ? '22px 34px' : `${store ? 24 : 10}px ${card ? 10 : 16}px 10px`,
+                padding: diamond
+                    ? '22px 34px'
+                    : `calc(${store ? 24 : 10}px - var(--ff-b, 0px)) calc(${card ? 10 : 16}px - var(--ff-b, 0px)) calc(10px - var(--ff-b, 0px))`,
                 textAlign: 'center',
-                background: diamond ? undefined : v('bg'),
+                background: diamond ? undefined : bt ? toneTint(bt, v('bg')) : v('bg'),
                 color: v('fg'),
-                border: diamond ? undefined : `1px solid ${lit ? v('accent') : v('border')}`,
-                boxShadow: diamond ? undefined : lit ? glow : '0 1px 2px rgba(0,0,0,.06)',
+                border: diamond ? undefined : `1px solid ${bt ?? (lit ? v('accent') : v('border'))}`,
+                ...(bt && { '--ff-box': bt }),
+                boxShadow: diamond ? undefined : '0 1px 2px rgba(0,0,0,.06)',
                 opacity: focus && !lit ? 0.7 : 1,
                 borderRadius: store ? '50% / 12px' : 10,
                 fontSize: 14,
                 fontWeight: 500,
-                transition: 'border-color .25s, box-shadow .25s, opacity .25s',
+                transition: 'border-color .4s, background .4s, box-shadow .4s, border-width .4s, padding .4s, opacity .25s',
                 cursor: 'default',
             }, children: [diamond && (_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", style: {
                         position: 'absolute',
@@ -389,7 +433,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                         height: '100%',
                         overflow: 'visible',
                         zIndex: -1,
-                    }, children: _jsx("polygon", { points: "50,0 100,50 50,100 0,50", fill: v('bg'), stroke: lit ? v('accent') : v('border'), strokeWidth: lit ? 1.6 : 1, vectorEffect: "non-scaling-stroke", style: { transition: 'stroke .25s' } }) })), store && (_jsx("div", { style: {
+                    }, children: _jsx("polygon", { points: "50,0 100,50 50,100 0,50", fill: bt ? toneTint(bt, v('bg')) : v('bg'), stroke: bt ?? (lit ? v('accent') : v('border')), strokeWidth: lit ? 1.6 : 1, vectorEffect: "non-scaling-stroke", style: { transition: 'stroke .4s, fill .4s, stroke-width .4s' } }) })), store && (_jsx("div", { style: {
                         position: 'absolute',
                         top: -1,
                         left: -1,
@@ -397,7 +441,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                         height: 24,
                         boxSizing: 'border-box',
                         borderRadius: '50%',
-                        border: `1px solid ${lit ? v('accent') : v('border')}`,
+                        border: `1px solid ${bt ?? (lit ? v('accent') : v('border'))}`,
                         transition: 'border-color .25s',
                     } })), _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: {
                         marginTop: 8,
@@ -451,7 +495,10 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                     zIndex: 3,
                     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-in{from{opacity:0;transform:translateY(3px)}to{opacity:1;transform:none}}' }), !noMap && (_jsx(_Fragment, { children: _jsx("div", { style: {
+                }, children: _jsx(Icon, { d: full ? 'M4 4l8 8M12 4l-8 8' : 'M9 3h4v4M7 13H3V9M13 3L9 7M3 13l4-4' }) }), _jsx("style", { children: '@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.
+                    `.${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',
                         padding: full ? '48px 24px 24px' : '24px 16px',
                         borderRadius: full ? 0 : '16px 16px 0 0',
@@ -478,15 +525,16 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                         height: '100%',
                                         overflow: 'visible',
                                         pointerEvents: 'none',
-                                    }, 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: k === 'on' ? v('accent') : v('muted') }) }, k))) }), routed.map((r) => {
+                                    }, 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);
+                                            const tone = hopTone(r.id);
                                             const hidden = !on && edges[ids.indexOf(r.id)].quiet;
                                             return (_jsx("path", { ref: (p) => {
                                                     paths.current[r.id] = p;
-                                                }, d: r.d, fill: "none", stroke: on ? 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: 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));
                                         }), Array.from({ length: Math.max(1, ...beats.map((b) => b.hops.length)) }, (_, j) => (_jsxs("g", { ref: (g) => {
                                                 dots.current[j] = g;
-                                            }, style: { opacity: 0 }, children: [_jsx("circle", { r: 10, fill: v('accent'), opacity: 0.2 }), _jsx("circle", { r: 4.5, fill: v('accent') })] }, j)))] }), Array.from({ length: Math.max(1, ...beats.map((b) => b.hops.length)) }, (_, j) => (_jsx("div", { ref: (c) => {
+                                            }, 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) => {
                                         chips.current[j] = c;
                                     }, style: {
                                         position: 'absolute',
@@ -510,6 +558,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                     if (e.label == null)
                                         return null;
                                     const on = litEdges.has(r.id);
+                                    const tone = hopTone(r.id);
                                     return (_jsx("div", { "data-fig-label": r.id, style: {
                                             position: 'absolute',
                                             left: r.mid.x,
@@ -521,9 +570,9 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                             borderRadius: 999,
                                             whiteSpace: 'nowrap',
                                             pointerEvents: 'none',
-                                            background: on ? v('accent') : v('bg'),
+                                            background: on ? (tone ? toneFill(tone) : v('accent')) : v('bg'),
                                             color: on ? ON_ACCENT : v('muted'),
-                                            border: `1px solid ${on ? v('accent') : v('border')}`,
+                                            border: `1px solid ${on ? (tone ?? v('accent')) : v('border')}`,
                                             opacity: !on && e.quiet ? 0 : focus && !on ? 0.6 : 1,
                                             fontFamily: MONO,
                                             transition: 'background .25s, color .25s, opacity .25s',
@@ -564,14 +613,15 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                 (hover != null && [rail.columns[row.from].id, rail.columns[row.to].id].includes(hover));
                             const [x1, x2] = [rail.columns[row.from].x, rail.columns[row.to].x];
                             const ly = y + RAIL.row / 2;
+                            const tone = state === 'now' && row.tone ? TONES[row.tone] : undefined;
                             const g = row.group != null ? rail.groups[row.group] : null;
-                            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 ? v('accent') : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeDasharray: row.async ? '4 3' : undefined, markerEnd: "url(#flowfig-rail-arrow)" }), row.async &&
+                            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 ? v('accent') : v('bg'), stroke: on ? 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}`));
+                                        })(), 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}`));
                         });
                     })(), _jsx("defs", { children: _jsx("marker", { id: "flowfig-rail-arrow", 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: v('muted') }) }) })] })), steps.length > 0 && (_jsxs("figcaption", { style: { marginTop: 14, textAlign: 'center' }, children: [_jsxs("div", { style: { display: 'flex', gap: 10, justifyContent: 'center', alignItems: 'center' }, children: [_jsx("button", { type: "button", "aria-label": playing ? 'Pause' : 'Play', title: playing ? 'Pause' : 'Play', style: iconBtn, onClick: () => setPlaying((p) => !p), children: _jsx(Icon, { d: playing ? 'M5.5 4v8M10.5 4v8' : 'M5 3.5v9l7.5-4.5z', fill: !playing }) }), _jsx("div", { role: "tablist", style: {
                                     display: 'inline-flex',

package/dist/init.d.ts

@@ -10,6 +10,19 @@ type Agent = {
     /** 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;
+};
+export declare const MCP_ENTRY: {
+    command: string;
+    args: string[];
 };
 export declare const AGENTS: Agent[];
 /** The ids of the agents that the repo at `dir` already uses. */
@@ -20,6 +33,8 @@ export declare function toggle(input: string, selected: Set<string>, count: numb
 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. */
 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. */
+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,11 +1,12 @@
 // `flowfig init`: write flowfig instructions for the coding agents of a repo. Pure functions where possible, so the tests need no TTY.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { AGENT_TEXT, SKILL_DESCRIPTION } from './guide.js';
 const START = '<!-- flowfig:start -->';
 const END = '<!-- flowfig:end -->';
+export const MCP_ENTRY = { command: 'npx', args: ['flowfig', 'mcp'] };
 export const AGENTS = [
     {
         id: 'claude',
@@ -13,6 +14,7 @@ export const AGENTS = [
         marks: ['.claude/', 'CLAUDE.md'],
         file: '.claude/skills/figure/SKILL.md',
         kind: 'whole',
+        mcp: { file: '.mcp.json', key: 'mcpServers', type: true, global: '.claude.json' },
         head: `---\nname: figure\ndescription: ${JSON.stringify(SKILL_DESCRIPTION)}\nuser_invocable: true\n---\n\n`,
     },
     { id: 'agents', name: 'AGENTS.md', marks: ['AGENTS.md'], file: 'AGENTS.md', kind: 'section', note: 'Codex, Amp, Jules, ...' },
@@ -22,6 +24,7 @@ export const AGENTS = [
         marks: ['.cursor/', '.cursorrules'],
         file: '.cursor/rules/flowfig.mdc',
         kind: 'whole',
+        mcp: { file: '.cursor/mcp.json', key: 'mcpServers', type: true, global: '.cursor/mcp.json' },
         head: '---\ndescription: Draw diagrams and flow figures with flowfig\nalwaysApply: false\n---\n\n',
     },
     {
@@ -30,10 +33,32 @@ export const AGENTS = [
         marks: ['.github/copilot-instructions.md'],
         file: '.github/copilot-instructions.md',
         kind: 'section',
+        mcp: { file: '.vscode/mcp.json', key: 'servers', type: true },
+    },
+    {
+        id: 'gemini',
+        name: 'Gemini CLI',
+        marks: ['GEMINI.md', '.gemini/'],
+        file: 'GEMINI.md',
+        kind: 'section',
+        mcp: { file: '.gemini/settings.json', key: 'mcpServers', global: '.gemini/settings.json' },
+    },
+    {
+        id: 'windsurf',
+        name: 'Windsurf',
+        marks: ['.windsurf/', '.windsurfrules'],
+        file: '.windsurf/rules/flowfig.md',
+        kind: 'whole',
+        mcpNote: 'add {"command":"npx","args":["flowfig","mcp"]} to the MCP config by hand',
+    },
+    {
+        id: 'kiro',
+        name: 'Kiro',
+        marks: ['.kiro/'],
+        file: '.kiro/steering/flowfig.md',
+        kind: 'whole',
+        mcp: { file: '.kiro/settings/mcp.json', key: 'mcpServers', global: '.kiro/settings/mcp.json' },
     },
-    { id: 'gemini', name: 'Gemini CLI', marks: ['GEMINI.md', '.gemini/'], file: 'GEMINI.md', kind: 'section' },
-    { id: 'windsurf', name: 'Windsurf', marks: ['.windsurf/', '.windsurfrules'], file: '.windsurf/rules/flowfig.md', kind: 'whole' },
-    { id: 'kiro', name: 'Kiro', marks: ['.kiro/'], file: '.kiro/steering/flowfig.md', kind: 'whole' },
 ];
 /** 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);
@@ -77,12 +102,34 @@ export function place(a, old) {
         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. */
+export function registerMcp(a, old) {
+    if (!a.mcp)
+        return undefined;
+    let json;
+    try {
+        json = old === undefined ? {} : JSON.parse(old);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof json !== 'object' || json === null || Array.isArray(json))
+        return undefined;
+    const servers = json[a.mcp.key] ?? {};
+    if (typeof servers !== 'object' || servers === null || Array.isArray(servers))
+        return undefined;
+    if ('flowfig' in servers)
+        return old; // the user may have pinned a version or set env: keep the entry
+    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';
+}
 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);
-    const listAgents = flag('--list-agents'), all = flag('--all-agents'), yes = flag('-y', '--yes'), global = flag('--global'), dry = flag('--dry-run');
+    const listAgents = flag('--list-agents'), all = flag('--all-agents'), yes = flag('-y', '--yes'), global = flag('--global'), dry = flag('--dry-run'), noMcp = flag('--no-mcp');
     let ids;
     const at = args.indexOf('--agents');
     if (at !== -1)
@@ -100,7 +147,7 @@ export async function runInit(argv) {
     if (unknown)
         return fail(`init: unknown agent "${unknown}" (ids: ${AGENTS.map((a) => a.id).join(', ')})`);
     if (global && ids?.some((i) => i !== 'claude'))
-        return fail('init: --global writes only the claude skill (use --agents claude)');
+        return fail('init: --global writes only the Claude skill and the MCP entry (use --agents claude)');
     const detected = detect(dir);
     const auto = new Set(detected.length ? detected : ['agents']);
     let chosen;
@@ -142,6 +189,45 @@ export async function runInit(argv) {
             }
         }
         console.log(`${status.padEnd(9)} ${path}`);
+        if (noMcp)
+            continue;
+        if (a.mcpNote) {
+            console.log(`note      ${a.id}: ${a.mcpNote}`);
+            continue;
+        }
+        if (!a.mcp || (global && !a.mcp.global))
+            continue;
+        const mcpPath = global ? join(homedir(), a.mcp.global) : join(dir, a.mcp.file);
+        const oldMcp = existsSync(mcpPath) ? readFileSync(mcpPath, 'utf8') : undefined;
+        const nextMcp = registerMcp(a, oldMcp);
+        let mcpStatus;
+        if (nextMcp === undefined)
+            mcpStatus = `skipped (not a JSON object with ${a.mcp.key})`;
+        else if (nextMcp === oldMcp)
+            mcpStatus = 'unchanged';
+        else {
+            mcpStatus = oldMcp === undefined ? 'created' : 'updated';
+            if (dry)
+                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.
+                const real = existsSync(mcpPath) ? realpathSync(mcpPath) : mcpPath;
+                const tmp = `${real}.${process.pid}.tmp`;
+                try {
+                    writeFileSync(tmp, nextMcp);
+                    if (existsSync(real))
+                        chmodSync(tmp, statSync(real).mode & 0o777);
+                    renameSync(tmp, real);
+                }
+                catch (e) {
+                    rmSync(tmp, { force: true });
+                    throw e;
+                }
+            }
+        }
+        console.log(`${mcpStatus.padEnd(9)} ${mcpPath}`);
     }
     return 0;
 }

package/dist/load.d.ts

@@ -0,0 +1,12 @@
+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 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

@@ -0,0 +1,59 @@
+// 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)
+        throw new Error(`${name}: no figure spec inside this SVG`);
+    return svg.slice(at + SPEC_OPEN.length, svg.indexOf(SPEC_CLOSE, at));
+}
+/** A spec from a `.json` or SVG path, or an object (`{ props }` or the props). Every error message starts with the name. */
+export function loadSpec(input, name = typeof input === 'string' ? input : 'spec') {
+    let loaded = input;
+    if (typeof input === 'string') {
+        if (!input.endsWith('.json') && !input.endsWith('.svg'))
+            throw new Error(`${input}: expected a .json or .svg path`);
+        try {
+            const text = readFileSync(input, 'utf8');
+            loaded = JSON.parse(input.endsWith('.svg') ? specOf(text, input) : text);
+        }
+        catch (e) {
+            const m = e.message;
+            throw new Error(m.startsWith(`${input}: `) ? m : `${input}: ${m}`);
+        }
+    }
+    const props = (loaded?.props ?? loaded);
+    if (!props?.layout)
+        throw new Error(`${name}: no figure props (expected { props: { layout, edges, steps } })`);
+    if (!Array.isArray(props.edges))
+        throw new Error(`${name}: edges must be an array (use [] for none)`);
+    if (props.steps?.some((s) => !Array.isArray(s?.flow)))
+        throw new Error(`${name}: each step needs a flow array`);
+    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 = {}) {
+    const spec = JSON.stringify({ props }).replaceAll(']]>', ']]\\u003e');
+    return toSvg(props, opts).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))
+        .sort((a, b) => (a.severity === b.severity ? a.rule.localeCompare(b.rule) : a.severity === 'error' ? -1 : 1));
+}
+const n = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
+/** One line per finding, the counts line (unless `withCounts` is false), and the `figure:` line. No color: the CLI adds it. */
+export function reportLines(props, findings, withCounts = true) {
+    const out = findings.map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${f.message}`);
+    const errors = findings.filter((f) => f.severity === 'error').length;
+    if (withCounts)
+        out.push(`${n(errors, 'error')}, ${n(findings.length - errors, 'warning')}`);
+    const c = counts(props);
+    out.push(`figure: ${n(c.boxes, 'box').replace('boxs', 'boxes')}, ${n(c.groups, 'group')}, ${n(c.edges, 'edge')}, ${n(c.steps, 'step')}, ${n(c.messages, 'message')}`);
+    return out;
+}