vizmatic 0.4.0 → 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 (147) hide show
  1. package/PROMPT.md +75 -531
  2. package/README.md +85 -1052
  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-FEIPTPBZ.js → chunk-4XE64I2U.js} +53 -463
  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 +369 -12
  19. package/dist/index.cjs +7413 -1810
  20. package/dist/index.d.cts +900 -599
  21. package/dist/index.d.ts +900 -599
  22. package/dist/index.js +5019 -3278
  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.js +1 -1
  39. package/dist/scene-runtime.cjs +168 -103
  40. package/dist/scene-runtime.d.cts +3 -2
  41. package/dist/scene-runtime.d.ts +3 -2
  42. package/dist/scene-runtime.js +3 -1
  43. package/dist/server-2FYHZ4UO.js +331 -0
  44. package/dist/stage-browser/browser.d.ts +2482 -0
  45. package/dist/stage-browser/chunk-SQE76S5B.js +1 -0
  46. package/dist/stage-browser/chunk-VZNL6JY2.js +59 -0
  47. package/dist/stage-browser/dagre.esm-N2NIVIAZ.js +6 -0
  48. package/dist/stage-browser/math-4WFNHVV2.js +18 -0
  49. package/dist/stage-browser/stage.js +19 -0
  50. package/dist/stage-export.cjs +4950 -0
  51. package/dist/stage-export.d.cts +112 -0
  52. package/dist/stage-export.d.ts +112 -0
  53. package/dist/stage-export.js +544 -0
  54. package/dist/stage.cjs +9745 -0
  55. package/dist/stage.d.cts +1678 -0
  56. package/dist/stage.d.ts +1678 -0
  57. package/dist/stage.js +5404 -0
  58. package/dist/svg-import-Djj2q7Pc.d.cts +742 -0
  59. package/dist/svg-import-Djj2q7Pc.d.ts +742 -0
  60. package/dist/video-CcHW1qhV.d.cts +532 -0
  61. package/dist/video-CcHW1qhV.d.ts +532 -0
  62. package/examples/README.md +18 -0
  63. package/examples/agent-pipeline.tsx +4 -4
  64. package/examples/animated-pipeline.tsx +1 -5
  65. package/examples/attention-head.tsx +12 -12
  66. package/examples/aurora-incident.tsx +4 -3
  67. package/examples/building-blocks.tsx +8 -9
  68. package/examples/catalog-charts.tsx +4 -4
  69. package/examples/catalog-content.tsx +7 -9
  70. package/examples/catalog-convolution-kernel.tsx +116 -0
  71. package/examples/catalog-data.tsx +2 -8
  72. package/examples/catalog-dataflow.tsx +5 -9
  73. package/examples/catalog-dense.tsx +80 -0
  74. package/examples/catalog-deployment.tsx +5 -11
  75. package/examples/catalog-diagrams.tsx +13 -16
  76. package/examples/catalog-drawing.tsx +7 -7
  77. package/examples/catalog-flows.tsx +4 -4
  78. package/examples/catalog-foundations.tsx +11 -11
  79. package/examples/catalog-gaussian-blur.tsx +146 -0
  80. package/examples/catalog-image-tensors.tsx +115 -0
  81. package/examples/catalog-ml.tsx +36 -31
  82. package/examples/catalog-numeric-matrices.tsx +93 -0
  83. package/examples/catalog-photo-blur.tsx +209 -0
  84. package/examples/catalog-science-ai.tsx +130 -0
  85. package/examples/catalog-science-chemistry.tsx +103 -0
  86. package/examples/catalog-science-math.tsx +93 -0
  87. package/examples/catalog-science-physics.tsx +84 -0
  88. package/examples/catalog-sequence.tsx +59 -38
  89. package/examples/data-pipeline-lineage-presentation.tsx +5 -0
  90. package/examples/data-pipeline-lineage.tsx +85 -0
  91. package/examples/daybreak-launch.tsx +1 -0
  92. package/examples/desired-quadrant.tsx +7 -8
  93. package/examples/engineering-dashboard-presentation.tsx +13 -0
  94. package/examples/engineering-dashboard.tsx +160 -0
  95. package/examples/engineering-flow.tsx +2 -4
  96. package/examples/eval-dashboard.tsx +6 -6
  97. package/examples/films/attention.ts +278 -0
  98. package/examples/films/cache-miss.ts +431 -0
  99. package/examples/films/catalog.json +132 -0
  100. package/examples/films/central-limit.ts +269 -0
  101. package/examples/films/complex-maps.ts +273 -0
  102. package/examples/films/deck-example.ts +224 -0
  103. package/examples/films/euler-circle.ts +179 -0
  104. package/examples/films/fourier-epicycles.ts +265 -0
  105. package/examples/films/gradient-descent.ts +345 -0
  106. package/examples/films/linear-maps.ts +175 -0
  107. package/examples/films/lorenz.ts +207 -0
  108. package/examples/films/pythagoras.ts +185 -0
  109. package/examples/films/taylor-series.ts +159 -0
  110. package/examples/films/vizmatic-title.ts +117 -0
  111. package/examples/llm-serving-stack-presentation.tsx +5 -0
  112. package/examples/llm-serving-stack.tsx +94 -0
  113. package/examples/model-garden.tsx +1 -0
  114. package/examples/model-router.tsx +6 -6
  115. package/examples/nccl-all-gather.tsx +3 -3
  116. package/examples/nccl-all-reduce.tsx +3 -3
  117. package/examples/nccl-all-to-all.tsx +1 -1
  118. package/examples/nccl-broadcast.tsx +1 -1
  119. package/examples/nccl-reduce-scatter.tsx +5 -5
  120. package/examples/orthogonal-routing.tsx +4 -4
  121. package/examples/pareto-frontier.tsx +9 -10
  122. package/examples/presentation-frame.tsx +6 -6
  123. package/examples/production-system-map-presentation.tsx +5 -0
  124. package/examples/production-system-map.tsx +130 -0
  125. package/examples/rag-graph.tsx +7 -7
  126. package/examples/release-card.tsx +5 -5
  127. package/examples/spec-anatomy.tsx +5 -5
  128. package/examples/system-architecture.tsx +19 -32
  129. package/examples/theme-system.tsx +1 -1
  130. package/examples/token-matrix.tsx +4 -2
  131. package/examples/transparent-badge.tsx +1 -2
  132. package/examples/videos/README.md +36 -2
  133. package/examples/videos/calculus-tangent.tsx +101 -0
  134. package/examples/videos/catalyst-pathway.tsx +56 -0
  135. package/examples/videos/causal-attention.tsx +91 -0
  136. package/examples/videos/convolution-kernel.tsx +34 -0
  137. package/examples/videos/gaussian-blur.tsx +32 -0
  138. package/examples/videos/image-to-matrix.tsx +22 -0
  139. package/examples/videos/matrix-multiplication.tsx +128 -0
  140. package/examples/videos/photo-gaussian-blur.tsx +39 -0
  141. package/examples/videos/wave-interference.tsx +80 -0
  142. package/examples/vizmatic-bare.d.ts +1 -0
  143. package/examples/vizmatic-hero.tsx +9 -18
  144. package/examples/website-workflow.tsx +7 -7
  145. package/examples/weekend-field-notes.tsx +3 -2
  146. package/package.json +65 -11
  147. package/dist/chunk-TH3F4SDB.js +0 -79
package/PROMPT.md CHANGED
@@ -1,592 +1,136 @@
1
1
  # Vizmatic agent prompt
2
2
 
3
- Use Vizmatic to create diagrams, figures, dashboards, presentation frames, animated GIFs, and MP4 videos from React scene primitives. Render dark and light files locally or in CI.
3
+ Use Vizmatic to explain things visually from code. It makes two kinds of output:
4
4
 
5
- ## Quick start
5
+ - A **film** is motion. Write a TypeScript function with `vizmatic/stage`. It plays live in a browser and exports to MP4, WebM, GIF, PNG, and SVG.
6
+ - A **figure** is a still. Write TSX with typed components from `vizmatic`. It renders to PNG and SVG in dark and light themes.
6
7
 
7
- Vizmatic requires Node.js 20 or newer. Install the CLI:
8
+ Vizmatic requires Node.js 20 or newer. MP4 and WebM also need FFmpeg.
8
9
 
9
10
  ```bash
10
- npm install -g vizmatic
11
+ npm install vizmatic
11
12
  ```
12
13
 
13
- Create `frame.tsx`:
14
+ ## Films
14
15
 
15
- ```tsx
16
- <Scene title="Agent visual pipeline">
17
- <Flow
18
- connectorTone="purple"
19
- stages={[
20
- { title: "Prompt", tone: "blue" },
21
- { title: "Scene spec", tone: "purple" },
22
- { title: "PNG / SVG / GIF", tone: "green" },
23
- ]}
24
- />
25
- </Scene>
26
- ```
27
-
28
- Render dark and light assets:
16
+ Start from a template, or write the function yourself. Templates are `explainer`, `equation`, `architecture`, `chart`, and `deck`.
29
17
 
