Skip to content

Developer Input Formats

Vivek Sarin edited this page Nov 16, 2026 · 1 revision

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.

Dispatch order

buildModel in src/model.ts checks the input in this order. The first match wins.

  1. draw.io: isDrawioSource (src/drawio/parse.ts). The source is an mxfile XML document, or an SVG that carries one.
  2. Storyboard: detectKind returns storyboard (a top-level scenes: key), and the source is not text. Parsed by parseStoryboard (src/story/parse.ts).
  3. Text: isTextSource is true. Parsed by parseText (src/text/parse.ts).
  4. 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.

YAML and JSON

parseDiagram in src/core/parse.ts does the following:

  1. Parses the source with the yaml package. JSON is valid YAML, so one parser handles both.
  2. 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.
  3. Enforces the LIMITS in src/core/types.ts.
  4. Builds the nodes, groups, and flows.
  5. Uses the given events, or derives the default events with deriveEvents (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.

Text format

The text format is in src/text/.

  • Header. HEADER in src/text/parse.ts lists the accepted header lines, such as flowchart, graph, sequenceDiagram, stateDiagram-v2, classDiagram, erDiagram, mindmap, gantt, architecture-beta, the C4* 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 IGNORED set lists the keywords that are accepted and not drawn. These include activate, autonumber, loop, alt, par, note, skinparam, title, and the accessibility keys.
  • Kind detection. sniffKind in src/text/kinds.ts chooses 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.

Gantt charts

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.

Storyboards

  • src/story/parse.ts parses and checks the elements and scenes. The published JSON Schema for storyboards is generated from src/schema/story.ts.
  • src/story/timeline.ts compiles the beats into the same Timeline structure that the engine plays. A beat's ms overrides the top-level speed.
  • src/layout/flex.ts lays out the cards, groups, and arrows. The layout is flexbox-like: row or column, with a gap and an alignment.

draw.io drawings

  • src/drawio/parse.ts reads a .drawio file (mxfile XML), or an SVG whose content holds an mxfile.
  • src/drawio/import.ts converts 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.ts keeps 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.

Embeds

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.

Adding a diagram kind

  1. Add the header to HEADER in src/text/parse.ts, if it is a text kind.
  2. Add the sniff rule to sniffKind in src/text/kinds.ts.
  3. Write a builder and its finish method in src/text/kinds.ts.
  4. Choose the layout. Use ELK by default, or add a layout module.
  5. Add tests to test/kinds.test.ts, and a render check to test/render.test.ts.
  6. Update the user pages in the wiki.

Related pages

Clone this wiki locally