flowfig 0.3.0 → 0.4.0

package/README.md

@@ -28,6 +28,31 @@ An agent with the flowfig instructions made faithful, checked diagrams more ofte
 
 [How we measured](#how-we-measured).
 
+## Use it
+
+Set up your repo:
+
+```bash
+npx flowfig init
+```
+
+Then start a new agent session. In Claude Code, run:
+
+```
+/figure how does login work
+```
+
+With any agent, ask in plain words:
+
+```
+draw a diagram of how login works in this repo
+use flowfig to draw the checkout flow as a sequence
+draw the refund process with a lane for each team
+```
+
+The agent writes an SVG and ends its reply with `npx flowfig open <path>`. Run that command to see the animation in your
+browser.
+
 ## One command
 
 ```bash
@@ -41,18 +66,7 @@ checks the figure itself with `check --strict` and `verify`, and removes the spe
 `draw` exits 1 and shows the tool calls that the permission rules denied. `draw` prints the result, the reply of the agent
 and the cost of the run. `draw` needs Claude Code on the machine and a login. `draw` does not run on Windows yet.
 `--out` sets the path (it must end in `.svg`), `--model` sets the model, `--max-turns` sets the turn cap (default 40) and
-`--json` prints `{ out, reply, cost, session, findings }` for scripts.
-
-## Quick start
-
-```bash
-npx flowfig init
-```
-
-Then ask your agent: "draw a diagram of how login works in this repo".
-
-`init` writes the flowfig instructions for the agents that your repo uses. The agent reads the code, writes a spec, runs
-`flowfig check`, fixes the faults, and renders the SVG.
+`--json` prints `{ out, reply, cost, session, findings }` for scripts. `--open` opens the figure in the default browser after the check.
 
 ## The problem
 
@@ -95,7 +109,9 @@ Then ask your agent: "draw a diagram of how login works in this repo".
 - [Three forms](#three-forms)
 - [The spec](#the-spec)
 - [Check a figure](#check-a-figure)
+- [Open and share a figure](#open-and-share-a-figure)
 - [Verify in CI](#verify-in-ci)
+- [For teams](#for-teams)
 - [MCP server](#mcp-server)
 - [Use in React](#use-in-react)
 - [Use from Node](#use-from-node)
@@ -315,6 +331,31 @@ A render runs the same check first. If the check finds an error, the render writ
 In React, `<Flow check />` runs the same rules on the layout that the browser drew. The player prints each fault with
 `console.warn`.
 
+## Open and share a figure
+
+`flowfig open` shows a figure in your default browser. On macOS, an `.svg` file often opens in a text editor or in Xcode. Thus
+`open` writes an HTML page that holds the SVG, and opens that page.
+
+```bash
+npx flowfig open docs/checkout.svg
+npx flowfig open docs/checkout.svg --html checkout.html    # also write the page to checkout.html
+npx flowfig docs/checkout.json docs/checkout.svg --open    # render, then open
+```
+
+`flowfig gif` writes an animated GIF of the whole loop. A GIF plays in Slack, Notion, X and slide decks, where an SVG
+animation does not play.
+
+```bash
+npx flowfig gif docs/checkout.svg                 # writes docs/checkout.gif
+npx flowfig gif docs/checkout.svg --step 2        # only step 2: writes docs/checkout-step2.gif
+npx flowfig gif docs/checkout.svg --dark --mp4    # the dark theme, and also docs/checkout.mp4
+```
+
+`gif` needs Chrome, Edge, Chromium or Brave in the standard install path. Set `CHROME_PATH` to use another browser program.
+`--fps` sets the frames per second (1 to 50, default 20). `--scale` sets the pixel scale (default 2). `--mp4` needs `ffmpeg`
+on the PATH. If a GIF is over 10 MB, `gif` prints a warning. Use `--step`, a lower `--fps` or a lower `--scale` to make the
+file smaller.
+
 ## Verify in CI
 
 A box, an edge or a hop can name the code it draws: `"source": "src/auth/login.ts#verifyPassword"`. `npx flowfig verify docs/login.svg`
@@ -340,6 +381,21 @@ steps:
       figures: 'docs/**/*.svg' # default **/*.svg
 ```
 
+A state lifecycle marks the first state with `mark: "start"` and each final state with `mark: "end"`.
+
+![An order status lifecycle with a start dot and two end rings](docs/order-status.svg)
+
+## For teams
+
+A process is a diagram too. `lanes: true` draws one lane per role and the steps left to right in time order. Each step
+links to a heading in the SOP, so `verify` fails when the SOP changes under the diagram.
+
+![The refund process across Customer, Support and Finance](docs/refund-process.svg)
+
+A plan is a figure too. `timeline: true` draws one track per team, with each item as a bar from its `from` date to its `to` date. A milestone has only `from`, and `today` draws the line for now.
+
+![A Q4 roadmap with three tracks, milestones and a today line](docs/roadmap.svg)
+
 ## MCP server
 
 `npx flowfig mcp` serves the tools `docs`, `check`, `render`, `verify` and `diff` over stdio, for an agent with no shell.
@@ -455,8 +511,9 @@ of the file. A second run also replaces a whole file that `init` wrote. If a who
 
 ## What flowfig does not draw
 
-flowfig draws parts, the messages between the parts, and their order. flowfig does not draw class diagrams, ER diagrams, Gantt
-charts, timelines with dates, charts of numbers or mind maps. Use Mermaid or a chart library for those.
+flowfig draws parts, the messages between the parts, and their order. flowfig draws a roadmap or a timeline with dates (`timeline: true`),
+and converts a Mermaid `gantt` to it. flowfig does not draw class diagrams, ER diagrams, charts of numbers or mind maps. Use Mermaid
+or a chart library for those.
 
 ## How we measured
 

package/dist/browser.d.ts

@@ -0,0 +1,33 @@
+export type Found = {
+    path: string | null;
+    checked: string[];
+};
+/** The first capture browser that exists. `CHROME_PATH` wins. Pure apart from `exists`. */
+export declare function findBrowser(o: {
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    exists: (p: string) => boolean;
+}): Found;
+export type Cdp = {
+    send(method: string, params?: object, sessionId?: string, timeoutMs?: number): Promise<any>;
+    once(event: string, sessionId?: string, timeoutMs?: number): Promise<any>;
+};
+/** Start the capture browser in headless mode with a CDP pipe. `close` stops it and never throws. */
+export declare function launch(path: string, profile: string, timeoutMs?: number): Promise<{
+    cdp: Cdp;
+    close: () => Promise<void>;
+}>;
+export type Capture = {
+    pngs: Buffer[];
+    width: number;
+    height: number;
+    loopMs: number;
+};
+/** Set the page, pause the animations and take one PNG per frame time. */
+export declare function captureFrames(cdp: Cdp, html: string, o: {
+    width: number;
+    height: number;
+    scale: number;
+    fps: number;
+    dark: boolean;
+}): Promise<Capture>;

package/dist/browser.js

@@ -0,0 +1,201 @@
+// The capture browser of `flowfig gif`: find it, start it in headless mode, and talk CDP to it over a pipe. Node only.
+import { spawn } from 'node:child_process';
+import { win32 } from 'node:path';
+const MAC = ['Google Chrome', 'Microsoft Edge', 'Chromium', 'Brave Browser'].map((n) => `/Applications/${n}.app/Contents/MacOS/${n}`);
+const LINUX = [
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/snap/bin/chromium',
+    '/usr/bin/microsoft-edge',
+    '/usr/bin/brave-browser',
+    '/opt/google/chrome/chrome',
+];
+const WINDOWS = [
+    'Google\\Chrome\\Application\\chrome.exe',
+    'Microsoft\\Edge\\Application\\msedge.exe',
+    'BraveSoftware\\Brave-Browser\\Application\\brave.exe',
+    'Chromium\\Application\\chrome.exe',
+];
+/** The first capture browser that exists. `CHROME_PATH` wins. Pure apart from `exists`. */
+export function findBrowser(o) {
+    const { env } = o;
+    const paths = env.CHROME_PATH
+        ? [env.CHROME_PATH]
+        : o.platform === 'darwin'
+            ? MAC
+            : o.platform === 'win32'
+                ? [env.PROGRAMFILES, env['PROGRAMFILES(X86)'], env.LOCALAPPDATA].flatMap((dir) => dir ? WINDOWS.map((p) => win32.join(dir, p)) : [])
+                : LINUX;
+    const checked = [];
+    for (const p of paths) {
+        checked.push(p);
+        if (o.exists(p))
+            return { path: p, checked };
+    }
+    return { path: null, checked };
+}
+/** Start the capture browser in headless mode with a CDP pipe. `close` stops it and never throws. */
+export function launch(path, profile, timeoutMs = 30_000) {
+    const args = [
+        '--headless=new',
+        '--remote-debugging-pipe',
+        `--user-data-dir=${profile}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--hide-scrollbars',
+        '--mute-audio',
+        // The GPU raster gave a different pixel run to run on a rounded corner, and a bigger GIF.
+        '--disable-gpu',
+        // A transform animation (the timeline playhead) runs on the compositor thread, so a seek can draw a stale x under load.
+        '--disable-threaded-animation',
+    ];
+    // Chrome refuses to start as root without it, for example in a Docker container.
+    if (process.getuid?.() === 0)
+        args.push('--no-sandbox');
+    const child = spawn(path, [...args, 'about:blank'], {
+        stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
+        // Its own process group, so close can stop the helpers too. Not on Windows: there it opens a console window.
+        detached: process.platform !== 'win32',
+    });
+    // The browser reads commands on fd 3 and writes replies on fd 4. A NUL byte ends each message.
+    const out = child.stdio[3], input = child.stdio[4];
+    out.on('error', () => { }); // a write after the exit fails; the exit handler below rejects the commands
+    let tail = '', dead = null, nextId = 1;
+    child.stderr.on('data', (d) => (tail = (tail + d.toString()).slice(-2048)));
+    const pending = new Map();
+    const events = [];
+    const stop = (e) => {
+        dead ??= e;
+        for (const w of [...pending.values(), ...events.splice(0)])
+            w.reject(dead);
+        pending.clear();
+    };
+    // The browser starts helper processes in its process group. A helper can outlive the browser and keep a pipe open.
+    const killGroup = () => {
+        try {
+            if (process.platform === 'win32')
+                child.kill('SIGKILL');
+            else if (child.pid)
+                process.kill(-child.pid, 'SIGKILL');
+        }
+        catch {
+            // the group is already gone
+        }
+    };
+    const closed = new Promise((done) => {
+        const end = (e) => (stop(e), done());
+        const stopped = (code) => new Error(`the browser stopped (exit ${code}): ${tail.trim()}`);
+        child.once('error', end);
+        child.once('exit', (code) => {
+            out.destroy(); // the write end of fd 3 does not close by itself, and 'close' waits for it
+            killGroup();
+            setTimeout(() => end(stopped(code)), 1000).unref(); // in case a pipe stays open after the group kill
+        });
+        child.once('close', (code) => end(stopped(code)));
+    });
+    let parts = [];
+    input.on('data', (chunk) => {
+        let start = 0;
+        for (let end = chunk.indexOf(0); end !== -1; start = end + 1, end = chunk.indexOf(0, start)) {
+            parts.push(chunk.subarray(start, end));
+            const msg = JSON.parse(Buffer.concat(parts).toString('utf8'));
+            parts = [];
+            if (msg.id !== undefined) {
+                const w = pending.get(msg.id);
+                pending.delete(msg.id);
+                if (msg.error)
+                    w?.reject(new Error(`${w.method}: ${msg.error.message}`));
+                else
+                    w?.resolve(msg.result);
+            }
+            else {
+                const i = events.findIndex((w) => w.event === msg.method && w.sessionId === msg.sessionId);
+                if (i !== -1)
+                    events.splice(i, 1)[0].resolve(msg.params);
+            }
+        }
+        if (start < chunk.length)
+            parts.push(chunk.subarray(start));
+    });
+    /** A promise that rejects after the timeout; `add` registers the waiter, `drop` removes it. */
+    const timed = (label, add, drop, ms = timeoutMs) => new Promise((resolve, reject) => {
+        if (dead)
+            return reject(dead);
+        const timer = setTimeout(() => {
+            drop();
+            reject(new Error(`${label}: no reply in ${ms / 1000} s`));
+        }, ms);
+        add({ resolve: (v) => (clearTimeout(timer), resolve(v)), reject: (e) => (clearTimeout(timer), reject(e)) });
+    });
+    const cdp = {
+        send: (method, params = {}, sessionId, ms) => {
+            const id = nextId++;
+            return timed(method, (w) => {
+                pending.set(id, { ...w, method });
+                out.write(JSON.stringify({ id, method, params, sessionId }) + '\0');
+            }, () => pending.delete(id), ms);
+        },
+        once: (event, sessionId, ms) => {
+            let me;
+            return timed(event, (w) => events.push((me = { ...w, event, sessionId })), () => events.splice(events.indexOf(me), 1), ms);
+        },
+    };
+    // No Browser.close: the profile is a temp folder with nothing to keep, and Chrome takes about 10 s to exit after it.
+    const close = async () => {
+        killGroup();
+        await closed;
+    };
+    return cdp.send('Browser.getVersion').then(() => ({ cdp, close }), async (e) => {
+        await close();
+        throw e;
+    });
+}
+/** Set the page, pause the animations and take one PNG per frame time. */
+export async function captureFrames(cdp, html, o) {
+    const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank' });
+    const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true });
+    const send = (method, params) => cdp.send(method, params, sessionId);
+    const run = async (expression) => {
+        const r = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true });
+        if (r.exceptionDetails)
+            throw new Error(`Runtime.evaluate: ${r.exceptionDetails.exception?.description ?? r.exceptionDetails.text}`);
+        return r.result.value;
+    };
+    await send('Emulation.setDeviceMetricsOverride', { width: o.width, height: o.height, deviceScaleFactor: o.scale, mobile: false });
+    // The figure picks its theme with a media query, so the run sets the query and leaves the SVG as it is.
+    await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: o.dark ? 'dark' : 'light' }] });
+    // The page goes in as content, not as a file: a snap browser has a private /tmp and cannot read the temp folder.
+    const { frameTree } = await send('Page.getFrameTree');
+    await send('Page.setDocumentContent', { frameId: frameTree.frame.id, html });
+    // CSS animations are in getAnimations(). The packet moves with SMIL, which only the <svg> element controls.
+    const info = await run(`(async () => {
+    await document.fonts.ready;
+    const svg = document.querySelector('svg');
+    const css = document.getAnimations();
+    for (const a of css) a.pause();
+    svg.pauseAnimations();
+    let loop = 0;
+    for (const a of css) loop = Math.max(loop, Number(a.effect.getTiming().duration) || 0);
+    for (const m of svg.querySelectorAll('animate, animateMotion, animateTransform, set'))
+      try { loop = Math.max(loop, m.getSimpleDuration() * 1000); } catch {}
+    const r = svg.getBoundingClientRect();
+    return { loop, x: r.x, y: r.y, width: r.width, height: r.height };
+  })()`);
+    const n = Math.max(1, Math.round((info.loop * o.fps) / 1000));
+    const clip = { x: info.x, y: info.y, width: info.width, height: info.height, scale: 1 };
+    const pngs = [];
+    for (let i = 0; i < n; i++) {
+        const t = (i * 1000) / o.fps;
+        await run(`(() => {
+      for (const a of document.getAnimations()) a.currentTime = ${t};
+      document.querySelector('svg').setCurrentTime(${t / 1000});
+      // two frames: one frame can fire before the browser draws the new time under load
+      return new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+    })()`);
+        const { data } = await send('Page.captureScreenshot', { format: 'png', clip });
+        pngs.push(Buffer.from(data, 'base64'));
+    }
+    return { pngs, width: Math.round(info.width * o.scale), height: Math.round(info.height * o.scale), loopMs: info.loop };
+}

package/dist/check.js

@@ -1,6 +1,6 @@
 // The rules behind `flowfig check`. They never draw and never measure: a renderer gives a Scene, and these read it. So one rule set
 // covers the SVG (estimated text) and the React player (measured text), and any later view that gives a scene.
-import { DARK, LIGHT, ON_ACCENT, TONES, edgeId, isGroup, nodes, str, toBeat, } from './model.js';
+import { DARK, LIGHT, ON_ACCENT, TONES, edgeId, isGroup, dayOf, isLanesLayout, validAt, laneColumns, nodes, str, toBeat, } from './model.js';
 import { textWidth } from './text.js';
 import { owners, parseSource } from './source.js';
 const err = (rule, ids, message) => ({ rule, severity: 'error', ids, message });
@@ -34,9 +34,9 @@ export function checkSpec(fig) {
             for (const h of b.hops)
                 if (!knownEdges.has(h.edge))
                     out.push(err('unknown-id', [h.edge], `${where} moves along edge "${h.edge}", which does not exist`));
-            for (const id of [...Object.keys(b.show ?? {}), ...(b.light ?? [])])
+            for (const id of [...Object.keys(b.show ?? {}), ...(b.light ?? []), ...(b.focus ?? [])])
                 if (!known.has(id))
-                    out.push(err('unknown-id', [id], `${where}: show or light names box "${id}", which does not exist`));
+                    out.push(err('unknown-id', [id], `${where}: show, light or focus names box "${id}", which does not exist`));
         }
     });
     const used = new Set((fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => h.edge))));
@@ -48,6 +48,61 @@ export function checkSpec(fig) {
     for (const [who, source] of owners(fig))
         if (source != null && !parseSource(source))
             out.push(warn('bad-source', [], `${who}: source "${source}" is not path or path#symbol`));
+    const marks = nodes(fig.layout).map((n) => n.mark);
+    const starts = marks.filter((m) => m === 'start').length;
+    const ends = marks.filter((m) => m === 'end').length;
+    if (starts > 1 || (starts && !ends))
+        out.push(warn('mark-count', [], `a lifecycle has one start and at least one end: ${starts} start, ${ends} end`));
+    if (fig.timeline && fig.lanes)
+        out.push(warn('timeline-and-lanes', [], 'the figure sets timeline and lanes; the renderers draw the timeline and ignore lanes'));
+    if (fig.timeline) {
+        if (!isLanesLayout(fig.layout))
+            out.push(err('lanes-need-column', [], 'a timeline uses the lanes layout: a column group of labeled groups, one per track, with boxes only inside'));
+        for (const n of nodes(fig.layout)) {
+            if (n.from == null)
+                out.push(err('timeline-need-from', [n.id], `box "${n.id}" has no from date, and a timeline needs one`));
+            const [f, t] = [n.from == null ? null : dayOf(n.from), n.to == null ? null : dayOf(n.to)];
+            for (const [name, v, d] of [
+                ['from', n.from, f],
+                ['to', n.to, t],
+            ])
+                if (v != null && d == null)
+                    out.push(err('bad-date', [n.id], `box "${n.id}": ${name} "${v}" is not a real YYYY-MM-DD date`));
+            if (f != null && t != null && t < f)
+                out.push(err('bad-date', [n.id], `box "${n.id}": to ${n.to} is before from ${n.from}`));
+        }
+        // A dependent item starts after its source ends. A milestone ends the day it starts.
+        const span = new Map(nodes(fig.layout).map((n) => [n.id, [n.from && dayOf(n.from), (n.to && dayOf(n.to)) ?? (n.from && dayOf(n.from))]]));
+        for (const e of fig.edges) {
+            const start = span.get(e.to)?.[0];
+            const end = span.get(e.from)?.[1];
+            if (start != null && end != null && start <= end)
+                out.push(warn('timeline-dependency-order', [e.from, e.to], `"${e.to}" does not start after "${e.from}" ends`));
+        }
+        if (fig.today != null && dayOf(fig.today) == null)
+            out.push(err('bad-date', [], `today "${fig.today}" is not a real YYYY-MM-DD date`));
+    }
+    else if (fig.lanes) {
+        const top = fig.layout;
+        if (!isLanesLayout(top))
+            out.push(err('lanes-need-column', [], 'lanes need a column group of labeled groups, one per lane, with boxes only inside'));
+        else {
+            const cols = laneColumns(fig);
+            for (const lane of top.children) {
+                const at = new Map();
+                for (const n of lane.children) {
+                    const c = cols.get(n.id);
+                    const other = at.get(c);
+                    if (other != null)
+                        out.push(warn('lane-column-taken', [other, n.id], `boxes "${other}" and "${n.id}" share column ${c} in lane "${str(lane.label)}"`));
+                    at.set(c, n.id);
+                }
+            }
+        }
+    }
+    for (const n of nodes(fig.layout))
+        if (n.at != null && !validAt(n.at))
+            out.push(err('bad-at', [n.id], `box "${n.id}": at ${n.at} is not an integer of 0 or more`));
     return out;
 }
 /** A point on the cubic Bézier at `t`. */
@@ -70,6 +125,8 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
                 out.push(err('text-overflow', [b.id], `box "${b.id}": "${t.text}" needs ${Math.ceil(need)} px, has ${Math.floor(t.room)} px`));
         }
     for (const e of scene.edges) {
+        if (e.behind)
+            continue;
         const pts = Array.from({ length: 33 }, (_, i) => at(e.curve, i / 32));
         for (const b of scene.boxes)
             if (b.id !== e.from && b.id !== e.to && pts.some((p) => inside(p, b.rect, 2)))