@donkeyclip/motorcortex-flowchart

A MotorCortex plugin for rendering Graphviz DOT flowcharts with animatable node entities and incremental graph building.

Features

• Render flowcharts from Graphviz DOT syntax
• Animate individual node properties (fill, glow, opacity) via MC Effects
• Incrementally build graphs — add nodes/edges at specific timeline positions via addCustomEntity
• In-place SVG diffing preserves DOM elements across graph updates, so Effect state (colors, glow) survives transitions
• Forward and backward seek support
• Graphviz WASM engine (@viz-js/viz) runs entirely in the browser

Installation

npm install @donkeyclip/motorcortex-flowchart

Getting Started

import { loadPlugin } from "@donkeyclip/motorcortex";
import Player from "@donkeyclip/motorcortex-player";
import FlowchartPluginDef from "@donkeyclip/motorcortex-flowchart";

const McFlowchart = loadPlugin(FlowchartPluginDef);

async function main() {
  // Load Graphviz WASM — must be called once before creating clips
  await FlowchartPluginDef.init();

  // Step 1: initial graph
  const flowchart = new McFlowchart.Clip(
    {
      dot: `digraph {
        rankdir=TB
        node [style=filled fillcolor="#eaf2f8" color="#2c3e50" fontcolor="#2c3e50"]
        A [label="Start" shape=ellipse]
        B [label="Decision" shape=diamond]
        A -> B
      }`,
      nodeIds: ["A", "B"],
    },
    {
      host: document.getElementById("clip"),
      containerParams: { width: "800px", height: "600px" },
      duration: 6000,
    },
  );

  // Animate node A's fill to red
  flowchart.addIncident(
    new McFlowchart.Attr(
      { animatedAttrs: { fill: "#e74c3c" } },
      { selector: "!#A", duration: 1000 },
    ),
    500,
  );

  // Step 2 at 2s: expand the graph
  flowchart.addCustomEntity(
    {
      dot: `digraph {
        rankdir=TB
        node [style=filled fillcolor="#eaf2f8" color="#2c3e50" fontcolor="#2c3e50"]
        A [label="Start" shape=ellipse]
        B [label="Decision" shape=diamond]
        C [label="Do something" shape=box]
        D [label="Do nothing" shape=box]
        A -> B
        B -> C [label="Yes"]
        B -> D [label="No"]
      }`,
      nodeIds: ["A", "B", "C", "D"],
    },
    "step2",
    [],
    2000,
  );

  new Player({ clip: flowchart });
}

main();

API

Plugin

| Method | Description | | --------------------------- | -------------------------------------------------------------------------------------------- | | FlowchartPluginDef.init() | Load Graphviz WASM engine. Returns a Promise. Must be called once before creating any clips. |

FlowchartClip (Clip)

Extends BrowserClip. Accepts these attrs:

| Attr | Type | Description | | --------- | ---------- | ------------------------------------------- | | dot | string | Initial DOT graph string | | nodeIds | string[] | Node IDs to register as animatable entities |

Clip props should include an explicit duration since addCustomEntity birthtimes don't auto-extend clip duration in the current MC version.

Incremental graph building

Use addCustomEntity to add graph steps at specific timeline positions:

flowchart.addCustomEntity(
  { dot: "digraph { ... }", nodeIds: ["A", "B", "C"] },
  "step-id",
  [], // classes
  2000, // birthtime (ms)
);

Each step provides the full DOT graph for that point in time. The plugin diffs the SVG in place: existing node elements persist (preserving Effect state), new nodes are appended, removed nodes are deleted, and edges are updated.

Attr (Effect)

Tweens visual properties of individual nodes. Target nodes with !#nodeId selector.

| Animated Attr | Type | Range | Description | | ------------- | -------- | --------- | ----------------------------------- | | fill | string | hex color | Node background fill color | | glow | number | 0..1 | CSS drop-shadow highlight intensity | | opacity | number | 0..1 | Node opacity |

// Glow node B
flowchart.addIncident(
  new McFlowchart.Attr(
    { animatedAttrs: { glow: 1 } },
    { selector: "!#B", duration: 300 },
  ),
  1000,
);

DOT Syntax

The plugin uses Graphviz DOT for graph definitions. Common patterns:

digraph {
  rankdir=TB                    // Top-to-bottom layout
  node [style=filled fillcolor="#eaf2f8" color="#2c3e50"]

  A [label="Start" shape=ellipse]
  B [label="Check" shape=diamond]
  C [label="Process" shape=box]

  A -> B
  B -> C [label="Yes"]
}

Supported shapes: ellipse, diamond, box, circle, record, plaintext, and all Graphviz shapes.

Known Limitations (v1)

• Layout jump on graph expansion: When nodes are added, Graphviz re-calculates all positions. Existing nodes may shift to new coordinates. Animated position transitions are planned for v2.
• Clip duration: addCustomEntity birthtimes don't auto-extend clip duration. Set an explicit duration on the clip.
• Backward seek: Uses in-place SVG diffing to preserve Effect state where possible.

Development

npm install
npm start        # Dev server with hot reload
npm run build    # Production build

License

MIT