vizmatic 0.1.34 → 0.1.36

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.
@@ -258,7 +258,7 @@ Frame helpers:
258
258
 
259
259
  - `defineIllustration(build, defaultTheme?)`: `build: (c: ThemeColors) => ReactElement`, `defaultTheme?: ThemeMode = "dark"`. Returns `{ create(theme), default }`.
260
260
  - `Canvas`: `children?`, `c`, `padding?: number = 40`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "center"`, `background?: string`. Default root background is alpha-transparent during PNG/SVG rendering.
261
- - `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: Canvas.justify = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Title/subtitle are optional and the title bar is omitted when no title is provided. Use `background={c.bg}` for an opaque theme frame.
261
+ - `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Title/subtitle are optional and the title bar is omitted when no title is provided. Use `background={c.bg}` for an opaque theme frame.
262
262
  - `TitleBar`: `title`, `subtitle?`, `c`.
263
263
 
264
264
  Layout primitives:
@@ -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:
@@ -359,19 +361,36 @@ Theme and render APIs:
359
361
 
360
362
  - `getThemeColors(mode, preset?)`: `mode: ThemeMode`; `preset?: "default" | "engineering"`. Use `engineering` for flat technical-blog figures with a light gray palette, left-aligned black titles, pastel nodes, thin neutral connectors, compact corners, no shadows, Inter labels, and JetBrains Mono annotations. In a bare frame, set `preset = "engineering";` before the JSX. Add `background={c.bg}` to `Scene` for an opaque light gray canvas; omit it for alpha transparency.
361
363
  - `getToneColor(tone, c)`, `getToneFill(tone, c)`, `getToneGradient(tone)`, `getColor(name, c?)`, `getGradient(name)`, `heatColor(value)`.
364
+ - `getReadableColor(name, c)`: returns the semantic color variant with greatest contrast against `c.bgCard`.
365
+ - `getReadableToneColor(tone, c, background?)`: maps a tone to a readable semantic color and falls back to readable foreground text when contrast is below 4.5:1. `background` defaults to `c.bgCard`.
366
+ - `getReadableTextColor(background, c)`: parses solid or alpha CSS colors and chooses a theme foreground meeting 4.5:1 contrast when possible.
367
+ - `createPlotArea(width, height, margin)`: returns `PlotArea` geometry with inner width and height clamped to at least one pixel.
362
368
  - `renderToPng(element, options, createFn?, theme?)`: `element`, `options: RenderOptions`, `createFn?: (theme: "dark" | "light") => ReactNode`, `theme?: "dark" | "light"`.
363
369
  - `renderToPngWithOutput(...)`: same arguments as `renderToPng`; returns logical `width` / `height` and physical `pixelWidth` / `pixelHeight`.
364
370
  - `Watermark`: JSX marker component for frame-module exports. Props are `WatermarkOptions` plus `children?: ReactNode`; children become the complete watermark body.
365
371
  - `WatermarkInput`: `boolean | string | WatermarkOptions | ReactElement<WatermarkElementProps>`. `true` uses Vizmatic defaults. A string sets the watermark text. A React element can be `<Watermark>...</Watermark>` or any custom element.
366
372
  - `WatermarkImageOptions`: `src`, `width?: number`, `height?: number`, `alt?: string`. Programmatic `src` should be a URL or data URI. CLI `--watermark-image` accepts URL, data URI, or local path.
367
373
  - `WatermarkOptions`: `text?: string | false`, `image?: string | WatermarkImageOptions`, `icon?: ReactNode | string | false`, `element?: ReactNode`, `position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" = "top-right"`, `opacity?: number`, `color?: string`.
374
+ - `normalizeWatermark(input)`: converts boolean, string, object, or React-element `WatermarkInput` to `WatermarkOptions | undefined`.
375
+ - `wrapWithBrand(element, width, height, theme?, label?)`: compatibility wrapper around `wrapWithWatermark`; theme defaults to `"dark"` and label defaults to `"Vizmatic"`.
376
+ - `getFonts()`: lazily loads and caches bundled Satori font data for advanced integrations.
377
+ - `loadAdditionalAsset(code, segment)`: Satori missing-glyph callback; resolves emoji segments to Twemoji data URIs and returns an empty font list for other codes.
368
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.
369
379
  - `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`, `scale?`.
