vizmatic 0.1.13 → 0.1.15

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 (47) hide show
  1. package/PROMPT.md +28 -8
  2. package/README.md +14 -2
  3. package/dist/cli.js +222 -63
  4. package/dist/index.cjs +85 -27
  5. package/dist/index.d.cts +10 -6
  6. package/dist/index.d.ts +10 -6
  7. package/dist/index.js +85 -27
  8. package/docs/PROMPT.md +28 -8
  9. package/docs/assets/examples/agent-pipeline_dark.png +0 -0
  10. package/docs/assets/examples/agent-pipeline_light.png +0 -0
  11. package/docs/assets/examples/animated-pipeline_dark.png +0 -0
  12. package/docs/assets/examples/animated-pipeline_light.png +0 -0
  13. package/docs/assets/examples/attention-head_dark.png +0 -0
  14. package/docs/assets/examples/attention-head_light.png +0 -0
  15. package/docs/assets/examples/embedding-map_dark.png +0 -0
  16. package/docs/assets/examples/embedding-map_light.png +0 -0
  17. package/docs/assets/examples/eval-dashboard_dark.png +0 -0
  18. package/docs/assets/examples/eval-dashboard_light.png +0 -0
  19. package/docs/assets/examples/manifest.json +16 -0
  20. package/docs/assets/examples/model-router_dark.png +0 -0
  21. package/docs/assets/examples/model-router_light.png +0 -0
  22. package/docs/assets/examples/presentation-frame_dark.png +0 -0
  23. package/docs/assets/examples/presentation-frame_light.png +0 -0
  24. package/docs/assets/examples/rag-graph_dark.png +0 -0
  25. package/docs/assets/examples/rag-graph_light.png +0 -0
  26. package/docs/assets/examples/release-card_dark.png +0 -0
  27. package/docs/assets/examples/release-card_light.png +0 -0
  28. package/docs/assets/examples/research-landscape_dark.png +0 -0
  29. package/docs/assets/examples/research-landscape_light.png +0 -0
  30. package/docs/assets/examples/sources.json +26 -6
  31. package/docs/assets/examples/spec-anatomy_dark.png +0 -0
  32. package/docs/assets/examples/spec-anatomy_light.png +0 -0
  33. package/docs/assets/examples/theme-background_dark.png +0 -0
  34. package/docs/assets/examples/theme-background_light.png +0 -0
  35. package/docs/assets/examples/theme-system_dark.png +0 -0
  36. package/docs/assets/examples/theme-system_light.png +0 -0
  37. package/docs/assets/examples/token-matrix_dark.png +0 -0
  38. package/docs/assets/examples/token-matrix_light.png +0 -0
  39. package/docs/assets/examples/transparent-badge_dark.png +0 -0
  40. package/docs/assets/examples/transparent-badge_light.png +0 -0
  41. package/examples/README.md +2 -0
  42. package/examples/model-router.tsx +1 -1
  43. package/examples/research-landscape.tsx +1 -1
  44. package/examples/theme-background.tsx +15 -0
  45. package/examples/transparent-badge.tsx +15 -0
  46. package/examples/vizmatic-bare.d.ts +1 -0
  47. package/package.json +2 -1
package/docs/PROMPT.md CHANGED
@@ -105,7 +105,23 @@ Render it:
105
105
  vizmatic frames --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right
