flowfig 0.7.0 → 0.8.1

package/dist/imports.d.ts

@@ -0,0 +1,11 @@
+import { type CodeFile, type Read } from './code.ts';
+export type Import = {
+    name: string;
+    local: string;
+    path: string | null;
+};
+export declare const OUTSIDE = "#outside";
+export declare function resolveTs(root: string, from: string, spec: string, read: Read): string | null;
+export declare function resolvePy(root: string, from: string, mod: string, read: Read, top?: string): string | null;
+export declare function importsOf(root: string, file: CodeFile, read: Read): Import[];
+export declare function leadsTo(root: string, fromPath: string, toPath: string, name: string, read?: Read, cache?: Map<string, CodeFile | null>, depth?: number): string | null;

package/dist/imports.js

@@ -0,0 +1,235 @@
+import { builtinModules } from 'node:module';
+import { posix, resolve } from 'node:path';
+import { codeFile, esc, langOf, outside, readFile } from './code.js';
+export const OUTSIDE = '#outside';
+const TS_EXT = ['', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '/index.ts', '/index.tsx', '/index.js'];
+const readIn = (root, path, read) => (outside(root, path) ? null : read(resolve(root, path)));
+const has = (root, path, read) => readIn(root, path, read) != null;
+function tsConfig(root, read) {
+    const paths = [];
+    let baseUrl;
+    let cfg = 'tsconfig.json';
+    for (let k = 0; k < 4 && cfg; k++) {
+        const raw = readIn(root, cfg, read);
+        if (raw == null)
+            break;
+        const dir = posix.dirname(cfg);
+        const own = /"baseUrl"\s*:\s*"([^"]*)"/.exec(raw)?.[1];
+        if (own != null)
+            baseUrl ??= posix.join(dir, own);
+        const block = /"paths"\s*:\s*\{([^}]*)\}/.exec(raw)?.[1] ?? '';
+        for (const m of block.matchAll(/"([^"]+)"\s*:\s*\[\s*"([^"]+)"/g))
+            paths.push({ base: own != null ? posix.join(dir, own) : dir, key: m[1], target: m[2] });
+        const ext = /"extends"\s*:\s*"(\.[^"]+)"/.exec(raw)?.[1];
+        cfg = ext ? posix.join(dir, ext.endsWith('.json') ? ext : `${ext}.json`) : '';
+    }
+    return { paths, baseUrl };
+}
+export function resolveTs(root, from, spec, read) {
+    const bases = [];
+    if (spec.startsWith('.'))
+        bases.push(posix.join(posix.dirname(from), spec));
+    else {
+        const cfg = tsConfig(root, read);
+        for (const { base, key, target } of cfg.paths) {
+            const star = key.indexOf('*');
+            const pre = star < 0 ? key : key.slice(0, star);
+            const post = star < 0 ? '' : key.slice(star + 1);
+            if (star < 0 ? spec !== key : !(spec.startsWith(pre) && spec.endsWith(post) && spec.length >= key.length - 1))
+                continue;
+            bases.push(posix.join(base, star < 0 ? target : target.replace('*', spec.slice(pre.length, spec.length - post.length))));
+        }
+        if (cfg.baseUrl != null)
+            bases.push(posix.join(cfg.baseUrl, spec));
+    }
+    for (const b of bases) {
+        const base = b.replace(/\.(js|mjs|cjs|jsx)$/, '');
+        const hit = TS_EXT.map((e) => base + e).find((p) => has(root, p, read));
+        if (hit)
+            return hit;
+    }
+    return spec.startsWith('node:') || builtinModules.includes(spec.split('/')[0]) ? OUTSIDE : null;
+}
+function pyTop(root, from, read) {
+    let d = posix.dirname(from);
+    while (d !== '.' && has(root, `${d}/__init__.py`, read))
+        d = posix.dirname(d);
+    return d;
+}
+export function resolvePy(root, from, mod, read, top) {
+    const hit = (b) => [`${b}.py`, `${b}/__init__.py`].find((p) => has(root, p, read)) ?? null;
+    if (mod.startsWith('.')) {
+        const dots = /^\.+/.exec(mod)[0].length;
+        let d = posix.dirname(from);
+        for (let k = 1; k < dots; k++) {
+            if (d === '.')
+                return null;
+            d = posix.dirname(d);
+        }
+        return hit(posix.join(d, mod.slice(dots).replace(/\./g, '/')));
+    }
+    const rel = mod.replace(/\./g, '/');
+    const d = top ?? pyTop(root, from, read);
+    return hit(rel) ?? (d === '.' ? null : hit(posix.join(d, rel)));
+}
+function goModule(root, from, read) {
+    let dir = posix.dirname(from);
+    for (;;) {
+        const text = readIn(root, posix.join(dir, 'go.mod'), read);
+        if (text != null)
+            return { mod: /module\s+(\S+)/.exec(text)?.[1], dir, text };
+        if (dir === '.')
+            return { dir, text: '' };
+        dir = posix.dirname(dir);
+    }
+}
+function goWork(root, from, read) {
+    for (let d = posix.dirname(from);; d = posix.dirname(d)) {
+        const text = readIn(root, posix.join(d, 'go.work'), read);
+        if (text != null)
+            return [...text.matchAll(/^\s*(?:use\s+)?"?(\.[^\s")]*)"?\s*$/gm)].flatMap((m) => {
+                const dir = posix.join(d, m[1]);
+                const mod = /module\s+(\S+)/.exec(readIn(root, posix.join(dir, 'go.mod'), read) ?? '')?.[1];
+                return mod ? [{ mod, dir }] : [];
+            });
+        if (d === '.')
+            return [];
+    }
+}
+const goRequired = (text, p) => [...text.matchAll(/^\s*(?:require\s+)?([\w.~-]+\/[\w.~/-]+)\s+v\S+/gm)].some((m) => (p === m[1] || p.startsWith(`${m[1]}/`)) && !new RegExp(`^\\s*(?:replace\\s+)?${esc(m[1])}\\b[^\\n]*=>`, 'm').test(text));
+export function importsOf(root, file, read) {
+    const { keep, lang, path } = file;
+    const out = [];
+    const add = (name, local, to) => out.push({ name, local, path: to });
+    if (lang === 'ts') {
+        for (const m of keep.matchAll(/\bimport\s+(type\s+)?([\s\S]*?)\s+from\s+(["'])([^"']+)\3/g)) {
+            const to = resolveTs(root, path, m[4], read);
+            const clause = m[2];
+            const def = /^([A-Za-z_$][\w$]*)\s*(,|$)/.exec(clause);
+            if (def)
+                add('default', def[1], to);
+            const ns = /\*\s+as\s+([A-Za-z_$][\w$]*)/.exec(clause);
+            if (ns)
+                add('*', ns[1], to);
+            const named = /\{([\s\S]*)\}/.exec(clause);
+            if (named)
+                for (const part of named[1].split(',')) {
+                    const p = part.trim().replace(/^type\s+/, '');
+                    if (!p)
+                        continue;
+                    const [a, b] = p.split(/\s+as\s+/);
+                    add(a.trim(), (b ?? a).trim(), to);
+                }
+        }
+        for (const m of keep.matchAll(/\b(?:const|let|var)\s+(\{[^}]*\}|[A-Za-z_$][\w$]*)\s*=\s*(?:await\s+)?(?:require|import)\((["'])([^"']+)\2\)/g)) {
+            const to = resolveTs(root, path, m[3], read);
+            if (m[1].startsWith('{'))
+                for (const p of m[1].slice(1, -1).split(',')) {
+                    const [a, b] = p.split(':').map((x) => x.trim());
+                    if (a)
+                        add(a, b ?? a, to);
+                }
+            else
+                add('*', m[1], to);
+        }
+    }
+    else if (lang === 'py') {
+        const top = pyTop(root, path, read);
+        for (const m of keep.matchAll(/^[ \t]*from\s+([\w.]+)\s+import\s+(\([^)]*\)|[^\n]+)/gm)) {
+            const to = resolvePy(root, path, m[1], read, top);
+            for (const part of m[2].replace(/[()]/g, '').split(',')) {
+                const p = part.trim();
+                if (!p)
+                    continue;
+                const [a, b] = p.split(/\s+as\s+/).map((x) => x.trim());
+                const sub = resolvePy(root, path, (m[1].endsWith('.') ? m[1] : `${m[1]}.`) + a, read, top);
+                if (sub)
+                    add('*', b ?? a, sub);
+                else
+                    add(a, b ?? a, to);
+            }
+        }
+        for (const m of keep.matchAll(/^[ \t]*import\s+([\w.]+)(\s+as\s+(\w+))?/gm))
+            add('*', m[3] ?? m[1].split('.')[0], resolvePy(root, path, m[1], read, top));
+    }
+    else if (lang === 'go') {
+        const { mod, dir, text } = goModule(root, path, read);
+        let work;
+        for (const m of keep.matchAll(/^\s*(?:import\s+)?(\w+|\.|_)?\s*"([^"]+)"/gm)) {
+            const p = m[2];
+            const inside = (w) => w.mod && (p === w.mod || p.startsWith(`${w.mod}/`));
+            const own = [
+                { mod, dir },
+                ...(p.split('/')[0].includes('.') && !inside({ mod, dir }) ? (work ??= goWork(root, path, read)) : []),
+            ].find(inside);
+            const to = own
+                ? posix.join(own.dir, p.slice(own.mod.length + 1))
+                : p.split('/')[0].includes('.') && !goRequired(text, p)
+                    ? null
+                    : OUTSIDE;
+            add('*', m[1] ?? p.split('/').at(-1), to);
+        }
+    }
+    return out;
+}
+function reexports(root, file, name, read) {
+    const N = esc(name);
+    const out = [];
+    if (name === '*')
+        return out;
+    if (file.lang === 'py') {
+        if (new RegExp(`^(?:(?:async\\s+)?def|class)\\s+${N}\\b|^${N}\\s*[:=]`, 'm').test(file.code))
+            return out;
+        for (const i of importsOf(root, file, read))
+            if (i.local === name || i.local === '*')
+                out.push([i.path, i.local === '*' ? '?' : i.name]);
+        return out.length > 1 ? [[null, '?']] : out;
+    }
+    if (file.lang !== 'ts')
+        return out;
+    if (new RegExp(`^export\\s+(?:default\\s+)?(?:async\\s+)?(?:function\\s*\\*?|class|const|let|var|enum)\\s*${N}\\b`, 'm').test(file.code))
+        return out;
+    for (const m of file.keep.matchAll(/\bexport\s+(?:type\s+)?(\*(?:\s+as\s+([\w$]+))?|\{([^}]*)\})\s+from\s+(["'])([^"']+)\4/g)) {
+        const p = resolveTs(root, file.path, m[5], read);
+        if (m[3] != null) {
+            for (const part of m[3].split(',')) {
+                const [a, b] = part
+                    .trim()
+                    .replace(/^type\s+/, '')
+                    .split(/\s+as\s+/);
+                if (a && (b ?? a).trim() === name)
+                    out.push([p, a.trim()]);
+            }
+        }
+        else if (m[2] == null ? name !== 'default' : m[2] === name)
+            out.push([p, m[2] == null ? name : '*']);
+    }
+    for (const m of file.keep.matchAll(/\bexport\s*\{([^}]*)\}(?!\s*from)/g))
+        for (const part of m[1].split(',')) {
+            const [a, b] = part.trim().split(/\s+as\s+/);
+            if (!a || (b ?? a).trim() !== name)
+                continue;
+            const i = importsOf(root, file, read).find((x) => x.local === a.trim());
+            if (i)
+                out.push([i.path, i.name]);
+        }
+    return out;
+}
+export function leadsTo(root, fromPath, toPath, name, read = readFile, cache = new Map(), depth = 0) {
+    if (fromPath === toPath)
+        return name;
+    if (langOf(fromPath) == null)
+        return posix.dirname(toPath) === fromPath ? name : null;
+    const file = depth < 5 ? codeFile(root, fromPath, read, cache) : null;
+    if (!file)
+        return null;
+    let star = false;
+    for (const [path, inner] of reexports(root, file, name, read)) {
+        const r = path == null || inner === '?' ? null : leadsTo(root, path, toPath, inner, read, cache, depth + 1);
+        if (r === '?' || inner === '?')
+            star = true;
+        else if (r != null)
+            return r;
+    }
+    return star ? '?' : null;
+}

package/dist/index.js

@@ -1,11 +1,11 @@
 'use client';
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useEffect, useMemo, useRef, useState } from 'react';
-import { route } from './geometry.js';
+import { arcRoom, avoidOf, 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, 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';
+import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, 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, labelLines, fitCap, LABEL_LINE, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, edgeTip, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const DEFAULTS = { ...LIGHT, font: 'inherit' };
 const v = (k) => `var(--fig-${k}, ${DEFAULTS[k]})`;
@@ -95,7 +95,9 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             : []),
     ]), [layout, tl, edges, timeline, today]);
     const step = active == null ? null : steps[active];
+    const allBeats = useMemo(() => steps.flatMap((s) => s.flow.map(toBeat)), [steps]);
     const beats = useMemo(() => (step?.flow ?? []).map(toBeat), [step]);
+    const cap = useMemo(() => fitCap({ layout, edges, steps, lanes, timeline }, 830), [layout, edges, steps, lanes, timeline]);
     const carded = useMemo(() => {
         const all = new Map();
         for (const b of steps.flatMap((s) => s.flow.map(toBeat)))
@@ -155,25 +157,18 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     h: r.height / k,
                 };
             });
