vizmatic 0.1.27 → 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 CHANGED
@@ -1,10 +1,10 @@
1
- # Vizmatic Agent Prompt
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
- ## Fastest Path
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 Installation
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 Example
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, not hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
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>Theme-aware visuals from structured scenes.</strong><br/>
7
- Give AI agents typed primitives. Get polished diagrams, figures, dashboards, slide frames, and animated GIFs.
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 Start
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 Skills
85
+ ## Agent skills
86
86
 
87
87
  ### Codex
88
88
 
89
- Vizmatic also ships as a Codex plugin with a bundled `$vizmatic` skill. Add this repo as a marketplace, install the Vizmatic plugin from Codex, then ask for visual assets directly:
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 Options
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 exact rendered dimensions for each file.
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
- | 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 |
214
- | Rich educational illustrations | React primitives rendered through Satori and resvg |
215
- | Theme-aware output | Semantic tones and dark/light theme tokens |
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-Paste Examples
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 Prompt
434
+ ## Agent prompt
415
435
 
416
- [`PROMPT.md`](PROMPT.md) is a plug-and-play instruction file for coding agents. It covers install, frame structure, every visual component with props, render commands, examples, quality rules, and final verification.
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 Gates
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 Chain Posture
457
+ ## Supply chain
438
458
 
439
- Vizmatic keeps runtime dependencies narrow: `react` for JSX frames, `satori` for JSX layout, `@resvg/resvg-js` for rasterization, `gifenc` for animated GIF output, and `tsx` so the CLI can load TSX scene files directly.
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 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.
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 Layout
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
- Manual release fallback:
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