vizmatic 0.1.22 → 0.1.24

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 (53) hide show
  1. package/PROMPT.md +33 -10
  2. package/README.md +43 -34
  3. package/assets/THIRD_PARTY_LICENSES.md +2 -1
  4. package/assets/licenses/OFL-1.1.txt +80 -0
  5. package/assets/licenses/twemoji-svg-MIT.txt +21 -0
  6. package/dist/cli.js +1182 -293
  7. package/dist/index.cjs +1078 -267
  8. package/dist/index.d.cts +91 -3
  9. package/dist/index.d.ts +91 -3
  10. package/dist/index.js +1074 -267
  11. package/examples/README.md +17 -16
  12. package/examples/building-blocks.tsx +85 -0
  13. package/examples/vizmatic-bare.d.ts +4 -0
  14. package/package.json +5 -4
  15. package/docs/PROMPT.md +0 -503
  16. package/docs/assets/examples/.gitkeep +0 -1
  17. package/docs/assets/examples/agent-pipeline_dark.png +0 -0
  18. package/docs/assets/examples/agent-pipeline_light.png +0 -0
  19. package/docs/assets/examples/animated-pipeline_dark.gif +0 -0
  20. package/docs/assets/examples/animated-pipeline_dark.png +0 -0
  21. package/docs/assets/examples/animated-pipeline_light.gif +0 -0
  22. package/docs/assets/examples/animated-pipeline_light.png +0 -0
  23. package/docs/assets/examples/attention-head_dark.png +0 -0
  24. package/docs/assets/examples/attention-head_light.png +0 -0
  25. package/docs/assets/examples/embedding-map_dark.png +0 -0
  26. package/docs/assets/examples/embedding-map_light.png +0 -0
  27. package/docs/assets/examples/eval-dashboard_dark.png +0 -0
  28. package/docs/assets/examples/eval-dashboard_light.png +0 -0
  29. package/docs/assets/examples/gif-manifest.json +0 -12
  30. package/docs/assets/examples/manifest.json +0 -124
  31. package/docs/assets/examples/model-router_dark.png +0 -0
  32. package/docs/assets/examples/model-router_light.png +0 -0
  33. package/docs/assets/examples/presentation-frame_dark.png +0 -0
  34. package/docs/assets/examples/presentation-frame_light.png +0 -0
  35. package/docs/assets/examples/rag-graph_dark.png +0 -0
  36. package/docs/assets/examples/rag-graph_light.png +0 -0
  37. package/docs/assets/examples/release-card_dark.png +0 -0
  38. package/docs/assets/examples/release-card_light.png +0 -0
  39. package/docs/assets/examples/research-landscape_dark.png +0 -0
  40. package/docs/assets/examples/research-landscape_light.png +0 -0
  41. package/docs/assets/examples/sources.json +0 -152
  42. package/docs/assets/examples/spec-anatomy_dark.png +0 -0
  43. package/docs/assets/examples/spec-anatomy_light.png +0 -0
  44. package/docs/assets/examples/theme-background_dark.png +0 -0
  45. package/docs/assets/examples/theme-background_light.png +0 -0
  46. package/docs/assets/examples/theme-system_dark.png +0 -0
  47. package/docs/assets/examples/theme-system_light.png +0 -0
  48. package/docs/assets/examples/token-matrix_dark.png +0 -0
  49. package/docs/assets/examples/token-matrix_light.png +0 -0
  50. package/docs/assets/examples/transparent-badge_dark.png +0 -0
  51. package/docs/assets/examples/transparent-badge_light.png +0 -0
  52. package/docs/assets/icon.svg +0 -16
  53. package/docs/assets/logo.svg +0 -30
package/PROMPT.md CHANGED
@@ -2,22 +2,39 @@
2
2
 
3
3
  Use Vizmatic to create polished, theme-aware diagrams, figures, dashboards, presentation frames, and animated GIFs from structured React scene primitives.
4
4
 
5
- ## Install Or Run
6
-
7
- Use the package manager already present in the project.
5
+ ## Fastest Path
8
6
 
9
7
  Install the CLI once:
10
8
 
11
9
  ```bash
12
- pnpm add -g vizmatic
10
+ npm install -g vizmatic
11
+ ```
12
+
13
+ Create `frame.tsx`:
14
+
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>
13
26
  ```
14
27
 
15
- Then render any frame directly:
28
+ Render dark and light assets:
16
29
 
17
30
  ```bash
18
31
  vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