370
380
  - `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`.
371
- - `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.
372
391
  - `renderAnimatedGifWithOutput(scenes, options)`: same arguments as `renderAnimatedGif`; returns physical `width` and `height`.
373
392
  - `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
374
- - `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.
375
394
 
376
395
  ## Prop-aware examples
377
396
 
@@ -456,10 +475,10 @@ height = 560;
456
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.
457
476
  - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` to keep layout stable.
458
477
  - Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
459
- - 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.
460
479
  - Render reusable assets in both themes with `--theme dark,light`.
461
480
  - Run `vizmatic check <frame> --theme dark,light --json` before final render and fix every error.
462
- - 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.
463
482
  - If render fails with `Canvas overflow detected`, increase the canvas, reduce content, or remove strict sizing. Do not ignore the error.
464
483
  - Confirm generated files exist and open at least one image before finishing.
465
484
 
package/README.md CHANGED
@@ -20,7 +20,7 @@
20
20
 
21
21
  <p align="center">
22
22
  <a href="https://bvolpato.github.io/vizmatic/">Website</a> ·
23
- <a href="https://bvolpato.github.io/vizmatic/#playground">Playground</a> ·
23
+ <a href="https://bvolpato.github.io/vizmatic/playground.html">Playground</a> ·
24
24
  <a href="examples">Examples</a> ·
25
25
  <a href="PROMPT.md">Agent Prompt</a> ·
26
26
  <a href="#api">API</a>
