vizmatic 0.1.5 → 0.1.7

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 (5) hide show
  1. package/PROMPT.md +176 -231
  2. package/README.md +98 -144
  3. package/dist/cli.js +4948 -33
  4. package/docs/PROMPT.md +176 -231
  5. package/package.json +6 -4
package/README.md CHANGED
@@ -37,7 +37,7 @@ Use Vizmatic as a one-off binary without touching `package.json`:
37
37
  pnpm dlx vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
38
38
  ```
39
39
 
40
- Frame files can import `react` and `vizmatic`; the CLI resolves those from its own package runtime in `dlx`/`npx` mode.
40
+ Bare CLI frames auto-import Vizmatic primitives and inject theme colors. Use normal imports when a frame needs helpers, data loading, custom dependencies, or direct renderer APIs.
41
41
 
42
42
  Install it when you want project scripts, editor types, or direct renderer APIs:
43
43
 
@@ -54,27 +54,18 @@ pnpm add github:bvolpato/vizmatic react
54
54
  Create a frame:
55
55
 
56
56
  ```tsx
57
- import React from "react"
58
- import { defineIllustration, Flow, Scene } from "vizmatic"
59
-
60
- export const width = 1040
61
- export const height = 560
62
-
63
- const frame = defineIllustration((c) => (
64
- <Scene c={c} title="Agent visual pipeline">
65
- <Flow
66
- c={c}
67
- stages={[
68
- { title: "Prompt", subtitle: "intent", tone: "blue" },
69
- { title: "Scene spec", subtitle: "typed structure", tone: "purple" },
70
- { title: "PNG / SVG / GIF", subtitle: "rendered artifact", tone: "green" },
71
- ]}
72
- />
73
- </Scene>
74
- ))
75
-
76
- export const create = frame.create
77
- export default frame.default
57
+ width = 1040
58
+ height = 560
59
+
60
+ <Scene title="Agent visual pipeline">
61
+ <Flow
62
+ stages={[
63
+ { title: "Prompt", subtitle: "intent", tone: "blue" },
64
+ { title: "Scene spec", subtitle: "typed structure", tone: "purple" },
65
+ { title: "PNG / SVG / GIF", subtitle: "rendered artifact", tone: "green" },
66
+ ]}
67
+ />
68
+ </Scene>
78
69
  ```
79
70
 
80
71
  Render it:
@@ -161,23 +152,16 @@ More examples live in [`examples/`](examples) and on the [website](https://bvolp
161
152
  Use this for small docs snippets and quick agent-generated frames.
162
153
 
163
154
  ```tsx
164
- import { defineIllustration, Flow, Scene } from "vizmatic"
165
-
166
- export const width = 1040
167
- export const height = 560
168
-
169
- const frame = defineIllustration((c) =>
170
- <Scene c={c} title="Agent pipeline">
171
- <Flow c={c} stages={[
172
- { title: "Prompt", tone: "blue" },
173
- { title: "Scene spec", tone: "purple" },
174
- { title: "PNG / GIF", tone: "green" },
175
- ]} />
176
- </Scene>
177
- )
178
-
179
- export const create = frame.create
180
- export default frame.default
155
+ width = 1040
156
+ height = 560
157
+
158
+ <Scene title="Agent pipeline">
159
+ <Flow stages={[
160
+ { title: "Prompt", tone: "blue" },
161
+ { title: "Scene spec", tone: "purple" },
162
+ { title: "PNG / GIF", tone: "green" },
163
+ ]} />
164
+ </Scene>
181
165
  ```
182
166
 
183
167
  ### Flow + callouts
@@ -185,33 +169,24 @@ export default frame.default
185
169
  Use this for process diagrams, architecture walkthroughs, and agent pipelines.
186
170
 
187
171
  ```tsx