30
18
  ```bash
31
- vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
19
+ npx vizmatic new intro --template explainer
32
20
  ```
33
21
 
34
- Check the scene before publishing:
35
-
36
- ```bash
37
- vizmatic check ./frame.tsx --theme dark,light --json
38
- ```
22
+ ```ts
23
+ import { axes, draw, dynamic, dot, fadeIn, film, line, tex, write } from 'vizmatic/stage'
39
24
 
40
- Fix all errors before the final render. Warnings report low contrast, text below 11px, overlapping labels, uneven panel whitespace, connector congestion, and asset fallbacks. Overflow errors name the affected edges and suggest dimensions.
25
+ export default film({ title: 'A limit you can see' }, (s) => {
26
+ s.chapter('The curve')
27
+ const plot = s.add(axes({ x: [-1, 4], y: [-1, 9], grid: true, width: 1080, height: 660 }).at(-340, 60))
28
+ s.play(draw(plot.grid, { lag: 0.02 }), draw(plot.lines), fadeIn(plot.numbers))
29
+ s.play(draw(plot.plot((x) => x * x, { stroke: 'blue', width: 5 })))
41
30
 
42
- The [browser playground](https://bvolpato.github.io/vizmatic/playground.html) supports component composition, inline text edits, undo/redo, and local drafts. Choose Freeform canvas for positioned `Board` / `CanvasItem` editing with move and resize handles and snapping. Structured editors cover pie segments, bar categories, scatter points, table cells, line series, interval data, and graph nodes/edges/groups; computed data stays in TSX. Save project writes a named `.vizmatic.json` file containing source, output theme, and canvas background, and Open project restores it. PNG/SVG exports preserve the full canvas.
31
+ s.chapter('The secant')
32
+ const h = s.value(2)
33
+ const secant = s.add(dynamic(() => {
34
+ const slope = 2 + h.value
35
+ return [
36
+ line(plot.world(0.2, 1 + slope * -0.8), plot.world(3.2, 1 + slope * 2.2), { stroke: 'yellow', width: 3.5 }),
37
+ dot(9, 'yellow').at(plot.world(1 + h.value, (1 + h.value) ** 2)),
38
+ ]
39
+ }))
40
+ s.play(fadeIn(secant))
41
+ s.play(write(s.add(tex('m = 2 + h', { size: 64 }).at(600, -120))))
42
+ s.play(h.to(0.02, { duration: 4 }))
43
+ s.wait(1.5)
44
+ })
45
+ ```
43
46
 
44
- For scenes already created inside a build or editor, use the typed `checkFrame` API instead of writing a frame file and launching the CLI. Pass a React element as `scene` or use `create(theme)` for theme-specific scenes. Set `failOn` to `"warning"` when warnings should fail CI. Reports include per-theme dimensions and diagnostics with stable codes plus element IDs or rendered locations where available. Use `vizmatic check <files> --json` when the CLI should discover and load frame modules.
47
+ Rules of the engine:
45
48
 
46
- ## Install in a project
49
+ - The stage is 1920 by 1080. (0, 0) is the center and y points down. Plots convert with `plot.world(x, y)`.
50
+ - The build function runs once and may run again while assets load. Keep it free of side effects.
51
+ - `s.play(...)` writes animation and moves time forward. `s.wait(seconds)` holds. `s.at(time, build)` authors at another time.
52
+ - A `dynamic(() => ...)` drawing rebuilds on every frame. Read `value.value` inside it to drive anything.
53
+ - `morph(a, b)` leaves `b` on stage and `a` hidden. Later code refers to `b`.
54
+ - Colors are look tokens such as `'blue'`, `'yellow'`, `'ink'`, and `'dim'`, so a film renders in every look.
55
+ - Run `vizmatic objects` and `vizmatic looks` to see what the installed version offers.
47
56
 
48
- Use the package manager already present in the project.
57
+ ### Check, look, and export
49
58
 
50
- Add Vizmatic to a project for scripts, editor types, or direct renderer APIs:
59
+ An agent cannot watch a video, so judge a film from the check and from stills.
51
60
 
52
61
  ```bash
53
- pnpm add vizmatic react
62
+ npx vizmatic check intro.ts --json
63
+ npx vizmatic film intro.ts --frame 3,6.5,12 --width 1280 --out stills
64
+ npx vizmatic film intro.ts --out dist/films --look midnight,paper --quality high
54
65
  ```
55
66
 
56
- To use the current GitHub version:
67
+ `vizmatic check` samples the moments where the film comes to rest. It reports `film.off_canvas`, `film.text_overlap`, and `film.text_crossed`, each with times, a `box` in canvas pixels, and a `stage` center in authoring coordinates. Fix every error, then open the stills and look at them. `vizmatic preview intro.ts` opens a live player with a timeline for a person to review.
57
68
 
58
- ```bash
59
- pnpm add github:bvolpato/vizmatic react
60
- ```
69
+ Motion guidance:
61
70
 
62
- Use the equivalent command for npm, Yarn, or Bun projects.
71
+ - Use one idea per beat. Hold for a second after each reveal, so a viewer can read it.
72
+ - Move the thing being explained. Avoid decorative motion.
73
+ - Give color a meaning and keep it. A quantity keeps its color from its first appearance to its last.
74
+ - Use chapters. They mark the player's timeline and are the steps of a presentation.
63
75
 
64
- ## Full frame example
76
+ ## Figures
65
77
 
66
- Create `frames/agent-pipeline.tsx`:
78
+ Create `frame.tsx`. `Scene` title and subtitle are optional.
67
79
 
68
80
  ```tsx
69
- width = 1040;
70
- height = 560;
71
-
72
- <Scene
73
- title="Agent visual pipeline"
74
- subtitle="prompt -> TSX scene -> render -> files"
75
- gap={26}
76
- >
81
+ <Scene title="Checkout, read path">
77
82
  <Flow
78
- connectorTone="purple"
79
83
  stages={[
80
- {
81
- eyebrow: "input",
82
- title: "Prompt",
83
- subtitle: "intent and constraints",
84
- tone: "blue",
85
- lines: ["domain language", "audience", "theme tokens"],
86
- width: 190,
87
- },
88
- {
89
- eyebrow: "contract",
90
- title: "Scene spec",
91
- subtitle: "typed structure",
92
- tone: "purple",
93
- lines: ["cards", "flows", "charts", "tables"],
94
- width: 190,
95
- },
96
- {
97
- eyebrow: "render",
98
- title: "Node renderer",
99
- subtitle: "headless output",
100
- tone: "cyan",
101
- lines: ["layout", "theme", "checks"],
102
- width: 190,
103
- },
104
- {
105
- eyebrow: "output",
106
- title: "PNG / SVG / GIF",
107
- subtitle: "rendered files",
108
- tone: "green",
109
- lines: ["dark + light", "alpha", "manifest"],
110
- width: 190,
111
- },
84
+ { title: "Gateway", subtitle: "Envoy, p99 9 ms", tone: "blue" },
85
+ { title: "Cart", subtitle: "Go, 840 rps", tone: "purple" },
86
+ { title: "Orders DB", subtitle: "Postgres, primary + 3", tone: "green" },
112
87
  ]}
113
88
  />
114
- <Row width="100%" gap={14}>
115
- <CalloutCard
116
- title="Use scene primitives"
117
- detail="Common diagrams do not need hand-written SVG paths or x/y coordinates."
118
- tone="purple"
119
- width={470}
120
- />
121
- <CalloutCard
122
- title="Use theme tokens"
123
- detail="Tokens set color, typography, radius, spacing, and contrast."
124
- tone="green"
125
- width={470}
126
- />
127
- </Row>
128
89
  </Scene>
129
90
  ```
130
91
 
131
- Render it:
132
-
133
92
  ```bash
134
- vizmatic frames --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right
93
+ npx vizmatic check ./frame.tsx --theme dark,light --json
94
+ npx vizmatic ./frame.tsx --out ./figures --theme dark,light --format both
135
95
  ```
136
96
 
137
- Generated `manifest.json` includes each output file plus its theme, path, width, and height.
138
-
139
- The static CLI defaults to PNG. Add `--format svg` for vector output or `--format both` to render PNG and SVG together in every requested theme.
97
+ Fix all errors before the final render. Warnings report low contrast, small text, overlapping labels, uneven panel whitespace, connector congestion, and asset fallbacks.
140
98
 
