flowfig 0.1.0 → 0.3.0

package/dist/mcp.d.ts

@@ -0,0 +1,139 @@
+export type Response = {
+    jsonrpc: '2.0';
+    id: unknown;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+};
+export declare const TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            paths?: undefined;
+            root?: undefined;
+            strict?: undefined;
+            old?: undefined;
+            new?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            spec: {
+                description: string;
+                anyOf: {
+                    type: string;
+                }[];
+            };
+            strict: {
+                type: string;
+                description: string;
+            };
+            width: {
+                type: string;
+                description: string;
+            };
+            minText: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            spec: {
+                description: string;
+                anyOf: {
+                    type: string;
+                }[];
+            };
+            strict: {
+                type: string;
+                description: string;
+            };
+            width: {
+                type: string;
+                description: string;
+            };
+            minText: {
+                type: string;
+                description: string;
+            };
+            out: {
+                type: string;
+                description: string;
+            };
+            paths?: undefined;
+            root?: undefined;
+            old?: undefined;
+            new?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            paths: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            root: {
+                type: string;
+                description: string;
+            };
+            strict: {
+                type: string;
+            };
+            old?: undefined;
+            new?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            paths?: undefined;
+            root?: undefined;
+            strict?: undefined;
+            old: {
+                description: string;
+                anyOf: {
+                    type: string;
+                }[];
+            };
+            new: {
+                description: string;
+                anyOf: {
+                    type: string;
+                }[];
+            };
+        };
+        required: string[];
+    };
+})[];
+/** One JSON-RPC message in, one response out; `undefined` for a notification. Pure, so the tests call it directly. */
+export declare function handle(message: unknown): Response | undefined;
+/** Read one message per line from `input`, write one response per line to `output`. Returns when `input` ends. */
+export declare function serve(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,216 @@
+// The MCP server: the check, render, verify, diff and docs tools over stdio JSON-RPC, for an agent with no shell.
+// No SDK: the subset the clients need is small, and the package keeps its zero dependencies.
+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 { check } from './svg.js';
+import { verify } 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.',
+    anyOf: [{ type: 'object' }, { type: 'string' }],
+};
+const checkProps = {
+    spec: specSchema,
+    strict: { type: 'boolean', description: 'Warnings count as errors.' },
+    width: { type: 'number', description: 'The page width in px the reader sees. Default 830.' },
+    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: 'check',
+        description: 'List the faults of a figure: unknown ids, text overflow, crossings, label overlap, small text, low contrast. Fix every error before render.',
+        inputSchema: { type: 'object', properties: checkProps, required: ['spec'] },
+    },
+    {
+        name: 'render',
+        description: 'Check a figure, then write it as one animated SVG file. Returns the check lines and the path. On an error, writes nothing.',
+        inputSchema: {
+            type: 'object',
+            properties: { ...checkProps, out: { type: 'string', description: 'The SVG path to write.' } },
+            required: ['spec', 'out'],
+        },
+    },
+    {
+        name: 'verify',
+        description: 'Check the code links (source) of one or more figures: the file and the symbol must exist under root.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                paths: { type: 'array', items: { type: 'string' }, description: 'Paths to .json files or SVGs.' },
+                root: { type: 'string', description: 'The folder the links resolve against. Default: the working directory.' },
+                strict: { type: 'boolean' },
+            },
+            required: ['paths'],
+        },
+    },
+    {
+        name: 'diff',
+        description: 'The spec changes between two figures, as a Markdown list.',
+        inputSchema: { type: 'object', properties: { old: specSchema, new: specSchema }, required: ['old', 'new'] },
+    },
+];
+class Bad extends Error {
+} // bad params: a JSON-RPC error, not a tool result
+class Fault extends Error {
+} // a path that cannot be read or written: a tool result with isError
+const ok = (text, isError = false) => isError ? { content: [{ type: 'text', text }], isError: true } : { content: [{ type: 'text', text }] };
+const spec = (v, name) => {
+    if (typeof v !== 'string' && (typeof v !== 'object' || v === null))
+        throw new Bad(`${name}: spec must be an object or a path`);
+    try {
+        return loadSpec(v);
+    }
+    catch (e) {
+        // The message of a path failure already starts with the path.
+        throw typeof v === 'string' ? new Fault(e.message) : new Bad(`${name}: ${e.message}`);
+    }
+};
+const need = (args, tool, keys) => {
+    for (const k of keys)
+        if (args[k] == null)
+            throw new Bad(`${tool}: ${k} is required`);
+};
+/** A present argument must have its type; a number must be positive. */
+const types = (args, tool, want) => {
+    for (const [k, t] of Object.entries(want)) {
+        const v = args[k];
+        if (v == null)
+            continue;
+        if (typeof v !== t || (t === 'number' && !(v > 0 && Number.isFinite(v)))) {
+            throw new Bad(`${tool}: ${k} must be ${t === 'number' ? 'a positive number' : `a ${t}`}`);
+        }
+    }
+};
+function run(name, args) {
+    if (name === 'docs')
+        return ok(GUIDE);
+    if (name === 'check' || name === 'render') {
+        need(args, name, name === 'render' ? ['spec', 'out'] : ['spec']);
+        types(args, name, { width: 'number', minText: 'number', out: 'string', strict: 'boolean' });
+        const props = spec(args.spec, name);
+        const opts = { width: args.width, minText: args.minText };
+        const findings = sortFindings(check(props, opts), args.strict === true);
+        const errors = findings.some((f) => f.severity === 'error');
+        const lines = reportLines(props, findings);
+        if (name === 'check' || errors)
+            return ok(lines.join('\n'), errors);
+        const out = String(args.out);
+        const svg = svgWithSpec(props);
+        try {
+            mkdirSync(dirname(out), { recursive: true });
+            writeFileSync(out, svg);
+        }
+        catch (e) {
+            throw new Fault(`${out}: ${e.message}`);
+        }
+        return ok([...lines, `${out} — ${(svg.length / 1024).toFixed(1)} kB`].join('\n'));
+    }
+    if (name === 'verify') {
+        need(args, name, ['paths']);
+        if (!Array.isArray(args.paths) || args.paths.some((p) => typeof p !== 'string'))
+            throw new Bad('verify: paths must be an array of strings');
+        types(args, name, { root: 'string', strict: 'boolean' });
+        const root = args.root == null ? process.cwd() : String(args.root);
+        const lines = [];
+        let errors = 0;
+        for (const p of args.paths) {
+            let props;
+            try {
+                props = spec(p, 'verify');
+            }
+            catch (e) {
+                if (!(e instanceof Fault))
+                    throw e;
+                errors++;
+                lines.push(`${'error'.padEnd(8)} ${'missing-file'.padEnd(18)} ${e.message}`);
+                continue;
+            }
+            const findings = sortFindings([...check(props), ...verify(props, { root })], 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')}`);
+        return ok(lines.join('\n'), errors > 0);
+    }
+    if (name === 'diff') {
+        need(args, name, ['old', 'new']);
+        return ok(formatDiff(diff(spec(args.old, 'diff'), spec(args.new, 'diff')), 'md'));
+    }
+    throw new Bad(`unknown tool "${name}"`);
+}
+const reply = (id, result) => ({ jsonrpc: '2.0', id, result });
+const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+/** One JSON-RPC message in, one response out; `undefined` for a notification. Pure, so the tests call it directly. */
+export function handle(message) {
+    if (typeof message !== 'object' || message === null)
+        return fail(null, -32600, 'invalid request');
+    const { id, method, params } = message;
+    const notification = id === undefined;
+    if (typeof method !== 'string')
+        return notification ? undefined : fail(id, -32600, 'invalid request');
+    if (notification)
+        return undefined; // a notification gets no reply, and a call sent as one does not run
+    const info = { name: 'flowfig', version: VERSION };
+    try {
+        switch (method) {
+            case 'initialize':
+                return reply(id, {
+                    protocolVersion: typeof params?.protocolVersion === 'string' ? params.protocolVersion : '2025-11-25',
+                    capabilities: { tools: {} },
+                    serverInfo: info,
+                });
+            case 'server/discover':
+                return reply(id, {
+                    resultType: 'complete',
+                    supportedVersions: ['2026-07-28'],
+                    capabilities: { tools: {} },
+                    _meta: { 'io.modelcontextprotocol/serverInfo': info },
+                });
+            case 'ping':
+                return reply(id, {});
+            case 'tools/list':
+                return reply(id, { tools: TOOLS });
+            case 'tools/call': {
+                const name = String(params?.name ?? '');
+                if (!TOOLS.some((t) => t.name === name))
+                    throw new Bad(`unknown tool "${name}"`);
+                return reply(id, run(name, params?.arguments ?? {}));
+            }
+            default:
+                return fail(id, -32601, `method not found: ${method}`);
+        }
+    }
+    catch (e) {
+        if (e instanceof Bad)
+            return fail(id, -32602, e.message);
+        if (e instanceof Fault)
+            return reply(id, ok(e.message, true));
+        return fail(id, -32603, e.message);
+    }
+}
+/** Read one message per line from `input`, write one response per line to `output`. Returns when `input` ends. */
+export async function serve(input, output) {
+    const rl = createInterface({ input, crlfDelay: Infinity });
+    for await (const line of rl) {
+        if (!line.trim())
+            continue;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            output.write(JSON.stringify(fail(null, -32700, 'parse error')) + '\n');
+            continue;
+        }
+        const response = handle(message);
+        if (response)
+            output.write(JSON.stringify(response) + '\n');
+    }
+}

package/dist/model.d.ts

@@ -13,6 +13,10 @@ export type FigNode = {
     lines?: number;
     /** Width in px. Overrides the width the layout picks. */
     width?: number;
+    /** A permanent state color for the box, such as a failing part. It gives a 1 px border and a light tint. An arrival with no hop tone uses it too. */
+    tone?: FigTone;
+    /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
+    source?: string;
 };
 /** A frame that lays out its children in a row or a column. Groups can hold groups. */
 export type FigGroup = {
@@ -43,6 +47,8 @@ export type FigEdge = {
     around?: 'above' | 'below';
     /** Draws the edge only while a step uses it. Use it for long edges that would cut across everything. */
     quiet?: boolean;
+    /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
+    source?: string;
 };
 /** One packet on one edge. A string is the edge `id`. */
 export type FigHop = string | {
@@ -52,8 +58,12 @@ export type FigHop = string | {
     back?: boolean;
     /** A small card that rides along with the packet. */
     data?: ReactNode;
+    /** Colors the packet, its data card, the edge and the box it arrives at, for this beat. The trail after the beat stays the accent. Default: the accent. */
+    tone?: FigTone;
     /** Marks a message that does not wait for an answer. The rail draws it dashed, with an `async` tag. Default: `false`. */
     async?: boolean;
+    /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
+    source?: string;
 };
 /** One moment of a step. No edges means a pause. */
 export type FigBeat = {
@@ -65,7 +75,7 @@ export type FigBeat = {
     show?: Record<string, FigContent>;
     /** Ids of boxes to highlight for this beat, without a packet or a content card. */
     light?: string[];
-    /** How long the beat lasts in ms. Default: the time one packet needs to cross an edge (`speed`). */
+    /** How long the beat lasts in ms. The packet crosses in `speed`; the rest is a hold. An explicit `ms` wins as written. Default: `speed` plus the time to read `say`. */
     ms?: number;
 };
 /** One line of a content card. */
@@ -83,8 +93,8 @@ export type FigRow = {
     /** Draws the text in a monospace font. Default: `false`. */
     mono?: boolean;
 };
-/** The color of a row tag. Each tone is a fixed color. */
-export type FigTone = 'blue' | 'purple' | 'green' | 'orange' | 'gray';
+/** The color of a row tag, a hop or a box. Each tone is a fixed color. */
+export type FigTone = 'blue' | 'purple' | 'green' | 'orange' | 'red' | 'gray';
 /** What a content card shows: rows, or anything React can render. */
 export type FigContent = FigRow[] | ReactNode;
 /** One story the figure can tell. The player shows one tab for each step. */
@@ -131,7 +141,9 @@ export type Beat = Omit<FigBeat, 'edges'> & {
         edge: string;
         back: boolean;
         data?: ReactNode;
+        tone?: FigTone;
         async?: boolean;
+        source?: string;
     }[];
 };
 export declare const toBeat: (b: FigHop | FigHop[] | FigBeat) => Beat;
@@ -148,6 +160,10 @@ export declare const BASE_RATE = 1.25;
 export declare const CARD_LINE = 15, CARD_PAD = 6;
 /** The fixed color of each row tone. */
 export declare const TONES: Record<FigTone, string>;
+/** A tone as a fill under white text: darker, so the text keeps its contrast. */
+export declare const toneFill: (c: string) => string;
+/** The light tint of a tone over a background: the fill of a toned box. */
+export declare const toneTint: (c: string, bg: string, pct?: number) => string;
 /** The width of an edge-label pill in px: the label text plus its padding. The rail uses it for a payload, so both look the same. */
 export declare const labelPillW: (label: string) => number;
 /** The width of the `async` tag in px. */
@@ -175,6 +191,12 @@ export declare const DARK: {
 export declare const ON_ACCENT = "#ffffff";
 /** Only text survives outside React: a React element has no string form. */
 export declare const str: (n: unknown) => string;
+/** The time a reader needs for a caption line: 400 ms plus 240 ms per word. The result is 0 for no text. */
+export declare const readMs: (say: unknown) => number;
+/** How long a beat lasts. An explicit `ms` wins as written. Else the beat lasts `speed` plus the time to read `say`. */
+export declare const beatMs: (b: Beat, speed: number) => number;
+/** The hold at the end of each step, before the next step starts. */
+export declare const STEP_HOLD_MS = 2000;
 export declare const nodes: (g: FigGroup) => FigNode[];
 /** The part counts of a spec, for the line that `flowfig check` prints. An agent copies the line into its reply. */
 export declare const counts: (p: FlowProps) => {

package/dist/model.js

@@ -25,8 +25,13 @@ export const TONES = {
     purple: '#8b5cf6',
     green: '#10b981',
     orange: '#f59e0b',
+    red: '#ef4444',
     gray: '#8b949e',
 };
+/** A tone as a fill under white text: darker, so the text keeps its contrast. */
+export const toneFill = (c) => `color-mix(in srgb, ${c} 64%, #000)`;
+/** The light tint of a tone over a background: the fill of a toned box. */
+export const toneTint = (c, bg, pct = 8) => `color-mix(in srgb, ${c} ${pct}%, ${bg})`;
 /** The width of an edge-label pill in px: the label text plus its padding. The rail uses it for a payload, so both look the same. */
 export const labelPillW = (label) => textWidth(label, 11, true) + 14;
 /** The width of the `async` tag in px. */
@@ -41,6 +46,15 @@ export const DARK = { accent: '#1f78c8', fg: '#e3e3e3', muted: '#9aa0a6', bg: '#
 export const ON_ACCENT = '#ffffff';
 /** Only text survives outside React: a React element has no string form. */
 export const str = (n) => (typeof n === 'string' || typeof n === 'number' ? String(n) : '');
+/** The time a reader needs for a caption line: 400 ms plus 240 ms per word. The result is 0 for no text. */
+export const readMs = (say) => {
+    const w = str(say).split(/\s+/).filter(Boolean).length;
+    return w ? 400 + 240 * w : 0;
+};
+/** How long a beat lasts. An explicit `ms` wins as written. Else the beat lasts `speed` plus the time to read `say`. */
+export const beatMs = (b, speed) => b.ms ?? speed + readMs(b.say);
+/** The hold at the end of each step, before the next step starts. */
+export const STEP_HOLD_MS = 2000;
 export const nodes = (g) => g.children.flatMap((c) => (isGroup(c) ? nodes(c) : [c]));
 const labeledGroups = (g) => (g.label ? 1 : 0) + g.children.reduce((n, c) => n + (isGroup(c) ? labeledGroups(c) : 0), 0);
 /** The part counts of a spec, for the line that `flowfig check` prints. An agent copies the line into its reply. */

package/dist/rail.d.ts

@@ -1,5 +1,5 @@
 import type { Rect } from './geometry.ts';
-import { type FlowProps } from './model.ts';
+import { type FigTone, type FlowProps } from './model.ts';
 export declare const RAIL: {
     readonly gap: 24;
     readonly band: 20;
@@ -45,6 +45,7 @@ export type RailRow = {
     to: number;
     text: string;
     async: boolean;
+    tone?: FigTone;
     pill?: {
         x: number;
         w: number;

package/dist/rail.js

@@ -43,6 +43,7 @@ export function layoutRail(fig, mapWidth) {
         back: h.back,
         text: str(h.data) || str(edges.get(h.edge).label),
         async: h.async === true,
+        tone: h.tone,
     }))));
     const msgs = perStep.flat(2);
     if (!msgs.length)
@@ -127,7 +128,20 @@ export function layoutRail(fig, mapWidth) {
                 const pill = m.text ? { x: mid - labelPillW(m.text) / 2, w: labelPillW(m.text) } : undefined;
                 if (group != null)
                     groups[group].rows.push(rows.length);
-                rows.push({ kind: 'message', step: si, beat: m.beat, n: ++n, edge: m.edge, from, to, text: m.text, async: m.async, pill, group });
+                rows.push({
+                    kind: 'message',
+                    step: si,
+                    beat: m.beat,
+                    n: ++n,
+                    edge: m.edge,
+                    from,
+                    to,
+                    text: m.text,
+                    async: m.async,
+                    tone: m.tone,
+                    pill,
+                    group,
+                });
             }
         }
     });

package/dist/scene.d.ts

@@ -12,12 +12,14 @@ export type SceneBox = {
     rect: Rect;
     texts: TextRun[];
 };
+/** `step` marks a rail row: rows of two steps never show at the same time, so their labels cannot overlap. */
 export type SceneEdge = {
     id: string;
     from: string;
     to: string;
     curve: [Pt, Pt, Pt, Pt];
     label?: Rect;
+    step?: number;
 };
 /** `minFont` is the smallest reading text in px, before any scale. Group frames are not boxes. */
 export type Scene = {

package/dist/source.d.ts

@@ -0,0 +1,18 @@
+import { type FlowProps } from './model.ts';
+/** `path` or `path#symbol`. No spaces, one `#` at most, both parts non-empty. `null` for a bad form. */
+export declare function parseSource(s: string): {
+    path: string;
+    symbol?: string;
+} | null;
+/** The GitHub anchor of a heading: lower case, only letters, digits, spaces and hyphens, spaces to hyphens. */
+export declare const headingSlug: (text: string) => string;
+export type Link = {
+    owner: string;
+    source: string;
+    path: string;
+    symbol?: string;
+};
+/** Every box, edge and hop with its raw `source`, well-formed or not. The one owner list that `links` and `checkSpec` share. */
+export declare function owners(fig: FlowProps): [string, string | undefined][];
+/** Every well-formed link in the figure, with the box, edge or hop that carries it. `bad-source` covers the rest. */
+export declare function links(fig: FlowProps): Link[];

package/dist/source.js

@@ -0,0 +1,29 @@
+// Code links, pure: no Node import, so the React and SVG entries stay browser-safe. `verify` in verify.ts reads the disk.
+import { edgeId, nodes, toBeat } from './model.js';
+/** `path` or `path#symbol`. No spaces, one `#` at most, both parts non-empty. `null` for a bad form. */
+export function parseSource(s) {
+    const m = /^([^\s#]+)(?:#([^\s#]+))?$/.exec(s);
+    if (!m)
+        return null;
+    return m[2] ? { path: m[1], symbol: m[2] } : { path: m[1] };
+}
+/** The GitHub anchor of a heading: lower case, only letters, digits, spaces and hyphens, spaces to hyphens. */
+export const headingSlug = (text) => text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N} -]/gu, '')
+    .replace(/ /g, '-');
+/** Every box, edge and hop with its raw `source`, well-formed or not. The one owner list that `links` and `checkSpec` share. */
+export function owners(fig) {
+    return [
+        ...nodes(fig.layout).map((n) => [`box "${n.id}"`, n.source]),
+        ...fig.edges.map((e) => [`edge "${edgeId(e)}"`, e.source]),
+        ...(fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => [`hop on "${h.edge}"`, h.source]))),
+    ];
+}
+/** Every well-formed link in the figure, with the box, edge or hop that carries it. `bad-source` covers the rest. */
+export function links(fig) {
+    return owners(fig).flatMap(([owner, source]) => {
+        const p = source == null ? null : parseSource(source);
+        return p ? [{ owner, source: source, ...p }] : [];
+    });
+}

package/dist/svg.d.ts

@@ -3,6 +3,8 @@ import type { Finding, Scene } from './scene.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';
 import { type FigTheme, type FlowProps } from './model.ts';
 export { LIGHT, DARK } from './model.ts';
 /** Options for `toSvg`, `render` and `check`. */