vizmatic 0.1.35 → 0.1.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/PROMPT.md CHANGED
@@ -173,69 +173,69 @@ export const watermark = (
173
173
  )
174
174
  ```
175
175
 
176
- Render animated frames with `createScenes(theme)`:
176
+ Render a sampled state timeline with `createAnimation(theme)`:
177
177
 
178
178
  ```bash
179
- vizmatic gif frames/animated-pipeline.tsx --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right --scale 1
179
+ vizmatic gif frames/animated-pipeline.tsx --out public/vizmatic --theme dark,light --fps 20 --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right --scale 1
180
180
  ```
181
181
 
182
182
  ## Animated frames
183
183
 
184
- An animated module exports `createScenes(theme)` for GIF output and keeps `create(theme)` for a static frame.
184
+ An animated module exports `createAnimation(theme)` for GIF output and keeps `create(theme)` for a static or reduced-motion fallback. Define state once, then describe holds, eased transitions, instant keyframes, and parallel property tracks. Vizmatic samples absolute timeline time and renders every GIF frame.
185
185
 
186
186
  ```tsx
187
187
  import React from "react"
188
- import {
189
- CalloutCard,
190
- defineIllustration,
191
- Flow,
192
- Scene,
193
- getThemeColors,
194
- type AnimatedScene,
195
- type ThemeColors,
196
- type ThemeMode,
197
- } from "vizmatic"
188
+ import { Scene, defineAnimation, getThemeColors, hold, keyframe, tween, type ThemeMode } from "vizmatic"
198
189
 
199
190
  export const width = 1040
200
191
  export const height = 560
201
192
 
202
- const stages = [
203
- { title: "Prompt", tone: "blue" as const },
204
- { title: "Scene spec", tone: "purple" as const },
205
- { title: "PNG / GIF", tone: "green" as const },
206
- ]
193
+ type State = { operation: number; progress: number }
207
194
 
208
- function buildFrame(c: ThemeColors, active: number) {
195
+ function buildFrame(theme: ThemeMode, state: State) {
196
+ const c = getThemeColors(theme)
209
197
  return (
210
- <Scene c={c} title="Animated agent pipeline">
211
- <Flow
212
- c={c}
213
- stages={stages.map((stage, index) => ({
214
- ...stage,
215
- title: index <= active ? stage.title : "Pending",
216
- tone: index <= active ? stage.tone : "neutral",
217
- }))}
218
- />
219
- <CalloutCard c={c} title="Scene changes over time" detail="Render with vizmatic gif." tone="green" />
198
+ <Scene c={c} title={state.operation === 0 ? "Broadcast" : "AllReduce"}>
199
+ <div style={{ display: "flex", width: "100%", height: 260, position: "relative" }}>
200
+ <div style={{
201
+ display: "flex",
202
+ position: "absolute",
203
+ left: 40 + state.progress * 720,
204
+ top: 90,
205
+ padding: "10px 16px",
206
+ borderRadius: 8,
207
+ background: c.accent,
208
+ color: c.textOnColor,
209
+ }}>chunk</div>
210
+ </div>
220
211
  </Scene>
221
212
  )
222
213
  }
223
214
 
224
- const frame = defineIllustration((c) => buildFrame(c, stages.length - 1))
215
+ export function createAnimation(theme: ThemeMode) {
216
+ return defineAnimation<State>({
217
+ initial: { operation: 0, progress: 0 },
218
+ timeline: [
219
+ hold(500, "Broadcast input"),
220
+ tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "Broadcast" }),
221
+ hold(500, "Broadcast output"),
222
+ keyframe({ operation: 1, progress: 0 }),
223
+ tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "AllReduce" }),
224
+ ],
225
+ fps: 20,
226
+ render: (state) => buildFrame(theme, state),
227
+ })
228
+ }
225
229
 