141
- PNG and SVG renders have transparent backgrounds by default. Use the theme background when the image needs an opaque canvas:
142
-
143
- ```bash
144
- vizmatic frames --out public/vizmatic --theme dark,light --background theme
145
- ```
146
-
147
- Or set it in the frame:
148
-
149
- ```tsx
150
- <Scene background={c.bg} title="Opaque article figure">
151
- <Flow stages={[{ title: "Theme fill", tone: "purple" }]} />
152
- </Scene>
153
- ```
154
-
155
- CSS alpha colors are preserved in PNG/SVG backgrounds. Use `<Scene background="rgba(15, 23, 42, 0.5)">` or `--background 'rgba(15, 23, 42, 0.5)'` for a semi-transparent canvas. Leave the background unset for fully transparent output. Contrast checks composite alpha text and nested backgrounds over known solid surfaces; a transparent canvas has no known host-page backdrop.
156
-
157
- When a CLI 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.
158
-
159
- Bare CLI frames do not need imports, `defineIllustration`, or `c` props. Use `c` for explicit tokens such as `background={c.bg}`. `Scene` title and subtitle are optional. Use a full module for other dependencies, reusable helpers, animation exports, or direct renderer APIs.
160
-
161
- Frame modules can export a watermark element instead of using CLI flags:
162
-
163
- ```tsx
164
- import { Watermark } from "vizmatic"
165
-
166
- export const watermark = (
167
- <Watermark position="bottom-right" opacity={0.82}>
168
- <div style={{
169
- display: "flex",
170
- alignItems: "center",
171
- gap: 6,
172
- color: "#7c3aed",
173
- fontFamily: "Inter",
174
- fontWeight: 800,
175
- fontSize: 12,
176
- }}>
177
- <img src="data:image/svg+xml;base64,..." width={14} height={14} />
178
- Your Product
179
- </div>
180
- </Watermark>
181
- )
182
- ```
183
-
184
- Render a sampled state timeline with `createAnimation(theme)`:
185
-
186
- ```bash
187
- vizmatic gif frames/animated-pipeline.tsx --out public/vizmatic --theme dark,light --fps 20 --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right --scale 1
188
- ```
99
+ Figures default to the `dense` density, like a figure in an engineering paper. Fill the space with useful detail: runtimes, rates, schemas, and limits. Do not spread three boxes across a slide. Use `density="presentation"` on a `Scene`, or `density` in a render option, only for a room. The densities are `dense`, `compact`, `comfortable`, `presentation`, or a number.
189
100
 
190
- ## Animated frames
101
+ Choose by meaning: `GraphDiagram` for systems, `SequenceDiagram` for interactions, `DataflowDiagram` for lineage, `DeploymentDiagram` for placement and trust, `TransformerTopology` for models, and `LineChart`, `BarChart`, `DataTable`, or `Heatmap` for data. Omit `width` and `height` to auto-grow from 960 by 540.
191
102
 
192
- An animated module exports `createAnimation(theme)` for GIF or MP4 output and keeps `create(theme)` for a static or reduced-motion fallback. Define state once, then describe holds, eased transitions, instant keyframes, and parallel property tracks. Vizmatic samples absolute timeline time and renders every frame.
103
+ PNG and SVG output is alpha-transparent by default. Add `--background theme` or `background={c.bg}` for an opaque canvas. Use `preset = "engineering";` with `--theme light` for flat article figures.
193
104
 
194
- For MP4, export `createAnimation(theme)` and run `vizmatic video frames/lesson.tsx --out public/videos --theme dark --fps 30`. This requires Node.js 20 or newer and FFmpeg with the `libx264` encoder; add `--audio narration.wav` for AAC audio. The CLI pads or trims audio to the animation duration. Exported canvas dimensions after `--scale` must be positive even integers. MP4 uses an opaque theme background by default and supports 1–120 fps independently of GIF cadence. The browser builder exports GIF; MP4 runs in Node.js. Keep `.vtt` or `.srt` captions as separate files and synchronize them to the finished timeline. Use `examples/videos/request-lifecycle.tsx` as a short, generic starting point and `examples/videos/signal-to-story.tsx` for a longer film with parallel tracks, path tracing, camera motion, and an ending held on screen. Animate the data or mechanism the lesson explains; avoid decorative logo or icon reveals. For package consumers, install Vizmatic and React in the project and FFmpeg separately. In the repository, `pnpm render:video` regenerates the showcase media.
105
+ Use a full module when a frame needs helper code or data:
195
106
 