-            const avoid = [];
+            const extra = [];
             el.querySelectorAll('[data-fig-outside]').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 });
+                extra.push({ x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k });
             });
-            if (tl)
-                for (const n of nodes(layout))
-                    if (rects[n.id])
-                        avoid.push({ ...rects[n.id], box: true });
             const stubs = lanePlan?.stubs ?? new Map();
-            if (stubs.size) {
-                for (const n of nodes(layout))
-                    if (rects[n.id])
-                        avoid.push(rects[n.id]);
+            if (stubs.size)
                 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 });
+                    extra.push({ x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k });
                 });
-            }
+            const avoid = avoidOf(nodes(layout).flatMap((n) => (rects[n.id] ? [rects[n.id]] : [])), extra, stubs.size > 0);
             const bands = {};
             el.querySelectorAll('[data-fig-copy]').forEach((n) => {
                 const r = n.getBoundingClientRect();
@@ -208,7 +203,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     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)) }),
+                ...(!tl && 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) {
@@ -285,7 +280,17 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     const e = edges[ids.indexOf(r.id)];
                     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 }) }];
+                    return [
+                        {
+                            id: r.id,
+                            from: e.from,
+                            to: e.to,
+                            curve: r.curve,
+                            label: labels[r.id],
+                            ...(tl && { behind: true }),
+                            ...(r.elbow && { elbow: r.elbow }),
+                        },
+                    ];
                 }),
                 ...(rail?.rows ?? []).flatMap((row) => {
                     const r = row.kind === 'message' ? labels[`rail:${row.n}`] : undefined;
@@ -458,7 +463,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         const inside = it.labelInside;
         const outside = (_jsx("span", { "data-fig-outside": "", style: { position: 'absolute', left: '100%', marginLeft: 6, whiteSpace: 'nowrap', fontSize: 13, fontWeight: 500, color: v('fg') }, children: label }));
         const top = LANE_PAD + it.row * (TL_BAR_H + TL_ROW_GAP);
-        return (_jsxs("div", { "data-fig": n.id, "data-diamond": it.milestone || undefined, onMouseEnter: () => setHover(n.id), onMouseLeave: () => setHover(null), style: {
+        return (_jsxs("div", { "data-fig": n.id, title: n.source, "data-diamond": it.milestone || undefined, onMouseEnter: () => setHover(n.id), onMouseLeave: () => setHover(null), style: {
                 position: 'absolute',
                 left: it.x,
                 top: it.milestone ? top + (TL_BAR_H - it.w) / 2 : top,
@@ -648,13 +653,15 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         const store = item.shape === 'store';
         const card = carded.has(item.id);
         const dl = diamond && !card ? diamondLines(item, nodeWidth(item, false) + 70) : null;
+        const w = diamond || card || item.width != null || str(item.label) ? nodeWidth(item, card, cap) + (diamond ? 70 : 0) : undefined;
+        const lines = w != null && !diamond && str(item.label) ? labelLines(item, w) : 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: {
+        return (_jsxs("div", { "data-fig": item.id, title: item.source, "data-diamond": diamond || undefined, onMouseEnter: () => setHover(item.id), onMouseLeave: () => setHover(null), style: {
                 position: 'relative',
                 isolation: 'isolate',
                 minWidth: 100,
-                maxWidth: card || diamond ? undefined : 190,
-                width: diamond ? nodeWidth(item, card) + 70 : (item.width ?? (card ? CARD_WIDTH : undefined)),
+                maxWidth: w == null ? cap : undefined,
+                width: w,
                 minHeight: dl ? Math.max(dl.h, (minHeight(item.id) ?? 0) + 24) : minHeight(item.id),
                 boxSizing: 'border-box',
                 display: 'flex',
@@ -707,7 +714,7 @@ 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 }), dl
+                    } })), lines ? (lines.map((l, i) => (_jsx("div", { style: { whiteSpace: 'nowrap', lineHeight: `${LABEL_LINE}px` }, children: l }, i)))) : (_jsx("div", { style: { lineHeight: `${LABEL_LINE}px` }, 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,
@@ -780,11 +787,10 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                 margin: '0 auto',
                                 transform: fit.scale < 1 ? `scale(${fit.scale})` : undefined,
                                 transformOrigin: 'top left',
-                                padding: 4,
-                                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,
+                                paddingTop: arcRoom(routed, 'above') || 4,
+                                paddingBottom: arcRoom(routed, 'below') || 4,
+                                paddingLeft: arcRoom(routed, 'left') || 4,
+                                paddingRight: arcRoom(routed, 'right') || 4,
                             }, children: [renderItem(layout, 0), _jsxs("svg", { style: {
                                         position: 'absolute',
                                         inset: 0,
@@ -797,11 +803,12 @@ 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;
+                                            const tip = edgeTip(r.id, edges[ids.indexOf(r.id)].source, allBeats);
                                             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));
+                                                    : 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', pointerEvents: tip ? 'stroke' : undefined }, children: tip && _jsx("title", { children: tip }) }, key));
                                             const guide = (_jsx("path", { ref: (p) => {
                                                     paths.current[r.id] = p;
                                                 }, d: r.d, fill: "none", stroke: "none" }, r.id));
@@ -899,7 +906,8 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                             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 ? (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 tip = edgeTip(row.edge, edges[ids.indexOf(row.edge)].source, allBeats);
+                            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: [tip && _jsx("title", { children: tip }), 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;
                                             const tx = !row.pill ? (x1 + x2) / 2 - tagW / 2 : x2 > x1 ? row.pill.x - tagW - 4 : row.pill.x + row.pill.w + 4;

package/dist/load.d.ts

@@ -8,3 +8,5 @@ export declare function svgWithSpec(props: FlowProps, opts?: SvgOptions, svg?: s
 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[];
+export declare function summaryLines(props: FlowProps): string[];
+export declare function verifyLines(props: FlowProps, figure: string, root?: string): string[];

package/dist/load.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
-import { counts } from './model.js';
+import { counts, toBeat } from './model.js';
+import { coverageLine, owners, unsureLines, verifyReport } from './verify.js';
 import { toSvg } from './svg.js';
 const SPEC_OPEN = '<metadata id="figure-spec"><![CDATA[';
 const SPEC_CLOSE = ']]></metadata>';
@@ -54,3 +55,25 @@ export function reportLines(props, findings, withCounts = true) {
     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;
 }
+const text = (x) => (typeof x === 'string' ? x : '');
+export function summaryLines(props) {
+    const edges = props.edges.map((e) => {
+        const label = text(e.label);
+        return `${e.from} -> ${e.to}${label ? `: ${label}` : ''}`;
+    });
+    const steps = (props.steps ?? []).map((s) => {
+        const hops = s.flow.reduce((k, b) => k + toBeat(b).hops.length, 0);
+        return `step "${text(s.label)}": ${hops} ${hops === 1 ? 'hop' : 'hops'}`;
+    });
+    return [...edges, ...steps];
+}
+export function verifyLines(props, figure, root = process.cwd()) {
+    if (!owners(props).some(([, source, via]) => source != null || via != null))
+        return [];
+    const { findings, coverage } = verifyReport(props, { root });
+    return [
+        ...findings.map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${figure}: ${f.message}`),
+        coverageLine(figure, coverage),
+        ...unsureLines(coverage),
+    ];
+}

package/dist/mcp.d.ts

@@ -13,6 +13,10 @@ export declare const TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            topic: {
+                type: string;
+                enum: string[];
+            };
             paths?: undefined;
             root?: undefined;
             strict?: undefined;
@@ -72,6 +76,7 @@ export declare const TOOLS: ({
                 type: string;
                 description: string;
             };
+            topic?: undefined;
             out: {
                 type: string;
                 description: string;
@@ -89,6 +94,7 @@ export declare const TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            topic?: undefined;
             paths: {
                 type: string;
                 items: {
@@ -114,6 +120,7 @@ export declare const TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            topic?: undefined;
             paths?: undefined;
             root?: undefined;
             strict?: undefined;

package/dist/mcp.js

@@ -2,11 +2,11 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { diff, formatDiff } from './diff.js';
-import { GUIDE } from './guide.js';
-import { loadSpec, reportLines, sortFindings, svgWithSpec } from './load.js';
+import { GUIDE, TOPICS } from './guide.js';
+import { loadSpec, reportLines, sortFindings, summaryLines, svgWithSpec, verifyLines } from './load.js';
 import { check, render } from './svg.js';
 import { checkRendered } from './check.js';
-import { verify } from './verify.js';
+import { coverageLine, unsureLines, verifyReport } from './verify.js';
 import { VERSION } from './version.js';
 const specSchema = {
     description: 'The figure: the props object, { props }, or a path to a .json file or an SVG that flowfig wrote.',
@@ -19,7 +19,11 @@ const checkProps = {
     minText: { type: 'number', description: 'The smallest text in px at that width. Default 10.' },
 };
 export const TOOLS = [
-    { name: 'docs', description: 'The flowfig guide. Read it before the first render.', inputSchema: { type: 'object', properties: {} } },
+    {
+        name: 'docs',
+        description: 'The flowfig guide. Read it before the first render. A topic gives the detail for one kind of figure.',
+        inputSchema: { type: 'object', properties: { topic: { type: 'string', enum: Object.keys(TOPICS) } } },
+    },
     {
         name: 'check',
         description: 'List the faults of a figure: unknown ids, text overflow, crossings, label overlap, small text, low contrast. Fix every error before render.',
@@ -84,8 +88,14 @@ const types = (args, tool, want) => {
     }
 };
 function run(name, args) {
-    if (name === 'docs')
-        return ok(GUIDE);
+    if (name === 'docs') {
+        const topic = args.topic;
+        if (topic == null)
+            return ok(GUIDE);
+        if (typeof topic !== 'string' || !Object.hasOwn(TOPICS, topic))
+            throw new Bad(`docs: topic must be one of ${Object.keys(TOPICS).join(', ')}`);
+        return ok(TOPICS[topic]);
+    }
     if (name === 'check' || name === 'render') {
         need(args, name, name === 'render' ? ['spec', 'out'] : ['spec']);
         types(args, name, { width: 'number', minText: 'number', out: 'string', strict: 'boolean' });
@@ -106,7 +116,7 @@ function run(name, args) {
         catch (e) {
             throw new Fault(`${out}: ${e.message}`);
         }
-        return ok([...lines, `${out} — ${(svg.length / 1024).toFixed(1)} kB`].join('\n'));
+        return ok([...lines, ...summaryLines(props), ...verifyLines(props, out), `${out} — ${(svg.length / 1024).toFixed(1)} kB`].join('\n'));
     }
     if (name === 'verify') {
         need(args, name, ['paths']);
@@ -115,6 +125,7 @@ function run(name, args) {
         types(args, name, { root: 'string', strict: 'boolean' });
         const root = args.root == null ? process.cwd() : String(args.root);
         const lines = [];
+        const counts = [];
         let errors = 0;
         for (const p of args.paths) {
             let props;
@@ -128,13 +139,15 @@ function run(name, args) {
                 lines.push(`${'error'.padEnd(8)} ${'missing-file'.padEnd(18)} ${e.message}`);
                 continue;
             }
-            const findings = sortFindings([...check(props), ...verify(props, { root })], args.strict === true);
+            const report = verifyReport(props, { root });
+            counts.push(coverageLine(p, report.coverage), ...unsureLines(report.coverage));
+            const findings = sortFindings([...check(props), ...report.findings], args.strict === true);
             errors += findings.filter((f) => f.severity === 'error').length;
             lines.push(...findings.map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${p}: ${f.message}`));
         }
         const n = (k, w) => `${k} ${w}${k === 1 ? '' : 's'}`;
         const total = lines.length;
-        lines.push(`${n(errors, 'error')}, ${n(total - errors, 'warning')}`);
+        lines.push(`${n(errors, 'error')}, ${n(total - errors, 'warning')}`, ...counts);
         return ok(lines.join('\n'), errors > 0);
     }
     if (name === 'diff') {

package/dist/model.d.ts

@@ -58,6 +58,8 @@ export type FigEdge = {
     quiet?: boolean;
     /** Code this draws: `path` or `path#symbol` from the repo root. Checked by `flowfig verify`. */
     source?: string;
+    /** The route, queue, topic or table that carries this edge. Checked by `flowfig verify`. */
+    via?: string;
 };
 /** One packet on one edge. A string is the edge `id`. */
 export type FigHop = string | {
@@ -73,6 +75,8 @@ export type FigHop = string | {
     async?: boolean;
     /** Code this draws: `path` or `path#symbol` from the repo root. Checked by `flowfig verify`. */
     source?: string;
+    /** The route, queue, topic or table that carries this edge. Checked by `flowfig verify`. */
+    via?: string;
 };
 /** One moment of a step. No edges means a pause. */
 export type FigBeat = {
@@ -161,9 +165,11 @@ export type Beat = Omit<FigBeat, 'edges'> & {
         tone?: FigTone;
         async?: boolean;
         source?: string;
+        via?: string;
     }[];
 };
 export declare const toBeat: (b: FigHop | FigHop[] | FigBeat) => Beat;
+export declare const edgeTip: (id: string, source: string | undefined, beats: Beat[]) => string | undefined;
 export declare const isRows: (c: FigContent) => c is FigRow[];
 export declare const edgeId: (e: FigEdge) => string;
 export declare const isGroup: (x: FigNode | FigGroup) => x is FigGroup;
@@ -227,11 +233,17 @@ export declare const isLanesLayout: (g: FigGroup) => boolean;
 export declare const validAt: (at: unknown) => at is number;
 /** The time column of each box: first use in the steps, then layout order. `at` wins. */
 export declare function laneColumns(fig: FlowProps): Map<string, number>;
+export declare const LABEL_LINE = 18;
 export declare const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190;
 export declare const LANE_BLOCK_GAP = 40;
 export declare const STUB = 12, STUB_CLEAR = 8, STUB_ROOM = 30;
 /** The width of a box as the SVG draws it, before a diamond adds its 70 px. */
-export declare function nodeWidth(item: FigNode, carded: boolean): number;
+export declare function nodeWidth(item: FigNode, carded: boolean, cap?: number): number;
+export declare function labelLines(item: FigNode, w: number): string[];
+export declare function itemWidth(item: FigNode | FigGroup, carded: {
+    has(id: string): boolean;
+}, edges: FigEdge[], cap?: number): number;
+export declare function fitCap(fig: FlowProps, width: number, padding?: number): number;
 export declare const diamondRoom: (w: number, h: number, far: number) => number;
 /** The lines of a diamond with no card. The diamond grows 15 px for each sub line that wraps. */
 export declare function diamondLines(item: FigNode, w: number): {
@@ -338,5 +350,4 @@ export declare const counts: (p: FlowProps) => {
     steps: number;
     messages: number;
 };
-/** A row's default gap grows to hold its widest edge label, plus 8 px each side. */
 export declare function groupGap(g: FigGroup, edges: FigEdge[]): number;