flowfig 0.9.0 → 0.11.0

package/dist/model.js

@@ -95,7 +95,7 @@ export function laneColumns(fig) {
     return cols;
 }
 export const LABEL_LINE = 18;
-export const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190;
+export const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190, DIAMOND_MAX_W = 170;
 export const LANE_BLOCK_GAP = 40;
 export 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. */
@@ -106,14 +106,16 @@ export function nodeWidth(item, carded, cap = NODE_MAX_W) {
         return CARD_WIDTH;
     const label = textWidth(str(item.label), 14) + 32;
     const sub = textWidth(str(item.sub), 12) + 32;
-    return Math.min(item.shape === 'decision' ? NODE_MAX_W : cap, Math.max(NODE_MIN_W, label, sub));
+    return Math.min(item.shape === 'decision' ? DIAMOND_MAX_W : cap, Math.max(NODE_MIN_W, label, sub));
 }
 export function labelLines(item, w) {
     const label = str(item.label);
-    if (item.shape === 'decision' || textWidth(label, 14) <= w - 32 + 0.5)
+    if (item.shape === 'decision')
+        return wrap(label, w - 102 + 0.5, 14);
+    if (textWidth(label, 14) <= w - 32 + 0.5)
         return [label];
     const lines = wrap(label, w - 32, 14);
-    return lines.length === 2 && lines.every((l) => textWidth(l, 14) <= w - 32) ? lines : [label];
+    return lines.every((l) => textWidth(l, 14) <= w - 32) ? lines : [label];
 }
 export function itemWidth(item, carded, edges, cap = NODE_MAX_W) {
     if (!isGroup(item))
@@ -137,21 +139,28 @@ export function fitCap(fig, width, padding = 24) {
     return cap;
 }
 export const diamondRoom = (w, h, far) => w * Math.max(0, 1 - far / (h / 2)) - 8;
-/** The lines of a diamond with no card. The diamond grows 15 px for each sub line that wraps. */
 export function diamondLines(item, w) {
     const sub = item.sub ? str(item.sub) : '';
-    for (let n = sub ? 1 : 0;; n++) {
-        const h = 62 + 15 * n;
-        const dy0 = n ? -2 - 7.5 * (n - 1) : 5;
-        const at = (dy, size) => Math.max(Math.abs(dy - 0.75 * size), dy + 0.25 * size);
-        const last = n ? at(dy0 + 15 * n, 12) : 0;
+    const label = labelLines(item, w);
+    const k = label.length - 1;
+    const at = (dy, size) => Math.max(Math.abs(dy - 0.75 * size), dy + 0.25 * size);
+    for (let n = sub ? 1 : 0, h = 0;;) {
+        h = Math.max(h, 62 + 15 * n + LABEL_LINE * k);
+        const dy0 = (n ? 5.5 : 5) - 7.5 * n - (LABEL_LINE / 2) * k;
+        const last = n ? at(dy0 + LABEL_LINE * k + 15 * n, 12) : 0;
         const lines = n ? wrap(sub, diamondRoom(w, h, last), 12) : [];
-        if (lines.length <= n || n >= 6)
-            return {
-                h,
-                label: { dy: dy0, far: at(dy0, 14) },
-                subs: lines.map((text, k) => ({ text, dy: dy0 + 15 * (k + 1), far: at(dy0 + 15 * (k + 1), 12) })),
-            };
+        const labels = label.map((text, i) => ({ text, dy: dy0 + LABEL_LINE * i, far: at(dy0 + LABEL_LINE * i, 14) }));
+        const subs = lines.map((text, j) => ({
+            text,
+            dy: dy0 + LABEL_LINE * k + 15 * (j + 1),
+            far: at(dy0 + LABEL_LINE * k + 15 * (j + 1), 12),
+        }));
+        if (lines.length > n && n < 6)
+            n++;
+        else if (h < w && labels.some((l) => textWidth(l.text, 14) > diamondRoom(w, h, l.far)))
+            h += 4;
+        else
+            return { h, label: labels, subs };
     }
 }
 /** The lane copies whose stub end has no clear place. The renderer grows each by STUB_ROOM. */
@@ -451,7 +460,7 @@ export const counts = (p) => {
         messages: st.reduce((n, s) => n + s.flow.reduce((m, b) => m + toBeat(b).hops.length, 0), 0),
     };
 };
-const idsIn = (c) => (isGroup(c) ? [...(c.id ? [c.id] : []), ...c.children.flatMap(idsIn)] : [c.id]);
+export const idsIn = (c) => (isGroup(c) ? [...(c.id ? [c.id] : []), ...c.children.flatMap(idsIn)] : [c.id]);
 const LINE_CLEAR = 16;
 export function groupGap(g, edges) {
     const side = new Map();
@@ -503,3 +512,37 @@ export const altText = (fig) => {
         desc: [`The figure has these boxes: ${boxes.join(', ')}.`, ...lines].join('\n'),
     };
 };
+const keyOf = (v, path) => {
+    if (typeof v === 'function' || typeof v === 'symbol')
+        return undefined;
+    if (typeof v === 'bigint')
+        return `${v}n`;
+    if (typeof v !== 'object' || v === null)
+        return v;
+    if (path.includes(v))
+        return '[cycle]';
+    const at = [...path, v];
+    if (Array.isArray(v))
+        return v.map((x) => keyOf(x, at));
+    const el = v;
+    const proto = Object.getPrototypeOf(v);
+    if (!el.$$typeof && proto !== Object.prototype && proto !== null)
+        return '[object]';
+    const src = el.$$typeof ? { type: typeof el.type === 'string' ? el.type : el.type?.name, key: el.key, props: el.props } : v;
+    return Object.fromEntries(Object.entries(src).flatMap(([k, x]) => (k === 'ref' || k.startsWith('_') ? [] : [[k, keyOf(x, at)]])));
+};
+export const specKey = (...parts) => JSON.stringify(keyOf(parts, []));
+// Edge labels are 11 px, the smallest reader text at scale 1.
+const READER_PX = 11;
+const DESKTOP_PX = 9;
+const DESKTOP_BOX = 600;
+export const textFloor = (box) => (box < DESKTOP_BOX ? READER_PX : DESKTOP_PX);
+export const fitScale = (wide, box, map) => Math.max(wide ? 1 : textFloor(box) / READER_PX, Math.min(1, box / map));
+export const shownFont = (size, place, scale) => size * (place === 'map' ? scale.map : place === 'rail' ? scale.rail : 1);
+const folds = (box, row) => box * READER_PX < row * textFloor(box);
+export const nextWide = (wide, box, map) => {
+    const row = Math.abs(wide) || map;
+    if (!folds(box, row))
+        return 0;
+    return wide > 0 && map >= wide ? -wide : wide || map;
+};

package/dist/open.d.ts

@@ -7,6 +7,7 @@ export declare function openerFor(platform: NodeJS.Platform, file: string): Open
 /** The temp page name: each character other than a letter, digit, - or _ becomes -. */
 export declare function pageName(svgPath: string): string;
 export declare const openedLine: (page: string) => string;
+export declare function openFile(path: string): Promise<void>;
 /** Write the page to a new temp folder, then start the opener. Returns the written paths. */
 export declare function openSvg(svgPath: string, html?: string): Promise<string[]>;
 export declare function runOpen(argv: string[]): Promise<number>;

package/dist/open.js

@@ -20,6 +20,16 @@ export function pageName(svgPath) {
         .replace(/[^\w-]/g, '-') + '.html');
 }
 export const openedLine = (page) => `${page} — opened in the default browser`;