19
32
  ```
20
33
 
34
+ ## Project Installation
35
+
36
+ Use the package manager already present in the project.
37
+
21
38
  Install in the project when the project needs scripts, editor types, or direct renderer APIs:
22
39
 
23
40
  ```bash
@@ -32,7 +49,7 @@ pnpm add github:bvolpato/vizmatic react
32
49
 
33
50
  For npm/yarn/bun projects, use the equivalent package-manager command.
34
51
 
35
- ## Create a frame
52
+ ## Larger Example
36
53
 
37
54
  Create `frames/agent-pipeline.tsx`:
38
55
 
@@ -105,6 +122,8 @@ Render it:
105
122
  vizmatic frames --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right
106
123
  ```
107
124
 
125
+ The generated `manifest.json` keeps `outputs` for compatibility and adds `outputDetails` with each file's theme, path, width, and height.
126
+
108
127
  PNG and SVG renders use alpha-transparent canvas backgrounds by default. Use the actual theme background when the host needs a full-frame image:
109
128
 
110
129
  ```bash
@@ -247,6 +266,7 @@ Cards, labels, and compact UI:
247
266
  - `TextLabel`: `text`, `c`, `variant?: keyof typography = "body"`, `color?`, `fontSize?`, `fontWeight?`, `width?`, `align?: "left" | "center" | "right" = "left"`, `math?: boolean = false`, `mono?: boolean = false`.
248
267
  - `MathText`: `text`. Returns formatted unicode-ish math text for simple `_` and `^` notation.
249
268
  - `formatMathText(text)`: `text: string`.
269
+ - `Icon`: `name`, `c`, `tone?: ToneName = "blue"`, `color?`, `size?: number = 24`, `strokeWidth?: number = 2`, `label?`, `muted?: boolean = false`. `IconName`: `"agent" | "chart" | "check" | "code" | "database" | "file" | "git" | "globe" | "image" | "layers" | "lock" | "play" | "spark" | "terminal" | "tool" | "warning"`.
250
270
  - `ToneStrip`: `tone`, `width?: number = 34`, `height?: number = 4`.
251
271
  - `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`.
252
272
  - `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 = 10`, `valueColor?`.
@@ -264,6 +284,7 @@ Lists, tables, status, and comparison:
264
284
  - `ProgressList`: `rows: ProgressRowSpec[]`, `c`, `gap?: number = 8`, `labelWidth?`, `valueWidth?`, `barHeight?`, `fontSize?`. `ProgressRowSpec`: `label`, `value`, `valueLabel?`, `tone?`, `muted?`.
265
285
  - `StatusRow`: `label`, `detail?`, `status?: "check" | "cross" | "warn" | "info" | "pending" | "dot" = "check"`, `tone?`, `c`, `boxed?: boolean = true`, `fontSize?: number = 11`, `width?`, `math?: boolean = false`.
266
286
  - `StatusList`: `rows: StatusRowSpec[]`, `c`, `gap?: number = 7`, `boxed?: boolean = true`, `fontSize?`, `width?`, `math?: boolean = false`. `StatusRowSpec`: `label`, `detail?`, `status?`, `tone?`.
287
+ - `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?`.
267
288
  - `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?`.
268
289
  - `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?`.
269
290
  - `DataTable`: `rows: ReactNode[][]`, `c`, `cellWidth?: number = 54`, `firstColWidth?: number = cellWidth`, `cellHeight?: number = 28`, `gap?: number = 5`, `headerRows?: number = 1`, `headerCols?: number = 1`, `fontSize?: number = 10`, `math?: boolean = false`.
@@ -286,6 +307,7 @@ Graphs and networks:
286
307
 
287
308
  - `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?`.
288
309
  - `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `padding?: number = 28`. `GraphDiagramNode`: `id`, `label`, `detail?`, `x`, `y`, `tone?`, `muted?`, `width?`, `height?`. `GraphDiagramEdge`: `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`.
310
+ - `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?`.
289
311
 
290
312
  Matrices and heatmaps:
291
313
 
@@ -296,6 +318,7 @@ Matrices and heatmaps:
296
318
  Charts and plots:
297
319
 
298
320
  - `ChartFrame`: `children`, `c`, `title?`, `subtitle?`, `legend?: ChartLegendItem[]`, `footer?`, `width?: number | string = "100%"`, `height?`, `padding?: number = 16`. `ChartLegendItem`: `label`, `color: ColorName | string`.
321
+ - `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?`.
299
322
  - `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?`.
300
323
  - `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?`.
301
324
  - `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?`.
@@ -333,12 +356,12 @@ Theme and render APIs:
333
356
  - `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.
