vizmatic 0.1.28 → 0.1.29
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/PROMPT.md +12 -9
- package/README.md +57 -34
- package/dist/cli.js +237 -94
- package/dist/index.cjs +216 -87
- package/dist/index.d.cts +24 -58
- package/dist/index.d.ts +24 -58
- package/dist/index.js +214 -87
- package/examples/README.md +3 -2
- package/examples/engineering-flow.tsx +54 -0
- package/examples/vizmatic-bare.d.ts +1 -0
- package/package.json +2 -1
package/PROMPT.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
# Vizmatic
|
|
1
|
+
# Vizmatic agent prompt
|
|
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
|
-
##
|
|
5
|
+
## Quick start
|
|
6
6
|
|
|
7
|
-
Install the CLI once:
|
|
7
|
+
Vizmatic requires Node.js 20 or newer. Install the CLI once:
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
10
|
npm install -g vizmatic
|
|
@@ -31,7 +31,7 @@ Render dark and light assets:
|
|
|
31
31
|
vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
## Project
|
|
34
|
+
## Project installation
|
|
35
35
|
|
|
36
36
|
Use the package manager already present in the project.
|
|
37
37
|
|
|
@@ -49,7 +49,7 @@ pnpm add github:bvolpato/vizmatic react
|
|
|
49
49
|
|
|
50
50
|
For npm/yarn/bun projects, use the equivalent package-manager command.
|
|
51
51
|
|
|
52
|
-
## Larger
|
|
52
|
+
## Larger example
|
|
53
53
|
|
|
54
54
|
Create `frames/agent-pipeline.tsx`:
|
|
55
55
|
|
|
@@ -349,17 +349,19 @@ SVG and geometry helpers:
|
|
|
349
349
|
|
|
350
350
|
Theme and render APIs:
|
|
351
351
|
|
|
352
|
-
- `getThemeColors(mode)`: `mode: ThemeMode`.
|
|
353
|
-
- `getToneColor(tone, c)`, `getToneGradient(tone)`, `getColor(name, c?)`, `getGradient(name)`, `heatColor(value)`.
|
|
352
|
+
- `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.
|
|
353
|
+
- `getToneColor(tone, c)`, `getToneFill(tone, c)`, `getToneGradient(tone)`, `getColor(name, c?)`, `getGradient(name)`, `heatColor(value)`.
|
|
354
354
|
- `renderToPng(element, options, createFn?, theme?)`: `element`, `options: RenderOptions`, `createFn?: (theme: "dark" | "light") => ReactNode`, `theme?: "dark" | "light"`.
|
|
355
|
+
- `renderToPngWithOutput(...)`: same arguments as `renderToPng`; returns logical `width` / `height` and physical `pixelWidth` / `pixelHeight`.
|
|
355
356
|
- `Watermark`: JSX marker component for frame-module exports. Props are `WatermarkOptions` plus `children?: ReactNode`; children become the complete watermark body.
|
|
356
357
|
- `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.
|
|
357
358
|
- `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.
|
|
358
359
|
- `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`.
|
|
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
|
+
- `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.
|
|
360
361
|
- `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`, `scale?`.
|
|
361
362
|
- `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`.
|
|
362
363
|
- `renderAnimatedGif(scenes, options)`: `scenes: AnimatedScene[]`, `options: AnimationOptions`.
|
|
364
|
+
- `renderAnimatedGifWithOutput(scenes, options)`: same arguments as `renderAnimatedGif`; returns physical `width` and `height`.
|
|
363
365
|
- `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
|
|
364
366
|
- `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.
|
|
365
367
|
|
|
@@ -439,7 +441,8 @@ height = 560;
|
|
|
439
441
|
|
|
440
442
|
## Quality rules
|
|
441
443
|
|
|
442
|
-
- Use semantic tones
|
|
444
|
+
- Use semantic tones instead of hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
|
|
445
|
+
- For Datadog Engineering-style article diagrams, set `preset = "engineering";` and render the light theme. Keep each figure focused on one transition or tradeoff.
|
|
443
446
|
- Keep canvas sizes explicit. Good defaults: `1040x560` for article figures, `1280x720` for slide frames, `900x520` for compact diagrams.
|
|
444
447
|
- For exploratory direct CLI frames, dimensions may be omitted; Vizmatic starts at `960x540` and grows to fit content if overflow is detected.
|
|
445
448
|
- 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.
|
package/README.md
CHANGED
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
<strong>
|
|
7
|
-
|
|
6
|
+
<strong>Structured visual assets for coding agents.</strong><br/>
|
|
7
|
+
Write one TSX scene and render theme-aware diagrams, figures, dashboards, slide frames, and animated GIFs.
|
|
8
8
|
</p>
|
|
9
9
|
|
|
10
10
|
<p align="center">
|
|
@@ -30,9 +30,9 @@
|
|
|
30
30
|
|
|
31
31
|
---
|
|
32
32
|
|
|
33
|
-
## Quick
|
|
33
|
+
## Quick start
|
|
34
34
|
|
|
35
|
-
Install the CLI once:
|
|
35
|
+
Vizmatic requires Node.js 20 or newer. Install the CLI once:
|
|
36
36
|
|
|
37
37
|
```bash
|
|
38
38
|
npm install -g vizmatic
|
|
@@ -82,14 +82,15 @@ Optional edge build from GitHub:
|
|
|
82
82
|
pnpm add github:bvolpato/vizmatic react
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
-
## Agent
|
|
85
|
+
## Agent skills
|
|
86
86
|
|
|
87
87
|
### Codex
|
|
88
88
|
|
|
89
|
-
Vizmatic
|
|
89
|
+
Vizmatic ships as a Codex plugin with a bundled `$vizmatic` skill. Add this repository as a marketplace, then install the plugin:
|
|
90
90
|
|
|
91
91
|
```bash
|
|
92
92
|
codex plugin marketplace add bvolpato/vizmatic --ref main
|
|
93
|
+
codex plugin add vizmatic@vizmatic
|
|
93
94
|
```
|
|
94
95
|
|
|
95
96
|
Example prompts:
|
|
@@ -152,7 +153,7 @@ rm -rf ~/.agents/skills/vizmatic
|
|
|
152
153
|
cp -R "$tmp/vizmatic/.agents/skills/vizmatic" ~/.agents/skills/vizmatic
|
|
153
154
|
```
|
|
154
155
|
|
|
155
|
-
## Rendering
|
|
156
|
+
## Rendering options
|
|
156
157
|
|
|
157
158
|
Add optional branding:
|
|
158
159
|
|
|
@@ -161,7 +162,7 @@ vizmatic ./frame.tsx --out ./dist/frames --theme dark,light --watermark "Acme" -
|
|
|
161
162
|
```
|
|
162
163
|
|
|
163
164
|
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
|
|
165
|
+
Each output directory includes `manifest.json`. `outputs` lists generated files; `outputDetails` records theme, path, and physical pixel dimensions for each file.
|
|
165
166
|
|
|
166
167
|
Render an animation:
|
|
167
168
|
|
|
@@ -207,17 +208,12 @@ Vizmatic gives them a constrained visual language:
|
|
|
207
208
|
|
|
208
209
|
| Need | Vizmatic answer |
|
|
209
210
|
|---|---|
|
|
210
|
-
|
|
|
211
|
-
|
|
|
212
|
-
| Headless
|
|
213
|
-
|
|
|
214
|
-
|
|
|
215
|
-
|
|
|
216
|
-
| Agent-friendly authoring | JSX scene modules with simple props |
|
|
217
|
-
| Reproducible artifacts | Pure Node render path, no browser required |
|
|
218
|
-
| Safer generated visuals | Overflow detection, autocrop, wrapping-safe labels |
|
|
219
|
-
| Animated explainers | GIF export from ordered scene states |
|
|
220
|
-
| Docs and decks | Same frame can become article art, report figure, or presentation slide |
|
|
211
|
+
| More than flowcharts | Charts, cards, matrices, timelines, trees, icons, and free composition |
|
|
212
|
+
| Editable output | Source-controlled TSX stays inspectable and renders consistently |
|
|
213
|
+
| Headless rendering | Node produces assets directly in local workflows and CI |
|
|
214
|
+
| Theme variants | One command renders dark and light output from semantic color tokens |
|
|
215
|
+
| Layout checks | Overflow detection, autocrop, and wrapping-safe labels catch common failures |
|
|
216
|
+
| Animation | Ordered scene states export as GIFs |
|
|
221
217
|
|
|
222
218
|
## Gallery
|
|
223
219
|
|
|
@@ -239,7 +235,7 @@ Vizmatic gives them a constrained visual language:
|
|
|
239
235
|
|
|
240
236
|
More examples live in [`examples/`](examples) and on the [website](https://bvolpato.github.io/vizmatic/).
|
|
241
237
|
|
|
242
|
-
## Copy-
|
|
238
|
+
## Copy-paste examples
|
|
243
239
|
|
|
244
240
|
### Minimal flow
|
|
245
241
|
|
|
@@ -258,6 +254,30 @@ height = 560;
|
|
|
258
254
|
</Scene>
|
|
259
255
|
```
|
|
260
256
|
|
|
257
|
+
For the flat visual language used in technical engineering articles, set the
|
|
258
|
+
`engineering` preset at the top of a bare frame:
|
|
259
|
+
|
|
260
|
+
```tsx
|
|
261
|
+
preset = "engineering";
|
|
262
|
+
width = 1040;
|
|
263
|
+
height = 560;
|
|
264
|
+
|
|
265
|
+
<Scene title="How requests reach the model" background={c.bg}>
|
|
266
|
+
<Flow stages={[
|
|
267
|
+
{ title: "Stable prefix", tone: "blue" },
|
|
268
|
+
{ title: "Dynamic turn", tone: "warm" },
|
|
269
|
+
{ title: "Model", tone: "purple" },
|
|
270
|
+
]} />
|
|
271
|
+
</Scene>
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
The preset supplies a light gray article palette, left-aligned black heading,
|
|
275
|
+
flat pastel nodes, thin connectors, restrained corners, Inter labels, and
|
|
276
|
+
JetBrains Mono annotations. It removes card shadows and decorative chrome.
|
|
277
|
+
`background={c.bg}` paints that palette across the canvas; omit it for alpha
|
|
278
|
+
transparency. Continue to render with `--theme light`; the preset is a visual
|
|
279
|
+
style, not a light/dark mode.
|
|
280
|
+
|
|
261
281
|
### Flow + callouts
|
|
262
282
|
|
|
263
283
|
Use this for process diagrams, architecture walkthroughs, and agent pipelines.
|
|
@@ -411,11 +431,11 @@ height = 620;
|
|
|
411
431
|
</Scene>
|
|
412
432
|
```
|
|
413
433
|
|
|
414
|
-
## Agent
|
|
434
|
+
## Agent prompt
|
|
415
435
|
|
|
416
|
-
[`PROMPT.md`](PROMPT.md)
|
|
436
|
+
[`PROMPT.md`](PROMPT.md) gives coding agents installation steps, frame structure, component props, render commands, examples, quality rules, and a final verification checklist.
|
|
417
437
|
|
|
418
|
-
## Quality
|
|
438
|
+
## Quality gates
|
|
419
439
|
|
|
420
440
|
Vizmatic treats generated visuals as source-controlled build artifacts. CI fails if examples, site assets, source snippets, or prompt copies drift from the repo source.
|
|
421
441
|
|
|
@@ -434,9 +454,9 @@ Run the full local gate:
|
|
|
434
454
|
./test.sh
|
|
435
455
|
```
|
|
436
456
|
|
|
437
|
-
## Supply
|
|
457
|
+
## Supply chain
|
|
438
458
|
|
|
439
|
-
Vizmatic
|
|
459
|
+
Vizmatic uses `react` for JSX frames, `satori` for layout, `@resvg/resvg-js` for rasterization, `gifenc` for GIF output, `parse-css-color` for animation backgrounds, and `tsx` so the CLI can load TSX scene files directly.
|
|
440
460
|
|
|
441
461
|
The published package vendors its default renderer assets under `assets/`: Inter, JetBrains Mono, Noto Sans, Noto Sans Math, and Twemoji SVGs. Normal CLI rendering should not need `fonts.gstatic.com` or `cdn.jsdelivr.net` at runtime. `VIZMATIC_FONT_DIR` can still point at a custom/cache font directory, `VIZMATIC_ASSET_DIR` can point at a relocated asset bundle, and `VIZMATIC_DISABLE_NETWORK=1` or `VIZMATIC_OFFLINE=1` prevents fallback to public downloads.
|
|
442
462
|
|
|
@@ -452,14 +472,19 @@ Package resolution is intentionally conservative:
|
|
|
452
472
|
### Themes
|
|
453
473
|
|
|
454
474
|
```ts
|
|
455
|
-
import { getThemeColors } from "vizmatic"
|
|
475
|
+
import { getThemeColors, getToneFill } from "vizmatic"
|
|
456
476
|
|
|
457
477
|
const dark = getThemeColors("dark")
|
|
458
478
|
const light = getThemeColors("light")
|
|
479
|
+
const engineering = getThemeColors("light", "engineering")
|
|
480
|
+
const engineeringNodeFill = getToneFill("purple", engineering)
|
|
459
481
|
```
|
|
460
482
|
|
|
461
483
|
Primitives receive `c`, the resolved theme object. This keeps every visual connected to one palette, typography scale, and contrast model.
|
|
462
484
|
|
|
485
|
+
Bare frames can select the same style with `preset = "engineering";`. Full
|
|
486
|
+
modules pass the optional second argument to `getThemeColors`.
|
|
487
|
+
|
|
463
488
|
### Component catalog
|
|
464
489
|
|
|
465
490
|
Vizmatic exports a fairly complete visual kit. Common cases should use these primitives before dropping to raw SVG or absolute positioning.
|
|
@@ -563,7 +588,9 @@ Vizmatic exports a fairly complete visual kit. Common cases should use these pri
|
|
|
563
588
|
| API | Use |
|
|
564
589
|
|---|---|
|
|
565
590
|
| `renderToPng` | Render React scene to PNG through Satori and resvg, with optional watermark, crop, scale, and overflow check. |
|
|
591
|
+
| `renderToPngWithOutput` | Render PNG and return logical plus physical pixel dimensions. |
|
|
566
592
|
| `renderAnimatedGif` | Render ordered `AnimatedScene[]` states to GIF with `fade`, `appear`, or no transition. |
|
|
593
|
+
| `renderAnimatedGifWithOutput` | Render GIF and return its physical pixel dimensions. |
|
|
567
594
|
| `renderToBuffer` | Render PNG to memory for tests and pipelines. |
|
|
568
595
|
| `renderToSvg` | Render SVG markup directly. |
|
|
569
596
|
| `Watermark` | JSX marker component for expressive frame-module watermarks. |
|
|
@@ -579,7 +606,7 @@ Vizmatic exports a fairly complete visual kit. Common cases should use these pri
|
|
|
579
606
|
import { renderAnimatedGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
|
|
580
607
|
```
|
|
581
608
|
|
|
582
|
-
`renderToPng` renders at 2x scale by default, uses alpha transparency unless `background` is set, checks for clipped content, crops extra
|
|
609
|
+
`renderToPng` renders at 2x scale by default, uses alpha transparency unless `background` is set, checks for clipped content, and crops extra whitespace while retaining 24 source pixels of padding around the detected content. It can also 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.
|
|
583
610
|
|
|
584
611
|
```ts
|
|
585
612
|
await renderToPng(element, {
|
|
@@ -621,7 +648,7 @@ await renderAnimatedGif(createScenes("dark"), {
|
|
|
621
648
|
})
|
|
622
649
|
```
|
|
623
650
|
|
|
624
|
-
## Project
|
|
651
|
+
## Project layout
|
|
625
652
|
|
|
626
653
|
```text
|
|
627
654
|
src/
|
|
@@ -655,12 +682,8 @@ gh workflow run release.yml -f version=patch
|
|
|
655
682
|
|
|
656
683
|
The workflow requires an `NPM_TOKEN` repository secret with publish access.
|
|
657
684
|
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
```bash
|
|
661
|
-
pnpm verify
|
|
662
|
-
npm publish --access public
|
|
663
|
-
```
|
|
685
|
+
Publishing stays in the workflow so package version, plugin metadata, tag,
|
|
686
|
+
release notes, and npm provenance remain synchronized.
|
|
664
687
|
|
|
665
688
|
## License
|
|
666
689
|
|