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.
Files changed (150) hide show
  1. package/PROMPT.md +75 -525
  2. package/README.md +87 -578
  3. package/ROADMAP.md +49 -67
  4. package/SCIENCE.md +250 -0
  5. package/assets/THIRD_PARTY_LICENSES.md +40 -1
  6. package/assets/fonts/InstrumentSerif-Italic.ttf +0 -0
  7. package/assets/fonts/InstrumentSerif-Regular.ttf +0 -0
  8. package/assets/licenses/raster-codecs-MIT.txt +74 -0
  9. package/dist/chunk-3F2VQ7NW.js +1 -0
  10. package/dist/chunk-4XE64I2U.js +755 -0
  11. package/dist/chunk-JHHPLALU.js +79 -0
  12. package/dist/chunk-LTX44BAE.js +112 -0
  13. package/dist/chunk-MLKGABMK.js +9 -0
  14. package/dist/chunk-PSBF4TEK.js +1 -0
  15. package/dist/chunk-RPAHMKAR.js +605 -0
  16. package/dist/chunk-RWF4VBUL.js +3617 -0
  17. package/dist/chunk-WHT6HRMX.js +4201 -0
  18. package/dist/cli.js +371 -10
  19. package/dist/index.cjs +11129 -2922
  20. package/dist/index.d.cts +1225 -369
  21. package/dist/index.d.ts +1225 -369
  22. package/dist/index.js +6220 -3015
  23. package/dist/math-LXB4FH4E.js +7 -0
  24. package/dist/math-QVCETQDQ.js +1 -0
  25. package/dist/scene-browser-assets.d.ts +38 -0
  26. package/dist/scene-browser-assets.js +53 -0
  27. package/dist/scene-browser-chunks/chunk-5MVLYGXM.js +70 -0
  28. package/dist/scene-browser-chunks/chunk-ASXKN3NU.js +1 -0
  29. package/dist/scene-browser-chunks/chunk-CM5Y5LZP.js +1 -0
  30. package/dist/scene-browser-chunks/chunk-DP7NB4EW.js +6 -0
  31. package/dist/scene-browser-chunks/emscripten-module.browser-M5AEKJGE.js +1 -0
  32. package/dist/scene-browser-chunks/ffi-FL6ORJU3.js +1 -0
  33. package/dist/scene-browser-chunks/module-ES6BEMUI-JD5S5VKR.js +1 -0
  34. package/dist/scene-browser-chunks/module-asyncify-2EFITU5U-HWPFJFJC.js +1 -0
  35. package/dist/scene-browser-chunks/scene-browser-layout-M3XSXMV4.js +27 -0
  36. package/dist/scene-browser.d.ts +117 -0
  37. package/dist/scene-browser.js +220 -0
  38. package/dist/scene-cli.d.ts +1 -0
  39. package/dist/scene-cli.js +4 -0
  40. package/dist/scene-runtime.cjs +995 -0
  41. package/dist/scene-runtime.d.cts +81 -0
  42. package/dist/scene-runtime.d.ts +81 -0
  43. package/dist/scene-runtime.js +22 -0
  44. package/dist/server-2FYHZ4UO.js +331 -0
  45. package/dist/stage-browser/browser.d.ts +2482 -0
  46. package/dist/stage-browser/chunk-SQE76S5B.js +1 -0
  47. package/dist/stage-browser/chunk-VZNL6JY2.js +59 -0
  48. package/dist/stage-browser/dagre.esm-N2NIVIAZ.js +6 -0
  49. package/dist/stage-browser/math-4WFNHVV2.js +18 -0
  50. package/dist/stage-browser/stage.js +19 -0
  51. package/dist/stage-export.cjs +4950 -0
  52. package/dist/stage-export.d.cts +112 -0
  53. package/dist/stage-export.d.ts +112 -0
  54. package/dist/stage-export.js +544 -0
  55. package/dist/stage.cjs +9745 -0
  56. package/dist/stage.d.cts +1678 -0
  57. package/dist/stage.d.ts +1678 -0
  58. package/dist/stage.js +5404 -0
  59. package/dist/svg-import-Djj2q7Pc.d.cts +742 -0
  60. package/dist/svg-import-Djj2q7Pc.d.ts +742 -0
  61. package/dist/video-CcHW1qhV.d.cts +532 -0
  62. package/dist/video-CcHW1qhV.d.ts +532 -0
  63. package/examples/README.md +18 -0
  64. package/examples/agent-pipeline.tsx +4 -4
  65. package/examples/animated-pipeline.tsx +1 -5
  66. package/examples/attention-head.tsx +12 -12
  67. package/examples/aurora-incident.tsx +4 -3
  68. package/examples/building-blocks.tsx +8 -9
  69. package/examples/catalog-charts.tsx +4 -4
  70. package/examples/catalog-content.tsx +7 -9
  71. package/examples/catalog-convolution-kernel.tsx +116 -0
  72. package/examples/catalog-data.tsx +2 -8
  73. package/examples/catalog-dataflow.tsx +5 -9
  74. package/examples/catalog-dense.tsx +80 -0
  75. package/examples/catalog-deployment.tsx +5 -11
  76. package/examples/catalog-diagrams.tsx +13 -16
  77. package/examples/catalog-drawing.tsx +7 -7
  78. package/examples/catalog-flows.tsx +4 -4
  79. package/examples/catalog-foundations.tsx +11 -11
  80. package/examples/catalog-gaussian-blur.tsx +146 -0
  81. package/examples/catalog-image-tensors.tsx +115 -0
  82. package/examples/catalog-ml.tsx +36 -31
  83. package/examples/catalog-numeric-matrices.tsx +93 -0
  84. package/examples/catalog-photo-blur.tsx +209 -0
  85. package/examples/catalog-science-ai.tsx +130 -0
  86. package/examples/catalog-science-chemistry.tsx +103 -0
  87. package/examples/catalog-science-math.tsx +93 -0
  88. package/examples/catalog-science-physics.tsx +84 -0
  89. package/examples/catalog-sequence.tsx +59 -38
  90. package/examples/data-pipeline-lineage-presentation.tsx +5 -0
  91. package/examples/data-pipeline-lineage.tsx +85 -0
  92. package/examples/daybreak-launch.tsx +1 -0
  93. package/examples/desired-quadrant.tsx +7 -8
  94. package/examples/engineering-dashboard-presentation.tsx +13 -0
  95. package/examples/engineering-dashboard.tsx +160 -0
  96. package/examples/engineering-flow.tsx +2 -4
  97. package/examples/eval-dashboard.tsx +6 -6
  98. package/examples/films/attention.ts +278 -0
  99. package/examples/films/cache-miss.ts +431 -0
  100. package/examples/films/catalog.json +132 -0
  101. package/examples/films/central-limit.ts +269 -0
  102. package/examples/films/complex-maps.ts +273 -0
  103. package/examples/films/deck-example.ts +224 -0
  104. package/examples/films/euler-circle.ts +179 -0
  105. package/examples/films/fourier-epicycles.ts +265 -0
  106. package/examples/films/gradient-descent.ts +345 -0
  107. package/examples/films/linear-maps.ts +175 -0
  108. package/examples/films/lorenz.ts +207 -0
  109. package/examples/films/pythagoras.ts +185 -0
  110. package/examples/films/taylor-series.ts +159 -0
  111. package/examples/films/vizmatic-title.ts +117 -0
  112. package/examples/llm-serving-stack-presentation.tsx +5 -0
  113. package/examples/llm-serving-stack.tsx +94 -0
  114. package/examples/model-garden.tsx +1 -0
  115. package/examples/model-router.tsx +6 -6
  116. package/examples/nccl-all-gather.tsx +3 -3
  117. package/examples/nccl-all-reduce.tsx +3 -3
  118. package/examples/nccl-all-to-all.tsx +1 -1
  119. package/examples/nccl-broadcast.tsx +1 -1
  120. package/examples/nccl-reduce-scatter.tsx +5 -5
  121. package/examples/orthogonal-routing.tsx +4 -4
  122. package/examples/pareto-frontier.tsx +9 -10
  123. package/examples/presentation-frame.tsx +6 -6
  124. package/examples/pressure-mechanism.scene.json +14 -0
  125. package/examples/production-system-map-presentation.tsx +5 -0
  126. package/examples/production-system-map.tsx +130 -0
  127. package/examples/rag-graph.tsx +7 -7
  128. package/examples/release-card.tsx +5 -5
  129. package/examples/spec-anatomy.tsx +5 -5
  130. package/examples/system-architecture.tsx +19 -32
  131. package/examples/theme-system.tsx +1 -1
  132. package/examples/token-matrix.tsx +4 -2
  133. package/examples/transparent-badge.tsx +1 -2
  134. package/examples/videos/README.md +62 -0
  135. package/examples/videos/calculus-tangent.tsx +101 -0
  136. package/examples/videos/catalyst-pathway.tsx +56 -0
  137. package/examples/videos/causal-attention.tsx +91 -0
  138. package/examples/videos/convolution-kernel.tsx +34 -0
  139. package/examples/videos/gaussian-blur.tsx +32 -0
  140. package/examples/videos/image-to-matrix.tsx +22 -0
  141. package/examples/videos/matrix-multiplication.tsx +128 -0
  142. package/examples/videos/photo-gaussian-blur.tsx +39 -0
  143. package/examples/videos/request-lifecycle.tsx +99 -0
  144. package/examples/videos/signal-to-story.tsx +126 -0
  145. package/examples/videos/wave-interference.tsx +80 -0
  146. package/examples/vizmatic-bare.d.ts +1 -0
  147. package/examples/vizmatic-hero.tsx +9 -18
  148. package/examples/website-workflow.tsx +7 -7
  149. package/examples/weekend-field-notes.tsx +3 -2
  150. 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 logo" width="460" />
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>Diagrams, charts, dashboards, and GIFs from TSX.</strong><br/>
7
- Render dark and light PNG, SVG, and GIF files locally or in CI.
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/examples/animated-pipeline_dark.gif" alt="Vizmatic animated render pipeline" width="760" />
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/">Website</a> ·
23
- <a href="https://bvolpato.github.io/vizmatic/playground.html">Playground</a> ·
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 requires Node.js 20 or newer. Install its CLI:
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 -g vizmatic
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
- `Scene` title and subtitle are optional. Omit both when surrounding copy already names the visual.
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 { renderToPng } from "vizmatic"
166
- import { create, width, height } from "./frame"
167
-
168
- await renderToPng(create("dark"), {
169
- width,
170
- height,
171
- outputPath: "dist/agent-pipeline.png",
172
- background: "theme", // omit for alpha-transparent output
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
- Frames can export their own watermark:
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
- ./test.sh
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
- ## Runtime assets
58
+ `npx vizmatic new intro --template architecture` starts from a working film. The templates are `explainer`, `equation`, `architecture`, `chart`, and `deck`.
257
59
 
258
- Vizmatic uses `react` for JSX frames, `satori` for layout, `@resvg/resvg-js` for PNG output, `gifenc` for GIFs, and `tsx` to load frame files.
60
+ ## What makes it different
259
61
 
260
- Published packages include Inter, JetBrains Mono, Noto Sans, Noto Sans Math, and a compressed Twemoji bundle 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.
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
- The complete Twemoji set stays available offline but ships as one Brotli bundle instead of 3,720 individual SVG files. `pnpm deps:check` keeps the package below 2.5 MB compressed, 5 MB unpacked, and 100 files.
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
- ## API
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
- ### Themes
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
- ```ts
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
- const dark = getThemeColors("dark")
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
- Primitives receive `c`, the resolved theme object, for colors and typography.
74
+ ## Figures
278
75
 
279
- Bare frames select the same style with `preset = "engineering";`. Full modules pass the preset as the second argument to `getThemeColors`.
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
- width = 960;
302
- height = 540;
303
-
304
- <Board width={960} height={540}>
305
- <CanvasItem x={40} y={40} width={280} height={160}>
306
- <MetricCard label="Requests" value="1,240" tone="green" />
307
- </CanvasItem>
308
- <CanvasItem x={360} y={40} width={540} height={340}>
309
- <PieChart title="Requests by outcome" format="integer" segments={[
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
- ```ts
565
- await renderAnimationGif(createAnimation("dark"), {
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
- `createScenes(theme)` and `renderAnimatedGif(AnimatedScene[])` remain supported for intentional scene cuts and pixel crossfades. `fps` controls their transition sampling as well as typed timelines. GIF output uses one shared 256-color palette and centisecond timing. Opaque animations use changed rectangles by default; set `deltaFrames: false` only for legacy decoder debugging. Transparent animations stay full-frame to preserve one-bit compositing. Use PNG/SVG for smooth alpha edges.
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
- ## Development
96
+ ## For coding agents
578
97
 
579
- See [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup, testing, visual review, dependency updates, and pull request guidance.
98
+ Install the skill. It teaches the engine, the object catalog, and the check workflow.
580
99
 
581
100
  ```bash
582
- pnpm install
583
- pnpm verify
584
- pnpm site:serve
101
+ npx skills add bvolpato/vizmatic --skill vizmatic -g -y
585
102
  ```
586
103
 
587
- The homepage, Components page, and Playground share a live component explorer. Choose a component to open its focused example, or use Add to scene to compose several components. Select an element to edit its literal props, add optional properties, duplicate or remove it, and move it within its group. Controls follow inline text and TSX edits. Computed props and expression-generated structure stay editable in the TSX. Preview framing and zoom preserve the full canvas in downloaded PNG and SVG files.
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
- Structured data editors let you add, remove, and change pie segments, bar categories, scatter points, and table cells. Nested styles, arrays, and objects also have JSON editors. Invalid shapes and missing graph node references report an error before changing the source. Computed data remains editable in TSX.
106
+ ## Documentation
592
107
 
593
- Open Canvas and palette to change the frame dimensions, style preset, and any theme color. Choose a transparent, theme, or custom CSS background. These settings are saved in the TSX and participate in undo, project files, share links, and exports. Bare CLI frames support the same metadata:
594
-
595
- ```tsx
596
- width = 960;
597
- height = 540;
598
- preset = "default";
599
- background = "#101827";
600
- themeColors = {"primary":"#22c55e","primaryLight":"hsl(140, 70%, 65%)"};
601
-
602
- <Board width={960} height={540}>
603
- <CanvasItem x={40} y={40} width={300} height={120}>
604
- <CalloutCard title="Your palette" detail="Colors travel with the frame." />
605
- </CanvasItem>
606
- </Board>
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
- Copy block copies the selected element as reusable bare TSX, including its setup and canvas settings. Inside a Board it keeps the enclosing CanvasItem and its geometry, so the copied block renders on its own. Ctrl/Command+C copies a block when its canvas handle is focused. Copy source copies the complete composition.
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
- The website is generated from `docs/*.template.html`, the shared shell in `scripts/site-shell.ts`, and the component registry. Run `pnpm site:build` after editing these sources, then `pnpm docs:check`. Use `pnpm site:serve` for browser validation. The generated agent references, property controls, and example adapters update with the same build. If the bundled fonts change, regenerate the website's WOFF2 files with `pnpm site:fonts` using uv.
620
-
621
- ## Publishing
622
-
623
- Prepare release commit locally, push it to protected `main`, and wait for required CI before pushing its tag:
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
- Tag push starts GitHub `Release` workflow. It verifies exact commit again, publishes npm provenance, and creates release notes with compare link and commits since previous version. Retry existing tag with `gh workflow run release.yml --ref vX.Y.Z -f tag=vX.Y.Z`. Workflow requires `NPM_TOKEN` repository secret with publish access.
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).