226
- export function createScenes(theme: ThemeMode): AnimatedScene[] {
227
- const c = getThemeColors(theme)
228
- return stages.map((_, index) => ({
229
- element: buildFrame(c, index),
230
- duration: index === stages.length - 1 ? 1000 : 700,
231
- transition: index === 0 ? "appear" : "fade",
232
- }))
230
+ export function create(theme: ThemeMode = "dark") {
231
+ return buildFrame(theme, { operation: 1, progress: 1 })
233
232
  }
234
233
 
235
- export const create = frame.create
236
- export default frame.default
234
+ export default create("dark")
237
235
  ```
238
236
 
237
+ Top-level timeline steps run sequentially. Properties inside one `tween` move together. Use `parallel({ x: [...], opacity: [...] })` when property tracks need different delays or durations. Default interpolation supports finite numbers; use a custom `interpolate(from, to, progress)` for colors, points, or other values. `createScenes(theme)` remains supported for deliberate scene cuts and pixel `fade`/`appear` transitions.
238
+
239
239
  ## Choose primitives
240
240
 
241
241
  Use Vizmatic primitives for common layouts. Use raw SVG only for geometry the component set cannot express.
@@ -274,7 +274,7 @@ Cards, labels, and compact UI:
274
274
  - `TextLabel`: `text`, `c`, `variant?: keyof typography = "body"`, `color?`, `fontSize?`, `fontWeight?`, `width?`, `align?: "left" | "center" | "right" = "left"`, `math?: boolean = false`, `mono?: boolean = false`.
275
275
  - `MathText`: `text`. Returns formatted unicode-ish math text for simple `_` and `^` notation.
276
276
  - `formatMathText(text)`: `text: string`.
277
- - `Icon`: `name`, `c`, `tone?: ToneName = "blue"`, `color?`, `size?: number = 24`, `strokeWidth?: number = 2`, `label?`, `muted?: boolean = false`. `IconName`: `"agent" | "chart" | "check" | "code" | "database" | "file" | "git" | "globe" | "image" | "layers" | "lock" | "play" | "spark" | "terminal" | "tool" | "warning"`.
277
+ - `Icon`: `name`, `c`, `tone?: ToneName = "blue"`, `color?`, `size?: number = 24`, `strokeWidth?: number = 2`, `label?`, `muted?: boolean = false`. `IconName` includes presentation icons plus architecture icons: `browser`, `bucket`, `cache`, `cloud`, `cluster`, `container`, `database`, `firewall`, `gateway`, `load-balancer`, `mobile`, `monitor`, `network`, `queue`, `server`, `storage`, `stream`, and `user`.
278
278
  - `ToneStrip`: `tone`, `width?: number = 34`, `height?: number = 4`.
279
279
  - `StepCard`: `title`, `c`, `subtitle?`, `eyebrow?`, `tone?: ToneName = "blue"`, `width?: number | string = 210`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "12px 14px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`.
280
280
  - `MetricCard`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "10px 12px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`, `valueMono?: boolean = true`, `valueFontSize?: number = 22`, `valueColor?`.
@@ -314,7 +314,9 @@ Flows and process diagrams:
314
314
  Graphs and networks:
315
315
 
316
316
  - `LayeredNetwork`: `c`, `layers: LayeredNetworkLayer[]`, `activePath?: number[] = []`, `annotations?: string[] = []`, `formula?`, `legend?: string = "highlighted path"`, `width?: number = 900`, `height?: number = 400`, `nodeSize?: number = 56`, `showFormula?: boolean = true`. `LayeredNetworkLayer`: `title`, `nodes: string[]`, `tone?`.
317
- - `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `labelFontSize?: number = 14`, `detailFontSize?: number = 11`, `arrowSize?: number = 5`, `padding?: number = 28`, `layout?: "auto" | "manual"`, `direction?: "LR" | "RL" | "TB" | "BT" = "LR"`, `nodeGap?: number = 34`, `rankGap?: number = 64`, `edgeGap?: number = 14`, `sizing?: "content" | "fixed" = "content"`. `GraphDiagramNode`: `id`, `label`, `detail?`, `x?`, `y?`, `tone?`, `muted?`, `width?`, `height?`. Omit coordinates on every node for automatic layout; array order is the stable tie-breaker and dimensions expand to fit unless `sizing="fixed"`. Set both coordinates on every node for manual normalized positioning. Mixed coordinate modes fail. `GraphDiagramEdge`: `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`.
317
+ - `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `groups?: GraphDiagramGroup[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `labelFontSize?: number = 14`, `detailFontSize?: number = 11`, `arrowSize?: number = 5`, `padding?: number = 28`, `layout?: "auto" | "manual"`, `direction?: "LR" | "RL" | "TB" | "BT" = "LR"`, `nodeGap?: number = 34`, `rankGap?: number = 64`, `edgeGap?: number = 14`, `sizing?: "content" | "fixed" = "content"`, `iconSize?: number = 20`, `ariaLabel?`. `GraphDiagramNode`: `id`, `label`, `detail?`, `x?`, `y?`, `tone?`, `muted?`, `width?`, `height?`, `group?`, `icon?: IconName | DiagramIconDefinition | ReactElement`, `iconSize?`. Icon size is clamped inside its node; custom React elements own their theme colors and accessible label. `GraphDiagramGroup`: `id`, `label`, `detail?`, `parent?`, `tone?`, `muted?`. Groups nest through `parent` and require automatic layout. Omit coordinates on every node for automatic layout; array order is the stable tie-breaker and dimensions expand to fit unless `sizing="fixed"`. Set both coordinates on every node for manual normalized positioning when no groups are present. Mixed coordinate modes fail. `GraphDiagramEdge`: `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`, `kind?: "sync" | "async" | "event" | "data" | "dependency" | "association"`, `style?: "solid" | "dashed" | "dotted"`, `arrow?: "forward" | "backward" | "both" | "none"`. Association edges default to no arrow.
318
+ - `defineDiagramIcon(id, render)`: defines a reusable custom graph icon. `render` receives `c`, `color`, `size`, and optional `label`.
319
+ - `defineIconRegistry(icons)`: preserves typed names for a set of custom or provider icons without global mutable state.
318
320
  - `TreeDiagram`: `root: TreeNodeSpec`, `c`, `title?`, `subtitle?`, `width?`, `height?`, `nodeWidth?: number = 156`, `nodeHeight?: number = 64`, `levelGap?: number = 58`, `siblingGap?: number = 24`, `padding?: number = 28`, `math?: boolean = false`. `TreeNodeSpec`: `label`, `id?`, `detail?`, `tone?`, `muted?`, `children?`.
319
321
 
320
322
  Matrices and heatmaps:
@@ -376,10 +378,19 @@ Theme and render APIs:
376
378
  - `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `theme?: "dark" | "light" = "dark"` for direct-render watermark defaults, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean | "height" | "both" = true`, `scale?: number = 2`. Default autocrop retains 24 source pixels around detected content. Use `crop: "height"` when host layouts require stable width but should still trim extra vertical whitespace.
377
379
  - `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`, `scale?`.
378
380
  - `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`.
379
- - `renderAnimatedGif(scenes, options)`: `scenes: AnimatedScene[]`, `options: AnimationOptions`.
381
+ - `defineAnimation({ initial, timeline, render, fps? })`: creates deterministic typed state animation. `fps` defaults to `20` and accepts integers from `1` to `50`.
382
+ - `hold(duration, label?)`: keep current state for milliseconds.
383
+ - `tween(to, { duration, easing?, interpolate?, label? })`: transition listed properties together. Easing is `"linear" | "ease-in" | "ease-out" | "ease-in-out"` or pure progress function.
384
+ - `keyframe(value, label?)`: apply instant partial state update.
385
+ - `parallel(tracks, label?)`: run property tracks concurrently; each track accepts `hold`, `tween`, and `keyframe` steps.
386
+ - `sampleAnimation(animation, time)`: evaluate state at exact millisecond.
387
+ - `sampleAnimationFrames(animation, { fps? })`: return deterministic state/frame samples with GIF-compatible delays.
388
+ - `renderAnimationGif(animation, options)`: stream timeline samples into GIF.
389
+ - `renderAnimationGifWithOutput(animation, options)`: same arguments and returns physical `width` and `height`.
390
+ - `renderAnimatedGif(scenes, options)`: legacy `AnimatedScene[]` renderer for scene cuts and pixel transitions. It also accepts a defined animation.
380
391
  - `renderAnimatedGifWithOutput(scenes, options)`: same arguments as `renderAnimatedGif`; returns physical `width` and `height`.
381
392
  - `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
382
- - `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `background?: "theme" | "transparent" | CSS color = "theme"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`. Transparent GIFs use one-bit transparency; use PNG/SVG when smooth alpha edges matter.
393
+ - `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `fps?: number`, `background?: "theme" | "transparent" | CSS color = "theme"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`. Transparent GIFs use one-bit transparency; use PNG/SVG when smooth alpha edges matter.
383
394
 
384
395
  ## Prop-aware examples
385
396
 
@@ -464,10 +475,10 @@ height = 560;
464
475
  - Prefer alpha-transparent PNG/SVG backgrounds for blog embeds and docs cards. Use theme backgrounds only when the host surface is unknown or needs full-frame fill.
465
476
  - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` to keep layout stable.
466
477
  - Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
467
- - Omit `x` and `y` from `GraphDiagram` nodes for automatic layered layout. Add both only when editorial composition needs manual control.
478
+ - Omit `x` and `y` from `GraphDiagram` nodes for automatic layered layout and nested groups. Add both only when an ungrouped graph needs editorial manual control.
468
479
  - Render reusable assets in both themes with `--theme dark,light`.
469
480
  - Run `vizmatic check <frame> --theme dark,light --json` before final render and fix every error.
470
- - Use GIF only when motion explains state change. Keep scenes short, export `createScenes(theme)`, and keep a static `create(theme)` fallback.
481
+ - Use GIF only when motion explains state change. Prefer `createAnimation(theme)` with `hold` and `tween`, keep timelines short, and keep static `create(theme)` fallback. Use `createScenes(theme)` only for deliberate cuts or crossfades.
471
482
  - If render fails with `Canvas overflow detected`, increase the canvas, reduce content, or remove strict sizing. Do not ignore the error.
472
483
  - Confirm generated files exist and open at least one image before finishing.
473
484
 
package/README.md CHANGED
@@ -134,7 +134,7 @@ Each output directory includes `manifest.json`. `outputs` lists generated files,
134
134
  Render an animation:
135
135
 
136
136
  ```bash
137
- vizmatic gif ./animated-frame.tsx --out ./dist/frames --theme dark,light --watermark "Acme" --watermark-image ./logo.svg
137
+ vizmatic gif ./animated-frame.tsx --out ./dist/frames --theme dark,light --fps 20 --watermark "Acme" --watermark-image ./logo.svg
138
138
  ```
139
139
 
140
140
  Or call the renderer directly:
@@ -180,13 +180,19 @@ Vizmatic provides reusable layout, diagram, and chart primitives:
180
180
  | Headless rendering | Node produces assets directly in local workflows and CI |
181
181
  | Theme variants | One command renders dark and light output from semantic color tokens |
182
182
  | Layout checks | Overflow, contrast, small text, label overlap, uneven panel whitespace, and connector congestion |
183
- | Animation | Ordered scene states export as GIFs |
183
+ | Animation | Typed state timelines, tweens, easing, holds, keyframes, and parallel tracks export as GIFs |
184
184
 
185
185
  ## Gallery
186
186
 
187
187
  <p>
188
188
  <img src="https://bvolpato.github.io/vizmatic/assets/examples/animated-pipeline_dark.gif" alt="Animated pipeline" width="380" />
189
- <img src="https://bvolpato.github.io/vizmatic/assets/examples/attention-head_dark.png" alt="Attention head" width="380" />
189
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/nccl-broadcast_dark.gif" alt="Animated NCCL Broadcast: root rank sends one buffer to every rank" width="300" />
190
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/nccl-all-reduce_dark.gif" alt="Animated NCCL AllReduce: every rank reduces values and receives the sum" width="300" />
191
+ </p>
192
+ <p>
193
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/nccl-all-gather_dark.gif" alt="Animated NCCL AllGather: every rank receives concatenated tensors" width="300" />
194
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/nccl-reduce-scatter_dark.gif" alt="Animated NCCL ReduceScatter: each rank receives one reduced chunk" width="300" />
195
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/nccl-all-to-all_dark.gif" alt="Animated NCCL AllToAll: every rank exchanges one chunk with every rank" width="300" />
190
196
  </p>
191
197
  <p>
192
198
  <img src="https://bvolpato.github.io/vizmatic/assets/examples/rag-graph_dark.png" alt="RAG graph" width="380" />
@@ -197,10 +203,13 @@ Vizmatic provides reusable layout, diagram, and chart primitives:
197
203
  <img src="https://bvolpato.github.io/vizmatic/assets/examples/theme-system_dark.png" alt="Theme system" width="380" />
198
204
  </p>
199
205
  <p>
206
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/system-architecture_dark.png" alt="System architecture" width="380" />
200
207
  <img src="https://bvolpato.github.io/vizmatic/assets/examples/presentation-frame_dark.png" alt="Presentation frame" width="380" />
201
208
  </p>
202
209
 
203
- More examples live in [`examples/`](examples). The website has a searchable [component catalog](https://bvolpato.github.io/vizmatic/components.html) with a rendered preview and source for every public component. [`PROMPT.md`](PROMPT.md) contains the full install, syntax, component, and verification reference for coding agents.
210
+ NCCL gallery examples cover five operations: Broadcast, AllReduce, AllGather, ReduceScatter, and AllToAll. Their diagrams follow NVIDIA's documented [collective operation semantics](https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/usage/collectives.html): rooted transfer, reduction, rank-ordered gathering, reduced chunk ownership, and pairwise exchange.
211
+
212
+ More examples live in [`examples/`](examples). The website has a searchable [component catalog](https://bvolpato.github.io/vizmatic/components.html) with a rendered preview and source for every public component. [`PROMPT.md`](PROMPT.md) contains the full install, syntax, component, and verification reference for coding agents. [`ROADMAP.md`](ROADMAP.md) tracks C4, provider packs, sequence, UML, deployment, network, dataflow, layout, and interoperability work.
204
213
 
205
214
  ## Repository checks
206
215
 
@@ -317,26 +326,33 @@ Use these primitives before writing raw SVG or absolute-positioned layouts.
317
326
  | `Flow` | Horizontal or vertical staged process diagram with optional detail rows. |
318
327
  | `Pipeline` | Process pipeline with stage labels and a shared title. |
319
328
  | `LayeredNetwork` | Neural-network/DAG diagram with layers, nodes, active path, annotations, and formula. |
320
- | `GraphDiagram` | Auto-laid or manually positioned node-edge graph with routed paths, labels, and tone-aware nodes. |
329
+ | `GraphDiagram` | Auto-laid architecture graph with nested boundaries, technical icons, typed relationships, and custom icon definitions. |
321
330
  | `TreeDiagram` | Auto-laid parent/child hierarchy for ownership, routing, taxonomy, and decision trees. |
322
331
 
323
- `GraphDiagram` uses deterministic layered layout when node coordinates are omitted:
332
+ `GraphDiagram` uses deterministic layered layout when node coordinates are omitted. Groups become nested system boundaries, while built-in technical icons keep common architecture nodes concise:
324
333
 
325
334
  ```tsx
326
335
  <GraphDiagram
336
+ ariaLabel="Checkout architecture"
337
+ groups={[
338
+ { id: "prod", label: "Production", tone: "blue" },
339
+ { id: "data", label: "Data", parent: "prod", tone: "green" },
340
+ ]}
327
341
  nodes={[
328
- { id: "prompt", label: "Prompt", tone: "blue" },
329
- { id: "render", label: "Render", tone: "purple" },
330
- { id: "asset", label: "PNG / SVG / GIF", tone: "green" },
342
+ { id: "client", label: "Client", icon: "browser", tone: "cyan" },
343
+ { id: "api", label: "API", icon: "server", group: "prod", tone: "purple" },
344
+ { id: "db", label: "Postgres", icon: "database", group: "data", tone: "green" },
331
345
  ]}
332
346
  edges={[
333
- { from: "prompt", to: "render" },
334
- { from: "render", to: "asset" },
347
+ { from: "client", to: "api", label: "HTTPS", kind: "sync" },
348
+ { from: "api", to: "db", label: "SQL", kind: "data", arrow: "both" },
335
349
  ]}
336
350
  />
337
351
  ```
338
352
 
339
- Set `x` and `y` on every node for normalized manual positioning. Mixed coordinate modes fail with a clear error. Automatic layout treats node and edge array order as its stable tie-breaker and expands `width` or `height` when needed. Set `sizing="fixed"` to keep exact graph dimensions and let overflow checks report a canvas that is too small. Use `direction`, `nodeGap`, `rankGap`, and `edgeGap` to tune the result.
353
+ Groups support unlimited nesting in automatic layout, reserve a boundary-header gutter, and clip long headers inside the boundary. Set `icon` to a built-in `IconName`, a React element, or a reusable icon from `defineDiagramIcon`; `defineIconRegistry` groups provider packs without a runtime registry. Icon size stays inside its node. Custom React elements own their theme colors and accessible label. Relationship `kind` selects solid, dashed, or dotted defaults, `style` overrides them, and `arrow` accepts `forward`, `backward`, `both`, or `none`. Associations default to no arrow.
354
+
355
+ Set `x` and `y` on every node for normalized manual positioning when no groups are present. Mixed coordinate modes fail with a clear error. Automatic layout treats node and edge array order as its stable tie-breaker and expands `width` or `height` when needed. Set `sizing="fixed"` to keep exact graph dimensions and let overflow checks report a canvas that is too small. Use `direction`, `nodeGap`, `rankGap`, and `edgeGap` to tune the result.
340
356
 
341
357
  #### Matrices, tables, and grids
342
358
 
@@ -371,6 +387,10 @@ Set `x` and `y` on every node for normalized manual positioning. Mixed coordinat
371
387
  | `renderToPngWithOutput` | Render PNG and return logical plus physical pixel dimensions. |
372
388
  | `renderAnimatedGif` | Render ordered `AnimatedScene[]` states to GIF with `fade`, `appear`, or no transition. |
373
389
  | `renderAnimatedGifWithOutput` | Render GIF and return its physical pixel dimensions. |
390
+ | `defineAnimation` | Define a typed state timeline rendered at deterministic sample times. |
391
+ | `hold`, `tween`, `keyframe`, `parallel` | Compose sequential pauses, eased property transitions, instant state changes, and staggered concurrent tracks. |
392
+ | `sampleAnimation` | Evaluate timeline state at an exact millisecond without rendering. |
393
+ | `renderAnimationGif` | Stream sampled timeline frames into a GIF without retaining every RGBA frame. |
374
394
  | `renderToBuffer` | Render PNG to memory for tests and pipelines. |
375
395
  | `renderToSvg` | Render SVG markup directly. |
376
396
  | `Watermark` | JSX marker component for expressive frame-module watermarks. |
@@ -389,7 +409,7 @@ Theme and chart helpers are public for custom primitives: `getReadableColor(name
389
409
  ### Rendering
390
410
 
391
411
  ```ts
392
- import { renderAnimatedGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
412
+ import { renderAnimatedGif, renderAnimationGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
393
413
  ```
394
414
 
395
415
  `renderToPng` renders at 2x scale, checks for clipping, and crops extra whitespace while keeping 24 source pixels around detected content. Output stays transparent unless `background` is set.
@@ -423,19 +443,40 @@ export const watermark = (
423
443
  )
424
444
  ```
425
445
 
426
- `renderAnimatedGif` turns ordered scene states into a looping GIF. GIF transparency is one-bit; use PNG or SVG when edges need full alpha.
446
+ Prefer `defineAnimation` when values should move, resize, or fade continuously. Timeline array runs sequentially; every property in one `tween` moves in parallel. `parallel` adds independent property tracks for staggered or overlapping motion. Renderer samples absolute time deterministically and includes exact initial and terminal states. Keep `create(theme)` as static fallback for PNG, docs previews, and reduced-motion users.
447
+
448
+ ```tsx
449
+ import { defineAnimation, hold, keyframe, tween } from "vizmatic"
450
+
451
+ export function createAnimation(theme: ThemeMode) {
452
+ return defineAnimation({
453
+ initial: { operation: 0, progress: 0 },
454
+ timeline: [
455
+ hold(500, "Broadcast input"),
456
+ tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "Transfer" }),
457
+ hold(500, "Broadcast output"),
458
+ keyframe({ operation: 1, progress: 0 }),
459
+ tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "AllReduce" }),
460
+ ],
461
+ fps: 20,
462
+ render: (state, frame) => buildFrame(theme, state, frame),
463
+ })
464
+ }
465
+ ```
427
466
 
428
467
  ```ts