196
107
  ```tsx
197
- import React from "react"
198
- import { Scene, defineAnimation, getThemeColors, hold, keyframe, tween, type ThemeMode } from "vizmatic"
108
+ import { Flow, Scene, getThemeColors, type ThemeMode } from "vizmatic"
199
109
 
200
110
  export const width = 1040
201
111
  export const height = 560
202
112
 
203
- type State = { operation: number; progress: number }
204
-
205
- function buildFrame(theme: ThemeMode, state: State) {
206
- const c = getThemeColors(theme)
207
- return (
208
- <Scene c={c} title={state.operation === 0 ? "Broadcast" : "AllReduce"}>
209
- <div style={{ display: "flex", width: "100%", height: 260, position: "relative" }}>
210
- <div style={{
211
- display: "flex",
212
- position: "absolute",
213
- left: 40 + state.progress * 720,
214
- top: 90,
215
- padding: "10px 16px",
216
- borderRadius: 8,
217
- background: c.accent,
218
- color: c.textOnColor,
219
- }}>chunk</div>
220
- </div>
221
- </Scene>
222
- )
223
- }
224
-
225
- export function createAnimation(theme: ThemeMode) {
226
- return defineAnimation<State>({
227
- initial: { operation: 0, progress: 0 },
228
- timeline: [
229
- hold(500, "Broadcast input"),
230
- tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "Broadcast" }),
231
- hold(500, "Broadcast output"),
232
- keyframe({ operation: 1, progress: 0 }),
233
- tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "AllReduce" }),
234
- ],
235
- fps: 20,
236
- render: (state) => buildFrame(theme, state),
237
- })
238
- }
239
-
240
113
  export function create(theme: ThemeMode = "dark") {
241
- return buildFrame(theme, { operation: 1, progress: 1 })
114
+ const c = getThemeColors(theme)
115
+ return <Scene c={c} title="Runtime path"><Flow c={c} stages={[{ title: "Input", tone: "blue" }, { title: "Check", tone: "purple" }]} /></Scene>
242
116
  }
243
-
244
- export default create("dark")
245
- ```
246
-
247
- Top-level timeline steps run sequentially. Properties inside one `tween` move together. Use `parallel({ x: [...], opacity: [...] })` when property tracks need different delays or durations. Default interpolation supports finite numbers; use a custom `interpolate(from, to, progress)` for colors, points, or other values. Infinite loops should finish on the same visual state where they start. Fade moving content out and reset it with a zero-duration `keyframe` while hidden instead of reversing a one-way operation. `createScenes(theme)` remains supported for deliberate scene cuts and pixel `fade`/`appear` transitions.
248
-
249
- ## Choose primitives
250
-
251
- Use Vizmatic primitives for common layouts. Use raw SVG only for geometry the component set cannot express.
252
-
253
- Shared values:
254
-
255
- - `ThemeMode`: `"dark" | "light"`.
256
- - `ToneName`: `"blue" | "purple" | "green" | "warm" | "cyan" | "pink" | "red" | "critical" | "neutral" | "sunset" | "ocean" | "dark"`.
257
- - `ColorName`: `"primary" | "secondary" | "positive" | "warning" | "critical" | "info" | "accent" | "neutral"`.
258
- - `FlexAlign`: `"start" | "center" | "end" | "stretch"`.
259
- - `FlexJustify`: `"start" | "center" | "end" | "space-between" | "space-around"`.
260
- - Bare CLI frames omit `c` props. The local `c` object remains available for explicit values such as `background={c.bg}`.
261
- - Full modules pass the `c: ThemeColors` value from `defineIllustration((c) => ...)` to visual components.
262
- - PNG/SVG renders are alpha-transparent by default. Use `--background theme`, `background: "theme"`, or `<Scene background={c.bg}>` for opaque theme fill.
263
- - Omitted CLI dimensions auto-grow on overflow. Explicit `width` / `height` remain fixed and fail on clipping.
264
-
265
- ## Component API
266
-
267
- Frame helpers:
268
-
269
- - `defineIllustration(build, defaultTheme?)`: `build: (c: ThemeColors) => ReactElement`, `defaultTheme?: ThemeMode = "dark"`. Returns `{ create(theme), default }`.
270
- - `Canvas`: `children?`, `c`, `padding?: number = 40`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "center"`, `background?: string`. Default root background is alpha-transparent during PNG/SVG rendering.
271
- - `Board`: `children?`, `c`, `width?: number = 960`, `height?: number = 540`, `background?: string`. Fixed relative canvas with a transparent default background; clips content outside its bounds. Match frame dimensions to the board. Dimensions must be finite, greater than zero, and at most 8192.
272
- - `CanvasItem`: `children?`, `x: number`, `y: number`, `width?: number`, `height?: number`. Absolute position in logical board pixels. Coordinates must be finite. Explicit dimensions must be greater than zero and at most 8192; they supply the child's width/height props. With both dimensions set, chart primitives scale proportionally to fit their complete plotting layer, headings, legends, and footer inside the item. Use literal coordinates and dimensions for preview move/resize controls.
273
- - `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Title/subtitle are optional and the title bar is omitted when no title is provided. Use `background={c.bg}` for an opaque theme frame.
274
- - `TitleBar`: `title`, `subtitle?`, `c`.
275
-
276
- Layout primitives:
277
-
278
- - `Row` / `Column`: `children`, `gap?: number = 12`, `align?: FlexAlign = "center"`, `justify?: FlexJustify = "center"`, `wrap?: boolean = false`, `width?: number | string`, `height?: number | string`, `style?: React.CSSProperties`.
279
- - `Stack`: `children`, `direction?: "vertical" | "horizontal" = "vertical"`, `gap?: number = 12`, `align?: "start" | "center" | "end" | "stretch" = "center"`, `wrap?: boolean = false`.
280
- - `Panel`: `title`, `c`, `children?`, `subtitle?`, `tone?: ToneName = "blue"`, `footer?`, `width?`, `minWidth?`, `height?`, `minHeight?`, `padding?: number | string = 14`, `radius?: number = 8`, `gap?: number = 10`, `align?: FlexAlign = "stretch"`, `justify?: FlexJustify = "start"`, `shadow?: boolean = true`, `background?`, `borderColor?`, `titleFontSize?`, `accentWidth?: number = 34`, `accentHeight?: number = 4`, `bodyStyle?: React.CSSProperties`.
281
- - `Card`: `children?`, `c`, `title?`, `subtitle?`, `tone?`, `footer?`, `width?`, `minWidth?`, `height?`, `minHeight?`, `padding?: number | string = 20`, `radius?: number = 8`, `gap?`, `align?: FlexAlign = "stretch"`, `justify?: FlexJustify = "start"`, `shadow?: boolean = false`, `background?`, `borderColor?`, `bodyStyle?: React.CSSProperties`.
282
- - `WindowFrame`: `c`, `children?`, `title?`, `variant?: "window" | "browser" | "terminal" = "window"`, `tone?: ToneName = "blue"`, `dots?: boolean = true`, `width?`, `minWidth?`, `height?`, `minHeight?`, `padding?: number | string = 16`, `radius?: number = 10`, `shadow?: boolean = true`, `background?`, `bodyStyle?: React.CSSProperties`.
283
-
284
- Cards, labels, and compact UI:
285
-
286
- - `TextLabel`: `text`, `c`, `variant?: keyof typography = "body"`, `color?`, `fontSize?`, `fontWeight?`, `width?`, `align?: "left" | "center" | "right" = "left"`, `math?: boolean = false`, `mono?: boolean = false`.
287
- - `MathText`: `text`. Returns formatted unicode-ish math text for simple `_` and `^` notation.
288
- - `formatMathText(text)`: `text: string`.
289
- - `Icon`: `name`, `c`, `tone?: ToneName = "blue"`, `color?`, `size?: number = 24`, `strokeWidth?: number = 2`, `label?`, `muted?: boolean = false`. `IconName` includes presentation icons plus architecture icons: `browser`, `bucket`, `cache`, `cloud`, `cluster`, `container`, `database`, `firewall`, `gateway`, `load-balancer`, `mobile`, `monitor`, `network`, `queue`, `server`, `storage`, `stream`, and `user`.
290
- - `ToneStrip`: `tone`, `width?: number = 34`, `height?: number = 4`.
291
- - `StepCard`: `title`, `c`, `subtitle?`, `eyebrow?`, `tone?: ToneName = "blue"`, `width?: number | string = 210`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "12px 14px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`.
292
- - `MetricCard`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "10px 12px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`, `valueMono?: boolean = true`, `valueFontSize?: number = 22`, `valueColor?`.
293
- - `CalloutCard`: `c`, `children?`, `title?`, `detail?`, `tone?: ToneName = "blue"`, `width?`, `minHeight?`, `padding?: number | string = 12`, `titleFontSize?: number`, `detailFontSize?: number`, `filled?: boolean = true`, `align?: "left" | "center" = "center"`.
294
- - `ValuePill`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?: number | string = 112`, `math?: boolean = false`.
295
- - `BadgePill`: `text`, `c`, `tone?: ToneName = "blue"`, `width?`, `minWidth?: number | string = 34`, `height?: number | string = 20`, `padding?: number | string = "0 8px"`, `radius?: number = 6`, `fontSize?: number = 11`, `mono?: boolean = true`, `filled?: boolean = false`, `math?: boolean = false`.
296
- - `Badge`: `label`, `c`, `color?: ColorName = "primary"`.
297
- - `GradientChip`: `title`, `c`, `subtitle?`, `tone?: ToneName = "blue"`, `gradient?`, `width?`, `minWidth?`, `height?`, `minHeight?: number | string = 78`, `padding?: number | string = "0 18px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "left"`, `subtitleMono?: boolean = true`, `math?: boolean = false`.
298
- - `EquationCard`: `title`, `formula`, `c`, `tone?: ToneName = "purple"`, `result?`, `detail?`, `width?: number | string = 190`, `height?`, `math?: boolean = false`, `align?: "left" | "center" = "left"`.
299
- - `DetailList`: `items`, `c`, `tone?`, `gap?: number = 7`, `padding?: number | string = "7px 8px"`, `fontSize?: number = 11`, `mono?: boolean = false`, `math?: boolean = false`.
300
-
301
- Lists, tables, status, and comparison:
302
-
303
- - `ProgressRow`: `label`, `value: number`, `valueLabel?`, `tone?: ToneName = "blue"`, `muted?: boolean = false`, `c`, `labelWidth?: number = 42`, `valueWidth?: number = 38`, `barHeight?: number = 8`, `fontSize?: number = 11`. Keep `value` in `[0, 1]`.
304
- - `ProgressList`: `rows: ProgressRowSpec[]`, `c`, `gap?: number = 8`, `labelWidth?`, `valueWidth?`, `barHeight?`, `fontSize?`. `ProgressRowSpec`: `label`, `value`, `valueLabel?`, `tone?`, `muted?`.
305
- - `StatusRow`: `label`, `detail?`, `status?: "check" | "cross" | "warn" | "info" | "pending" | "dot" = "check"`, `tone?`, `c`, `boxed?: boolean = true`, `fontSize?: number = 11`, `width?`, `math?: boolean = false`.
306
- - `StatusList`: `rows: StatusRowSpec[]`, `c`, `gap?: number = 7`, `boxed?: boolean = true`, `fontSize?`, `width?`, `math?: boolean = false`. `StatusRowSpec`: `label`, `detail?`, `status?`, `tone?`.
307
- - `Timeline`: `events: TimelineEventSpec[]`, `c`, `title?`, `subtitle?`, `direction?: "vertical" | "horizontal" = "vertical"`, `width?`, `eventWidth?`, `gap?: number = 12`, `markerSize?: number = 14`, `math?: boolean = false`. `TimelineEventSpec`: `title`, `detail?`, `time?`, `tone?`, `status?`, `width?`.
308
- - `KeyValueList`: `rows: KeyValueRow[]`, `c`, `title?`, `width?`, `minWidth?`, `keyWidth?`, `gap?: number = 0`, `fontSize?: number = 11`, `divider?: boolean = true`, `keyMono?: boolean = false`, `math?: boolean = false`. `KeyValueRow`: `key`, `value`, `tone?`, `valueMono?`.
309
- - `Comparison`: `sides: ComparisonSideSpec[]`, `c`, `divider?: ReactNode | boolean = false`, `gap?: number = 14`, `sideWidth?`, `minHeight?`, `align?: FlexAlign = "stretch"`, `math?: boolean = false`. `ComparisonSideSpec`: `title`, `subtitle?`, `eyebrow?`, `tone?`, `lines?`, `children?`, `footer?`, `width?`.
310
- - `DataTable`: `rows: ReactNode[][]`, `c`, `cellWidth?: number = 54`, `firstColWidth?: number = cellWidth`, `cellHeight?: number = 28`, `gap?: number = 5`, `headerRows?: number = 1`, `headerCols?: number = 1`, `fontSize?: number = 11`, `math?: boolean = false`.
311
- - `Grid`: `rows: Array<Array<ReactNode | GridCell>>`, `c`, `cellWidth?: number = 34`, `cellHeight?: number = 30`, `gap?: number = 5`, `radius?: number = 7`, `fontSize?: number = 11`, `math?: boolean = false`, `headerRows?: number = 0`, `headerCols?: number = 0`. `GridCell`: `label?`, `tone?`, `color?`, `backgroundColor?`, `borderColor?`, `opacity?`.
312
- - `CodeBlock`: `lines: Array<ReactNode | CodeLineSpec>`, `c`, `title?`, `tone?`, `width?`, `minWidth?`, `fontSize?: number = 12`, `showLineNumbers?: boolean = false`, `padding?: number | string = 14`, `radius?: number = 10`, `background?`, `shadow?: boolean = false`, `math?: boolean = false`. `CodeLineSpec`: `text`, `tone?`, `dim?`, `prefix?`.
313
-
314
- Tiles:
315
-
316
- - `Tile`: combines `TileSpec` with display props. `TileSpec`: `title`, `subtitle?`, `eyebrow?`, `icon?`, `tone?`, `lines?`, `children?`, `width?`, `minHeight?`. Display props: `c`, `align?: "left" | "center" = "center"`, `padding?: number | string = "14px 16px"`, `radius?: number = 10`, `shadow?: boolean = true`, `math?: boolean = false`.
317
- - `TileGrid`: `tiles: TileSpec[]`, `c`, `columns?`, `gap?: number = 12`, `tileWidth?`, `minHeight?`, `align?: "left" | "center" = "center"`, `math?: boolean = false`.
318
-
319
- Flows and process diagrams:
320
-
321
- - `Flow`: `stages: FlowStageSpec[]`, `c`, `direction?: "horizontal" | "vertical" = "horizontal"`, `gap?: number = 10`, `connectorLength?: number = 28`, `connectorTone?: ToneName = "neutral"`, `align?: FlexAlign = "center"`, `math?: boolean = false`. `FlowStageSpec`: `title`, `subtitle?`, `eyebrow?`, `tone?`, `lines?`, `children?`, `width?`, `minWidth?`, `minHeight?`, `padding?`.
322
- - `FlowArrow`: `direction?: "down" | "right" | "up" | "left" = "right"`, `label?`, `length?: number = 40`, `c`, `tone?: ToneName = "blue"`, `color?`.
323
- - `Connector`: same props as `FlowArrow`.
324
- - `Pipeline`: `stages: PipelineStage[]`, `c`, `title?`. `PipelineStage`: `label`, `sublabel?`, `icon?`, `color?: ColorName`.
325
-
326
- Graphs and networks:
327
-
328
- - `LayeredNetwork`: `c`, `layers: LayeredNetworkLayer[]`, `activePath?: number[] = []`, `annotations?: string[] = []`, `formula?`, `legend?: string = "highlighted path"`, `width?: number = 900`, `height?: number = 400`, `nodeSize?: number = 56`, `showFormula?: boolean = true`. `LayeredNetworkLayer`: `title`, `nodes: string[]`, `tone?`.
329
- - `GraphDiagram` routing options: `routing?: "dagre" | "straight" | "orthogonal" = "dagre"`, `routingClearance?: number = 12`. Dagre preserves existing routes; straight connects facing node sides; orthogonal avoids node boxes and group headers with right-angle paths. Node layout remains automatic or manual independently of routing. `GraphDiagramNode` additionally accepts `ports?: GraphDiagramPort[]`; a port is `{ id: string, side: "top" | "right" | "bottom" | "left", offset?: number = 0.5 }`. Offset is finite and in `[0, 1]`, running left to right or top to bottom. `GraphDiagramEdge` additionally accepts `fromPort?`, `toPort?`, `fromSide?`, and `toSide?`. An endpoint cannot combine a port reference with a side. Explicit anchors opt an edge into orthogonal geometry even in Dagre mode. Missing references, duplicate port IDs, and invalid offsets fail validation.
330
-
331
- - Orthogonal routing separates parallel relationships, supports self-loops with distinct endpoint anchors, and uses `edgeGap` for lane spacing. It runs offline with limits of 64 node/header obstacles, 256 edges, 18,000 grid points per search, 54,000 search states per search, and 160,000 search states per diagram. A blocked path, unavailable separate lane, same-anchor self-loop, or exhausted limit omits that connector and emits a checker error with code `layout.connector_unroutable`. Increase canvas size or spacing, choose different sides/ports, or reduce clearance; do not publish missing connectors. See `examples/orthogonal-routing.tsx`.
332
-
333
- - `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `groups?: GraphDiagramGroup[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `labelFontSize?: number = 14`, `detailFontSize?: number = 11`, `arrowSize?: number = 5`, `padding?: number = 28`, `layout?: "auto" | "manual"`, `direction?: "LR" | "RL" | "TB" | "BT" = "LR"`, `nodeGap?: number = 34`, `rankGap?: number = 64`, `edgeGap?: number = 14`, `sizing?: "content" | "fixed" = "content"`, `iconSize?: number = 20`, `id?`, `ariaLabel?`, `title?`, `description?`. `GraphDiagramNode`: `id`, `label`, `detail?`, `href?`, `title?`, `x?`, `y?`, `tone?`, `muted?`, `width?`, `height?`, `group?`, `icon?: IconName | DiagramIconDefinition | ReactElement`, `iconSize?`. Icon size is clamped inside its node; custom React elements own their theme colors and accessible label. `GraphDiagramGroup`: `id`, `label`, `detail?`, `parent?`, `tone?`, `muted?`. Groups nest through `parent` and require automatic layout. Omit coordinates on every node for automatic layout; array order is the stable tie-breaker and dimensions expand to fit unless `sizing="fixed"`. Set both coordinates on every node for manual normalized positioning when no groups are present. Mixed coordinate modes fail. `GraphDiagramEdge`: `id?`, `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`, `href?`, `title?`, `kind?: "sync" | "async" | "event" | "data" | "dependency" | "association"`, `style?: "solid" | "dashed" | "dotted"`, `arrow?: "forward" | "backward" | "both" | "none"`. Association edges default to no arrow. `title`, `description`, and `id` add structured SVG metadata and deterministic graph, node, and edge IDs. Nodes and edges can link to HTTP(S), `mailto:`, `tel:`, fragment, or relative URLs; unsupported schemes fail. Use these properties for `renderToSvg` and playground SVG downloads.
334
- - `SequenceDiagram`: `participants`, ordered `items`, `c`, and optional `width`, `height`, spacing, title, subtitle, and `ariaLabel`. Participants have `id`, `label`, optional `detail`, `tone`, `kind`, and `icon`. Items are messages (`from`, `to`, `label`, `kind?: "sync" | "async" | "return"`), notes, activations, or recursive fragments with `kind: "alt" | "loop" | "parallel"` and labeled branches.
335
- - `DataflowDiagram`: `nodes`, `edges`, optional nested `boundaries`, `c`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Nodes require `id`, `label`, and `kind: "source" | "transform" | "store" | "sink"`; optional schema metadata renders in node detail, with optional `href` and `title` for SVG links and tooltips. Edges use `mode?: "batch" | "stream"`, optional schema/label metadata, and optional `id`, `href`, and `title`.
336
- - `DeploymentDiagram`: `nodes`, `connections`, optional nested `boundaries`, `c`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Boundaries distinguish region, zone, VPC, subnet, namespace, host, cluster, and trust scopes. Nodes declare infrastructure kind, boundary, and ports, with optional `href` and `title`. Connections declare ingress, egress, internal, or cross-boundary direction plus protocol and port references; `id`, `href`, and `title` add stable SVG identity and links.
337
- - `DeploymentPort`: `id`, `port?`, `protocol?`, `label?`, `direction?: "ingress" | "egress" | "bidirectional"`, `side?: GraphPortSide`, `offset?: number`. With explicit `routing="straight"` or `routing="orthogonal"`, connection `fromPort` / `toPort` references require declared node ports and anchor geometrically. Side defaults follow graph direction and ingress/egress use; explicit side/offset overrides them. Default Dagre deployment rendering keeps the existing label-only behavior.
338
- - `TransformerTopology`: `blocks`, optional `routes`, `c`, `expandRepeats?`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Blocks use embedding, attention, norm, MLP, residual, router, output, or custom kinds with tensor shapes and repeat counts, plus optional `href` and `title`. Routes use activation, residual, KV-cache, expert, or collective semantics, plus optional `id`, `href`, and `title`. `formatTensorShape(shape)` formats reusable shape metadata.
339
- - `defineDiagramIcon(id, render)`: defines a reusable custom graph icon. `render` receives `c`, `color`, `size`, and optional `label`.
340
- - `defineIconRegistry(icons)`: preserves typed names for a set of custom or provider icons without global mutable state.
341
- - `TreeDiagram`: `root: TreeNodeSpec`, `c`, `title?`, `subtitle?`, `width?`, `height?`, `nodeWidth?: number = 156`, `nodeHeight?: number = 64`, `levelGap?: number = 58`, `siblingGap?: number = 24`, `padding?: number = 28`, `math?: boolean = false`. `TreeNodeSpec`: `label`, `id?`, `detail?`, `tone?`, `muted?`, `children?`.
342
-
343
- Matrices and heatmaps:
344
-
345
- - `Matrix`: `data: number[][]`, `c`, `rowLabels?`, `colLabels?`, `labels?`, `title?`, `cellSize?: number = 48`, `cellWidth?`, `cellHeight?`, `rowLabelWidth?`, `format?: "decimal" | "percent" | "integer" = "decimal"`, `colorize?: boolean = true`, `colorScale?: "heat" | "strength" = "heat"`.
346
- - `Heatmap`: `data: number[][]`, `xLabels`, `yLabels`, `c`, `labels?`, `title?`, `cellSize?: number = 52`, `cellWidth?`, `cellHeight?`, `rowLabelWidth?`, `colorScale?: "heat" | "strength"`.
347
- - `TiledMatrix`: `rows`, `cols`, `c`, `regions?: TiledMatrixRegion[] = []`, `title?`, `subtitle?`, `cellSize?: number = 24`, `gap?: number = 3`, `tone?: ToneName = "blue"`, `muted?: boolean = false`, `crossedOut?: boolean = false`. `TiledMatrixRegion`: `rowStart`, `rowEnd`, `colStart`, `colEnd`, `tone?`.
348
-
349
- Charts and plots:
350
-
351
- - `ChartFrame`: `children`, `c`, `title?`, `subtitle?`, `legend?: ChartLegendItem[]`, `footer?`, `width?: number | string = "100%"`, `height?`, `padding?: number = 16`. `ChartLegendItem`: `label`, `color: ColorName | string`.
352
- - `PieChart`: `segments: DonutChartSegment[]`, `c`, `title?`, `subtitle?`, `width?: number = 360`, `height?: number = 240`, `size?`, `format?: ChartValueFormat = "decimal"`, `showLegend?: boolean = true`, `footer?`. Each segment has `label`, `value`, optional `color`, and optional `valueLabel`. Values must be finite and non-negative; zero slices are omitted. The full-circle pie shows part-to-whole proportions, with values and shares in the legend. Use `examples/pie-chart.tsx` for a complete frame.
353
- - `DonutChart`: `segments: DonutChartSegment[]`, `c`, `title?`, `subtitle?`, `width?: number = 360`, `height?: number = 230`, `size?`, `thickness?`, `format?: ChartValueFormat = "decimal"`, `centerLabel?`, `centerValue?`, `showLegend?: boolean = true`, `footer?`. `DonutChartSegment`: `label`, `value`, `color?`, `valueLabel?`.
354
- - `BarChart`: `data: BarChartDatum[]`, `c`, `title?`, `subtitle?`, `width?: number = 320`, `height?: number = 220`, `min?`, `max?`, `format?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `showValues?: boolean = true`, `yAxisLabel?`, `footer?`. `BarChartDatum`: `label`, `value`, `color?`, `valueLabel?`.
355
- - `ParetoBarChart`: `data: BarChartDatum[]`, `c`, `title?`, `subtitle?`, `width?: number = 520`, `height?: number = 300`, `format?: ChartValueFormat = "integer"`, `showGrid?: boolean = true`, `showValues?: boolean = true`, `footer?`. A classic categorical Pareto chart with descending bars and a cumulative percentage line, separate value/share axes, and stable tie order. Values must be finite and non-negative. Sorting preserves the input array. A positive total ends at 100%; an all-zero total stays at 0%. Use this for the causes behind a total, and `ParetoChart` for a non-dominated scatter frontier. See `examples/pareto-bar-chart.tsx`.
356
- - `LineChart`: `series: LineChartSeries[]`, `c`, `title?`, `subtitle?`, `width?: number = 420`, `height?: number = 240`, `labels?`, `min?`, `max?`, `format?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `showPoints?: boolean = true`, `yAxisLabel?`, `footer?`. `LineChartSeries`: `name`, `points`, `color?`, `area?`.
357
- - `ScatterPlot`: `points: ScatterPoint[]`, `c`, `title?`, `subtitle?`, `width?: number = 380`, `height?: number = 260`, `xMin?`, `xMax?`, `yMin?`, `yMax?`, `xAxisLabel?`, `yAxisLabel?`, `formatX?: ChartValueFormat = "decimal"`, `formatY?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `footer?`. `ScatterPoint`: `x`, `y`, `label?`, `color?`, `size?`.
358
- - `ParetoChart`: `points: ScatterPoint[]`, `c`, `title?`, `subtitle?`, `width?: number = 640`, `height?: number = 360`, `xMin?`, `xMax?`, `yMin?`, `yMax?`, `xAxisLabel?`, `yAxisLabel?`, `formatX?: ChartValueFormat = "decimal"`, `formatY?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `xScale?: "linear" | "log" = "linear"`, `xObjective?: "minimize" | "maximize" = "minimize"`, `yObjective?: "minimize" | "maximize" = "maximize"`, `frontierColor?`, `showGoal?: boolean = true`, `goalLabel?`, `footer?`. It detects non-dominated points automatically; logarithmic x scales omit non-positive points.
359
- - `QuadrantChart`: `points: ScatterPoint[]`, `regions`, `c`, `title?`, `subtitle?`, `width?: number = 700`, `height?: number = 360`, `xMin?`, `xMax?`, `yMin?`, `yMax?`, `xThreshold?`, `yThreshold?`, `xAxisLabel?`, `yAxisLabel?`, `formatX?: ChartValueFormat = "decimal"`, `formatY?: ChartValueFormat = "decimal"`, `showTicks?: boolean = false`, `showGrid?: boolean = false`, `footer?`. Without explicit domains, points use normalized 0-1 coordinates and thresholds default to centered splits. `regions`: `{ topLeft, topRight, bottomLeft, bottomRight }`, each `QuadrantRegion`: `label`, `detail?`, `color?`, `emphasis?`.
360
- - `IntervalPlot`: `data: IntervalDatum[]`, `c`, `title?`, `subtitle?`, `width?: number = 640`, `height?: number = 220`, `min?`, `max?`, `format?: ChartValueFormat = "decimal"`, `axisLabel?`, `footer?`. `IntervalDatum`: `label`, `low`, `mid`, `high`, `color?`, `lowLabel?`, `midLabel?`, `highLabel?`.
361
- - `StackedBar`: `segments: StackedBarSegment[]`, `c`, `width?: number = 480`, `height?: number = 68`, `title?`, `subtitle?`, `showLegend?: boolean = true`. `StackedBarSegment`: `label`, `value`, `color?`, `valueLabel?`.
362
- - `MiniBarChart`: `data: MiniBarDatum[]`, `c`, `max?`, `minBarHeight?: number = 8`, `height?: number = 92`, `barWidth?: number = 22`, `gap?: number = 10`, `radius?: number = 7`, `fontSize?: number = 11`, `showValues?: boolean = false`. `MiniBarDatum`: `label`, `value`, `tone?`, `color?`, `valueLabel?`, `opacity?`.
363
- - `AxisPlot`: `c`, `width`, `height`, `xMin?: number = -1`, `xMax?: number = 1`, `yMin?: number = -1`, `yMax?: number = 1`, `padding?: number = 18`, `showFrame?: boolean = true`, `showAxes?: boolean = true`, `showGrid?: boolean = false`, `gridCount?: number = 5`, `frameRx?: number = 8`, `frameFill?`, `frameStroke?`, `axisColor?`, `points?: AxisPlotPoint[] = []`, `vectors?: AxisPlotVector[] = []`, `paths?: AxisPlotPath[] = []`, `xAxisLabel?`, `yAxisLabel?`, `children?`.
364
- - `AxisPlotPoint`: `x`, `y`, `fill?`, `tone?`, `r?`, `stroke?`, `strokeWidth?`, `opacity?`.
365
- - `AxisPlotVector`: `x1`, `y1`, `x2`, `y2`, `color?`, `tone?`, `strokeWidth?`, `opacity?`, `arrow?`, `arrowSize?`, `showStartDot?`, `showEndDot?`, `dotRadius?`.
366
- - `AxisPlotPath`: `points: Array<{ x, y }>`, `color?`, `tone?`, `strokeWidth?`, `opacity?`, `interpolation?: "linear" | "step-after"`, `dashed?`.
367
- - `ChartValueFormat`: `"decimal" | "percent" | "integer" | "compact" | ((value: number) => string)`.
368
-
369
- SVG and geometry helpers:
370
-
371
- - `SvgFrame`: `key?`, `x?: number = 0`, `y?: number = 0`, `width`, `height`, `c`, `rx?: number = 8`, `fill?`, `stroke?`, `strokeWidth?: number = 1`, `opacity?`.
372
- - `SvgPoint`: `key?`, `cx`, `cy`, `r?: number = 5`, `fill`, `stroke?`, `strokeWidth?`, `opacity?`.
373
- - `SvgMathText`: positioned HTML overlay with `text`, `x`, `y`, `fill`, `fontSize?: number = 13`, `fontFamily?: string = "JetBrains Mono"`, `fontWeight?: number = 800`, `textAnchor?: "start" | "middle" | "end" = "middle"`, `dominantBaseline?: string = "middle"`, `opacity?: number = 1`. Place it beside, not inside, raw SVG geometry in a `position: "relative"` container.
374
- - `SvgFrame` pairs well with `VectorArrow`, `VectorSegment`, `SvgPoint`, `DotPoint`, `DashedLine`, and `Legend` inside custom SVG.
375
- - `Arrow`: `direction?: "down" | "right" | "up" | "left" = "down"`, `label?`, `length?: number = 40`, `c`, `color?`.
376
- - `VectorArrow`: `key?`, `x1`, `y1`, `x2`, `y2`, `color`, `strokeWidth?: number = 2`, `arrowSize?: number = 2.2`, `opacity?: number = 1`.
377
- - `VectorSegment`: `key?`, `x1`, `y1`, `x2`, `y2`, `color`, `strokeWidth?: number = 4`, `opacity?: number = 1`, `showStartDot?: boolean = false`, `showEndDot?: boolean = true`, `dotRadius?: number = 4.5`.
378
- - `Box`: `label`, `c`, `color?: ColorName = "primary"`, `width?`, `height?`, `fontSize?: number = 14`, `gradient?: boolean = false`, `sublabel?`, `icon?`, `radius?: number = 8`, `outlined?: boolean = false`.
379
- - `ArrowMarkerDef`: `id`, `color`, `size?: number = 5`.
380
- - `DotPoint`: `x`, `y`, `label`, `color`, `c`, `size?: number = 12`, `labelOffset?: { x?: number; y?: number }`.
381
- - `DashedLine`: `x1`, `y1`, `x2`, `y2`, `color`, `dotSpacing?: number = 8`, `dotSize?: number = 2`.
382
- - `Legend`: `items: LegendItem[]`, `c`, `title?`. `LegendItem`: `label`, `color`, `style?: "solid" | "dashed"`.
383
-
384
- Theme and render APIs:
385
-
386
- - `checkFrame(frame, options?)`: Check `{ scene: ReactNode }` or `{ create(theme): ReactNode }` inputs. Frame metadata accepts `source?`, `width?`, `height?`, and `autoSize?`. Options accept `themes?: ThemeMode[]`, `background?: "transparent" | "theme" | CSS color`, and `failOn?: "error" | "warning" | "info" | "never"`; defaults are both themes, transparent background, and errors only. `ok` means diagnostics pass `failOn`; `rendered` means every requested theme completed rendering. Reports include per-theme `dimensions` and `diagnostics`, plus `summary` severity counts.
387
- - `CHECK_DIAGNOSTIC_CODES`, `CheckDiagnostic`, `CheckDiagnosticCode`, `CheckDiagnosticLocation`, `CheckAutoSize`, `CheckAutoSizeAxes`, `CheckFrameInput`, `CheckFrameReport`, `CheckOptions`: Stable code list and TypeScript contracts for programmatic checks. Locations contain a React `path` or rendered `x`, `y`, `width`, and `height`; available element identifiers appear as `elementId` and `relatedElementIds` on diagnostics.
388
- - `getThemeColors(mode, preset?)`: `mode: ThemeMode`; `preset?: "default" | "engineering"`. Use `engineering` for flat technical-blog figures with a light gray palette, left-aligned black titles, pastel nodes, thin neutral connectors, compact corners, no shadows, Inter labels, and JetBrains Mono annotations. In a bare frame, set `preset = "engineering";` before the JSX. Add `background={c.bg}` to `Scene` for an opaque light gray canvas; omit it for alpha transparency.
389
- - `getToneColor(tone, c)`, `getToneFill(tone, c)`, `getToneGradient(tone)`, `getColor(name, c?)`, `getGradient(name)`, `heatColor(value)`.
390
- - `getReadableColor(name, c)`: returns the semantic color variant with greatest contrast against `c.bgCard`.
391
- - `getReadableToneColor(tone, c, background?)`: maps a tone to a readable semantic color and falls back to readable foreground text when contrast is below 4.5:1. `background` defaults to `c.bgCard`.
392
- - `getReadableTextColor(background, c)`: parses solid or alpha CSS colors and chooses a theme foreground meeting 4.5:1 contrast when possible.
393
- - `createPlotArea(width, height, margin)`: returns `PlotArea` geometry with inner width and height clamped to at least one pixel.
394
- - `renderToPng(element, options, createFn?, theme?)`: `element`, `options: RenderOptions`, `createFn?: (theme: "dark" | "light") => ReactNode`, `theme?: "dark" | "light"`.
395
- - `renderToPngWithOutput(...)`: same arguments as `renderToPng`; returns logical `width` / `height`, physical `pixelWidth` / `pixelHeight`, and painted `contentBounds`.
396
- - `CanvasOverflowError`: typed clipping failure from strict static or animated renders. Exposes `width`, `height`, `overflow`, and optional animation frame/scene/time/label metadata.
397
- - `Watermark`: JSX marker component for frame-module exports. Props are `WatermarkOptions` plus `children?: ReactNode`; children become the complete watermark body.
398
- - `WatermarkInput`: `boolean | string | WatermarkOptions | ReactElement<WatermarkElementProps>`. `true` uses Vizmatic defaults. A string sets the watermark text. A React element can be `<Watermark>...</Watermark>` or any custom element.
399
- - `WatermarkImageOptions`: `src`, `width?: number`, `height?: number`, `alt?: string`. Programmatic `src` should be a URL or data URI. CLI `--watermark-image` accepts URL, data URI, or local path.
400
- - `WatermarkOptions`: `text?: string | false`, `image?: string | WatermarkImageOptions`, `icon?: ReactNode | string | false`, `element?: ReactNode`, `position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" = "top-right"`, `opacity?: number`, `color?: string`.
401
- - `normalizeWatermark(input)`: converts boolean, string, object, or React-element `WatermarkInput` to `WatermarkOptions | undefined`.
402
- - `wrapWithBrand(element, width, height, theme?, label?)`: compatibility wrapper around `wrapWithWatermark`; theme defaults to `"dark"` and label defaults to `"Vizmatic"`.
403
- - `getFonts()`: lazily loads and caches bundled Satori font data for advanced integrations.
404
- - `loadAdditionalAsset(code, segment)`: Satori missing-glyph callback; resolves emoji segments from the compressed offline Twemoji bundle or public fallback and returns an empty font list for other codes.
405
- - `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `theme?: "dark" | "light" = "dark"` for direct-render watermark defaults, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean | "height" | "both" = true`, `scale?: number = 2`. Default autocrop retains 24 source pixels around detected content. Use `crop: "height"` when host layouts require stable width but should still trim extra vertical whitespace.
406
- - `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`, `scale?`.
407
- - `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`.
408
- - `defineAnimation({ initial, timeline, render, fps? })`: creates deterministic typed state animation. `fps` defaults to `20` and accepts integers from `1` to `50`.
409
- - `hold(duration, label?)`: keep current state for milliseconds.
410
- - `tween(to, { duration, easing?, interpolate?, label? })`: transition listed properties together. Easing is `"linear" | "ease-in" | "ease-out" | "ease-in-out"` or pure progress function.
411
- - `keyframe(value, label?)`: apply instant partial state update.
412
- - `parallel(tracks, label?)`: run property tracks concurrently; each track accepts `hold`, `tween`, and `keyframe` steps.
413
- - `sampleAnimation(animation, time)`: evaluate state at exact millisecond.
414
- - `sampleAnimationFrame(animation, time, { index, count, delay, fps })`: sample state and timeline context at an exact video timestamp.
415
- - `sampleAnimationFrames(animation, { fps? })`: return deterministic state/frame samples with GIF-compatible delays.
416
- - `analyzeAnimationCadence(animation, { fps? })`: return frame count, encoded duration, target interval, and delay range without rendering.
417
- - `renderAnimationGif(animation, options)`: stream timeline samples into GIF.
418
- - `renderAnimationVideo(animation, { width, height, outputPath, fps?, scale?, theme?, background?, watermark?, audioPath?, crf?, preset?, threads?, signal? })`: render typed TSX frames to H.264 MP4. Defaults to 30 fps and an opaque theme background; streams frames and checks overflow at each timestamp. FFmpeg is installed separately.
419
- - `renderRgbaVideo(renderFrame, { width, height, duration, outputPath, fps?, audioPath?, crf?, preset?, signal? })`: encode caller-painted RGBA frames without buffering the whole film.
420
- - `tracePolyline(points, progress)` and `pointAlongPath(points, progress)`: reveal and follow a path by arc length; `arcSwap(from, to, progress, options?)` exchanges positions along mirrored arcs; `smoothstep(progress)` clamps and eases progress.
421
- - `renderAnimationGifWithOutput(animation, options)`: same arguments and returns dimensions, input/encoded frame counts, delta-frame count, duration, and byte size.
422
- - `renderAnimatedGif(scenes, options)`: legacy `AnimatedScene[]` renderer for scene cuts and pixel transitions. It also accepts a defined animation.
423
- - `renderAnimatedGifWithOutput(scenes, options)`: same arguments as `renderAnimatedGif`; returns dimensions and encoding metrics.
424
- - `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
425
- - `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `fps?: number`, `deltaFrames?: boolean = true`, `background?: "theme" | "transparent" | CSS color = "theme"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`. Every actual frame is checked for overflow. Opaque GIFs encode changed rectangles; transparent GIFs stay full-frame for correct one-bit compositing. Use PNG/SVG when smooth alpha edges matter.
426
-
427
- ## Prop-aware examples
428
-
429
- ### Window + code + status
430
-
431
- ```tsx
432
- width = 1040;
433
- height = 560;
434
-
435
- <Scene title="Release gate" subtitle="tool output and checklist">
436
- <Row gap={18} align="stretch">
437
- <WindowFrame title="ci.log" variant="terminal" tone="green" width={520}>
438
- <CodeBlock
439
- fontSize={12}
440
- showLineNumbers
441
- lines={[
442
- { text: "pnpm typecheck", tone: "green", prefix: "$" },
443
- { text: "pnpm test", tone: "green", prefix: "$" },
444
- { text: "pnpm render:examples", tone: "cyan", prefix: "$" },
445
- ]}
446
- />
447
- </WindowFrame>
448
- <StatusList
449
- width={360}
450
- rows={[
451
- { label: "Types", detail: "clean", status: "check", tone: "green" },
452
- { label: "Visuals", detail: "dark/light generated", status: "check", tone: "cyan" },
453
- { label: "NPM", detail: "auth required", status: "warn", tone: "warm" },
454
- ]}
455
- />
456
- </Row>
457
- </Scene>
458
117
  ```
459
118
 
460
- ### Matrix + chart
119
+ ## Reference
461
120
 
462
- ```tsx
463
- width = 1040;
464
- height = 560;
465
-
466
- <Scene title="Attention audit" subtitle="weights, scores, and distribution">
467
- <Row gap={18} align="stretch">
468
- <Heatmap
469
- title="Attention"
470
- xLabels={["q1", "q2", "q3"]}
471
- yLabels={["k1", "k2", "k3"]}
472
- data={[
473
- [0.9, 0.2, 0.1],
474
- [0.4, 0.8, 0.2],
475
- [0.1, 0.3, 0.7],
476
- ]}
477
- />
478
- <Matrix
479
- title="Scores"
480
- format="decimal"
481
- rowLabels={["A", "B", "C"]}
482
- colLabels={["x", "y", "z"]}
483
- data={[
484
- [0.4, 0.7, 0.2],
485
- [0.5, 0.2, 0.8],
486
- ]}
487
- />
488
- <StackedBar
489
- width={300}
490
- title="Token budget"
491
- segments={[
492
- { label: "prompt", value: 42, color: "primary" },
493
- { label: "context", value: 38, color: "info" },
494
- { label: "answer", value: 20, color: "positive" },
495
- ]}
496
- />
497
- </Row>
498
- </Scene>
499
- ```
500
-
501
- ## Rendering rules
502
-
503
- - Use semantic tones instead of hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
504
- - For Datadog Engineering-style article diagrams, set `preset = "engineering";` and render the light theme. Keep each figure focused on one transition or tradeoff.
505
- - Use explicit sizes for final assets. Common sizes are `1040x560` for article figures, `1280x720` for slide frames, and `900x520` for compact diagrams.
506
- - During exploration, dimensions can be omitted. Vizmatic starts at `960x540` and grows to fit content.
507
- - Prefer alpha-transparent PNG/SVG backgrounds for blog embeds and docs cards. Use theme backgrounds only when the host surface is unknown or needs full-frame fill.
508
- - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` to keep layout stable.
509
- - Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
510
- - Omit `x` and `y` from `GraphDiagram` nodes for automatic layered layout and nested groups. Add both only when an ungrouped graph needs editorial manual control.
511
- - Render reusable assets in both themes with `--theme dark,light`.
512
- - Run `vizmatic check <frame> --theme dark,light --json` before final render and fix every error.
513
- - Use GIF only when motion explains state change. Prefer `createAnimation(theme)` with `hold` and `tween`, keep timelines short, match terminal and initial visuals for infinite loops, and keep static `create(theme)` fallback. Sampling follows exact cadence boundaries and includes terminal state. Use `analyzeAnimationCadence` when timing must be audited. Use `createScenes(theme)` only for deliberate cuts or crossfades.
514
- - If render fails with `Canvas overflow detected`, increase the canvas, reduce content, or remove strict sizing. Do not ignore the error.
515
- - Confirm generated files exist and open at least one image before finishing.
516
-
517
- ## Common recipes
518
-
519
- ### RAG graph
520
-
521
- ```tsx
522
- width = 1040;
523
- height = 560;
524
-
525
- <Scene title="RAG control graph" subtitle="retrieval with a citation check" align="center">
526
- <GraphDiagram
527
- width={820}
528
- height={390}
529
- nodeWidth={132}
530
- rankGap={44}
531
- nodes={[
532
- { id: "query", label: "Query", detail: "intent", tone: "blue" },
533
- { id: "retrieve", label: "Retrieve", detail: "top-k docs", tone: "cyan" },
534
- { id: "rerank", label: "Rerank", detail: "quality gate", tone: "warm" },
535
- { id: "answer", label: "Answer", detail: "grounded draft", tone: "green" },
536
- { id: "verify", label: "Verify", detail: "citations", tone: "critical" },
537
- ]}
538
- edges={[
539
- { from: "query", to: "retrieve", label: "search", tone: "blue" },
540
- { from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
541
- { from: "rerank", to: "answer", label: "context", tone: "green" },
542
- { from: "answer", to: "verify", label: "claims", tone: "critical" },
543
- ]}
544
- />
545
- </Scene>
546
- ```
547
-
548
- ### Evaluation dashboard
549
-
550
- ```tsx
551
- width = 1040;
552
- height = 620;
553
-
554
- <Scene title="Evaluation snapshot" subtitle="charts inherit theme, labels, and contrast">
555
- <Row gap={18} align="stretch">
556
- <BarChart
557
- width={440}
558
- height={260}
559
- title="Pass rate by task"
560
- format="percent"
561
- data={[
562
- { label: "tools", value: 0.82, color: "positive" },
563
- { label: "math", value: 0.71, color: "secondary" },
564
- { label: "code", value: 0.77, color: "primary" },
565
- { label: "long", value: 0.58, color: "warning" },
566
- ]}
567
- />
568
- <LineChart
569
- width={440}
570
- height={260}
571
- title="Quality over releases"
572
- format="percent"
573
- labels={["v1", "v2", "v3", "v4", "v5"]}
574
- series={[
575
- { name: "quality", points: [0.55, 0.61, 0.69, 0.74, 0.81], color: "positive", area: true },
576
- { name: "latency", points: [0.72, 0.69, 0.66, 0.62, 0.59], color: "warning" },
577
- ]}
578
- />
579
- </Row>
580
- </Scene>
581
- ```
121
+ - [CLI](https://bvolpato.github.io/vizmatic/docs/cli.html) and [Exporting](https://bvolpato.github.io/vizmatic/docs/exporting.html): every flag.
122
+ - [Animations](https://bvolpato.github.io/vizmatic/docs/animations.html), [Objects](https://bvolpato.github.io/vizmatic/docs/objects.html), [Camera](https://bvolpato.github.io/vizmatic/docs/camera.html), and [3D](https://bvolpato.github.io/vizmatic/docs/three-d.html): the film API.
123
+ - [Figure recipes](https://bvolpato.github.io/vizmatic/docs/figure-recipes.html) and [Figures reference](https://bvolpato.github.io/vizmatic/docs/figures.html): component props and complete frames.
124
+ - [Science guide](https://github.com/bvolpato/vizmatic/blob/main/SCIENCE.md): accurate diagrams for math, physics, chemistry, and machine learning.
125
+ - [`llms-full.txt`](https://bvolpato.github.io/vizmatic/llms-full.txt): this prompt, all guides, and the component catalog.
582
126
 
583
127
  ## Final response
584
128
 
585
129
  After creating a visual, report:
586
130
 
587
131
  - files created or changed
588
- - render command used
589
- - output image paths, including GIF paths when generated
590
- - whether dark/light variants rendered
591
- - whether structured validation passed
132
+ - the exact render command used
133
+ - output paths
134
+ - which looks or themes rendered
135
+ - whether `vizmatic check` passed
592
136
  - any overflow or layout fixes made