Skip to content

Authoring Cookbook

Vivek Sarin edited this page Nov 20, 2026 · 2 revisions

FlowMotion 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.

Parallel requests, focused layers, and a response

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: 1000

Expected 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 and an embedded graph

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: [] }

Parallel events with a join and a branch

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.

Validate a generated file

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.flow

This 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:

  1. Open the file in the FlowMotion editor and inspect the preview.
  2. Seek to each scene and beat boundary.
  3. Check parallel motion, reverse motion, visibility, colors, and persistent rows.
  4. Test Next and reset if interactive: true.
  5. Download the SVG and open it in a viewer with SVG animation support.
  6. Compare the same simulated times, not screenshots captured at unrelated playback positions.

Instructions to include with an AI authoring request

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 .flow definition without invented keys or mixed grammars. Preserve existing IDs and embeds when editing. Explain the intended scenes, parallel steps, and responses. Validate with lintSource and buildModel when 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:

Clone this wiki locally