Skip to content

machina-explorer

machina-explorer is an experimental browser-based UI on top of machina-inspect. Paste a config object, click Analyze, and the app runs structural checks and renders a mermaid state diagram, all in the browser tab.

  • Paste and analyze: Drop a raw FSM config object into the editor and click Analyze. The app evaluates it via new Function() and builds the state graph with buildStateGraph(). inspectGraph() then runs the structural checks, and the diagram renders from the result.
  • Inspect findings: Findings are grouped by type (unreachable states, _onEnter loops, missing handlers). A clean config shows a confirmation instead.
  • State diagram: Generates a stateDiagram-v2 mermaid diagram from the StateGraph IR. Possible transitions (conditional returns) are labeled with (?). Child FSMs appear as nested subgraphs.
  • Handler notes toggle: Optionally overlay the list of handler keys (including _onEnter and _onExit) on each state node in the diagram.
  • Export: Copy the raw mermaid source to the clipboard, or download the rendered diagram as an SVG.

Vanilla TypeScript without a framework. A CodeMirror 6 editor fills the left panel, and the findings plus the diagram fill the right one.

The new piece is mermaid-generator.ts, a pure function that converts a StateGraph plus config object into a mermaid stateDiagram-v2 string. It doesn’t touch the DOM, and a CLI or server-side tool could reuse it.

editor.ts       → CodeMirror 6 wrapper
evaluator.ts    → new Function() eval + shape validation
mermaid-generator.ts → StateGraph → mermaid string (pure)
diagram.ts      → mermaid.render() → SVG in DOM
report.ts       → findings → DOM (XSS-safe)
export.ts       → clipboard + PNG download
main.ts         → wires everything together
// Evaluate the pasted config string
const evalResult = evaluateConfig(source);

// Build the state graph IR (used by both inspect and diagram generator)
const graph = buildStateGraph(evalResult.config);

// Run all structural checks
const findings = inspectGraph(graph);

// Generate mermaid source from the graph + config
const mermaidSource = generateMermaid(graph, config, { handlerNotes: true });

// Render the mermaid string as an SVG
await renderDiagram(container, mermaidSource);

The app builds the graph once and stores it. The handler-notes toggle re-runs generateMermaid() and renderDiagram(), and eval and inspect don’t run again.

examples/machina-explorer/