Repository navigation
Authoring Cookbook
These are complete definitions, not fragments. Save a YAML example as a .flow file without the fence, or paste it into a flowmotion block in a note.
Read the authoring reference first for keyword definitions, compatibility, and limits. Examples describe the development implementation; use a matching plugin build.
This storyboard places layers above the runtimes and Engine to their left. Groups control layout without creating layer-to-runtime arrows.
Both requests in the first beat start together. Separate scenes turn database connectors on only when needed. Later scenes retain completed connectors as faint, headless lines. The return packet uses back: true; its arrowhead points toward the source.
title: Parallel runtime walkthrough
speed: 1800
interactive: true
controls: true
header: true
footer: true
elements:
- id: engine
type: rectangle
content: [{ type: title, text: Engine }]
- id: layer1
type: rectangle
content: [{ type: title, text: Layer 1 }]
- id: layer2
type: rectangle
content: [{ type: title, text: Layer 2 }]
- id: layers
type: group
label: { title: Layers }
children: [layer1, layer2]
layout: { direction: row, gap: 16 }
- id: runtime1
type: rectangle
content: [{ type: title, text: Runtime 1 }]
- id: runtime2
type: rectangle
content: [{ type: title, text: Runtime 2 }]
- id: runtimes
type: group
label: { title: Runtimes }
children: [runtime1, runtime2]
layout: { direction: column, gap: 24 }
- id: stack
type: group
children: [layers, runtimes]
layout: { direction: column, gap: 48, align: center }
- id: db
type: cylinder
content: [{ type: title, text: Database }]
- id: diagram
type: group
children: [engine, stack, db]
layout: { direction: row, gap: 100, align: center }
- { id: dispatch1, type: arrow, start: { id: engine }, end: { id: runtime1 } }
- { id: dispatch2, type: arrow, start: { id: engine }, end: { id: runtime2 } }
- { id: query1, type: arrow, start: { id: runtime1 }, end: { id: db } }
- { id: query2, type: arrow, start: { id: runtime2 }, end: { id: db } }
scenes:
- label: Dispatch in parallel
presentation:
defaults:
nodes: { opacity: 0.3, highlight: false }
arrows: { visible: false, packet: false, highlight: false }
nodes:
engine: { opacity: 1, highlight: true }
runtime1: { opacity: 1, fill: '#dbeafe', stroke: '#2563eb' }
layer1: { opacity: 1, fill: '#dbeafe', stroke: '#2563eb' }
runtime2: { opacity: 1, fill: '#ffedd5', stroke: '#c2410c' }
layer2: { opacity: 1, fill: '#ffedd5', stroke: '#c2410c' }
arrows:
dispatch1: { visible: true, packet: true, highlight: true }
dispatch2: { visible: true, packet: true, highlight: true }
beats:
- say: Engine calls both runtimes together.
light: [engine]
edges:
- { edge: dispatch1, data: request }
- { edge: dispatch2, data: request }
- label: Query in parallel
presentation:
defaults:
nodes: { opacity: 0.3, highlight: false }
arrows: { visible: true, opacity: 0.35, arrowheads: none, packet: false, highlight: false }
nodes:
runtime1: { opacity: 1, fill: '#dbeafe', stroke: '#2563eb' }
layer1: { opacity: 1, fill: '#dbeafe', stroke: '#2563eb' }
runtime2: { opacity: 1, fill: '#ffedd5', stroke: '#c2410c' }
layer2: { opacity: 1, fill: '#ffedd5', stroke: '#c2410c' }
db: { opacity: 1, highlight: true }
arrows:
query1: { opacity: 1, arrowheads: end, packet: true, highlight: true }
query2: { opacity: 1, arrowheads: end, packet: true, highlight: true }
beats:
- say: Each runtime queries the database.
edges: [{ edge: query1, data: query }, { edge: query2, data: query }]
- label: Runtime 1 responds
presentation:
defaults:
nodes: { opacity: 0.3, highlight: false }
arrows: { opacity: 0.35, arrowheads: none, packet: false, highlight: false }
nodes:
engine: { opacity: 1, highlight: true }
runtime1: { opacity: 1, fill: '#dbeafe', stroke: '#2563eb' }
layer1: { opacity: 1, fill: '#dbeafe', stroke: '#2563eb' }
arrows:
dispatch1: { opacity: 1, arrowheads: start, packet: true, highlight: true }
beats:
- say: Runtime 1 responds while only its layer remains emphasized.
edges: [{ edge: dispatch1, data: response, back: true }]
- label: Completed connections
presentation:
defaults:
arrows: { opacity: 0.35, arrowheads: none, packet: false, highlight: false }
beats:
- say: The completed connections remain visible without arrowheads.
ms: 1000Expected checkpoints:
| Simulated time | Expected result |
|---|---|
| 400 ms | Two Engine-to-runtime packets; query connectors hidden; both layers colored |
| 2200 ms | Two query packets; dispatch connectors faint and headless |
| 4000 ms | One reversed response packet toward Engine; Layer 2 dimmed |
| 5600 ms | No moving packets; all connectors faint and headless |
To make the dispatch sequential, put dispatch1 and dispatch2 in separate beats. To change presentation between them, use separate scenes and repeat the settings needed in each.
Rows persist between scenes until replaced. This example replaces a text/graph row set, then clears it. lit references names inside the row graph, not the outer card ID.
title: Cache contents
speed: 1400
footer: true
elements:
- id: cache
type: rectangle
width: 300
content:
- { type: title, text: Cache }
- { type: subtitle, text: Session state }
scenes:
- label: Populate
beats:
- say: Store the request and its dependency graph.
light: [cache]
show:
cache:
- { type: row, tag: key, text: session-42, meta: cached, mark: new, tone: blue, mono: true }
- type: graph
tone: purple
nodes: [request, result]
links: [[request, result]]
lit: [result]
- say: Replace both rows with a status row.
show:
cache:
- { text: Cache hit, tone: green }
- say: Clear the card contents.
show: { cache: [] }Use event dependencies when "wait until both finish" matters more than narrated scene layout. Both transfers depend on one fork. The join waits for both database processes. The branch chooses success; failure is skipped.
diagram: { id: parallel-query, direction: LR, edgeLabels: true }
controls: true
animation: { autoplay: false, loop: false, speed: 1 }
groups:
- { id: storage, label: Storage }
nodes:
- { id: engine, label: Engine }
- { id: db1, label: DB1, shape: cylinder, group: storage }
- { id: db2, label: DB2, shape: cylinder, group: storage }
- { id: result, label: Result, shape: diamond }
flows:
- { id: query1, from: engine, to: db1, payload: query }
- { id: query2, from: engine, to: db2, payload: query }
- { id: response, from: db1, to: result, payload: combined result, line: dotted }
events:
- { id: dispatch, type: fork }
- { id: send1, type: transfer, flow: query1, duration: 500, after: dispatch }
- { id: send2, type: transfer, flow: query2, duration: 500, after: dispatch }
- { id: read1, type: process, node: db1, duration: 400, after: send1 }
- { id: read2, type: process, node: db2, duration: 800, after: send2 }
- { id: waiting, type: wait, node: engine, after: dispatch, until: [read1, read2] }
- { id: gathered, type: join, after: [read1, read2] }
- { id: choose, type: branch, node: result, after: gathered, select: [success] }
- { id: success, type: transfer, flow: response, after: choose, duration: 500 }
- { id: failure, type: process, node: result, after: choose, fail: true }
- { id: finished, type: complete, node: result, after: success }The transfers run from 0 to 500 ms. read1 ends at 900 ms and read2 at 1300 ms. Waiting and joining last until 1300 ms. The success packet runs from 1300 to 1800 ms. An unselected failure path must not put the result node into an error state.
In the matching repository checkout, save the following as a temporary .mts file at the repository root. Replace the input path in the run command. This requires the checkout's existing dependencies; it does not send diagram content to an AI service.
import { readFile } from 'node:fs/promises';
import { buildModel } from './src/model.ts';
import { lintSource } from './src/schema/index.ts';
const source = await readFile(process.argv[2]!, 'utf8');
const issues = lintSource(source);
for (const issue of issues) {
console.error(`${issue.severity}: ${issue.message}`);
}
if (issues.some((issue) => issue.severity === 'error')) {
process.exitCode = 1;
} else {
const model = await buildModel(source);
console.log({
nodes: model.layout.nodes.length,
flows: model.layout.edges.length,
durationMs: model.timeline.total,
});
}node --import tsx validate-flow.mts /absolute/path/to/architecture.flowThis procedure validates a standalone definition, not an unresolved src block or an entire Markdown note. For draw.io input, use buildModel; the YAML linter is not an XML validator.
After validation:
- Open the file in the FlowMotion editor and inspect the preview.
- Seek to each scene and beat boundary.
- Check parallel motion, reverse motion, visibility, colors, and persistent rows.
- Test Next and reset if
interactive: true. - Download the SVG and open it in a viewer with SVG animation support.
- Compare the same simulated times, not screenshots captured at unrelated playback positions.
For a reusable setup, copy the AI authoring skill and its two schema files. For a one-off request, use the prompt below.
Use the FlowMotion authoring reference and cookbook from the same revision as my plugin build. Prefer storyboard YAML for scene presentation, or event YAML for dependency scheduling. Return a complete
.flowdefinition without invented keys or mixed grammars. Preserve existing IDs and embeds when editing. Explain the intended scenes, parallel steps, and responses. Validate withlintSourceandbuildModelwhen a checkout is available, and state what visual verification was performed. If tools are unavailable, say the output is unvalidated. Do not claim compatibility with arbitrary Mermaid or PlantUML syntax.
Give the tool both pages, not only an example screenshot:
© 2026 @vrsarin. FlowMotion documentation.