v0.9.0

flowfig 0.9.0 adds two commands. flowfig trace lists the calls under a function, so your agent reads less code before
it draws a figure. flowfig coverage finds the figures that fail or are stale, and the code that has no figure. Each
figure is now accessible to screen readers, and it stops moving if the reader asks for reduced motion.

$ npx flowfig trace src/verify.ts#verify
src/verify.ts#verify -> src/verify.ts#verifyReport          src/verify.ts:104
src/verify.ts#verifyReport -> src/source.ts#links           src/verify.ts:49
src/verify.ts#verifyReport -> src/edges.ts#edgeResult       src/verify.ts:81
...
stop    depth 2: 11 symbols not followed
summary: 13 symbols, 12 found, 0 unsure, 0 open, 4 calls outside the repo, 0.1 s

New

• flowfig trace <file#symbol>. It starts at one function and follows its calls. Each line gives the caller, the
  callee, and the file and line of the call. Each edge passes the same check as verify. If trace cannot name a target,
  it prints an unsure or an open line with the reason, and it does not guess. Ask your coding agent to run it before
  it writes a figure. Then the agent reads only the lines that the trace names. Options: --depth (default 2), --max
  (default 40), --root, --json. It reads TypeScript, JavaScript, Python, Go, Java, C# and Rust.
• flowfig coverage. It reads each figure in the repo and gives it a state: ok, stale, fail or none. A
  figure is stale if git shows that a linked file changed after the figure. With --entries <glob>, it lists the code
  files that no figure covers. With --strict, it exits 1 if a figure is fail or stale, so you can run it in CI.
• Accessible figures. Each SVG now has role="img", a title, and a text transcript of the steps for screen
  readers. The <Flow /> player gives the same title and transcript.
• Reduced motion in the SVG. If the reader asks for reduced motion, the SVG holds a still frame at the end of the
  first step. The transcript covers every step.
• Alt text. A render prints an alt: line. Use that text in the alt of the <img> tag in your README.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• flowfig coverage reads commit dates with git. Without git, it does not check stale.

Upgrade

• Render your figures again to add the title, the transcript and the reduced-motion frame.
• A render now prints one more line, alt: ..., after the step lines. If a script reads the render output, check it.
• If your GitHub workflow uses the flowfig Action, change it to iamalvisng/flowfig@v0.9.0.

Full Changelog: v0.8.4...v0.9.0

v0.8.4

flowfig 0.8.4 gives edge labels more room. Each arrow now shows its line and arrowhead on both sides of its label.

Improvements

• Room around labels. The gap between two boxes holds the edge label and a visible line on each side of it. Before,
  a label could fill the whole gap and hide the arrow.
• Labels away from boxes. An edge label keeps 6 px from every box when the figure has the room.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.

Upgrade

• Figures with edge labels get a little wider when you render them again. If a wide figure now reports small-text,
  shorten a label or make a box narrower.
• If your GitHub workflow uses the flowfig Action, change it to iamalvisng/flowfig@v0.8.4.

Full Changelog: v0.8.3...v0.8.4

v0.8.3

flowfig 0.8.3 links each state of a state diagram to its own enum member, and fixes two edge routes that crossed a box.

Improvements

• Enum members in source. A box source can name an enum member as Owner.name, for example
  src/status.ts#OrderStatus.Paid. verify checks that the member is defined in the enum. This works in TypeScript,
  JavaScript, Java, C#, Rust and Python (class Owner(Enum)). A name in a comment or a string does not pass.
• Edges around boxes. If you set around on an edge and that side has no free path, the edge now takes a free side.
  A right-angle edge that goes to the left now also avoids the boxes in its way.
• Edge lines at the border. An edge that runs along the figure border keeps its full line width.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.

Upgrade

• No change is needed. Edges with a blocked around side can take a new route when you render the figure again.
• If your GitHub workflow uses the flowfig Action, change it to iamalvisng/flowfig@v0.8.3.

Full Changelog: v0.8.2...v0.8.3

v0.8.2

flowfig 0.8.2 changes only the package description and keywords on npm. The code is the same as in 0.8.1.

Upgrade

• No change is needed. If your GitHub workflow uses the flowfig Action, you can change it to iamalvisng/flowfig@v0.8.2.

Full Changelog: v0.8.1...v0.8.2

v0.8.1

flowfig 0.8.1 makes figures easier to read, and an agent needs fewer steps to draw one.

npx flowfig spec.json docs/login.svg
# 0 errors, 0 warnings
# figure: 8 boxes, 0 groups, 8 edges, 2 steps, 17 messages
# client -> limiter: log in
# limiter -> redis: count tries
# ...
# docs/login.svg: 4 of 4 boxes defined; edges: 6 found, 0 not found, 1 unsure, 1 not checked

New