@@ -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) and on the [website](https://bvolpato.github.io/vizmatic/). [`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
 
@@ -211,8 +220,9 @@ Generated examples and website files are committed. CI fails when a build change
211
220
  | `pnpm lint` | TypeScript coverage plus GitHub Actions validation with actionlint |
212
221
  | `pnpm test` | Render pipeline behavior, watermark options, and output validation |
213
222
  | `pnpm render:examples` | Dark/light PNGs, animated GIFs, source snippets, and website HTML |
223
+ | `pnpm check:examples` | Every example renders in both themes without errors or visual warnings |
214
224
  | `pnpm docs:check` | Local asset references, `PROMPT.md` sync, source modal themes, and homepage affordances |
215
- | `pnpm deps:check` | npm audit plus package tarball contents before release |
225
+ | `pnpm deps:check` | npm audit plus package tarball contents, size, and file-count budgets before release |
216
226
  | `./test.sh` drift check | Confirms render and docs commands leave no uncommitted output |
217
227
 
218
228
  Run the full local gate:
@@ -227,6 +237,8 @@ Vizmatic uses `react` for JSX frames, `satori` for layout, `@resvg/resvg-js` for
227
237
 
228
238
  Published packages include Inter, JetBrains Mono, Noto Sans, Noto Sans Math, and Twemoji SVGs under `assets/`, so normal CLI rendering does not fetch them at runtime. Set `VIZMATIC_FONT_DIR` or `VIZMATIC_ASSET_DIR` to use other local assets. Set `VIZMATIC_DISABLE_NETWORK=1` or `VIZMATIC_OFFLINE=1` to disable public fallbacks.
229
239
 
240
+ The complete Twemoji set is intentionally bundled so arbitrary emoji render offline. `pnpm deps:check` keeps that tradeoff bounded: the package must stay below 3.25 MB compressed, 12.5 MB unpacked, and 4,000 files.
241
+
230
242
  ## API
231
243
 
232
244
  ### Themes
@@ -314,26 +326,33 @@ Use these primitives before writing raw SVG or absolute-positioned layouts.
314
326
  | `Flow` | Horizontal or vertical staged process diagram with optional detail rows. |
315
327
  | `Pipeline` | Process pipeline with stage labels and a shared title. |
316
328
  | `LayeredNetwork` | Neural-network/DAG diagram with layers, nodes, active path, annotations, and formula. |
317
- | `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. |
318
330
  | `TreeDiagram` | Auto-laid parent/child hierarchy for ownership, routing, taxonomy, and decision trees. |
319
331
 
320
- `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:
321
333
 
322
334
  ```tsx
323
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
+ ]}
324
341
  nodes={[
325
- { id: "prompt", label: "Prompt", tone: "blue" },
326
- { id: "render", label: "Render", tone: "purple" },
327
- { 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" },
328
345
  ]}
329
346
  edges={[
330
- { from: "prompt", to: "render" },
331
- { from: "render", to: "asset" },
347
+ { from: "client", to: "api", label: "HTTPS", kind: "sync" },
348
+ { from: "api", to: "db", label: "SQL", kind: "data", arrow: "both" },
332
349
  ]}
333
350
  />
334
351
  ```
335
352
 
336
- 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.
337
356
 
338
357
  #### Matrices, tables, and grids
339
358
 
@@ -368,19 +387,29 @@ Set `x` and `y` on every node for normalized manual positioning. Mixed coordinat
368
387
  | `renderToPngWithOutput` | Render PNG and return logical plus physical pixel dimensions. |
369
388
  | `renderAnimatedGif` | Render ordered `AnimatedScene[]` states to GIF with `fade`, `appear`, or no transition. |
370
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. |
371
394
  | `renderToBuffer` | Render PNG to memory for tests and pipelines. |
372
395
  | `renderToSvg` | Render SVG markup directly. |
373
396
  | `Watermark` | JSX marker component for expressive frame-module watermarks. |
374
397
  | `wrapWithWatermark` | Add optional watermark text, image/icon, custom element, and position to a frame. |
398
+ | `normalizeWatermark` | Normalize boolean, string, object, or React-element watermark input to `WatermarkOptions`. |
399
+ | `wrapWithBrand` | Compatibility wrapper for adding a text watermark through `wrapWithWatermark`. |
400
+ | `getFonts` | Load and cache bundled Satori font data for advanced renderer integrations. |
401
+ | `loadAdditionalAsset` | Resolve Satori missing-glyph requests, including bundled or cached Twemoji assets. |
375
402
  | `detectBackgroundColor` | Find dominant transparent/background color for cropping. |
376
403
  | `detectContentBounds` | Compute non-background bounds for autocrop. |
377
404
  | `cropPixels` | Crop raw pixel buffers. |
378
405
  | `detectOverflow` | Fail frames that clip content at canvas edges. |
379
406
 
407
+ Theme and chart helpers are public for custom primitives: `getReadableColor(name, c)` selects the highest-contrast semantic variant, `getReadableToneColor(tone, c, background?)` adapts tone text to a background, and `getReadableTextColor(background, c)` chooses a foreground meeting 4.5:1 contrast when possible. `createPlotArea(width, height, margin)` returns clamped chart geometry for custom axes and marks.
408
+
380
409
  ### Rendering
381
410
 
382
411
  ```ts
383
- import { renderAnimatedGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
412
+ import { renderAnimatedGif, renderAnimationGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
384
413
  ```
385
414
 
386
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.
@@ -414,19 +443,40 @@ export const watermark = (
414
443
  )
415
444
  ```
416
445
 
417
- `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 terminal state. 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
+ ```
418
466
 
419
467
  ```ts
420
- await renderAnimatedGif(createScenes("dark"), {
468
+ await renderAnimationGif(createAnimation("dark"), {
421
469
  width: 1040,
422
470
  height: 560,
423
- outputPath: "dist/agent-pipeline.gif",
471
+ outputPath: "dist/collective.gif",
424
472
  watermark: { text: "Your Product", image: "data:image/png;base64,...", position: "bottom-right" },
425
473
  theme: "dark",
426
474
  scale: 1,
427
475
  })
428
476
  ```
429
477
 
478
+ `createScenes(theme)` and `renderAnimatedGif(AnimatedScene[])` remain supported for intentional scene cuts and pixel crossfades. GIF output uses centisecond timing, at most 256 colors per frame, and one-bit transparency. Use PNG/SVG for smooth alpha edges.
479
+
430
480
  ## Development
431
481
 
432
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.