Repository navigation
Developer Input Formats
FlowMotion accepts four kinds of input. Each has its own parser, and each produces the same shared model. This page explains how the parsers are chosen and where each one lives.
buildModel in src/model.ts checks the input in this order. The first match wins.
-
draw.io:
isDrawioSource(src/drawio/parse.ts). The source is anmxfileXML document, or an SVG that carries one. -
Storyboard:
detectKindreturnsstoryboard(a top-levelscenes:key), and the source is not text. Parsed byparseStoryboard(src/story/parse.ts). -
Text:
isTextSourceis true. Parsed byparseText(src/text/parse.ts). -
YAML or JSON: everything else. Parsed by
parseDiagram(src/core/parse.ts).
The storyboard check only runs when the input is not text. A text diagram is therefore never read as a storyboard.
parseDiagram in src/core/parse.ts does the following:
- Parses the source with the
yamlpackage. JSON is valid YAML, so one parser handles both. - Checks each field and reports problems. The field rules are in the code of
parseDiagram. The published JSON Schema is separate, and is used by editors. See Schema and validation. - Enforces the
LIMITSinsrc/core/types.ts. - Builds the nodes, groups, and flows.
- Uses the given
events, or derives the default events withderiveEvents(src/core/auto.ts). The default is: every node runs once, and every flow carries one packet. Back edges are drawn but not scheduled.
Input is untrusted. Validation problems are returned with their line numbers. The plugin shows up to 12 of them.
The text format is in src/text/.
-
Header.
HEADERinsrc/text/parse.tslists the accepted header lines, such asflowchart,graph,sequenceDiagram,stateDiagram-v2,classDiagram,erDiagram,mindmap,gantt,architecture-beta, theC4*headers, and the PlantUML tags@startuml,@startmindmap, and@startgantt. -
Directives. Lines of the form
%% @name value. The supported directives are@speed,@loop,@autoplay,@duration, and@fail. An unknown directive is an error. -
Ignored keywords. The
IGNOREDset lists the keywords that are accepted and not drawn. These includeactivate,autonumber,loop,alt,par,note,skinparam,title, and the accessibility keys. -
Kind detection.
sniffKindinsrc/text/kinds.tschooses the parser for a PlantUML or Mermaid source. The per-kind parsers are in the same file.
Each per-kind parser fills a Builder. The finish method turns the builder into the shared Diagram. Adding a new kind means adding a builder, a sniff rule, and tests.
A Gantt chart is laid out on a time axis, not by ELK. src/layout/gantt.ts puts one row per task and places each task from its schedule.
-
src/story/parse.tsparses and checks theelementsandscenes. The published JSON Schema for storyboards is generated fromsrc/schema/story.ts. -
src/story/timeline.tscompiles the beats into the sameTimelinestructure that the engine plays. A beat'smsoverrides the top-levelspeed. -
src/layout/flex.tslays out the cards, groups, and arrows. The layout is flexbox-like: row or column, with a gap and an alignment.
-
src/drawio/parse.tsreads a.drawiofile (mxfileXML), or an SVG whosecontentholds anmxfile. -
src/drawio/import.tsconverts the shapes into the shared model. It keeps draw.io's own coordinates, so the drawing does not move. - Arrows are laid out with
src/layout/fixed.ts, which computes where a ray from a box centre leaves the box. -
src/drawio/sanitize.tskeeps the drawing and removes anything that could run code or load a resource from outside. The SVG tag list is an allowlist. Output is prefixed so that several drawings can share a page.
The draw.io editor itself is not part of this parser. It is in dist/plugin/drawio, and the plugin serves it. See Obsidian plugin.
parseEmbed in src/core/embed.ts reads the src: block. The allowed keys are src, controls, controlsPosition, mode, height, width, header, footer, and paper. The src value must end in .flow, .drawio, .svg, .yaml, .yml, or .json.
- Add the header to
HEADERinsrc/text/parse.ts, if it is a text kind. - Add the sniff rule to
sniffKindinsrc/text/kinds.ts. - Write a builder and its
finishmethod insrc/text/kinds.ts. - Choose the layout. Use ELK by default, or add a layout module.
- Add tests to
test/kinds.test.ts, and a render check totest/render.test.ts. - Update the user pages in the wiki.
© 2026 @vrsarin. FlowMotion documentation.