vizmatic 0.3.2 → 0.5.0
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 +75 -525
- package/README.md +87 -578
- package/ROADMAP.md +49 -67
- package/SCIENCE.md +250 -0
- package/assets/THIRD_PARTY_LICENSES.md +40 -1
- package/assets/fonts/InstrumentSerif-Italic.ttf +0 -0
- package/assets/fonts/InstrumentSerif-Regular.ttf +0 -0
- package/assets/licenses/raster-codecs-MIT.txt +74 -0
- package/dist/chunk-3F2VQ7NW.js +1 -0
- package/dist/chunk-4XE64I2U.js +755 -0
- package/dist/chunk-JHHPLALU.js +79 -0
- package/dist/chunk-LTX44BAE.js +112 -0
- package/dist/chunk-MLKGABMK.js +9 -0
- package/dist/chunk-PSBF4TEK.js +1 -0
- package/dist/chunk-RPAHMKAR.js +605 -0
- package/dist/chunk-RWF4VBUL.js +3617 -0
- package/dist/chunk-WHT6HRMX.js +4201 -0
- package/dist/cli.js +371 -10
- package/dist/index.cjs +11129 -2922
- package/dist/index.d.cts +1225 -369
- package/dist/index.d.ts +1225 -369
- package/dist/index.js +6220 -3015
- package/dist/math-LXB4FH4E.js +7 -0
- package/dist/math-QVCETQDQ.js +1 -0
- package/dist/scene-browser-assets.d.ts +38 -0
- package/dist/scene-browser-assets.js +53 -0
- package/dist/scene-browser-chunks/chunk-5MVLYGXM.js +70 -0
- package/dist/scene-browser-chunks/chunk-ASXKN3NU.js +1 -0
- package/dist/scene-browser-chunks/chunk-CM5Y5LZP.js +1 -0
- package/dist/scene-browser-chunks/chunk-DP7NB4EW.js +6 -0
- package/dist/scene-browser-chunks/emscripten-module.browser-M5AEKJGE.js +1 -0
- package/dist/scene-browser-chunks/ffi-FL6ORJU3.js +1 -0
- package/dist/scene-browser-chunks/module-ES6BEMUI-JD5S5VKR.js +1 -0
- package/dist/scene-browser-chunks/module-asyncify-2EFITU5U-HWPFJFJC.js +1 -0
- package/dist/scene-browser-chunks/scene-browser-layout-M3XSXMV4.js +27 -0
- package/dist/scene-browser.d.ts +117 -0
- package/dist/scene-browser.js +220 -0
- package/dist/scene-cli.d.ts +1 -0
- package/dist/scene-cli.js +4 -0
- package/dist/scene-runtime.cjs +995 -0
- package/dist/scene-runtime.d.cts +81 -0
- package/dist/scene-runtime.d.ts +81 -0
- package/dist/scene-runtime.js +22 -0
- package/dist/server-2FYHZ4UO.js +331 -0
- package/dist/stage-browser/browser.d.ts +2482 -0
- package/dist/stage-browser/chunk-SQE76S5B.js +1 -0
- package/dist/stage-browser/chunk-VZNL6JY2.js +59 -0
- package/dist/stage-browser/dagre.esm-N2NIVIAZ.js +6 -0
- package/dist/stage-browser/math-4WFNHVV2.js +18 -0
- package/dist/stage-browser/stage.js +19 -0
- package/dist/stage-export.cjs +4950 -0
- package/dist/stage-export.d.cts +112 -0
- package/dist/stage-export.d.ts +112 -0
- package/dist/stage-export.js +544 -0
- package/dist/stage.cjs +9745 -0
- package/dist/stage.d.cts +1678 -0
- package/dist/stage.d.ts +1678 -0
- package/dist/stage.js +5404 -0
- package/dist/svg-import-Djj2q7Pc.d.cts +742 -0
- package/dist/svg-import-Djj2q7Pc.d.ts +742 -0
- package/dist/video-CcHW1qhV.d.cts +532 -0
- package/dist/video-CcHW1qhV.d.ts +532 -0
- package/examples/README.md +18 -0
- package/examples/agent-pipeline.tsx +4 -4
- package/examples/animated-pipeline.tsx +1 -5
- package/examples/attention-head.tsx +12 -12
- package/examples/aurora-incident.tsx +4 -3
- package/examples/building-blocks.tsx +8 -9
- package/examples/catalog-charts.tsx +4 -4
- package/examples/catalog-content.tsx +7 -9
- package/examples/catalog-convolution-kernel.tsx +116 -0
- package/examples/catalog-data.tsx +2 -8
- package/examples/catalog-dataflow.tsx +5 -9
- package/examples/catalog-dense.tsx +80 -0
- package/examples/catalog-deployment.tsx +5 -11
- package/examples/catalog-diagrams.tsx +13 -16
- package/examples/catalog-drawing.tsx +7 -7
- package/examples/catalog-flows.tsx +4 -4
- package/examples/catalog-foundations.tsx +11 -11
- package/examples/catalog-gaussian-blur.tsx +146 -0
- package/examples/catalog-image-tensors.tsx +115 -0
- package/examples/catalog-ml.tsx +36 -31
- package/examples/catalog-numeric-matrices.tsx +93 -0
- package/examples/catalog-photo-blur.tsx +209 -0
- package/examples/catalog-science-ai.tsx +130 -0
- package/examples/catalog-science-chemistry.tsx +103 -0
- package/examples/catalog-science-math.tsx +93 -0
- package/examples/catalog-science-physics.tsx +84 -0
- package/examples/catalog-sequence.tsx +59 -38
- package/examples/data-pipeline-lineage-presentation.tsx +5 -0
- package/examples/data-pipeline-lineage.tsx +85 -0
- package/examples/daybreak-launch.tsx +1 -0
- package/examples/desired-quadrant.tsx +7 -8
- package/examples/engineering-dashboard-presentation.tsx +13 -0
- package/examples/engineering-dashboard.tsx +160 -0
- package/examples/engineering-flow.tsx +2 -4
- package/examples/eval-dashboard.tsx +6 -6
- package/examples/films/attention.ts +278 -0
- package/examples/films/cache-miss.ts +431 -0
- package/examples/films/catalog.json +132 -0
- package/examples/films/central-limit.ts +269 -0
- package/examples/films/complex-maps.ts +273 -0
- package/examples/films/deck-example.ts +224 -0
- package/examples/films/euler-circle.ts +179 -0
- package/examples/films/fourier-epicycles.ts +265 -0
- package/examples/films/gradient-descent.ts +345 -0
- package/examples/films/linear-maps.ts +175 -0
- package/examples/films/lorenz.ts +207 -0
- package/examples/films/pythagoras.ts +185 -0
- package/examples/films/taylor-series.ts +159 -0
- package/examples/films/vizmatic-title.ts +117 -0
- package/examples/llm-serving-stack-presentation.tsx +5 -0
- package/examples/llm-serving-stack.tsx +94 -0
- package/examples/model-garden.tsx +1 -0
- package/examples/model-router.tsx +6 -6
- package/examples/nccl-all-gather.tsx +3 -3
- package/examples/nccl-all-reduce.tsx +3 -3
- package/examples/nccl-all-to-all.tsx +1 -1
- package/examples/nccl-broadcast.tsx +1 -1
- package/examples/nccl-reduce-scatter.tsx +5 -5
- package/examples/orthogonal-routing.tsx +4 -4
- package/examples/pareto-frontier.tsx +9 -10
- package/examples/presentation-frame.tsx +6 -6
- package/examples/pressure-mechanism.scene.json +14 -0
- package/examples/production-system-map-presentation.tsx +5 -0
- package/examples/production-system-map.tsx +130 -0
- package/examples/rag-graph.tsx +7 -7
- package/examples/release-card.tsx +5 -5
- package/examples/spec-anatomy.tsx +5 -5
- package/examples/system-architecture.tsx +19 -32
- package/examples/theme-system.tsx +1 -1
- package/examples/token-matrix.tsx +4 -2
- package/examples/transparent-badge.tsx +1 -2
- package/examples/videos/README.md +62 -0
- package/examples/videos/calculus-tangent.tsx +101 -0
- package/examples/videos/catalyst-pathway.tsx +56 -0
- package/examples/videos/causal-attention.tsx +91 -0
- package/examples/videos/convolution-kernel.tsx +34 -0
- package/examples/videos/gaussian-blur.tsx +32 -0
- package/examples/videos/image-to-matrix.tsx +22 -0
- package/examples/videos/matrix-multiplication.tsx +128 -0
- package/examples/videos/photo-gaussian-blur.tsx +39 -0
- package/examples/videos/request-lifecycle.tsx +99 -0
- package/examples/videos/signal-to-story.tsx +126 -0
- package/examples/videos/wave-interference.tsx +80 -0
- package/examples/vizmatic-bare.d.ts +1 -0
- package/examples/vizmatic-hero.tsx +9 -18
- package/examples/website-workflow.tsx +7 -7
- package/examples/weekend-field-notes.tsx +3 -2
- package/package.json +77 -12
package/README.md
CHANGED
|
@@ -1,641 +1,150 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="https://bvolpato.github.io/vizmatic/assets/logo.svg" alt="Vizmatic
|
|
2
|
+
<a href="https://bvolpato.github.io/vizmatic/"><img src="https://bvolpato.github.io/vizmatic/assets/logo.svg" alt="Vizmatic" width="360" /></a>
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
<strong>
|
|
7
|
-
|
|
6
|
+
<strong>Explain things in motion, from code.</strong><br/>
|
|
7
|
+
Vector films that play live in a browser and export frame-exact to MP4. Dense technical figures from TSX.
|
|
8
8
|
</p>
|
|
9
9
|
|
|
10
10
|
<p align="center">
|
|
11
11
|
<a href="https://github.com/bvolpato/vizmatic/actions/workflows/ci.yml"><img src="https://github.com/bvolpato/vizmatic/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
|
|
12
|
-
<a href="https://github.com/bvolpato/vizmatic/actions/workflows/pages.yml"><img src="https://github.com/bvolpato/vizmatic/actions/workflows/pages.yml/badge.svg" alt="Pages" /></a>
|
|
13
|
-
<a href="https://github.com/bvolpato/vizmatic/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
|
|
14
12
|
<a href="https://www.npmjs.com/package/vizmatic"><img src="https://img.shields.io/npm/v/vizmatic?color=%2334d058" alt="npm version" /></a>
|
|
13
|
+
<a href="https://github.com/bvolpato/vizmatic/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
|
|
15
14
|
</p>
|
|
16
15
|
|
|
17
16
|
<p align="center">
|
|
18
|
-
<img src="https://bvolpato.github.io/vizmatic/assets/
|
|
17
|
+
<a href="https://bvolpato.github.io/vizmatic/films.html"><img src="https://bvolpato.github.io/vizmatic/assets/films/fourier-epicycles.png" alt="A still from a Vizmatic film: rotating circles trace a curve" width="820" /></a>
|
|
19
18
|
</p>
|
|
20
19
|
|
|
21
20
|
<p align="center">
|
|
22
|
-
<a href="https://bvolpato.github.io/vizmatic/">
|
|
23
|
-
<a href="https://bvolpato.github.io/vizmatic/
|
|
21
|
+
<a href="https://bvolpato.github.io/vizmatic/films.html">Films</a> ·
|
|
22
|
+
<a href="https://bvolpato.github.io/vizmatic/docs/">Docs</a> ·
|
|
23
|
+
<a href="https://bvolpato.github.io/vizmatic/studio.html">Studio</a> ·
|
|
24
24
|
<a href="https://bvolpato.github.io/vizmatic/components.html">Components</a> ·
|
|
25
|
-
<a href="https://bvolpato.github.io/vizmatic/agents.html">For agents</a>
|
|
26
|
-
<a href="examples">Examples</a> ·
|
|
27
|
-
<a href="PROMPT.md">Agent Prompt</a> ·
|
|
28
|
-
<a href="#api">API</a>
|
|
25
|
+
<a href="https://bvolpato.github.io/vizmatic/agents.html">For agents</a>
|
|
29
26
|
</p>
|
|
30
27
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
## Quick start
|
|
28
|
+
## A film in 15 lines
|
|
34
29
|
|
|
35
|
-
Vizmatic
|
|
30
|
+
Vizmatic needs Node.js 20 or newer. MP4 export also needs [FFmpeg](https://ffmpeg.org/download.html).
|
|
36
31
|
|
|
37
32
|
```bash
|
|
38
|
-
npm install
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
Create `frame.tsx`:
|
|
42
|
-
|
|
43
|
-
```tsx
|
|
44
|
-
<Scene title="Agent visual pipeline">
|
|
45
|
-
<Flow
|
|
46
|
-
stages={[
|
|
47
|
-
{ title: "Prompt", subtitle: "intent", tone: "blue" },
|
|
48
|
-
{ title: "Scene spec", subtitle: "typed structure", tone: "purple" },
|
|
49
|
-
{ title: "PNG / SVG / GIF", subtitle: "files", tone: "green" },
|
|
50
|
-
]}
|
|
51
|
-
/>
|
|
52
|
-
</Scene>
|
|
33
|
+
npm install vizmatic
|
|
53
34
|
```
|
|
54
35
|
|
|
55
|
-
`
|
|
56
|
-
|
|
57
|
-
Render it directly:
|
|
58
|
-
|
|
59
|
-
```bash
|
|
60
|
-
vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
Check both themes before publishing. `--json` reports overflow, contrast, small text, overlapping labels, uneven panel whitespace, connector congestion, asset failures, and suggested dimensions:
|
|
64
|
-
|
|
65
|
-
```bash
|
|
66
|
-
vizmatic check ./frame.tsx --theme dark,light --json
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
PNG and SVG renders have transparent backgrounds by default. Add `--background theme` for an opaque dark or light canvas:
|
|
70
|
-
|
|
71
|
-
```bash
|
|
72
|
-
vizmatic ./frame.tsx --out ./dist/frames --theme dark,light --background theme
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
CSS alpha colors stay semi-transparent in PNG and SVG output. Set the canvas background in the frame or pass a quoted CSS color to `--background`:
|
|
76
|
-
|
|
77
|
-
```tsx
|
|
78
|
-
<Scene background="rgba(15, 23, 42, 0.5)">
|
|
79
|
-
<CalloutCard title="Alpha background" detail="The host page remains visible through the canvas." />
|
|
80
|
-
</Scene>
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
vizmatic ./frame.tsx --background 'rgba(15, 23, 42, 0.5)'
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
When a frame omits `width` or `height`, Vizmatic starts at `960x540` and grows that axis if content overflows. Set `autoSize = false` when dimensions must remain fixed and clipping should fail the render.
|
|
88
|
-
|
|
89
|
-
Bare CLI frames do not need imports. Use a regular module when a frame needs helper code, data loading, other dependencies, animation, or direct renderer APIs.
|
|
90
|
-
|
|
91
|
-
Add Vizmatic to a project for scripts, editor types, or direct renderer APIs:
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
pnpm add vizmatic react
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
To use the current GitHub version:
|
|
98
|
-
|
|
99
|
-
```bash
|
|
100
|
-
pnpm add github:bvolpato/vizmatic react
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
## Agent skill
|
|
104
|
-
|
|
105
|
-
Install the Vizmatic skill for Codex, Claude Code, Cursor, OpenCode, or another compatible agent:
|
|
106
|
-
|
|
107
|
-
```bash
|
|
108
|
-
npx skills add bvolpato/vizmatic --skill vizmatic -g -y
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
Choose agents explicitly when needed:
|
|
112
|
-
|
|
113
|
-
```bash
|
|
114
|
-
npx skills add bvolpato/vizmatic --skill vizmatic -g -a codex -a claude-code -a cursor -a opencode -y
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
Example prompts:
|
|
118
|
-
|
|
119
|
-
```text
|
|
120
|
-
Use the Vizmatic skill to create a theme-aware architecture diagram and render dark/light PNG files.
|
|
121
|
-
Use the Vizmatic skill to turn this release workflow into an animated GIF for docs.
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
Skill source lives in [`.agents/skills/vizmatic`](.agents/skills/vizmatic). Review it before installing with `npx skills add bvolpato/vizmatic --list`.
|
|
125
|
-
|
|
126
|
-
The [agent guide](https://bvolpato.github.io/vizmatic/agents.html) explains installation and the check/render workflow. Agents can discover instructions through [llms.txt](https://bvolpato.github.io/vizmatic/llms.txt), load the [full context bundle](https://bvolpato.github.io/vizmatic/llms-full.txt), or read [runnable component examples as JSON](https://bvolpato.github.io/vizmatic/components.json).
|
|
127
|
-
|
|
128
|
-
Codex and Claude Code can also install Vizmatic as a plugin:
|
|
129
|
-
|
|
130
|
-
```bash
|
|
131
|
-
codex plugin marketplace add bvolpato/vizmatic --ref main
|
|
132
|
-
codex plugin add vizmatic@vizmatic
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
```bash
|
|
136
|
-
claude plugin marketplace add bvolpato/vizmatic
|
|
137
|
-
claude plugin install vizmatic@vizmatic --scope user
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
## Rendering options
|
|
141
|
-
|
|
142
|
-
Add a text or image watermark when output needs branding:
|
|
143
|
-
|
|
144
|
-
```bash
|
|
145
|
-
vizmatic ./frame.tsx --out ./dist/frames --theme dark,light --watermark "Acme" --watermark-image ./logo.svg
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
Each output directory includes `manifest.json`. `outputs` lists generated files, and `outputDetails` records theme, path, and pixel dimensions.
|
|
149
|
-
|
|
150
|
-
Static CLI renders default to PNG. Use `--format svg` for vector output or `--format both` to export PNG and SVG together. Each manifest output detail includes its `format`; both formats support themes, backgrounds, watermarks, cropping, and automatic canvas growth.
|
|
151
|
-
|
|
152
|
-
```bash
|
|
153
|
-
vizmatic ./frame.tsx --out ./visuals --theme dark,light --format both
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
Render an animation:
|
|
157
|
-
|
|
158
|
-
```bash
|
|
159
|
-
vizmatic gif ./animated-frame.tsx --out ./dist/frames --theme dark,light --fps 20 --watermark "Acme" --watermark-image ./logo.svg
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Or call the renderer directly:
|
|
36
|
+
Create `intro.ts`:
|
|
163
37
|
|
|
164
38
|
```ts
|
|
165
|
-
import {
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
watermark: { text: "Acme", image: "data:image/svg+xml;base64,...", position: "top-right" },
|
|
39
|
+
import { axes, draw, fadeIn, film, tex, write } from 'vizmatic/stage'
|
|
40
|
+
|
|
41
|
+
export default film({ title: 'My first film' }, (s) => {
|
|
42
|
+
const plot = s.add(axes({ x: [-3, 3], y: [-1, 9], grid: true }).at(-240, 40))
|
|
43
|
+
s.play(draw(plot.grid, { lag: 0.02 }), draw(plot.lines), fadeIn(plot.numbers))
|
|
44
|
+
s.play(draw(plot.plot((x) => x * x, { stroke: 'blue', width: 5 })))
|
|
45
|
+
s.play(write(s.add(tex('y = x^2', { size: 72 }).at(600, -200))))
|
|
46
|
+
s.wait(1)
|
|
174
47
|
})
|
|
175
48
|
```
|
|
176
49
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
```tsx
|
|
180
|
-
import { Watermark } from "vizmatic"
|
|
181
|
-
|
|
182
|
-
export const watermark = (
|
|
183
|
-
<Watermark position="bottom-right" opacity={0.82}>
|
|
184
|
-
<div style={{ display: "flex", alignItems: "center", gap: 6, color: "#7c3aed", fontWeight: 800 }}>
|
|
185
|
-
<img src="data:image/svg+xml;base64,..." width={14} height={14} />
|
|
186
|
-
Acme
|
|
187
|
-
</div>
|
|
188
|
-
</Watermark>
|
|
189
|
-
)
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
## What Vizmatic handles
|
|
193
|
-
|
|
194
|
-
Coding agents can write a small component tree more reliably than raw SVG paths and hand-tuned coordinates.
|
|
195
|
-
|
|
196
|
-
Vizmatic provides reusable layout, diagram, and chart primitives:
|
|
197
|
-
|
|
198
|
-
| Need | Vizmatic answer |
|
|
199
|
-
|---|---|
|
|
200
|
-
| More than flowcharts | Charts, cards, matrices, timelines, trees, icons, and custom composition |
|
|
201
|
-
| Editable output | Source-controlled TSX stays inspectable and renders consistently |
|
|
202
|
-
| Headless rendering | Node produces assets directly in local workflows and CI |
|
|
203
|
-
| Theme variants | One command renders dark and light output from semantic color tokens |
|
|
204
|
-
| Layout checks | Overflow, contrast, small text, label overlap, uneven panel whitespace, and connector congestion |
|
|
205
|
-
| Animation | Typed state timelines, tweens, easing, holds, keyframes, and parallel tracks export as GIFs |
|
|
206
|
-
|
|
207
|
-
## Gallery
|
|
208
|
-
|
|
209
|
-
<p>
|
|
210
|
-
<img src="https://bvolpato.github.io/vizmatic/assets/examples/animated-pipeline_dark.gif" alt="Animated pipeline" width="380" />
|
|
211
|
-
<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" />
|
|
212
|
-
<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" />
|
|
213
|
-
</p>
|
|
214
|
-
<p>
|
|
215
|
-
<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" />
|
|
216
|
-
<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" />
|
|
217
|
-
<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" />
|
|
218
|
-
</p>
|
|
219
|
-
<p>
|
|
220
|
-
<picture><source media="(prefers-color-scheme: dark)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/rag-graph_dark.png" /><source media="(prefers-color-scheme: light)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/rag-graph_light.png" /><img src="https://bvolpato.github.io/vizmatic/assets/examples/rag-graph_light.png" alt="RAG graph" width="380" /></picture>
|
|
221
|
-
<picture><source media="(prefers-color-scheme: dark)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/eval-dashboard_dark.png" /><source media="(prefers-color-scheme: light)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/eval-dashboard_light.png" /><img src="https://bvolpato.github.io/vizmatic/assets/examples/eval-dashboard_light.png" alt="Evaluation dashboard" width="380" /></picture>
|
|
222
|
-
</p>
|
|
223
|
-
<p>
|
|
224
|
-
<picture><source media="(prefers-color-scheme: dark)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/token-matrix_dark.png" /><source media="(prefers-color-scheme: light)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/token-matrix_light.png" /><img src="https://bvolpato.github.io/vizmatic/assets/examples/token-matrix_light.png" alt="Token matrix" width="380" /></picture>
|
|
225
|
-
<picture><source media="(prefers-color-scheme: dark)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/theme-system_dark.png" /><source media="(prefers-color-scheme: light)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/theme-system_light.png" /><img src="https://bvolpato.github.io/vizmatic/assets/examples/theme-system_light.png" alt="Theme system" width="380" /></picture>
|
|
226
|
-
</p>
|
|
227
|
-
<p>
|
|
228
|
-
<picture><source media="(prefers-color-scheme: dark)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/system-architecture_dark.png" /><source media="(prefers-color-scheme: light)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/system-architecture_light.png" /><img src="https://bvolpato.github.io/vizmatic/assets/examples/system-architecture_light.png" alt="System architecture" width="380" /></picture>
|
|
229
|
-
<picture><source media="(prefers-color-scheme: dark)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/presentation-frame_dark.png" /><source media="(prefers-color-scheme: light)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/presentation-frame_light.png" /><img src="https://bvolpato.github.io/vizmatic/assets/examples/presentation-frame_light.png" alt="Presentation frame" width="380" /></picture>
|
|
230
|
-
</p>
|
|
231
|
-
|
|
232
|
-
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.
|
|
233
|
-
|
|
234
|
-
More examples live in [`examples/`](examples). Browse the searchable [component catalog on the homepage](https://bvolpato.github.io/vizmatic/#component-browser), copy a focused example, or open it in the playground to edit and render both themes. The [full catalog](https://bvolpato.github.io/vizmatic/components.html) also includes category previews and source. [`PROMPT.md`](PROMPT.md) contains the full install, syntax, component, and verification reference for coding agents. [`ROADMAP.md`](ROADMAP.md) tracks the next C4, provider pack, UML, layout, and interoperability capabilities.
|
|
235
|
-
|
|
236
|
-
## Repository checks
|
|
237
|
-
|
|
238
|
-
Generated examples and website files are committed. CI fails when a build changes them without a matching source update.
|
|
239
|
-
|
|
240
|
-
| Gate | What it protects |
|
|
241
|
-
|---|---|
|
|
242
|
-
| `pnpm lint` | TypeScript coverage plus GitHub Actions validation with actionlint |
|
|
243
|
-
| `pnpm test` | Render pipeline behavior, watermark options, and output validation |
|
|
244
|
-
| `pnpm render:examples` | Dark/light PNGs, animated GIFs, source snippets, and website HTML |
|
|
245
|
-
| `pnpm check:examples` | Every example renders in both themes without errors or visual warnings |
|
|
246
|
-
| `pnpm docs:check` | Local asset references, `PROMPT.md` sync, source modal themes, and homepage affordances |
|
|
247
|
-
| `pnpm deps:check` | npm audit plus package tarball contents, size, and file-count budgets before release |
|
|
248
|
-
| `./test.sh` drift check | Confirms render and docs commands leave no uncommitted output |
|
|
249
|
-
|
|
250
|
-
Run the full local gate:
|
|
50
|
+
Then watch it, check it, and export it:
|
|
251
51
|
|
|
252
52
|
```bash
|
|
253
|
-
|
|
53
|
+
npx vizmatic preview intro.ts # live player with a timeline. Reloads when you save.
|
|
54
|
+
npx vizmatic check intro.ts # finds clipped text, overlaps, and strokes through labels
|
|
55
|
+
npx vizmatic film intro.ts --out dist # 1080p60 MP4
|
|
254
56
|
```
|
|
255
57
|
|
|
256
|
-
|
|
58
|
+
`npx vizmatic new intro --template architecture` starts from a working film. The templates are `explainer`, `equation`, `architecture`, `chart`, and `deck`.
|
|
257
59
|
|
|
258
|
-
|
|
60
|
+
## What makes it different
|
|
259
61
|
|
|
260
|
-
|
|
62
|
+
**Everything on stage is real geometry.** Lines, glyphs, equations, and grids are all Bezier paths. Any shape can trace itself, morph into any other shape, or bend through a function. Equations use TeX glyphs, and `morphMatching` moves the shared terms from one line of a derivation to the next.
|
|
261
63
|
|
|
262
|
-
|
|
64
|
+
**A film is a pure function of time.** The build function runs once and writes a timeline. Any frame can then be sampled at any time, in any order. Scrubbing is instant, and identical input gives identical frames.
|
|
263
65
|
|
|
264
|
-
|
|
66
|
+
**One film, two destinations.** The same source paints live on a canvas with `<vz-film>`, and renders to MP4, WebM, GIF, PNG, or SVG in Node. Frames rasterize on worker threads, with real motion blur and bloom when you ask for them.
|
|
265
67
|
|
|
266
|
-
|
|
68
|
+
**It looks right by default.** Five looks set the background, ink, pigments, and light. Authors write `color: 'yellow'`, so one film renders in `midnight`, `paper`, `blueprint`, `chalk`, and `neon`.
|
|
267
69
|
|
|
268
|
-
|
|
269
|
-
import { getThemeColors, getToneFill } from "vizmatic"
|
|
70
|
+
**Figures pack information.** The TSX components default to the `dense` density: small type, hairlines, and tight gutters, like a figure in a good engineering paper. Set `density="presentation"` to use the same source on a slide.
|
|
270
71
|
|
|
271
|
-
|
|
272
|
-
const light = getThemeColors("light")
|
|
273
|
-
const engineering = getThemeColors("light", "engineering")
|
|
274
|
-
const engineeringNodeFill = getToneFill("purple", engineering)
|
|
275
|
-
```
|
|
72
|
+
**Defects come back as data.** `vizmatic check --json` reports problems with their times and bounding boxes, so a coding agent can find and fix them without watching anything.
|
|
276
73
|
|
|
277
|
-
|
|
74
|
+
## Figures
|
|
278
75
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
### Component catalog
|
|
282
|
-
|
|
283
|
-
Use these primitives before writing raw SVG or absolute-positioned layouts.
|
|
284
|
-
|
|
285
|
-
#### Frame and layout
|
|
286
|
-
|
|
287
|
-
| Component | Use |
|
|
288
|
-
|---|---|
|
|
289
|
-
| `defineIllustration` | Wraps a theme-aware frame builder and exports `create(theme)` plus a default element. |
|
|
290
|
-
| `Canvas` | Low-level full-frame root with alpha-transparent default background, optional background fill, padding, and vertical alignment. |
|
|
291
|
-
| `Board` | Fixed canvas for freely positioned components, with explicit dimensions and an optional background. |
|
|
292
|
-
| `CanvasItem` | Positions and sizes a component at logical-pixel `x` / `y` coordinates. Charts fit their complete plotting layers, labels, and frame inside the item. |
|
|
293
|
-
| `Scene` | Standard frame wrapper with optional title/subtitle, content column, and theme-aware typography. |
|
|
294
|
-
| `TitleBar` | Shared title/subtitle block used by `Scene`. |
|
|
295
|
-
| `Row` / `Column` | Flex layout primitives with gap, alignment, wrapping, width, and height props. |
|
|
296
|
-
| `Stack` | Layered vertical stack for repeated cards, tokens, or processing layers. |
|
|
297
|
-
|
|
298
|
-
Use `Board` with `CanvasItem` for layouts that people can move and resize in the browser builder. Coordinates and sizes remain in the TSX source. Set the frame dimensions to match the board; the board clips content outside its bounds. With both item dimensions set, chart primitives scale proportionally to fit the complete chart, including wrapped headings, legends, and footers.
|
|
76
|
+
Render a TSX figure in each theme:
|
|
299
77
|
|
|
300
78
|
```tsx
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
{ label: "Successful", value: 82, color: "positive" },
|
|
311
|
-
{ label: "Retried", value: 18, color: "warning" },
|
|
312
|
-
]} />
|
|
313
|
-
</CanvasItem>
|
|
314
|
-
</Board>
|
|
315
|
-
```
|
|
316
|
-
|
|
317
|
-
#### Surfaces, labels, and cards
|
|
318
|
-
|
|
319
|
-
| Component | Use |
|
|
320
|
-
|---|---|
|
|
321
|
-
| `Panel` | Titled card surface with tone strip, subtitle, footer, shadow, and body controls. |
|
|
322
|
-
| `Card` | Flexible surface for custom content without a forced title. |
|
|
323
|
-
| `StepCard` | Compact stage card for flows, choices, and process steps. |
|
|
324
|
-
| `MetricCard` | KPI/value card with label, value, detail, tone, and monospace value support. |
|
|
325
|
-
| `CalloutCard` | Highlight block for takeaways, warnings, decisions, and summaries. |
|
|
326
|
-
| `WindowFrame` | Browser/terminal-style framed panel for code, UI, or tool output. |
|
|
327
|
-
| `Box` | Gradient or outlined labeled rectangle with optional icon and sublabel. |
|
|
328
|
-
| `Tile` / `TileGrid` | Uniform repeated tiles with tone, title, detail, and metric layouts. |
|
|
329
|
-
| `Badge` / `BadgePill` | Small labels for status, categories, and annotations. |
|
|
330
|
-
| `ValuePill` | Compact value badge for numbers or short state labels. |
|
|
331
|
-
| `GradientChip` | Small colored chip with gradient fill for legends and tone keys. |
|
|
332
|
-
| `ToneStrip` | Small semantic accent strip for visual grouping. |
|
|
333
|
-
| `Icon` | Curated SVG icon set for cards, callouts, compact rows, and presentation frames. |
|
|
334
|
-
| `TextLabel` | Wrapping-safe text with variant, color, math formatting, width, and alignment. |
|
|
335
|
-
| `MathText` / `formatMathText` | Converts simple `x_i` / `x^2` style strings into readable unicode math text. |
|
|
336
|
-
| `SvgMathText` | Positioned HTML overlay for math labels aligned to custom plot coordinates. Place it beside, not inside, raw SVG geometry in a relative container. |
|
|
337
|
-
|
|
338
|
-
#### Arrows, connectors, and SVG helpers
|
|
339
|
-
|
|
340
|
-
| Component | Use |
|
|
341
|
-
|---|---|
|
|
342
|
-
| `Arrow` | Simple directional arrow element. |
|
|
343
|
-
| `FlowArrow` / `Connector` | Theme-aware connector between flow stages. |
|
|
344
|
-
| `VectorArrow` | SVG vector arrow for coordinate-style diagrams. |
|
|
345
|
-
| `VectorSegment` | Labeled segment/vector primitive for geometry and embedding visuals. |
|
|
346
|
-
| `SvgFrame` | SVG container with theme-aware background and border. |
|
|
347
|
-
| `SvgPoint` / `DotPoint` | Point markers with optional labels. |
|
|
348
|
-
| `ArrowMarkerDef` | SVG arrowhead marker definition for custom line charts and graph edges. |
|
|
349
|
-
| `DashedLine` | Dotted/dashed SVG line helper. |
|
|
350
|
-
| `Legend` | Reusable legend block with colored items and optional title. |
|
|
351
|
-
|
|
352
|
-
#### Lists, comparisons, and status blocks
|
|
353
|
-
|
|
354
|
-
| Component | Use |
|
|
355
|
-
|---|---|
|
|
356
|
-
| `DetailList` | Compact repeated detail rows inside panels and flow stages. |
|
|
357
|
-
| `ProgressRow` / `ProgressList` | Progress bars with labels, values, tones, and optional math text. |
|
|
358
|
-
| `StatusRow` / `StatusList` | Check, cross, warning, info, pending, and dot rows. |
|
|
359
|
-
| `Timeline` | Vertical or horizontal milestone list with tone markers, time labels, and compact event cards. |
|
|
360
|
-
| `KeyValueList` | Structured label/value rows for configs and metadata. |
|
|
361
|
-
| `CodeBlock` | Themed code panel with highlighted lines and optional annotations. |
|
|
362
|
-
| `EquationCard` | Formula card with title, equation, and supporting detail. |
|
|
363
|
-
| `Comparison` | Side-by-side comparison panel with two titled sides and detail rows. |
|
|
364
|
-
|
|
365
|
-
#### Flows, pipelines, and graph diagrams
|
|
366
|
-
|
|
367
|
-
| Component | Use |
|
|
368
|
-
|---|---|
|
|
369
|
-
| `Flow` | Horizontal or vertical staged process diagram with optional detail rows. |
|
|
370
|
-
| `Pipeline` | Process pipeline with stage labels and a shared title. |
|
|
371
|
-
| `LayeredNetwork` | Neural-network/DAG diagram with layers, nodes, active path, annotations, and formula. |
|
|
372
|
-
| `GraphDiagram` | Auto-laid architecture graph with nested boundaries, technical icons, typed relationships, and custom icon definitions. |
|
|
373
|
-
| `TreeDiagram` | Auto-laid parent/child hierarchy for ownership, routing, taxonomy, and decision trees. |
|
|
374
|
-
| `SequenceDiagram` | Participants, lifelines, activations, notes, sync/async/return messages, and control fragments. |
|
|
375
|
-
| `DataflowDiagram` | Schema-aware source, transform, store, and sink lineage with batch or streaming edges. |
|
|
376
|
-
| `DeploymentDiagram` | Nested infrastructure boundaries with workload kinds, ports, protocols, and trust direction. |
|
|
377
|
-
| `TransformerTopology` | Transformer blocks, tensor shapes, repeated layers, residual paths, caches, experts, and collectives. |
|
|
378
|
-
|
|
379
|
-
`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:
|
|
380
|
-
|
|
381
|
-
```tsx
|
|
382
|
-
<GraphDiagram
|
|
383
|
-
ariaLabel="Checkout architecture"
|
|
384
|
-
groups={[
|
|
385
|
-
{ id: "prod", label: "Production", tone: "blue" },
|
|
386
|
-
{ id: "data", label: "Data", parent: "prod", tone: "green" },
|
|
387
|
-
]}
|
|
388
|
-
nodes={[
|
|
389
|
-
{ id: "client", label: "Client", icon: "browser", tone: "cyan" },
|
|
390
|
-
{ id: "api", label: "API", icon: "server", group: "prod", tone: "purple" },
|
|
391
|
-
{ id: "db", label: "Postgres", icon: "database", group: "data", tone: "green" },
|
|
392
|
-
]}
|
|
393
|
-
edges={[
|
|
394
|
-
{ from: "client", to: "api", label: "HTTPS", kind: "sync" },
|
|
395
|
-
{ from: "api", to: "db", label: "SQL", kind: "data", arrow: "both" },
|
|
396
|
-
]}
|
|
397
|
-
/>
|
|
398
|
-
```
|
|
399
|
-
|
|
400
|
-
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.
|
|
401
|
-
|
|
402
|
-
Set `id`, `title`, and `description` for accessible SVG exports. Nodes and edges accept safe `href` links and tooltip `title` text. These semantics are included by `renderToSvg` and the playground SVG download; see the [SVG accessibility guide](docs/accessibility.md) for supported links and stable ID behavior.
|
|
403
|
-
|
|
404
|
-
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.
|
|
405
|
-
|
|
406
|
-
Connector routing is separate from node layout. The default `routing="dagre"` preserves existing geometry. Choose `routing="straight"` for direct connectors or `routing="orthogonal"` for right-angle routes that avoid node boxes and group headers. `routingClearance` defaults to 12 logical pixels; `edgeGap` separates parallel traffic. Orthogonal routing supports automatic and manual node positions, self-loops with distinct anchors, and separated parallel routes.
|
|
407
|
-
|
|
408
|
-
Declare node `ports` as `{ id, side, offset? }`, then reference them with edge `fromPort` / `toPort`. Sides are `top`, `right`, `bottom`, or `left`; offsets run from 0 to 1 along the side and default to 0.5. An edge can instead specify `fromSide` / `toSide`. Use either a port reference or a side for each endpoint. Explicit anchors also opt an edge into orthogonal geometry when the routing mode is Dagre. With explicit straight or orthogonal routing, `DeploymentDiagram` anchors declared port references and accepts port `side` / `offset` overrides.
|
|
409
|
-
|
|
410
|
-
Routing runs synchronously offline with limits of 64 node/header obstacles and 256 edges, plus bounded grid and search work. A blocked route, repeated route with no separate lane, or exhausted limit omits the affected connector and makes the checker report `layout.connector_unroutable` as an error. Increase spacing or canvas size, change anchors, or reduce clearance before publishing. Missing port references fail validation. See the [routed graph example](examples/orthogonal-routing.tsx).
|
|
411
|
-
|
|
412
|
-
The [import guide](docs/import.md) documents the supported Mermaid and D2 subsets and their structured source diagnostics.
|
|
413
|
-
|
|
414
|
-
#### Matrices, tables, and grids
|
|
415
|
-
|
|
416
|
-
| Component | Use |
|
|
417
|
-
|---|---|
|
|
418
|
-
| `Matrix` | Numeric matrix visualization for linear algebra and attention examples. |
|
|
419
|
-
| `Heatmap` | Color-scaled matrix/attention heatmap. |
|
|
420
|
-
| `TiledMatrix` | Matrix with region labels and grouped tiles. |
|
|
421
|
-
| `DataTable` | Compact text table with header rows/columns and monospace cells. |
|
|
422
|
-
| `Grid` | General-purpose cell grid with per-cell label, tone, color, border, and opacity. |
|
|
423
|
-
|
|
424
|
-
#### Charts and plots
|
|
425
|
-
|
|
426
|
-
| Component | Use |
|
|
427
|
-
|---|---|
|
|
428
|
-
| `ChartFrame` | Shared chart wrapper with title, subtitle, footer, and theme-aware shell. |
|
|
429
|
-
| `AxisPlot` | Low-level axis plot for custom lines, paths, and plotted values. |
|
|
430
|
-
| `PieChart` | Full-circle part-to-whole chart with segment values, percentages, and a legend. |
|
|
431
|
-
| `DonutChart` | Part-to-whole chart with center label/value, segment labels, and shared chart styling. |
|
|
432
|
-
| `MiniBarChart` | Small bar chart for cards and dashboards. |
|
|
433
|
-
| `StackedBar` | Segmented horizontal bar with labels and percentages. |
|
|
434
|
-
| `BarChart` | Full bar chart with ticks, labels, values, grids, and formats. |
|
|
435
|
-
| `LineChart` | Multi-series line chart with optional area fill, points, labels, and grid. |
|
|
436
|
-
| `ScatterPlot` | Labeled scatter plot with axes, ticks, point sizing, and collision-aware labels. |
|
|
437
|
-
| `ParetoBarChart` | Categories sorted by descending count with a cumulative percentage line and separate count/share axes. |
|
|
438
|
-
| `ParetoChart` | Automatic non-dominated frontier for competing objectives, including log-scaled cost axes. |
|
|
439
|
-
| `QuadrantChart` | 2x2 decision matrix with numeric axes, configurable thresholds, labeled points, and optional region emphasis. |
|
|
440
|
-
| `IntervalPlot` | Timeline/range plot for spans, phases, latencies, and schedules. |
|
|
441
|
-
|
|
442
|
-
Use `PieChart` for category shares, `BarChart` for category values, `ScatterPlot` for paired numeric observations, and `ParetoBarChart` to identify the categories behind most of a total. Pie and Pareto bar values must be finite and non-negative; zero-valued pie slices are omitted. Pareto bars sort descending without changing the input array and preserve input order for equal values. The cumulative line reaches 100% when the total is positive. See the [pie](examples/pie-chart.tsx) and [Pareto bar](examples/pareto-bar-chart.tsx) examples.
|
|
443
|
-
|
|
444
|
-
`ParetoChart` shows a non-dominated scatter frontier for competing objectives. It defaults to minimizing x and maximizing y, which fits cost-versus-score comparisons. Set `xObjective` or `yObjective` for other tradeoffs. Non-positive x values are omitted on a logarithmic x-axis. `QuadrantChart` accepts raw numeric domains, threshold values, tick formats, and optional grid lines; omit them to keep normalized 0-1 coordinates and centered splits. Regions accept `emphasis: true` to give one decision region a stronger fill and border.
|
|
445
|
-
|
|
446
|
-
#### Rendering and verification
|
|
447
|
-
|
|
448
|
-
| API | Use |
|
|
449
|
-
|---|---|
|
|
450
|
-
| `checkFrame` | Check a React scene or themed frame and return typed diagnostics with configurable severity-based pass/fail. |
|
|
451
|
-
| `renderToPng` | Render React scene to PNG through Satori and resvg, with optional watermark, crop, scale, and overflow check. |
|
|
452
|
-
| `renderToPngWithOutput` | Render PNG and return logical dimensions, physical pixel dimensions, and painted `contentBounds`. |
|
|
453
|
-
| `CanvasOverflowError` | Typed clipping failure with canvas dimensions and per-edge overflow details. |
|
|
454
|
-
| `renderAnimatedGif` | Render ordered `AnimatedScene[]` states to GIF with `fade`, `appear`, or no transition. |
|
|
455
|
-
| `renderAnimatedGifWithOutput` | Render GIF and return dimensions, timing, encoded-frame, delta-frame, and byte metrics. |
|
|
456
|
-
| `defineAnimation` | Define a typed state timeline rendered at deterministic sample times. |
|
|
457
|
-
| `hold`, `tween`, `keyframe`, `parallel` | Compose sequential pauses, eased property transitions, instant state changes, and staggered concurrent tracks. |
|
|
458
|
-
| `sampleAnimation` | Evaluate timeline state at an exact millisecond without rendering. |
|
|
459
|
-
| `analyzeAnimationCadence` | Inspect sampled frame count, target interval, encoded duration, and delay range. |
|
|
460
|
-
| `renderAnimationGif` | Stream sampled timeline frames into a GIF without retaining every RGBA frame. |
|
|
461
|
-
| `renderToBuffer` | Render PNG to memory for tests and pipelines. |
|
|
462
|
-
| `renderToSvg` | Render SVG markup directly. |
|
|
463
|
-
| `Watermark` | JSX marker component for expressive frame-module watermarks. |
|
|
464
|
-
| `wrapWithWatermark` | Add optional watermark text, image/icon, custom element, and position to a frame. |
|
|
465
|
-
| `normalizeWatermark` | Normalize boolean, string, object, or React-element watermark input to `WatermarkOptions`. |
|
|
466
|
-
| `wrapWithBrand` | Compatibility wrapper for adding a text watermark through `wrapWithWatermark`. |
|
|
467
|
-
| `getFonts` | Load and cache bundled Satori font data for advanced renderer integrations. |
|
|
468
|
-
| `loadAdditionalAsset` | Resolve Satori missing-glyph requests, including bundled or cached Twemoji assets. |
|
|
469
|
-
| `detectBackgroundColor` | Find dominant transparent/background color for cropping. |
|
|
470
|
-
| `detectContentBounds` | Compute non-background bounds for autocrop. |
|
|
471
|
-
| `cropPixels` | Crop raw pixel buffers. |
|
|
472
|
-
| `detectOverflow` | Fail frames that clip content at canvas edges. |
|
|
473
|
-
|
|
474
|
-
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.
|
|
475
|
-
|
|
476
|
-
### Programmatic checking
|
|
477
|
-
|
|
478
|
-
Use `checkFrame` when a build, editor, or agent already has a React scene in memory. Pass `scene` for one fixed element or `create(theme)` for theme-specific elements:
|
|
479
|
-
|
|
480
|
-
```tsx
|
|
481
|
-
import { CalloutCard, Scene, checkFrame, getThemeColors } from "vizmatic"
|
|
482
|
-
|
|
483
|
-
const report = await checkFrame({
|
|
484
|
-
source: "agent-pipeline",
|
|
485
|
-
width: 640,
|
|
486
|
-
height: 360,
|
|
487
|
-
create(theme) {
|
|
488
|
-
const c = getThemeColors(theme)
|
|
489
|
-
return (
|
|
490
|
-
<Scene c={c}>
|
|
491
|
-
<CalloutCard c={c} title="Ready" detail="Checked in-process" tone="green" />
|
|
492
|
-
</Scene>
|
|
493
|
-
)
|
|
494
|
-
},
|
|
495
|
-
}, {
|
|
496
|
-
themes: ["dark", "light"],
|
|
497
|
-
background: "theme",
|
|
498
|
-
failOn: "warning",
|
|
499
|
-
})
|
|
500
|
-
|
|
501
|
-
if (!report.ok) throw new Error(`Visual check failed: ${report.summary.errors} errors`)
|
|
502
|
-
```
|
|
503
|
-
|
|
504
|
-
`failOn` accepts `"error"` (the default), `"warning"`, `"info"`, or `"never"`. `report.ok` means the diagnostics pass that policy; `report.rendered` means every requested theme completed rendering. Each theme report includes resolved and output dimensions, stable diagnostic codes, and severity counts. Diagnostics expose `elementId`, related IDs, and a `location` path or rendered bounds when available. Import `CHECK_DIAGNOSTIC_CODES`, `CheckDiagnostic`, `CheckFrameInput`, and `CheckFrameReport` for typed integrations. Use `vizmatic check ... --json` when the checker should discover and load frame files itself.
|
|
505
|
-
|
|
506
|
-
### Rendering
|
|
507
|
-
|
|
508
|
-
```ts
|
|
509
|
-
import { renderAnimatedGif, renderAnimationGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
|
|
510
|
-
```
|
|
511
|
-
|
|
512
|
-
`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.
|
|
513
|
-
|
|
514
|
-
Use `background: "theme"` to paint `c.bg`, or pass a CSS color. Use `crop: "height"` to keep canvas width while trimming vertical whitespace. `watermark.image` accepts a URL or data URI; CLI flag `--watermark-image` also accepts a local path. A frame module can export `watermark = <Watermark>...</Watermark>`. `brand` remains a compatibility alias.
|
|
515
|
-
|
|
516
|
-
```ts
|
|
517
|
-
await renderToPng(element, {
|
|
518
|
-
width: 1040,
|
|
519
|
-
height: 560,
|
|
520
|
-
outputPath: "dist/frame.png",
|
|
521
|
-
background: "theme",
|
|
522
|
-
theme: "dark",
|
|
523
|
-
watermark: { text: "Your Product", image: "https://example.com/logo.svg", position: "top-right" },
|
|
524
|
-
crop: "height",
|
|
525
|
-
scale: 2,
|
|
526
|
-
})
|
|
527
|
-
```
|
|
528
|
-
|
|
529
|
-
Frame modules can export watermark config directly:
|
|
530
|
-
|
|
531
|
-
```tsx
|
|
532
|
-
import { Watermark } from "vizmatic"
|
|
533
|
-
|
|
534
|
-
export const watermark = (
|
|
535
|
-
<Watermark position="bottom-right">
|
|
536
|
-
<div style={{ color: "#7c3aed", fontFamily: "Inter", fontWeight: 800 }}>
|
|
537
|
-
Acme Research
|
|
538
|
-
</div>
|
|
539
|
-
</Watermark>
|
|
540
|
-
)
|
|
541
|
-
```
|
|
542
|
-
|
|
543
|
-
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 exact cadence boundaries plus terminal state, checks every rendered frame for overflow, coalesces unchanged frames, and delta-encodes changed rectangles on opaque GIFs. Infinite loops should end on same visual state where they begin. Fade moving content out and reset it with a `keyframe` while hidden instead of reversing a one-way operation. Keep `create(theme)` as static fallback for PNG, docs previews, and reduced-motion users.
|
|
544
|
-
|
|
545
|
-
```tsx
|
|
546
|
-
import { defineAnimation, hold, keyframe, tween } from "vizmatic"
|
|
547
|
-
|
|
548
|
-
export function createAnimation(theme: ThemeMode) {
|
|
549
|
-
return defineAnimation({
|
|
550
|
-
initial: { operation: 0, progress: 0 },
|
|
551
|
-
timeline: [
|
|
552
|
-
hold(500, "Broadcast input"),
|
|
553
|
-
tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "Transfer" }),
|
|
554
|
-
hold(500, "Broadcast output"),
|
|
555
|
-
keyframe({ operation: 1, progress: 0 }),
|
|
556
|
-
tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "AllReduce" }),
|
|
557
|
-
],
|
|
558
|
-
fps: 20,
|
|
559
|
-
render: (state, frame) => buildFrame(theme, state, frame),
|
|
560
|
-
})
|
|
561
|
-
}
|
|
79
|
+
<Scene title="Checkout, read path">
|
|
80
|
+
<Flow
|
|
81
|
+
stages={[
|
|
82
|
+
{ title: "Gateway", subtitle: "Envoy, p99 9 ms", tone: "blue" },
|
|
83
|
+
{ title: "Cart", subtitle: "Go, 840 rps", tone: "purple" },
|
|
84
|
+
{ title: "Orders DB", subtitle: "Postgres, primary + 3", tone: "green" },
|
|
85
|
+
]}
|
|
86
|
+
/>
|
|
87
|
+
</Scene>
|
|
562
88
|
```
|
|
563
89
|
|
|
564
|
-
```
|
|
565
|
-
|
|
566
|
-
width: 1040,
|
|
567
|
-
height: 560,
|
|
568
|
-
outputPath: "dist/collective.gif",
|
|
569
|
-
watermark: { text: "Your Product", image: "data:image/png;base64,...", position: "bottom-right" },
|
|
570
|
-
theme: "dark",
|
|
571
|
-
scale: 1,
|
|
572
|
-
})
|
|
90
|
+
```bash
|
|
91
|
+
npx vizmatic ./frame.tsx --out ./figures --theme dark,light --format both
|
|
573
92
|
```
|
|
574
93
|
|
|
575
|
-
|
|
94
|
+
Read [Diagrams and density](https://bvolpato.github.io/vizmatic/docs/diagrams.html) and the [figures reference](https://bvolpato.github.io/vizmatic/docs/figures.html), or browse the [component catalog](https://bvolpato.github.io/vizmatic/components.html).
|
|
576
95
|
|
|
577
|
-
##
|
|
96
|
+
## For coding agents
|
|
578
97
|
|
|
579
|
-
|
|
98
|
+
Install the skill. It teaches the engine, the object catalog, and the check workflow.
|
|
580
99
|
|
|
581
100
|
```bash
|
|
582
|
-
|
|
583
|
-
pnpm verify
|
|
584
|
-
pnpm site:serve
|
|
101
|
+
npx skills add bvolpato/vizmatic --skill vizmatic -g -y
|
|
585
102
|
```
|
|
586
103
|
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
Choose the Freeform canvas template for a positioned builder. Move and resize `CanvasItem` components through the preview handles, use grid snapping, or adjust their literal coordinates in the inspector. Arrow keys nudge a focused handle; Shift makes a larger move and Alt bypasses snapping. The layout remains ordinary `Board` / `CanvasItem` TSX.
|
|
104
|
+
Agents can also read [`llms.txt`](https://bvolpato.github.io/vizmatic/llms.txt), and `vizmatic objects --json` and `vizmatic looks --json` list what the installed version offers.
|
|
590
105
|
|
|
591
|
-
|
|
106
|
+
## Documentation
|
|
592
107
|
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
108
|
+
| Read this | For |
|
|
109
|
+
|---|---|
|
|
110
|
+
| [Getting started](https://bvolpato.github.io/vizmatic/docs/) | Your first film, in two minutes |
|
|
111
|
+
| [Core concepts](https://bvolpato.github.io/vizmatic/docs/concepts.html) | The stage, the timeline, and why frames are pure |
|
|
112
|
+
| [Objects](https://bvolpato.github.io/vizmatic/docs/objects.html) | Axes, planes, charts, graphs, code, and 3D |
|
|
113
|
+
| [CLI](https://bvolpato.github.io/vizmatic/docs/cli.html) and [Exporting](https://bvolpato.github.io/vizmatic/docs/exporting.html) | Every command, format, and quality level |
|
|
114
|
+
| [Embedding](https://bvolpato.github.io/vizmatic/docs/embedding.html) | A live, seekable film in any page |
|
|
115
|
+
| [Editable scenes](https://bvolpato.github.io/vizmatic/docs/editable-scenes.html) | Running untrusted TSX in a bounded sandbox |
|
|
116
|
+
| [TSX animation](https://bvolpato.github.io/vizmatic/docs/tsx-animation.html) | Animating an existing figure with typed timelines |
|
|
117
|
+
| [Science guide](SCIENCE.md) | Accurate diagrams for math, physics, chemistry, and machine learning |
|
|
118
|
+
| [Roadmap](ROADMAP.md) | What shipped and what comes next |
|
|
119
|
+
| [Contributing](CONTRIBUTING.md) | Setup, checks, and the release process |
|
|
120
|
+
|
|
121
|
+
## Consumer security overrides
|
|
122
|
+
|
|
123
|
+
Vizmatic 0.5.0's MathJax tree resolves `speech-rule-engine`, which uses `@xmldom/xmldom`. Its Satori tree resolves `fflate`. Pin these patched transitive versions in a consuming project before you install Vizmatic.
|
|
124
|
+
|
|
125
|
+
For npm, add these root-level entries to `package.json`:
|
|
126
|
+
|
|
127
|
+
```json
|
|
128
|
+
{
|
|
129
|
+
"overrides": {
|
|
130
|
+
"@xmldom/xmldom": "0.9.12",
|
|
131
|
+
"fflate": "0.7.5"
|
|
132
|
+
}
|
|
133
|
+
}
|
|
607
134
|
```
|
|
608
135
|
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
Edits are saved locally in this browser and restore after reload. Component, shared-source, and gallery links open their own examples. Editing clears the original example or source bookmark so reload can recover your draft. Undo and redo cover source typing, controls, inline text, and scene operations, with up to 100 source snapshots for the current session. Use the buttons or Ctrl/Command+Z and Ctrl/Command+Shift+Z. Drafts do not sync between devices; use Save project to download a named `.vizmatic.json` file containing source, output theme, and canvas background, then Open project to restore it. Share and Copy source also let you move your TSX between tools.
|
|
612
|
-
|
|
613
|
-
Double-click a text label in the preview to edit its literal TSX value. Press Enter or click outside to save, Shift+Enter for a new line, or Escape to cancel. Keyboard users can focus a label and press Enter or F2. Labels derived from computed expressions or ambiguous source values stay editable in the TSX editor.
|
|
614
|
-
|
|
615
|
-
Choose the Animation scene template to play, pause, scrub time, and export a GIF in the browser. Bare animated source declares `animationDuration = 3` and optionally `animationFps = 10` before setup code. The injected `t` variable is time in seconds; Vizmatic timeline helpers continue to use milliseconds. Gallery timeline animations are adapted to the same browser workflow. Browser GIFs use an opaque canvas fill, with limits of 120 frames, 2 million pixels per frame, and 60 million pixels total. Static CLI render and check evaluate these snippets at `t=0`. Use a CLI animation module for larger animations or transparent GIF output.
|
|
616
|
-
|
|
617
|
-
The generated `components.json` includes compiler-derived prop types, requiredness, and finite allowed-value references. Shared value lists live in `propEnums`; defaults are not inferred. Full TypeScript definitions remain the contract for structured data and React values.
|
|
136
|
+
For pnpm 11, add these entries to the root `pnpm-workspace.yaml`. The CLI uses esbuild to compile films and frames, so allow its install script:
|
|
618
137
|
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
```bash
|
|
626
|
-
npm version patch --no-git-tag-version
|
|
627
|
-
pnpm sync:plugin-versions
|
|
628
|
-
pnpm docs:check
|
|
629
|
-
git add package.json plugins/vizmatic/.codex-plugin/plugin.json plugins/vizmatic/.claude-plugin/plugin.json .claude-plugin/marketplace.json
|
|
630
|
-
git commit -m "Release v$(node -p "require('./package.json').version")"
|
|
631
|
-
git push origin main
|
|
632
|
-
# Push annotated vX.Y.Z tag only after CI passes on release commit.
|
|
138
|
+
```yaml
|
|
139
|
+
overrides:
|
|
140
|
+
'@xmldom/xmldom': 0.9.12
|
|
141
|
+
fflate: 0.7.5
|
|
142
|
+
allowBuilds:
|
|
143
|
+
esbuild: true
|
|
633
144
|
```
|
|
634
145
|
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
The workflow keeps package version, plugin metadata, tag, release notes, and npm provenance in sync.
|
|
146
|
+
Then add Vizmatic with your package manager. The install updates the lockfile with these transitive pins.
|
|
638
147
|
|
|
639
148
|
## License
|
|
640
149
|
|
|
641
|
-
MIT
|
|
150
|
+
MIT. Bundled fonts and other third-party assets keep their own licenses. See [`assets/THIRD_PARTY_LICENSES.md`](assets/THIRD_PARTY_LICENSES.md).
|