334
357
  - `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.
335
358
  - `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`.
336
- - `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean | "height" | "both" = true`, `scale?: number = 2`. Use `crop: "height"` when host layouts require stable width but should still trim extra vertical whitespace.
337
- - `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `watermark?`, `brand?`, `scale?`.
338
- - `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `watermark?`, `brand?`.
359
+ - `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`. Use `crop: "height"` when host layouts require stable width but should still trim extra vertical whitespace.
360
+ - `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`, `scale?`.
361
+ - `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`.
339
362
  - `renderAnimatedGif(scenes, options)`: `scenes: AnimatedScene[]`, `options: AnimationOptions`.
340
363
  - `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
341
- - `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `background?: "theme" | "transparent" | CSS color = "theme"` for GIF reliability, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`.
364
+ - `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `background?: "theme" | "transparent" | CSS color = "theme"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`. Transparent GIFs use one-bit transparency; use PNG/SVG when smooth alpha edges matter.
342
365
 
343
366
  ## Prop-aware examples
344
367
 
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <img src="docs/assets/logo.svg" alt="Vizmatic logo" width="460" />
2
+ <img src="https://bvolpato.github.io/vizmatic/assets/logo.svg" alt="Vizmatic logo" width="460" />
3
3
  </p>
4
4
 
5
5
  <p align="center">
@@ -15,7 +15,7 @@
15
15
  </p>
16
16
 
17
17
  <p align="center">
18
- <img src="docs/assets/examples/animated-pipeline_dark.gif" alt="Vizmatic animated render pipeline" width="760" />
18
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/animated-pipeline_dark.gif" alt="Vizmatic animated render pipeline" width="760" />
19
19
  </p>
20
20
 
21
21
  <p align="center">
@@ -35,10 +35,26 @@
35
35
  Install the CLI once:
36
36
 
37
37
  ```bash
38
- pnpm add -g vizmatic
38
+ npm install -g vizmatic
39
39
  ```
40
40
 
41
- Then render any frame directly:
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: "artifact", tone: "green" },
50
+ ]}
51
+ />
52
+ </Scene>
53
+ ```
54
+
55
+ `Scene` title and subtitle are optional. Omit both when surrounding copy already names the visual.
56
+
57
+ Render it directly:
42
58
 
43
59
  ```bash
44
60
  vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
@@ -136,32 +152,16 @@ rm -rf ~/.agents/skills/vizmatic
136
152
  cp -R "$tmp/vizmatic/.agents/skills/vizmatic" ~/.agents/skills/vizmatic
137
153
  ```
138
154
 
139
- Create a frame:
155
+ ## Rendering Options
140
156
 
141
- ```tsx
142
- width = 1040;
143
- height = 560;
144
-
145
- <Scene title="Agent visual pipeline">
146
- <Flow
147
- stages={[
148
- { title: "Prompt", subtitle: "intent", tone: "blue" },
149
- { title: "Scene spec", subtitle: "typed structure", tone: "purple" },
150
- { title: "PNG / SVG / GIF", subtitle: "rendered artifact", tone: "green" },
151
- ]}
152
- />
153
- </Scene>
154
- ```
155
-
156
- `Scene` title and subtitle are optional. Omit both for visual-only figures, badges, inline blog diagrams, or frames where surrounding copy already supplies the title.
157
-
158
- Render it:
157
+ Add optional branding:
159
158
 
160
159
  ```bash
161
160
  vizmatic ./frame.tsx --out ./dist/frames --theme dark,light --watermark "Acme" --watermark-image ./logo.svg
162
161
  ```
163
162
 
164
163
  The PNG canvas is alpha-transparent by default. Use `--background theme` for an opaque theme-colored frame, or set `background={c.bg}` on `Scene` / `Canvas`.
164
+ Each output directory includes `manifest.json`. `outputs` lists generated files; `outputDetails` records theme, path, and exact rendered dimensions for each file.
165
165
 
166
166
  Render an animation:
167
167
 
@@ -207,6 +207,10 @@ Vizmatic gives them a constrained visual language:
207
207
 
208
208
  | Need | Vizmatic answer |
209
209
  |---|---|