188
- import React from "react"
189
- import { CalloutCard, defineIllustration, Flow, Row, Scene } from "vizmatic"
190
-
191
- export const width = 1040
192
- export const height = 560
193
-
194
- const frame = defineIllustration((c) => (
195
- <Scene c={c} title="Agent visual pipeline" subtitle="prompt -> scene spec -> verified artifact" gap={26}>
196
- <Flow
197
- c={c}
198
- connectorTone="purple"
199
- stages={[
200
- { eyebrow: "input", title: "Prompt", subtitle: "intent", tone: "blue", lines: ["goal", "audience", "constraints"], width: 190 },
201
- { eyebrow: "contract", title: "Scene spec", subtitle: "typed structure", tone: "purple", lines: ["cards", "flows", "charts"], width: 190 },
202
- { eyebrow: "render", title: "Satori", subtitle: "React primitives", tone: "cyan", lines: ["layout", "theme", "safe text"], width: 190 },
203
- { eyebrow: "output", title: "PNG / GIF", subtitle: "verified asset", tone: "green", lines: ["autocrop", "overflow checks"], width: 190 },
204
- ]}
205
- />
206
- <Row width="100%" gap={14}>
207
- <CalloutCard c={c} title="Model writes structure" detail="No hand-written SVG paths." tone="purple" width={470} />
208
- <CalloutCard c={c} title="Theme stays in control" detail="Colors and typography come from tokens." tone="green" width={470} />
209
- </Row>
210
- </Scene>
211
- ))
212
-
213
- export const create = frame.create
214
- export default frame.default
172
+ width = 1040
173
+ height = 560
174
+
175
+ <Scene title="Agent visual pipeline" subtitle="prompt -> scene spec -> verified artifact" gap={26}>
176
+ <Flow
177
+ connectorTone="purple"
178
+ stages={[
179
+ { eyebrow: "input", title: "Prompt", subtitle: "intent", tone: "blue", lines: ["goal", "audience", "constraints"], width: 190 },
180
+ { eyebrow: "contract", title: "Scene spec", subtitle: "typed structure", tone: "purple", lines: ["cards", "flows", "charts"], width: 190 },
181
+ { eyebrow: "render", title: "Satori", subtitle: "React primitives", tone: "cyan", lines: ["layout", "theme", "safe text"], width: 190 },
182
+ { eyebrow: "output", title: "PNG / GIF", subtitle: "verified asset", tone: "green", lines: ["autocrop", "overflow checks"], width: 190 },
183
+ ]}
184
+ />
185
+ <Row width="100%" gap={14}>
186
+ <CalloutCard title="Model writes structure" detail="No hand-written SVG paths." tone="purple" width={470} />
187
+ <CalloutCard title="Theme stays in control" detail="Colors and typography come from tokens." tone="green" width={470} />
188
+ </Row>
189
+ </Scene>
215
190
  ```
216
191
 
217
192
  ### Animated GIF
@@ -280,38 +255,29 @@ vizmatic gif ./animated-frame.tsx --out ./dist/frames --theme dark,light --water
280
255
  Use this for workflows with branches, retries, and validation loops.
281
256
 
282
257
  ```tsx