106
106
  ```
107
107
 
108
- For direct CLI frames, skip imports, `defineIllustration`, and `c` props by default. The CLI injects Vizmatic primitives and theme colors. Use the full module form when you need custom dependencies, direct renderer APIs, advanced reusable JSX helpers, or animation exports.
108
+ 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
+
110
+ ```bash
111
+ vizmatic frames --out public/vizmatic --theme dark,light --background theme
112
+ ```
113
+
114
+ Or set it in the frame:
115
+
116
+ ```tsx
117
+ <Scene background={c.bg} title="Opaque article figure">
118
+ <Flow stages={[{ title: "Theme fill", tone: "purple" }]} />
119
+ </Scene>
120
+ ```
121
+
122
+ If a direct CLI frame omits `width` or `height`, Vizmatic starts at `960x540` and grows omitted axes when overflow is detected. Explicit dimensions stay strict and should be used when exact output size matters.
123
+
124
+ For direct CLI frames, skip imports, `defineIllustration`, and `c` props by default. The CLI injects Vizmatic primitives and theme colors. Reference `c` only when you need explicit theme tokens such as `background={c.bg}`. Use the full module form when you need custom dependencies, direct renderer APIs, advanced reusable JSX helpers, or animation exports.
109
125
 
110
126
  Frame modules can also export a watermark element when code-owned branding is clearer than CLI flags:
111
127
 
@@ -204,16 +220,18 @@ Shared values:
204
220
  - `ColorName`: `"primary" | "secondary" | "positive" | "warning" | "critical" | "info" | "accent" | "neutral"`.
205
221
  - `FlexAlign`: `"start" | "center" | "end" | "stretch"`.
206
222
  - `FlexJustify`: `"start" | "center" | "end" | "space-between" | "space-around"`.
207
- - In bare CLI frames, omit `c`; the CLI injects theme colors into Vizmatic components.
223
+ - In bare CLI frames, omit `c` props; the CLI injects theme colors into Vizmatic components. The local `c` token object is still available for explicit values like `background={c.bg}`.
208
224
  - In full modules, most visual components require `c: ThemeColors`; inside `defineIllustration((c) => ...)`, pass that same `c` down.
225
+ - PNG/SVG renders are alpha-transparent by default. Use `--background theme`, `background: "theme"`, or `<Scene background={c.bg}>` for opaque theme fill.
226
+ - Omitted CLI dimensions auto-grow on overflow. Explicit `width` / `height` remain fixed and fail on clipping.
209
227
 
210
228
  ## Component API
211
229
 
212
230
  Frame helpers:
213
231
 
214
232
  - `defineIllustration(build, defaultTheme?)`: `build: (c: ThemeColors) => ReactElement`, `defaultTheme?: ThemeMode = "dark"`. Returns `{ create(theme), default }`.
215
- - `Canvas`: `children?`, `c`, `padding?: number = 40`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "center"`, `background?: string`.
216
- - `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: Canvas.justify = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`.
233
+ - `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.
234
+ - `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: Canvas.justify = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Use `background={c.bg}` for an opaque theme frame.
217
235
  - `TitleBar`: `title`, `subtitle?`, `c`.
218
236
 
219
237
  Layout primitives:
@@ -315,12 +333,12 @@ Theme and render APIs:
315
333
  - `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.
316
334
  - `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.
317
335
  - `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`.
318
- - `RenderOptions`: `width`, `height`, `outputPath`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean = true`, `scale?: number = 2`.
319
- - `renderToBuffer(element, width, height, options?)`: `options` supports `watermark?`, `brand?`, `scale?`.
320
- - `renderToSvg(element, width, height, options?)`: `options` supports `watermark?`, `brand?`.
336
+ - `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean = true`, `scale?: number = 2`.
337
+ - `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `watermark?`, `brand?`, `scale?`.
338
+ - `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `watermark?`, `brand?`.
321
339
  - `renderAnimatedGif(scenes, options)`: `scenes: AnimatedScene[]`, `options: AnimationOptions`.
322
340
  - `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
323
- - `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`.
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"`.
324
342
 
325
343
  ## Prop-aware examples
326
344
 
@@ -400,6 +418,8 @@ height = 560;
400
418
 
401
419
  - Use semantic tones, not hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
402
420
  - Keep canvas sizes explicit. Good defaults: `1040x560` for article figures, `1280x720` for slide frames, `900x520` for compact diagrams.
421
+ - For exploratory direct CLI frames, dimensions may be omitted; Vizmatic auto-grows omitted axes if content overflows.
422
+ - 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.
403
423
  - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` props to stabilize layout.
404
424
  - Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
405
425
  - Render both dark and light when shipping reusable assets: `--theme dark,light`.
@@ -89,6 +89,14 @@
89
89
  "spec-anatomy_light.png"
90
90
  ]
91
91
  },
92
+ {
93
+ "name": "theme-background",
94
+ "source": "examples/theme-background.tsx",
95
+ "outputs": [
96
+ "theme-background_dark.png",
97
+ "theme-background_light.png"
98
+ ]
99
+ },
92
100
  {
93
101
  "name": "theme-system",
94
102
  "source": "examples/theme-system.tsx",
@@ -104,5 +112,13 @@
104
112
  "token-matrix_dark.png",
105
113
  "token-matrix_light.png"
106
114
  ]
115
+ },
116
+ {
117
+ "name": "transparent-badge",
118
+ "source": "examples/transparent-badge.tsx",
119
+ "outputs": [
120
+ "transparent-badge_dark.png",
121
+ "transparent-badge_light.png"
122
+ ]
107
123
  }
108
124
  ]