210
+ | Richer figures than Mermaid | Charts, cards, matrices, timelines, trees, icons, and free composition |
211
+ | Deterministic output unlike image generation | Source-controlled TSX stays editable and renders consistently |
212
+ | Headless output without browser screenshots | Node renderer produces assets directly in local workflows and CI |
213
+ | Dark and light variants | One command renders both themes from semantic color tokens |
210
214
  | Rich educational illustrations | React primitives rendered through Satori and resvg |
211
215
  | Theme-aware output | Semantic tones and dark/light theme tokens |
212
216
  | Agent-friendly authoring | JSX scene modules with simple props |
@@ -218,19 +222,19 @@ Vizmatic gives them a constrained visual language:
218
222
  ## Gallery
219
223
 
220
224
  <p>
221
- <img src="docs/assets/examples/animated-pipeline_dark.gif" alt="Animated pipeline" width="380" />
222
- <img src="docs/assets/examples/attention-head_dark.png" alt="Attention head" width="380" />
225
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/animated-pipeline_dark.gif" alt="Animated pipeline" width="380" />
226
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/attention-head_dark.png" alt="Attention head" width="380" />
223
227
  </p>
224
228
  <p>
225
- <img src="docs/assets/examples/rag-graph_dark.png" alt="RAG graph" width="380" />
226
- <img src="docs/assets/examples/eval-dashboard_dark.png" alt="Evaluation dashboard" width="380" />
229
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/rag-graph_dark.png" alt="RAG graph" width="380" />
230
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/eval-dashboard_dark.png" alt="Evaluation dashboard" width="380" />
227
231
  </p>
228
232
  <p>
229
- <img src="docs/assets/examples/token-matrix_dark.png" alt="Token matrix" width="380" />
230
- <img src="docs/assets/examples/theme-system_dark.png" alt="Theme system" width="380" />
233
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/token-matrix_dark.png" alt="Token matrix" width="380" />
234
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/theme-system_dark.png" alt="Theme system" width="380" />
231
235
  </p>
232
236
  <p>
233
- <img src="docs/assets/examples/presentation-frame_dark.png" alt="Presentation frame" width="380" />
237
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/presentation-frame_dark.png" alt="Presentation frame" width="380" />
234
238
  </p>
235
239
 