283
- import React from "react"
284
- import { defineIllustration, GraphDiagram, Scene } from "vizmatic"
285
-
286
- export const width = 1040
287
- export const height = 560
288
-
289
- const frame = defineIllustration((c) => (
290
- <Scene c={c} title="RAG control graph" subtitle="retrieval is a graph, not a prompt append" align="center">
291
- <GraphDiagram
292
- c={c}
293
- width={820}
294
- height={390}
295
- nodes={[
296
- { id: "query", label: "Query", detail: "intent", x: 0.08, y: 0.52, tone: "blue" },
297
- { id: "retrieve", label: "Retrieve", detail: "top-k docs", x: 0.40, y: 0.25, tone: "cyan" },
298
- { id: "rerank", label: "Rerank", detail: "quality gate", x: 0.68, y: 0.25, tone: "warm" },
299
- { id: "answer", label: "Answer", detail: "grounded draft", x: 0.92, y: 0.52, tone: "green" },
300
- { id: "verify", label: "Verify", detail: "citations", x: 0.52, y: 0.78, tone: "critical" },
301
- ]}
302
- edges={[
303
- { from: "query", to: "retrieve", label: "search", tone: "blue" },
304
- { from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
305
- { from: "rerank", to: "answer", label: "context", tone: "green" },
306
- { from: "answer", to: "verify", label: "claims", tone: "critical" },
307
- { from: "verify", to: "retrieve", label: "retry", dashed: true, tone: "warm" },
308
- ]}
309
- />
310
- </Scene>
311
- ))
312
-
313
- export const create = frame.create
314
- export default frame.default
258
+ width = 1040
259
+ height = 560
260
+
261
+ <Scene title="RAG control graph" subtitle="retrieval is a graph, not a prompt append" align="center">
262
+ <GraphDiagram
263
+ width={820}
264
+ height={390}
265
+ nodes={[
266
+ { id: "query", label: "Query", detail: "intent", x: 0.08, y: 0.52, tone: "blue" },
267
+ { id: "retrieve", label: "Retrieve", detail: "top-k docs", x: 0.40, y: 0.25, tone: "cyan" },
268
+ { id: "rerank", label: "Rerank", detail: "quality gate", x: 0.68, y: 0.25, tone: "warm" },
269
+ { id: "answer", label: "Answer", detail: "grounded draft", x: 0.92, y: 0.52, tone: "green" },
270
+ { id: "verify", label: "Verify", detail: "citations", x: 0.52, y: 0.78, tone: "critical" },
271
+ ]}
272
+ edges={[
273
+ { from: "query", to: "retrieve", label: "search", tone: "blue" },
274
+ { from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
275
+ { from: "rerank", to: "answer", label: "context", tone: "green" },
276
+ { from: "answer", to: "verify", label: "claims", tone: "critical" },
277
+ { from: "verify", to: "retrieve", label: "retry", dashed: true, tone: "warm" },
278
+ ]}
279
+ />
280
+ </Scene>
315
281
  ```
316
282
 
317
283
  ### Evaluation dashboard
@@ -319,46 +285,36 @@ export default frame.default
319
285
  Use this for compact report figures and release decks.
320
286
 
321
287
  ```tsx
322
- import React from "react"
323
- import { BarChart, defineIllustration, LineChart, Row, Scene } from "vizmatic"
324
-
325
- export const width = 1040
326
- export const height = 620
327
-
328
- const frame = defineIllustration((c) => (
329
- <Scene c={c} title="Evaluation snapshot" subtitle="charts inherit theme, labels, and contrast">
330
- <Row gap={18} align="stretch">
331
- <BarChart
332
- c={c}
333
- width={440}
334
- height={260}
335
- title="Pass rate by task"
336
- format="percent"
337
- data={[
338
- { label: "tools", value: 0.82, color: "positive" },
339
- { label: "math", value: 0.71, color: "secondary" },
340
- { label: "code", value: 0.77, color: "primary" },
341
- { label: "long", value: 0.58, color: "warning" },
342
- ]}
343
- />
344
- <LineChart
345
- c={c}
346
- width={440}
347
- height={260}
348
- title="Quality over releases"
349
- format="percent"
350
- labels={["v1", "v2", "v3", "v4", "v5"]}
351
- series={[
352
- { name: "quality", points: [0.55, 0.61, 0.69, 0.74, 0.81], color: "positive", area: true },
353
- { name: "latency", points: [0.72, 0.69, 0.66, 0.62, 0.59], color: "warning" },
354
- ]}
355
- />
356
- </Row>
357
- </Scene>
358
- ))
359
-
360
- export const create = frame.create
361
- export default frame.default
288
+ width = 1040
289
+ height = 620
290
+
291
+ <Scene title="Evaluation snapshot" subtitle="charts inherit theme, labels, and contrast">
292
+ <Row gap={18} align="stretch">
293
+ <BarChart
294
+ width={440}
295
+ height={260}
296
+ title="Pass rate by task"
297
+ format="percent"
298
+ data={[
299
+ { label: "tools", value: 0.82, color: "positive" },
300
+ { label: "math", value: 0.71, color: "secondary" },
301
+ { label: "code", value: 0.77, color: "primary" },
302
+ { label: "long", value: 0.58, color: "warning" },
303
+ ]}
304
+ />
305
+ <LineChart
306
+ width={440}
307
+ height={260}
308
+ title="Quality over releases"
309
+ format="percent"
310
+ labels={["v1", "v2", "v3", "v4", "v5"]}
311
+ series={[
312
+ { name: "quality", points: [0.55, 0.61, 0.69, 0.74, 0.81], color: "positive", area: true },
313
+ { name: "latency", points: [0.72, 0.69, 0.66, 0.62, 0.59], color: "warning" },
314
+ ]}
315
+ />
316
+ </Row>
317
+ </Scene>
362
318
  ```
363
319
 
364
320
  ## Agent Prompt
@@ -371,19 +327,17 @@ Vizmatic treats generated visuals as source-controlled build artifacts. CI fails
371
327
 
372
328
  | Gate | What it protects |
373
329
  |---|---|
374
- | `pnpm typecheck` | Type safety across `src/`, `examples/`, `scripts/`, and tests |
330
+ | `pnpm lint` | Static TypeScript coverage across `src/`, `examples/`, `scripts/`, and tests |
375
331
  | `pnpm test` | Render pipeline behavior, watermark options, and output validation |
376
332
  | `pnpm render:examples` | Dark/light PNGs, animated GIFs, source snippets, and website HTML |
377
333
  | `pnpm docs:check` | Local asset references, `PROMPT.md` sync, source modal themes, and homepage affordances |
378
- | `pnpm security:audit` | Fails on known low-or-higher npm advisories |
379
- | `npm pack --dry-run` | Published package contents before release |
380
- | CI generated-file check | Ensures rendered docs/examples are committed |
334
+ | `pnpm deps:check` | npm audit plus package tarball contents before release |
335
+ | `./test.sh` drift check | Ensures render/docs commands do not create extra changes |
381
336
 
382
337
  Run the full local gate:
383
338
 
384
339
  ```bash
385
- pnpm verify
386
- git diff --exit-code
340
+ ./test.sh
387
341
  ```
388
342
 
389
343
  ## Supply Chain Posture