• One command per try. A render now prints one line per edge and per step, and the verify counts when the figure
  has a source or a via. You do not need a separate verify or --spec call to read the figure back.
  --no-verify skips the verify part. flowfig verify stays for CI.
• Code on hover. If a box, an edge or a hop has a source, the SVG and the <Flow /> player show it on hover.
  The label can be plain words, and the code name stays one hover away.
• Check rule plain-text (warning). It reports a label that looks like code (findUserByEmail, validate_rows,
  run()), a label that is a database or cache command (SELECT, SET sess:1 EX 3600), a say line or a caption
  over 20 words, and filler words such as "seamless" or "robust". An HTTP request line such as GET /user passes. If the
  word is a product name, keep it.
• Short guide. flowfig docs prints a core guide of about half the old length. flowfig docs <topic> prints one
  topic: lanes, timeline, rail, marks or verify. The MCP docs tool takes the same topic.

Improvements

• Edges go around boxes. If a straight edge would cross a box, the edge goes around it with an arc or a right-angle
  path.
• Labels find free space. An edge label moves along its edge to a spot clear of boxes and other labels.
• Gaps fit the labels. The space between boxes grows to hold the edge labels between them. A gap that you set is
  now the smallest gap, not a fixed one.
• Long box labels wrap to two lines before the text gets smaller.
• verify gives fewer wrong "not found" results. If the caller calls a function that it receives, such as Express
  next(), the edge is "unsure" with the reason. If the caller is a variable such as const router = Router(), the check
  also reads the statements on it, such as router.post(...), in TypeScript, JavaScript and Python.
• flowfig diff now reports a change to via, a hop's source or via, a removed repeat of the same hop, and a
  step caption change.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.

Upgrade

• Figures can change their layout when you render them again: edges route around boxes, and gaps grow to fit labels.
  Render your figures again and look at them.
• If your figures use code names as labels, the new plain-text warning reports them. Put the code name in source
  and write the label in plain words. Under --strict the warning is an error.
• If your GitHub workflow uses the flowfig Action, change it to iamalvisng/flowfig@v0.8.1.

Full Changelog: v0.8.0...v0.8.1

flowfig 0.8.0

flowfig verify now checks the arrows, not only the names. It tells you which edges of a figure the code really makes, so a reviewer can see which parts to trust.

npx flowfig verify docs/login.svg
# docs/login.svg: 7 of 7 boxes defined; edges: 9 found, 0 not found, 1 unsure, 1 not checked

New

• Edge check. verify gives each edge one result:
  • found: the caller code calls or references the callee, through an import, the same file or a typed receiver.
  • not found: the code does not make that call. verify prints a warning, and --strict makes it an error.
  • unsure: verify cannot decide, for example when a receiver has no declared type. It lists the edge with the reason and never fails CI.
  • not checked: the edge has no code to check, or the file is in a language that verify does not read.
• Languages. Edge checks work in TypeScript, JavaScript, Python, Go, Java, C# and Rust.
• Methods. A source can name a method: src/auth/session.ts#Session.refresh.
• via for edges across a process. Set via to the route, queue, topic, table, file or key that both sides use, for example "via": "order-paid". For a via edge, "found" means that the caller code and the callee file both use that name. It does not prove that a handler serves it.
• Counts everywhere. The CLI, the MCP verify tool and the GitHub Action comment show the box and edge counts. verify --json adds a coverage list with the counts and the unsure edges.
• Agent guide. The instructions that flowfig init installs teach agents to set edge sources and via, and to fix each edge that verify does not find.

Improvements

• Box check. In a code file, a box symbol must be defined, not only mentioned. A name in a comment or a string no longer passes.
• flowfig/verify exports verifyReport, which returns the findings and the counts. verify keeps its signature.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• flowfig gif uses Chrome, Edge, Chromium or Brave from your machine, and needs a little-endian CPU (x64 or ARM).

Upgrade

• A box source whose symbol the file only mentions, and does not define, now fails verify with symbol not defined. Point the source at the file that defines the symbol, or use path#Owner.name for a method.
• Edges that verify cannot find give warnings, not errors, unless you use --strict. Run npx flowfig verify <figure> once after the upgrade and fix the edges it reports.
• If your GitHub workflow uses the flowfig Action, change it to iamalvisng/flowfig@v0.8.0.

Full Changelog: v0.7.0...v0.8.0

flowfig 0.7.0

Faster GIF export, smaller SVG files, and faster renders of large figures. The figures look the same.

npx flowfig gif docs/checkout.svg

Improvements

• Faster GIF export. flowfig gif captures frames in up to 4 browser tabs at once and encodes them faster. On a test machine, the GIF of a 16-second figure takes about 16 seconds, down from about 35. The GIF bytes stay the same.
• Smaller SVG files. The SVG keeps one keyframe for each run of equal values. A typical figure is 15 to 40 percent smaller, and a large figure can be 20 times smaller. The animation is frame-for-frame the same.
• Faster renders. Large figures and wrapped swimlanes render 2 to 3 times faster. flowfig renders a figure once per call, also through the MCP render tool.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• flowfig gif uses Chrome, Edge, Chromium or Brave from your machine, and needs a little-endian CPU (x64 or ARM).