236
240
  More examples live in [`examples/`](examples) and on the [website](https://bvolpato.github.io/vizmatic/).
@@ -417,7 +421,7 @@ Vizmatic treats generated visuals as source-controlled build artifacts. CI fails
417
421
 
418
422
  | Gate | What it protects |
419
423
  |---|---|
420
- | `pnpm lint` | Static TypeScript coverage across `src/`, `examples/`, `scripts/`, and tests |
424
+ | `pnpm lint` | TypeScript coverage plus GitHub Actions validation with actionlint |
421
425
  | `pnpm test` | Render pipeline behavior, watermark options, and output validation |
422
426
  | `pnpm render:examples` | Dark/light PNGs, animated GIFs, source snippets, and website HTML |
423
427
  | `pnpm docs:check` | Local asset references, `PROMPT.md` sync, source modal themes, and homepage affordances |
@@ -487,6 +491,7 @@ Vizmatic exports a fairly complete visual kit. Common cases should use these pri
487
491
  | `ValuePill` | Compact value badge for numbers or short state labels. |
488
492
  | `GradientChip` | Small colored chip with gradient fill for legends and tone keys. |
489
493
  | `ToneStrip` | Small semantic accent strip for visual grouping. |
494
+ | `Icon` | Curated SVG icon set for cards, callouts, compact rows, and presentation frames. |
490
495
  | `TextLabel` | Wrapping-safe text with variant, color, math formatting, width, and alignment. |
491
496
  | `MathText` / `formatMathText` | Converts simple `x_i` / `x^2` style strings into readable unicode math text. |
492
497
  | `SvgMathText` | SVG text helper for math labels inside custom plots. |
@@ -512,6 +517,7 @@ Vizmatic exports a fairly complete visual kit. Common cases should use these pri
512
517
  | `DetailList` | Compact repeated detail rows inside panels and flow stages. |
513
518
  | `ProgressRow` / `ProgressList` | Progress bars with labels, values, tones, and optional math text. |
514
519
  | `StatusRow` / `StatusList` | Check, cross, warning, info, pending, and dot rows. |
520
+ | `Timeline` | Vertical or horizontal milestone list with tone markers, time labels, and compact event cards. |
515
521
  | `KeyValueList` | Structured label/value rows for configs and metadata. |
516
522
  | `CodeBlock` | Themed code panel with highlighted lines and optional annotations. |
517
523
  | `EquationCard` | Formula card with title, equation, and supporting detail. |
@@ -525,6 +531,7 @@ Vizmatic exports a fairly complete visual kit. Common cases should use these pri
525
531
  | `Pipeline` | Process pipeline with stage labels and a shared title. |
526
532
  | `LayeredNetwork` | Neural-network/DAG diagram with layers, nodes, active path, annotations, and formula. |
527
533
  | `GraphDiagram` | Positioned node-edge graph with labels, dashed/muted edges, and tone-aware nodes. |
534
+ | `TreeDiagram` | Auto-laid parent/child hierarchy for ownership, routing, taxonomy, and decision trees. |
528
535
 
529
536
  #### Matrices, tables, and grids
530
537
 
@@ -542,6 +549,7 @@ Vizmatic exports a fairly complete visual kit. Common cases should use these pri
542
549
  |---|---|
543
550
  | `ChartFrame` | Shared chart wrapper with title, subtitle, footer, and theme-aware shell. |
544
551
  | `AxisPlot` | Low-level axis plot for custom lines, paths, and plotted values. |
552
+ | `DonutChart` | Part-to-whole chart with center label/value, segment labels, and shared chart styling. |
545
553
  | `MiniBarChart` | Small bar chart for cards and dashboards. |
546
554
  | `StackedBar` | Segmented horizontal bar with labels and percentages. |
547
555
  | `BarChart` | Full bar chart with ticks, labels, values, grids, and formats. |
@@ -571,7 +579,7 @@ Vizmatic exports a fairly complete visual kit. Common cases should use these pri
571
579
  import { renderAnimatedGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
572
580
  ```
573
581
 
574
- `renderToPng` renders at 2x scale by default, uses alpha transparency unless `background` is set, checks for clipped content, crops extra vertical whitespace, and can apply an optional watermark. Use `background: "theme"` to paint `c.bg`, or any CSS color string for a fixed fill. Use `crop: "height"` when a downstream layout needs fixed width but still wants vertical whitespace trimmed. Use `watermark.image` for a URL or data URI; the CLI also accepts local image paths through `--watermark-image`. For frame-owned branding, export `watermark = <Watermark>...</Watermark>` from the frame module. `brand` still works as a compatibility alias.
582
+ `renderToPng` renders at 2x scale by default, uses alpha transparency unless `background` is set, checks for clipped content, crops extra vertical whitespace, and can apply an optional watermark. Use `background: "theme"` to paint `c.bg`, or any CSS color string for a fixed fill. Pass `theme: "light"` when direct renderer calls should use light watermark defaults. Use `crop: "height"` when a downstream layout needs fixed width but still wants vertical whitespace trimmed. Use `watermark.image` for a URL or data URI; the CLI also accepts local image paths through `--watermark-image`. For frame-owned branding, export `watermark = <Watermark>...</Watermark>` from the frame module. `brand` still works as a compatibility alias.
575
583
 
576
584
  ```ts
577
585
  await renderToPng(element, {
@@ -579,6 +587,7 @@ await renderToPng(element, {
579
587
  height: 560,
580
588
  outputPath: "dist/frame.png",
581
589
  background: "theme",
590
+ theme: "dark",
582
591
  watermark: { text: "Your Product", image: "https://example.com/logo.svg", position: "top-right" },
583
592
  crop: "height",
584
593
  scale: 2,
@@ -599,7 +608,7 @@ export const watermark = (
599
608
  )
600
609
  ```
601
610
 
602
- `renderAnimatedGif` turns ordered scene states into a looping GIF.
611
+ `renderAnimatedGif` turns ordered scene states into a looping GIF. Transparent GIFs use GIF's one-bit transparency; PNG and SVG remain the better choice for full alpha edges.
603
612
 
604
613
  ```ts
605
614
  await renderAnimatedGif(createScenes("dark"), {
@@ -638,7 +647,7 @@ pnpm site:serve
638
647
 
639
648
  ## Publishing
640
649
 
641
- Preferred release path is the GitHub `Release` workflow. It runs the full verification gate, bumps the package version, publishes to npm with provenance, pushes the tag, and creates a GitHub release.
650
+ Preferred release path is the GitHub `Release` workflow. It runs the full verification gate, bumps the package version, publishes to npm with provenance, pushes the tag, and creates a GitHub release. Release notes always start with a "Changes since latest version" section containing the previous tag, current tag, compare link, and commits before GitHub's generated notes.
642
651
 
643
652
  ```bash
644
653
  gh workflow run release.yml -f version=patch
@@ -18,10 +18,11 @@ runtime fetches.
18
18
  Copyright 2022 Google LLC. All Rights Reserved.
19
19
  Source: https://github.com/notofonts/math
20
20
 
21
- SIL Open Font License 1.1 text: https://openfontlicense.org/open-font-license-official-text/
21
+ Full license: [`licenses/OFL-1.1.txt`](licenses/OFL-1.1.txt).
22
22
 
23
23
  ## Emoji
24
24
 
25
25
  - Twemoji SVG assets from `@twemoji/svg@15.0.0`: MIT.
26
26
  Copyright (c) 2023 Samuel Kopp.
27
27
  Source: https://github.com/boywithkeyboard/twemoji_svg
28
+ Full license: [`licenses/twemoji-svg-MIT.txt`](licenses/twemoji-svg-MIT.txt).
@@ -0,0 +1,80 @@
1
+ SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
2
+
3
+ PREAMBLE
4
+ The goals of the Open Font License (OFL) are to stimulate worldwide
5
+ development of collaborative font projects, to support the font creation
6
+ efforts of academic and linguistic communities, and to provide a free and
7
+ open framework in which fonts may be shared and improved in partnership with
8
+ others.
9
+
10
+ The OFL allows the licensed fonts to be used, studied, modified and
11
+ redistributed freely as long as they are not sold by themselves. The fonts,
12
+ including any derivative works, can be bundled, embedded, redistributed and/or
13
+ sold with any software provided that any reserved names are not used by
14
+ derivative works. The fonts and derivatives, however, cannot be released under
15
+ any other type of license. The requirement for fonts to remain under this
16
+ license does not apply to any document created using the fonts or their
17
+ derivatives.
18
+
19
+ DEFINITIONS
20
+ "Font Software" refers to the set of files released by the Copyright Holder(s)
21
+ under this license and clearly marked as such. This may include source files,
22
+ build scripts and documentation.
23
+
24
+ "Reserved Font Name" refers to any names specified as such after the copyright
25
+ statement(s).
26
+
27
+ "Original Version" refers to the collection of Font Software components as
28
+ distributed by the Copyright Holder(s).
29
+
30
+ "Modified Version" refers to any derivative made by adding to, deleting, or
31
+ substituting, in part or in whole, any of the components of the Original
32
+ Version, by changing formats or by porting the Font Software to a new
33
+ environment.
34
+
35
+ "Author" refers to any designer, engineer, programmer, technical writer or
36
+ other person who contributed to the Font Software.
37
+
38
+ PERMISSION & CONDITIONS
39
+ Permission is hereby granted, free of charge, to any person obtaining a copy of
40
+ the Font Software, to use, study, copy, merge, embed, modify, redistribute, and
41
+ sell modified and unmodified copies of the Font Software, subject to the
42
+ following conditions:
43
+
44
+ 1) Neither the Font Software nor any of its individual components, in Original
45
+ or Modified Versions, may be sold by itself.
46
+
47
+ 2) Original or Modified Versions of the Font Software may be bundled,
48
+ redistributed and/or sold with any software, provided that each copy contains
49
+ the above copyright notice and this license. These can be included either as
50
+ stand-alone text files, human-readable headers or in the appropriate
51
+ machine-readable metadata fields within text or binary files as long as those
52
+ fields can be easily viewed by the user.
53
+
54
+ 3) No Modified Version of the Font Software may use the Reserved Font Name(s)
55
+ unless explicit written permission is granted by the corresponding Copyright
56
+ Holder. This restriction only applies to the primary font name as presented to
57
+ the users.
58
+
59
+ 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font Software
60
+ shall not be used to promote, endorse or advertise any Modified Version,
61
+ except to acknowledge the contribution(s) of the Copyright Holder(s) and the
62
+ Author(s) or with their explicit written permission.
63
+
64
+ 5) The Font Software, modified or unmodified, in part or in whole, must be
65
+ distributed entirely under this license, and must not be distributed under any
66
+ other license. The requirement for fonts to remain under this license does not
67
+ apply to any document created using the Font Software.
68
+
69
+ TERMINATION
70
+ This license becomes null and void if any of the above conditions are not met.
71
+
72
+ DISCLAIMER
73
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
74
+ IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
75
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
76
+ TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR
77
+ ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL,
78
+ INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF
79
+ CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE
80
+ THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 Samuel Kopp
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.