npm package: @immediate-diagram/renderer
Description: Pluggable layout engine, SVG renderer, animation engine, and timeline playback for Immediate Diagram.
Latest version: 1.2.3

# @immediate-diagram/renderer

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

## Install

```bash
bun add @immediate-diagram/renderer
```

> **Note:** This package publishes raw `.ts` source. Requires [Bun](https://bun.sh) 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

```typescript
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:

```typescript
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

```typescript
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

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

## License

MIT