Visual explainer can now draw a state machine straight from your code. Point a page at a reducer or transition function and it walks every state the code can reach, then shows what you missed: states nobody drew, events that never fire, dead ends, and broken rules you can replay step by step. Questions on a page are also safer: a suggested answer you never touched no longer goes back to the agent as your approval. Pages look good with no styling of their own, and Pi users can choose where pages are saved.
Highlights
- State machines from your code. A new
/state-machinecommand finds the code, draws every reachable state, and turns each broken rule into a test you can keep. Diff reviews and comparisons use it too, so they show what a change breaks. - Skipped questions stay skipped. An untouched suggested answer now comes back as "no answer", so an agent can't start work on an "Approve" you never clicked.
- Pages read well with no page CSS. Text keeps a readable width, code blocks are framed and lists are indented. Long pages get a section menu that stays at the top.
- Choose where Pi saves pages. Use your own folder, or a folder inside each project.
- Works in single-binary Pi builds. The Pi extension now loads in Pi builds made with Bun, such as Pi-Bolt, instead of stopping Pi from starting.
Highlights
- State machines drawn from your own code. Point a page at a reducer or transition function and it walks every state the code can reach: states you forgot to draw, events that never fire, dead ends, and broken rules you can replay step by step. A new
/state-machinecommand does the whole job. - Questions you skip stay skipped. A suggested answer no longer reaches the agent as your choice unless you pick it.
- Pages read well without any styling of their own, and long pages get a section menu that stays at the top.
- In Pi, you choose where pages are saved, including a folder inside each project.
- The Pi extension now loads in Pi builds that ship as a single Bun binary, such as Pi-Bolt.
Added
- Pages read well without any page CSS. Paragraphs and lists keep a comfortable line length, code blocks get a framed, scrollable style, plain lists get proper indents, and the blocks of a section get even spacing, so a figure's caption no longer sits on the paragraph after it.
- A section menu for long pages. One
<nav>line gives a bar that stays at the top, scrolls sideways on a phone, and marks the section you are reading. - Rendering a page flags drawing labels that have no color, which show as black text on a dark background.
- State machines drawn from the code itself. Point a page at the reducer or transition function in your repo, and the page walks every state the code can reach. It shows the states you forgot to draw, the events that never fire, the dead ends, and each rule the code breaks as the shortest path there, which you can replay step by step. A machine too big to place by hand is laid out for you, and a machine with independent parts, like playback and volume, draws each part in its own box. A new
/state-machinecommand runs the whole workflow, from finding the code to a test you can keep for each broken rule. The MCP server runs your code this way only when it starts withVISUAL_EXPLAINER_RUN_MODELS=1. Inspired by the/statechartskill in cursor/plugins (pstack), which walks a machine with TLA+; this kit walks the code directly and needs nothing installed. - In Pi, choose where pages are saved with a
visualExplainer.outputDirsetting, in your own settings or a project's. Set it to"project"to keep each repository's pages in its own.agent/diagrams/, or give any path. Thanks to @IdrisGit for #128.
Changed
- Diff reviews and comparisons walk a state machine read from the code on each side, so they show a rule a change newly breaks or a state it makes unreachable.
Fixed
- Sending a reply no longer answers the questions you left alone. A question with a suggested answer used to go into the reply as that answer, marked "(default)", so an agent could read an untouched "Approve" as approval and start work. It now goes in as "no answer" until you pick an option. Thanks to @IdrisGit for #129 and @mplibunao for reporting #127.
- The Pi extension loads in a Pi built as a single Bun binary, such as Pi-Bolt. It used to stop Pi from starting with
ENOENT: no such file or directory, lstat '/$bunfs/root/pi'. Thanks to @crisboarna for #126. - A question whose suggested answer was written on the question instead of on the option showed nothing pre-selected and gave no warning. Rendering now stops with an error that shows where it belongs.
- Values that change during a step-through, like a counter, showed as black, unreadable text in dark mode unless the page styled them itself.
- An arrow's label no longer crosses the arrow beside it; the drawing widens to hold it.