@immediate-diagram/renderer

Pluggable layout engine, SVG renderer, animation engine, and timeline playback for Immediate Diagram.

Install

bun add @immediate-diagram/renderer

Note: This package publishes raw .ts source. Requires Bun as runtime.

Features

• 5 layout strategies — graph (dagre), columnar (sequence), polar (pie/donut), nested (block), geometric (venn)
• SVG rendering — produces self-contained SVG strings with inline styles and interactive hover/focus
• Animation engine — CSS transition tracking, state interpolation, DOM patching
• Timeline playback — headless multi-state sequencing with play/pause/step/scrub

Usage

Parse + Layout + Render

import { parseOrThrow } from "@immediate-diagram/parser";
import { narrowDiagram } from "@immediate-diagram/shared";
import { LayoutEngine, renderDiagram } from "@immediate-diagram/renderer";

const doc = parseOrThrow('flowchart\nA["Start"] --> B["End"]');
const diagram = narrowDiagram(doc);

const engine = new LayoutEngine();
const positioned = engine.layout(diagram);
const svg = renderDiagram(positioned);
// svg is a complete <svg>...</svg> string

Layout Strategies

Each diagram type uses an appropriate layout strategy:

| Strategy | Diagram Types | Implementation | |----------|--------------|----------------| | GraphLayoutStrategy | flowchart, architecture | @dagrejs/dagre (~30KB) | | ColumnarLayoutStrategy | sequence | Custom (zero deps) | | PolarLayoutStrategy | pie, donut | Custom (zero deps) | | NestedLayoutStrategy | block | Custom (zero deps) | | GeometricLayoutStrategy | venn | Custom (zero deps) |

Animation

Apply state overrides and animate between states:

import { applyState, filterHiddenElements } from "@immediate-diagram/renderer";

// Apply a named state to a diagram AST (mutates styles, hides elements)
const stateAst = applyState(diagram, "active");

Timeline Playback

import { createTimelineEngine } from "@immediate-diagram/renderer";

const engine = createTimelineEngine({
  steps: [
    { from: "default", to: "active", durationMs: 1000 },
    { from: "active", to: "done", durationMs: 800 },
  ],
  onStateChange: (from, to) => console.log(`${from} -> ${to}`),
  onProgress: (progress) => console.log(`${(progress * 100).toFixed(0)}%`),
});

engine.play();

API Reference

Layout

• LayoutEngine — orchestrates strategy selection and layout computation
• GraphLayoutStrategy — dagre-based directed graph layout
• ColumnarLayoutStrategy — column-based sequence diagram layout
• PolarLayoutStrategy — radial pie/donut chart layout
• GeometricLayoutStrategy — circle-packing Venn diagram layout
• NestedLayoutStrategy — recursive nested block layout

Rendering

• renderDiagram(positioned) — renders any PositionedDiagram to SVG string
• renderGraphDiagram(), renderSequenceDiagram(), renderPieDiagram(), renderBlockDiagram(), renderVennDiagram() — type-specific renderers

Animation

• applyState(diagram, stateName) — apply state overrides to a diagram AST
• filterHiddenElements(ast) — remove visible: false elements from AST
• AnimationEngine — full animation engine with interpolation and DOM patching
• createFrameController() — rAF-based frame loop controller

Timeline

• createTimelineEngine() — headless timeline playback
• TimelineManager — manages multiple timeline definitions
• createTimelineAnimationConnector() — connects timeline engine to animation engine

Development

bun test            # Run tests
bun run typecheck   # Type checking
bun run bench       # Run benchmarks

License

MIT