Mermaid to Hyperframes

Convert Mermaid flowchart .mmd files into Hyperframes projects with seekable GSAP motion.

Unofficial HyperFrames community tool.

Demo

Each demo shows the source diagram next to the rendered motion graphic.

Quick Start

Create ./motion and render ./motion/output.mp4 in one command:

npx mermaid-to-hyperframes ./diagram.mmd --out ./motion --render

Preview without rendering an MP4:

npx mermaid-to-hyperframes ./diagram.mmd --out ./motion --open

Work with an already generated project:

cd ./motion
npx hyperframes preview
npx hyperframes render --output output.mp4

Local development from this repository:

npm install
npm run build
node dist/cli.js ./diagram.mmd --out ./motion --open

The generated project contains index.html, the original source.mmd, motion-plan.json, a local package.json, and commands for Hyperframes preview/render. Use --render when you want the MP4 immediately; omit it when you only want the editable Hyperframes project.

By default, --resolution fit sizes the MP4 canvas to the Mermaid SVG aspect ratio. Use --resolution landscape, --resolution portrait, or --resolution square when you want a fixed video format.

For a clean diagram-only render, captions are off by default. Add --captions on if you want a bottom explainer caption. The camera is static by default and fits the full diagram into frame; add --ken-burns on for a zoom-in, pan, and zoom-out camera path across dense diagrams.

Current Scope

• Supported: Mermaid flowchart and graph
• Output: Hyperframes HTML composition
• Main effect: nodes and edges reveal in graph order from a stable camera

Limitations

This is not yet "any .mmd complexity, no caveats." v1 supports Mermaid flowchart / graph diagrams that Mermaid CLI can render into the standard flowchart SVG structure. Large diagrams render, but the result can become visually dense and the semantic reveal order is best-effort for advanced Mermaid syntax.

Development

Run the local checks:

npm install
npm run check
npm run check:fixtures

check:fixtures converts several real Mermaid flowcharts, including subgraphs, chained edges, styled nodes, branching paths, and a larger system diagram, then runs hyperframes lint on each generated project.

Human-reviewable fixture previews and MP4s live under test/fixtures/flowcharts. Regenerate them with:

npm run fixtures:previews