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 +65 -46
- package/README.md +68 -18
- package/ROADMAP.md +66 -0
- package/dist/cli.js +868 -108
- package/dist/index.cjs +851 -92
- package/dist/index.d.cts +120 -8
- package/dist/index.d.ts +120 -8
- package/dist/index.js +837 -92
- package/examples/README.md +13 -0
- package/examples/_shared/nccl-collective.tsx +420 -0
- package/examples/catalog-charts.tsx +199 -0
- package/examples/catalog-content.tsx +154 -0
- package/examples/catalog-data.tsx +183 -0
- package/examples/catalog-diagrams.tsx +145 -0
- package/examples/catalog-drawing.tsx +106 -0
- package/examples/catalog-flows.tsx +111 -0
- package/examples/catalog-foundations.tsx +123 -0
- package/examples/nccl-all-gather.tsx +14 -0
- package/examples/nccl-all-reduce.tsx +14 -0
- package/examples/nccl-all-to-all.tsx +14 -0
- package/examples/nccl-broadcast.tsx +14 -0
- package/examples/nccl-reduce-scatter.tsx +14 -0
- package/examples/system-architecture.tsx +68 -0
- package/examples/vizmatic-bare.d.ts +2 -0
- package/package.json +7 -5
package/PROMPT.md
CHANGED
|
@@ -173,69 +173,69 @@ export const watermark = (
|
|
|
173
173
|
)
|
|
174
174
|
```
|
|
175
175
|
|
|
176
|
-
Render
|
|
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 `
|
|
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
|
-
|
|
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(
|
|
195
|
+
function buildFrame(theme: ThemeMode, state: State) {
|
|
196
|
+
const c = getThemeColors(theme)
|
|
209
197
|
return (
|
|
210
|
-
<Scene c={c} title="
|
|
211
|
-
<
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
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
|
-
|
|
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
|
|
227
|
-
|
|
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
|
|
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?:
|
|
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
|
|
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"
|
|
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
|
-
- `
|
|
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
|
|
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.
|
|
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
|
|
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 |
|
|
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/
|
|
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
|
-
|
|
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
|
|
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: "
|
|
326
|
-
{ id: "
|
|
327
|
-
{ id: "
|
|
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: "
|
|
331
|
-
{ from: "
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
|
468
|
+
await renderAnimationGif(createAnimation("dark"), {
|
|
421
469
|
width: 1040,
|
|
422
470
|
height: 560,
|
|
423
|
-
outputPath: "dist/
|
|
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.
|