+export async function openFile(path) {
+    const o = process.env.FLOWFIG_OPENER
+        ? { cmd: process.env.FLOWFIG_OPENER, args: [path], verbatim: false }
+        : openerFor(process.platform, path);
+    await new Promise((resolve, reject) => {
+        const child = spawn(o.cmd, o.args, { detached: true, windowsHide: true, stdio: 'ignore', windowsVerbatimArguments: o.verbatim });
+        child.once('spawn', () => (child.unref(), resolve()));
+        child.once('error', (e) => reject(new Error(`${e.message}. Open ${path} in a browser.`)));
+    });
+}
 /** Write the page to a new temp folder, then start the opener. Returns the written paths. */
 export async function openSvg(svgPath, html) {
     const page = pageHtml(readFileSync(svgPath, 'utf8'), basename(svgPath));
@@ -30,14 +40,7 @@ export async function openSvg(svgPath, html) {
     writeFileSync(temp, page);
     if (html)
         writeFileSync(html, page);
-    const o = process.env.FLOWFIG_OPENER
-        ? { cmd: process.env.FLOWFIG_OPENER, args: [temp], verbatim: false }
-        : openerFor(process.platform, temp);
-    await new Promise((resolve, reject) => {
-        const child = spawn(o.cmd, o.args, { detached: true, windowsHide: true, stdio: 'ignore', windowsVerbatimArguments: o.verbatim });
-        child.once('spawn', () => (child.unref(), resolve()));
-        child.once('error', (e) => reject(new Error(`${e.message}. Open ${temp} in a browser.`)));
-    });
+    await openFile(temp);
     return html ? [temp, html] : [temp];
 }
 export async function runOpen(argv) {

package/dist/page.d.ts

@@ -1 +1,2 @@
-export declare function pageHtml(svg: string, title: string): string;
+export declare const esc: (s: string) => string;
+export declare function pageHtml(svg: string, title: string, before?: string, after?: string, head?: string): string;

package/dist/page.js

@@ -1,14 +1,15 @@
-const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-export function pageHtml(svg, title) {
+export const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export function pageHtml(svg, title, before = '', after = '', head = '') {
     // Use element selectors only: figure styles use class names.
     return `<!doctype html>
 <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${esc(title)}</title>
-<style>
+${head}<style>
 :root { color-scheme: light dark }
 body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: Canvas }
 svg { display: block; max-width: 100%; height: auto }
 </style>
-${svg}
+${before}${svg}${after}
 `;
 }

package/dist/svg.d.ts

@@ -1,10 +1,11 @@
 import { type CheckOptions } from './check.ts';
 import type { Finding, Scene } from './scene.ts';
+import type { DiffMarks } from './diff.ts';
 export type { CheckOptions } from './check.ts';
 export type { Finding, Scene } from './scene.ts';
 export type * from './model.ts';
 export { parseSource, links, type Link } from './source.ts';
-export { diff, formatDiff, type Change } from './diff.ts';
+export { diff, formatDiff, mergeFigures, type Change, type DiffMark, type DiffMarks } from './diff.ts';
 import { type FigTheme, type FlowProps } from './model.ts';
 export { LIGHT, DARK } from './model.ts';
 /** Options for `toSvg`, `render` and `check`. */
@@ -18,9 +19,13 @@ export type SvgOptions = {
     /** Lanes: page width and smallest text size that set the wrap. Default: 830 and 10. */
     width?: number;
     minText?: number;
+    /** Draws a still diff with a legend. `mergeFigures` makes the marks. */
+    marks?: DiffMarks;
+    /** Links a box to an href, by box id. `flowfig atlas` sets it. */
+    links?: Record<string, string>;
 };
 /** The SVG string and the scene it drew. The scene shape may change; use `toSvg` for the SVG only. */
-export declare function render(fig: FlowProps, opts?: SvgOptions): {
+export declare function render(spec: FlowProps, opts?: SvgOptions): {
     svg: string;
     scene: Scene;
 };

package/dist/svg.js

@@ -1,17 +1,23 @@
 // Wrapping is approximate: text is measured by character class, not by a browser.
-import { arcRoom, avoidOf, route } from './geometry.js';
+import { arcRoom, avoidOf, markSide, route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.js';
 import { textWidth, wrap } from './text.js';
 import { checkRendered, planFor } from './check.js';
+import { autoLayout, rowBreaks } from './auto.js';
 export { parseSource, links } from './source.js';
-export { diff, formatDiff } from './diff.js';
+export { diff, formatDiff, mergeFigures } from './diff.js';
 import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, STUB_ROOM, laneBlock, laneEnd, tightCopies, LABEL_LINE, itemWidth, labelLines, fitCap, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, altText, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, labelSpan, outsideLabelRect, edgeTip, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const LINE = CARD_LINE, CARD_SIDE = 8, ROW_GAP = 4;
 const SUB_LINE = 15;
+const MIN_W = 320;
 const FRAME_TOP = 37, FRAME_BOTTOM = 18;
-// The card-on fills approximate the player's 8 % accent tint.
-const vars = (t, cardOn) => `--accent:${t.accent}; --fg:${t.fg}; --muted:${t.muted}; --bg:${t.bg}; --surface:${t.surface}; --border:${t.border}; --card-on:${cardOn}; --tint:color-mix(in srgb, var(--accent) 10%, var(--surface));`;
+const color = (t, k) => {
+    const v = String(t[k]);
+    const depth = [...v].reduce((d, c) => (d < 0 ? d : d + (c === '(' ? 1 : c === ')' ? -1 : 0)), 0);
+    return /^[#a-zA-Z0-9 ,.%()/+-]+$/.test(v) && !/url\(/i.test(v) && depth === 0 ? v : LIGHT[k];
+};
+const vars = (t, cardOn) => `--accent:${color(t, 'accent')}; --fg:${color(t, 'fg')}; --muted:${color(t, 'muted')}; --bg:${color(t, 'bg')}; --surface:${color(t, 'surface')}; --border:${color(t, 'border')}; --card-on:${cardOn}; --tint:color-mix(in srgb, var(--accent) 10%, var(--surface));`;
 const content = (c) => (isRows(c) ? c : str(c));
 const esc = (s) => s.replace(/[<>&"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' })[c]);
 const n2 = (v) => Math.round(v * 10) / 10;
@@ -159,13 +165,39 @@ function place(item, x, y, s, out) {
         }
     }
 }
+const MARK_COLOR = { added: TONES.green, removed: TONES.red, changed: TONES.orange };
+const marked = (mark, inner) => mark === 'removed' ? `<g opacity="0.5" stroke-dasharray="5 4">${inner}</g>` : mark ? `<g stroke-width="2">${inner}</g>` : inner;
+function legendOf(m) {
+    const count = (kind) => Object.values(m.boxes).filter((k) => k === kind).length + Object.values(m.edges).filter((k) => k === kind).length;
+    const items = ['added', 'removed', 'changed'].filter(count).map((k) => ({ color: MARK_COLOR[k], text: `${k} ${count(k)}` }));
+    if (m.steps)
+        items.push({ color: 'none', text: 'steps: see the text diff' });
+    return items.length ? items : [{ color: 'none', text: 'no change in boxes and edges' }];
+}
+const legendWidths = (items) => items.map((i) => textWidth(i.text, 12) + (i.color === 'none' ? 0 : 16));
+const legendWidth = (items) => legendWidths(items).reduce((a, b) => a + b + 20, -20);
+function legendSvg(items, W, H) {
+    if (!items.length)
+        return '';
+    const widths = legendWidths(items);
+    let x = (W - legendWidth(items)) / 2;
+    return items
+        .map((i, k) => {
+        const sq = i.color === 'none' ? '' : `<rect x="${n2(x)}" y="${n2(H - 24)}" width="10" height="10" rx="2" fill="${i.color}"/>`;
+        const out = `${sq}<text x="${n2(x + (i.color === 'none' ? 0 : 16))}" y="${n2(H - 15)}" font-size="12" fill="var(--muted)">${esc(i.text)}</text>\n`;
+        x += widths[k] + 20;
+        return out;
+    })
+        .join('');
+}
 const SYSTEM_FONT = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
 /** The SVG string and the scene it drew. The scene shape may change; use `toSvg` for the SVG only. */
-export function render(fig, opts = {}) {
+export function render(spec, opts = {}) {
+    const fig = autoLayout(spec);
     const speed = (opts.speed ?? fig.speed ?? 900) / 1000 / BASE_RATE;
     const pad = opts.padding ?? 24;
     const tl = fig.timeline && isLanesLayout(fig.layout) ? timelineLayout(fig, TL_AXIS_W) : null;
-    const synthetic = tl != null && !fig.steps?.length;
+    const synthetic = tl != null && !fig.steps?.length && !opts.marks;
     const steps = synthetic ? timelineBeats(fig) : (fig.steps ?? []);
     const beats = steps.map((s) => s.flow.map(toBeat));
     const cards = new Map();
@@ -233,6 +265,7 @@ export function render(fig, opts = {}) {
             to: end(ids[i], e.to, false),
             around: e.around ?? (plan?.around.has(ids[i]) ? 'below' : undefined),
             ...(tl && { sides: ['r', 'l'], elbow: true }),
+            ...(rowBreaks.has(e) && { drop: true }),
             ...(stubs.has(ids[i]) && { stub: stubs.get(ids[i]).map(labelPillW), bands: [bandOf(ids[i], e.from, 0), bandOf(ids[i], e.to, 1)] }),
             ...(!tl && e.label != null && { labelW: labelPillW(str(e.label)) }),
         })), rects, tips, avoidOf(placed.filter((p) => !isGroup(p.item)), stubs.size
@@ -264,10 +297,10 @@ export function render(fig, opts = {}) {
         const dl = dia ? diamondLines(p.item, p.w) : null;
         const room = (far) => diamondRoom(p.w, p.h, far);
         const flat = (p.item.shape === 'decision' ? p.w - 70 : p.w) - 16;
-        const texts = labelLines(p.item, p.w).map((text) => ({
+        const texts = labelLines(p.item, p.w).map((text, i) => ({
             text,
             fontSize: 14,
-            room: dl ? room(dl.label.far) : flat,
+            room: dl ? room(dl.label[i].far) : flat,
         }));
         if (dl)
             for (const l of dl.subs)
@@ -451,8 +484,13 @@ export function render(fig, opts = {}) {
                 cls(p.lane && 'lane', anim(on, 'stroke: var(--accent)', 'stroke: var(--border)', 'n')) +
                 `/><text x="${n2(p.x + FRAME_SIDE)}" y="${n2(p.lane ? p.y + p.h / 2 + 4 : p.y + 20)}" class="frame">${esc(str(item.label).toUpperCase())}</text>`);
         }
-        const tip = (inner) => (item.source ? `<g><title>${esc(item.source)}</title>${inner}</g>` : inner);
-        const bt = item.tone && TONES[item.tone];
+        const diffMark = opts.marks?.boxes[item.id];
+        const href = opts.links?.[item.id];
+        const tip = (inner) => {
+            const body = marked(diffMark, item.source ? `<g><title>${esc(item.source)}</title>${inner}</g>` : inner);
+            return href == null ? body : `<a href="${esc(href)}" tabindex="-1">${body}</a>`;
+        };
+        const bt = diffMark ? MARK_COLOR[diffMark] : item.tone && TONES[item.tone];
         const stroke = cls(boxAnim(item.id, true, bt));
         if (p.tl) {
             const fill0 = bt ? toneTint(bt, 'var(--bg)') : 'var(--bg)';
@@ -473,7 +511,7 @@ export function render(fig, opts = {}) {
         const contents = cards.get(item.id);
         const cardTop = p.y + p.h - 10 - (contents ? cardH.get(item.id) : 0);
         const dl = item.shape === 'decision' && !contents ? diamondLines(item, p.w) : null;
-        const labelY = item.shape === 'store' ? p.y + 24 + 13 : contents ? p.y + 10 + 13 : p.y + p.h / 2 + (dl ? dl.label.dy : item.sub ? -2 : 5);
+        const labelY = item.shape === 'store' ? p.y + 24 + 13 : contents ? p.y + 10 + 13 : p.y + p.h / 2 + (dl ? dl.label[0].dy : item.sub ? -2 : 5);
         const shape = item.shape === 'decision'
             ? `<polygon points="${n2(cx)},${n2(p.y)} ${n2(p.x + p.w)},${n2(p.y + p.h / 2)} ${n2(cx)},${n2(p.y + p.h)} ${n2(p.x)},${n2(p.y + p.h / 2)}" fill="${fill0}" stroke="${stroke0}"${stroke}/>`
             : item.shape === 'store'
@@ -482,7 +520,7 @@ export function render(fig, opts = {}) {
                 : `<rect x="${n2(p.x)}" y="${n2(p.y)}" width="${n2(p.w)}" height="${n2(p.h)}" rx="10" fill="${fill0}" stroke="${stroke0}"${stroke}/>`;
         const lines = labelLines(item, p.w);
         const extra = (lines.length - 1) * LABEL_LINE;
-        const firstY = item.shape === 'store' || contents ? labelY : labelY - extra / 2;
+        const firstY = item.shape === 'store' || contents || dl ? labelY : labelY - extra / 2;
         const label = lines.map((l, i) => `<text x="${n2(cx)}" y="${n2(firstY + i * LABEL_LINE)}" class="label">${esc(l)}</text>`).join('');
         const sub = dl
             ? dl.subs.map((l) => `<text x="${n2(cx)}" y="${n2(p.y + p.h / 2 + l.dy)}" class="sub">${esc(l.text)}</text>`).join('')
@@ -490,11 +528,13 @@ export function render(fig, opts = {}) {
                 ? `<text x="${n2(cx)}" y="${n2(firstY + extra + SUB_LINE)}" class="sub">${esc(str(item.sub))}</text>`
                 : '';
         const dot = bt ?? 'var(--accent)';
-        const my = n2(p.y + p.h / 2);
+        const side = item.mark && markSide(item.id, item.mark, routed);
+        const mx = n2(side === 'l' ? p.x - 12 : side === 'r' ? p.x + p.w + 12 : cx);
+        const my = n2(side === 't' ? p.y - 12 : side === 'b' ? p.y + p.h + 12 : p.y + p.h / 2);
         const mark = item.mark === 'start'
-            ? `<circle cx="${n2(p.x - 12)}" cy="${my}" r="5" fill="${dot}"/>`
+            ? `<circle cx="${mx}" cy="${my}" r="5" fill="${dot}"/>`
             : item.mark === 'end'
-                ? `<circle cx="${n2(p.x + p.w + 12)}" cy="${my}" r="6.25" fill="none" stroke="${dot}" stroke-width="1.5"/><circle cx="${n2(p.x + p.w + 12)}" cy="${my}" r="4" fill="${dot}"/>`
+                ? `<circle cx="${mx}" cy="${my}" r="6.25" fill="none" stroke="${dot}" stroke-width="1.5"/><circle cx="${mx}" cy="${my}" r="4" fill="${dot}"/>`
                 : '';
         return tip(shape + label + sub + mark + (contents ? card(p, cardTop, contents) : ''));
     });
@@ -562,18 +602,21 @@ export function render(fig, opts = {}) {
         const lit = cls(toned
             ? frames(on.map((x, i) => (x ? `stroke: ${col[i]}; stroke-width: ${EDGE_ON}` : off)), 'e', off)
             : anim(on, `stroke: var(--accent); stroke-width: ${EDGE_ON}`, off, 'e'));
+        const em = opts.marks?.edges[r.id];
+        const line = em && (em !== 'changed' || e.label == null) ? MARK_COLOR[em] : 'var(--muted)';
         const tip = edgeTip(r.id, e.source, beats.flat());
         const path0 = r.stub
             ? r.stub.parts
-                .map((d) => `<path d="${d}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`)
+                .map((d) => `<path d="${d}" fill="none" stroke="${line}" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`)
                 .join('') + `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="none"/>`
-            : `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`;
+            : `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="${line}" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`;
         const path = tip ? `<g><title>${esc(tip)}</title>${path0}</g>` : path0;
-        const pill = (x, y, lw, text) => `<rect x="${n2(x - lw / 2)}" y="${n2(y - 9)}" width="${n2(lw)}" height="18" rx="9" fill="var(--bg)" stroke="var(--border)"` +
+        const pillColor = em ? MARK_COLOR[em] : undefined;
+        const pill = (x, y, lw, text) => `<rect x="${n2(x - lw / 2)}" y="${n2(y - 9)}" width="${n2(lw)}" height="18" rx="9" fill="${pillColor ? toneTint(pillColor, 'var(--bg)', 14) : 'var(--bg)'}" stroke="${pillColor ?? 'var(--border)'}"` +
             cls(toned
                 ? frames(on.map((x, i) => x ? `fill: ${tone[i] ? toneFill(col[i]) : col[i]}; stroke: ${col[i]}` : 'fill: var(--bg); stroke: var(--border)'), 'l', 'fill: var(--bg); stroke: var(--border)')
                 : anim(on, 'fill: var(--accent); stroke: var(--accent)', 'fill: var(--bg); stroke: var(--border)', 'l')) +
-            `/><text x="${n2(x)}" y="${n2(y + 4)}"${cls('edgelabel', anim(on, `fill: ${ON_ACCENT}`, 'fill: var(--muted)', 'x'))}>${esc(text)}</text>`;
+            `/><text x="${n2(x)}" y="${n2(y + 4)}"${cls('edgelabel', anim(on, `fill: ${ON_ACCENT}`, 'fill: var(--muted)', 'x'))}${pillColor ? ' style="fill: var(--fg)"' : ''}>${esc(text)}</text>`;
         let label = '';
         if (r.stub) {
             fonts.push(11);
@@ -586,7 +629,7 @@ export function render(fig, opts = {}) {
             fonts.push(11);
             label = pill(r.mid.x, r.mid.y, lw, str(e.label));
         }
-        return hidden ? `<g opacity="0"${shown}>${path}${label}</g>` : path + label;
+        return marked(em === 'removed' ? em : undefined, hidden ? `<g opacity="0"${shown}>${path}${label}</g>` : path + label);
     });
     const packets = hops.map((h, i) => {
         const t0 = h.t0 / total, t1 = h.t1 / total, tEnd = h.tEnd / total;
@@ -683,16 +726,21 @@ export function render(fig, opts = {}) {
     }
     const bounds = placed[0];
     const [arcT, arcB, arcL, arcR] = ['above', 'below', 'left', 'right'].map((w) => arcRoom(routed, w));
-    const capLines = [...new Set(captions)].flatMap((c) => wrap(c, Math.max(560, bounds.w), 13.5).length);
-    const mapW = Math.max(bounds.w + pad * 2 + arcL + arcR, 560);
+    const legend = opts.marks ? legendOf(opts.marks) : [];
+    const stepLabels = fig.rail || synthetic ? [] : steps.map((s) => textWidth(str(s.label), 13, true));
+    const floor = Math.max(MIN_W, ...[...stepLabels, legend.length ? legendWidth(legend) : 0].map((w) => w + 16));
+    const mapW = Math.max(bounds.w + pad * 2 + arcL + arcR, floor);
     const rail = fig.rail ? layoutRail(fig, fig.rail === 'only' ? 560 : mapW) : null;
     const only = fig.rail === 'only' && rail != null;
+    const wrapW = Math.max(only ? 560 : MIN_W, bounds.w);
+    const capLines = [...new Set(captions)].flatMap((c) => wrap(c, wrapW, 13.5).length);
     const capTop = rail ? 20 : 26;
     const capH = steps.length ? capTop + 4 + Math.max(0, ...capLines) * 20 : 0;
-    const W = only ? Math.max(560, rail.width) : Math.max(mapW, rail?.width ?? 0);
+    const W = only ? Math.max(560, floor, rail.width) : Math.max(mapW, rail?.width ?? 0);
     const mapH = only ? 0 : bounds.h + pad * 2 + arcT + arcB;
     const top = only ? pad : mapH + RAIL.gap;
-    const H = only ? pad + rail.height + capH : mapH + (rail ? RAIL.gap + rail.height : 0) + capH;
+    const legendH = opts.marks ? 34 : 0;
+    const H = (only ? pad + rail.height + capH : mapH + (rail ? RAIL.gap + rail.height : 0) + capH) + legendH;
     const shift = (W - (bounds.w + pad * 2 + arcL + arcR)) / 2 + arcL;
     const railX = rail ? (W - rail.width) / 2 : 0;
     const labels = rail || synthetic
@@ -703,7 +751,7 @@ export function render(fig, opts = {}) {
         });
     const said = [...new Set(captions)].map((text) => {
         const on = captions.map((c) => c === text);
-        const lines = wrap(text, Math.max(560, bounds.w), 13.5);
+        const lines = wrap(text, wrapW, 13.5);
         return (`<g opacity="0"${cls(anim(on, 'opacity: 1', 'opacity: 0', 'y'))}>` +
             lines.map((l, li) => `<text x="${n2(W / 2)}" y="${n2(H - capH + capTop + 16 + li * 20)}" class="caption">${esc(l)}</text>`).join('') +
             `</g>`);
@@ -828,10 +876,12 @@ ${todaySvg}
 `}${railSvg}
 ${labels.join('\n')}
 ${said.join('\n')}
-</svg>
+${legendSvg(legend, W, H)}</svg>
 `;
     if (rail)
         fonts.push(12, 13);
+    if (legend.length)
+        fonts.push(12);
     const scene = {
         width: n2(W),
         ...(!only && { area: { x: -shift, y: -arcT, w: W, h: mapH } }),

package/dist/trace.js

@@ -258,11 +258,18 @@ export function trace(start, { root = process.cwd(), depth = 2, max = 40, read =
 }
 const count = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
 export function traceLines(r, depth, max) {
-    const pairs = r.edges.map((e) => `${e.from} -> ${e.to}`);
-    const width = Math.max(0, ...pairs.map((p) => p.length));
+    const file = (id) => id.slice(0, id.indexOf('#'));
+    const lineNo = (e) => (e.at.startsWith(`${file(e.from)}:`) ? e.at.slice(file(e.from).length + 1) : e.at);
+    const width = Math.max(0, ...r.edges.map((e) => lineNo(e).length));
     const symbols = new Set([r.start, ...r.edges.map((e) => e.to)]).size;
+    let last = '';
     return [
-        ...r.edges.map((e, i) => `${pairs[i].padEnd(width)}   ${e.at}`),
+        ...r.edges.flatMap((e) => {
+            const head = e.from === last ? [] : [e.from];
+            last = e.from;
+            const to = file(e.to) === file(e.from) ? e.to.slice(e.to.indexOf('#') + 1) : e.to;
+            return [...head, `  ${lineNo(e).padEnd(width)}  ${to}`];
+        }),
         ...r.unsure.map((u) => `unsure  ${u.at}  ${u.reason}`),
         ...r.open.map((o) => `open    ${o.at}  ${o.reason}`),
         ...r.stops.map((s) => `stop    ${s.reason} ${s.reason === 'depth' ? depth : max}: ${count(s.count, 'symbol')} not followed`),

package/dist/verify.d.ts

@@ -16,6 +16,8 @@ export type Coverage = {
 };
 export declare const coverageLine: (figure: string, c: Coverage) => string;
 export declare const unsureLines: (c: Coverage) => string[];
+export declare const SPEC_MARK = "<metadata id=\"figure-spec\">";
+export declare function detailFindings(fig: FlowProps, root: string, read?: Read): Finding[];
 /** The links against the files under `root`. A path outside `root` counts as a missing file. */
 export declare function verifyReport(fig: FlowProps, { root, read, cache, }?: {
     root?: string;

package/dist/verify.js

@@ -3,8 +3,25 @@ import { edgeId, nodes, toBeat } from './model.js';
 import { headingSlug, links } from './source.js';
 import { codeFile, isDefined, outside, readFile } from './code.js';
 import { edgeResult } from './edges.js';
+import { reexports } from './imports.js';
 export { parseSource, headingSlug, owners, links } from './source.js';
 const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const defines = (root, file, symbol, read, cache, depth = 0) => {
+    if (!file || depth > 5)
+        return null;
+    if (isDefined(file, symbol))
+        return true;
+    let doubt = false;
+    for (const [path, inner] of reexports(root, file, symbol, read)) {
+        const target = path == null || inner === '?' ? null : codeFile(root, path, read, cache);
+        const r = inner === '*' ? (target ? true : null) : defines(root, target, inner, read, cache, depth + 1);
+        if (r)
+            return true;
+        if (r == null)
+            doubt = true;
+    }
+    return doubt ? null : false;
+};
 const hasHeading = (text, slug) => text.split('\n').some((line) => {
     const m = /^#{1,6}\s+(.*?)\s*#*\s*$/.exec(line);
     return m != null && headingSlug(m[1]) === slug;
@@ -15,14 +32,27 @@ export const coverageLine = (figure, c) => `${figure}: ${c.boxesDefined} of ${c.
         ? `; edges: ${c.found} found, ${c.notFound} not found, ${c.unsure} unsure, ${c.notChecked} not checked`
         : '');
 export const unsureLines = (c) => c.unsureEdges.map((e) => `unsure   edge "${e.id}": ${e.reason}`);
+export const SPEC_MARK = '<metadata id="figure-spec">';
+export function detailFindings(fig, root, read = readFile) {
+    return nodes(fig.layout).flatMap((n) => {
+        if (typeof n.detail !== 'string')
+            return [];
+        const text = outside(root, n.detail) ? null : read(resolve(root, n.detail));
+        const why = text == null ? 'file not found' : text.includes(SPEC_MARK) ? '' : 'no figure spec in the file';
+        return why
+            ? [{ rule: 'missing-detail', severity: 'warning', ids: [n.id], message: `box "${n.id}" -> ${n.detail}: ${why}` }]
+            : [];
+    });
+}
 /** The links against the files under `root`. A path outside `root` counts as a missing file. */
 export function verifyReport(fig, { root = process.cwd(), read = readFile, cache = new Map(), } = {}) {
     const findings = [];
     const coverage = emptyCoverage();
+    findings.push(...detailFindings(fig, root, read));
     const all = links(fig);
     if (!all.length)
         return {
-            findings: [{ rule: 'no-source', severity: 'warning', ids: [], message: 'no box, edge or hop has a source' }],
+            findings: [...findings, { rule: 'no-source', severity: 'warning', ids: [], message: 'no box, edge or hop has a source' }],
             coverage,
         };
     const files = new Map();
@@ -32,14 +62,17 @@ export function verifyReport(fig, { root = process.cwd(), read = readFile, cache
             files.set(full, outside(root, l.path) ? null : read(full));
         const text = files.get(full);
         const before = findings.length;
+        let doubt = false;
         const fail = (rule, what) => findings.push({ rule, severity: 'error', ids: [], message: `${l.owner} -> ${l.source}: ${what}` });
         if (text == null)
             fail('missing-file', 'file not found');
         else if (l.symbol) {
             const code = codeFile(root, l.path, read, cache);
             if (code) {
-                if (!isDefined(code, l.symbol))
+                const r = defines(root, code, l.symbol, read, cache);
+                if (r === false)
                     fail('missing-symbol', 'symbol not defined');
+                doubt = r == null;
             }
             else if (!new RegExp(`(^|[^\\w$])${escape(l.symbol)}(?![\\w$])`).test(text) &&
                 !(/\.(md|markdown)$/i.test(l.path) && hasHeading(text, l.symbol)))
@@ -47,7 +80,7 @@ export function verifyReport(fig, { root = process.cwd(), read = readFile, cache
         }
         if (l.owner.startsWith('box "')) {
             coverage.boxes++;
-            if (findings.length === before)
+            if (findings.length === before && !doubt)
                 coverage.boxesDefined++;
         }
     }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.9.0";
+export declare const VERSION = "0.11.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The release list bumps this with package.json.
-export const VERSION = '0.9.0';
+export const VERSION = '0.11.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowfig",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Your coding agent draws animated diagrams from your code, and flowfig checks each box and arrow against that code. CI fails when a diagram drifts from the code. The output is one animated SVG with no script, for a README, PR or issue. Works with Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf and Kiro.",
   "license": "MIT",
   "repository": {