Upgrade

No breaking change. Render your figures again to get the smaller SVG files.

Full Changelog: v0.6.0...v0.7.0

flowfig 0.6.0

Cleaner timelines and swimlanes, stricter checks, and Windows support for open and gif.

npx flowfig init   # get the new agent instructions

Improvements

• Timeline. The animation starts at the first item, so the first frame of a GIF and of a README shows the playhead in place. The today line and the playhead run behind the bars and do not cross the bar text. A dependency line goes around the bars it does not connect.
• Swimlanes. An edge label stays inside one lane, not on the border between two lanes. A decision at the end of a wrapped block keeps its stub label inside its lane and inside the figure.
• Windows. The tests now run on Windows in CI, including gif with Chrome. flowfig gif stops all browser helper processes on Windows and removes its temp folder. flowfig init prints paths with / on every system.
• Agent instructions. A pasted Mermaid design keeps its arrow types: a plain arrow stays a plain message, even for a queue. In a process document, the agent draws each path to its end, with one step per path. When a text does not fit its box, the agent widens the box or moves the detail, and does not cut a fact.

Fixes

• On Windows, flowfig verify accepted a source path outside the repo. It now reports it.

Checks

These checks are new, so a figure that passed check --strict in 0.5.0 can now report a fault:

• label-overlap also reports an edge label across a lane border.
• edge-crosses-box also reports a timeline dependency line through a bar.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• flowfig gif uses Chrome, Edge, Chromium or Brave from your machine.

Upgrade

Render your figures again with 0.6.0 and run check --strict. Run npx flowfig init again in your repo to get the new agent instructions.

Full Changelog: v0.5.0...v0.6.0

flowfig 0.5.0

Long swimlane processes now fit in one figure, and decision boxes keep their text inside the diamond.

npx flowfig init   # get the new agent instructions

New

• Swimlanes wrap. When the steps of a lanes: true figure do not fit the page width, flowfig wraps the time columns into blocks, one under the other. Each block shows only the lanes that have a step in it. An edge between two blocks becomes two short labeled stubs, for example "→ Inspect" and "from Ship item". A process of 7 or more steps now stays readable in one figure.
• lane-end-block check. check warns when an edge in a wrapped figure ends at a lane that no nearby block shows.
• stub-crosses-edge check. check warns when a stub line crosses another edge. --strict makes it an error.

Improvements

• A decision box (shape: 'decision') wraps its sub line inside the diamond outline and grows taller when it needs more room. check now tests the text against the diamond shape.
• --width now also sets where the lanes wrap, in the CLI and in the MCP render tool.
• Agents keep a long process in one figure. For a process document, agents now also show every deadline, every message to a person, every choice and every wait for a reply.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.

Upgrade

No breaking change. A lanes figure that fits the width renders as before. Run npx flowfig init again in your repo to get the new agent instructions.

Full Changelog: v0.4.0...v0.5.0

flowfig 0.4.0

Swimlanes, a timeline form, start and end marks, and two new commands: open shows a figure in your browser, and gif makes an animated GIF that you can share anywhere.

npx flowfig open docs/checkout.svg   # show the figure in your default browser
npx flowfig gif docs/checkout.svg    # write docs/checkout.gif

New

• Swimlanes. Set lanes: true and give each box an at lane and time column. Each role gets its own band with a label. Use it for a process that several teams share.
• Timeline form. Set timeline: true to draw a roadmap with dated bars, milestones, dependency lines, a today line and a moving playhead. check reports dates out of order.
• Start and end marks. A lifecycle box can show a start dot or an end ring.
• flowfig open <figure.svg>. Opens the figure in your default browser. Add --open to a render or to draw to do the same after the figure is written.
• flowfig gif <figure.svg> [out.gif]. Writes an animated GIF for Slack, Notion, slides, or any place that does not play SVG animation. Options: --step <n> for one step, --dark, --fps, --scale, and --mp4 to also write an MP4.

Improvements

• After npx flowfig init, agents use flowfig when you ask for a diagram and name no other tool. In Claude Code, you can also run /figure <question>.
• Agent replies end with the npx flowfig open command for the new figure.
• flowfig init has a new screen: pick your agents with the arrow keys and the space bar.

Requirements

• Node 18 or later.
• React 18 or later, only for the <Flow /> player.
• flowfig gif uses Chrome, Edge, Chromium or Brave from your machine. Set CHROME_PATH to choose one.
• flowfig gif --mp4 also needs ffmpeg on your PATH.

Upgrade

No breaking change. Run npx flowfig init again in your repo to get the new agent instructions.

Full Changelog: v0.3.0...v0.4.0