429
- await renderAnimatedGif(createScenes("dark"), {
468
+ await renderAnimationGif(createAnimation("dark"), {
430
469
  width: 1040,
431
470
  height: 560,
432
- outputPath: "dist/agent-pipeline.gif",
471
+ outputPath: "dist/collective.gif",
433
472
  watermark: { text: "Your Product", image: "data:image/png;base64,...", position: "bottom-right" },
434
473
  theme: "dark",
435
474
  scale: 1,
436
475
  })
437
476
  ```
438
477
 
478
+ `createScenes(theme)` and `renderAnimatedGif(AnimatedScene[])` remain supported for intentional scene cuts and pixel crossfades. `fps` controls their transition sampling as well as typed timelines. GIF output uses one shared 256-color palette, centisecond timing, and one-bit transparency. Prefer 10, 20, 25, or 50 FPS and align tween or transition durations to frame intervals, such as multiples of 50 ms at 20 FPS. Other timings alternate centisecond delays to preserve total duration. Use PNG/SVG for smooth alpha edges.
479
+
439
480
  ## Development
440
481
 
441
482
  ```bash
package/ROADMAP.md ADDED
@@ -0,0 +1,66 @@
1
+ # Technical diagram roadmap
2
+
3
+ Vizmatic aims to make polished technical diagrams easy from TSX while keeping rendering deterministic, offline-capable, theme-aware, and composable with charts or presentation frames.
4
+
5
+ Benchmarks: [Diagrams](https://diagrams.mingrammer.com/), [D2](https://d2lang.com/), [Structurizr](https://docs.structurizr.com/), [Mermaid](https://mermaid.js.org/), and [PlantUML](https://plantuml.com/).
6
+
7
+ ## Available now
8
+
9
+ - Deterministic Dagre layout in four directions.
10
+ - Nested system boundaries through `GraphDiagram.groups`.
11
+ - Built-in generic icons for users, clients, services, infrastructure, data, networks, and operations.
12
+ - Reusable custom icon definitions and typed icon registries.
13
+ - Labeled synchronous, asynchronous, event, data, dependency, and association relationships.
14
+ - Solid, dashed, and dotted connectors with forward, backward, bidirectional, or no arrows.
15
+ - Manual positioning for ungrouped editorial diagrams.
16
+ - Connector diagnostics for crossings, label collisions, crowded endpoints, and parallel routes.
17
+ - Dark, light, and Engineering visual presets with PNG, SVG, and GIF output.
18
+ - Typed state timelines with holds, eased tweens, keyframes, parallel tracks, deterministic sampling, and streamed GIF encoding.
19
+
20
+ ## Next capability batches
21
+
22
+ ### Architecture model and views
23
+
24
+ - C4 person, software system, container, component, and deployment semantics.
25
+ - One reusable model with context, container, component, deployment, and dynamic views.
26
+ - Named views, filtered views, legends, tags, and technology metadata.
27
+ - Drill-down links and stable element identifiers in SVG output.
28
+
29
+ ### Technical icon packs
30
+
31
+ - Build-time generated GCP and Kubernetes packs from pinned Apache-2.0 Iconify data.
32
+ - Optional provider modules so unused icons do not increase core bundle size.
33
+ - Asset metadata with source, version, license, and trademark notice.
34
+ - User-supplied AWS and Azure adapters until redistribution terms support bundled packs.
35
+ - No default runtime icon API or network dependency.
36
+
37
+ ### Interaction and software design
38
+
39
+ - Sequence diagrams with participants, lifelines, activations, sync/async/return messages, notes, and `alt`/`loop`/`parallel` fragments.
40
+ - UML class and component diagrams with compartments, inheritance, aggregation, composition, multiplicity, and stereotypes.
41
+ - State machines with nested states, guards, entry/exit actions, and parallel regions.
42
+ - ER diagrams with tables, fields, keys, data types, and cardinality-aware relationships.
43
+
44
+ ### Infrastructure and data systems
45
+
46
+ - Deployment and network views with regions, zones, VPCs, subnets, namespaces, hosts, ports, protocols, trust boundaries, and ingress/egress.
47
+ - Dataflow and lineage views with sources, sinks, stores, transformations, schemas, and batch/stream semantics.
48
+ - Swimlanes and activity diagrams for ownership, handoffs, conditions, and parallel work.
49
+
50
+ ### Layout and rendering
51
+
52
+ - Named ports and endpoint anchors.
53
+ - Orthogonal, curved, and user-routed connectors with parallel-edge separation.
54
+ - Layout adapter interface with Dagre as default and ELK as optional backend.
55
+ - Per-boundary direction, collapsed groups, named scenarios, and reusable animation compositions.
56
+ - Tooltips, links, and accessible structured descriptions in SVG.
57
+ - Import/export adapters for Mermaid, D2, Structurizr, Kubernetes, and Terraform where semantics map safely.
58
+
59
+ ## Design constraints
60
+
61
+ - Keep current `GraphDiagram` input backward compatible.
62
+ - Compile specialized diagram APIs into shared typed models instead of separate rendering stacks.
63
+ - Keep default rendering deterministic and offline.
64
+ - Treat provider licensing and trademarks as product requirements.
65
+ - Add tests for behavior contracts and regressions, not source-text presence.
66
+ - Ship each capability with dark/light reference renders, docs, and diagnostics.