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/PROMPT.md CHANGED
@@ -31,84 +31,66 @@ For npm/yarn/bun projects, use the equivalent package-manager command.
31
31
  Create `frames/agent-pipeline.tsx`:
32
32
 
33
33
  ```tsx
34
- import React from "react"
35
- import {
36
- CalloutCard,
37
- defineIllustration,
38
- Flow,
39
- Row,
40
- Scene,
41
- } from "vizmatic"
42
-
43
- export const width = 1040
44
- export const height = 560
45
-
46
- const frame = defineIllustration((c) => (
47
- <Scene
48
- c={c}
49
- title="Agent visual pipeline"
50
- subtitle="prompt -> scene spec -> verified artifact"
51
- gap={26}
52
- >
53
- <Flow
54
- c={c}
55
- connectorTone="purple"
56
- stages={[
57
- {
58
- eyebrow: "input",
59
- title: "Prompt",
60
- subtitle: "intent and constraints",
61
- tone: "blue",
62
- lines: ["domain language", "audience", "theme tokens"],
63
- width: 190,
64
- },
65
- {
66
- eyebrow: "contract",
67
- title: "Scene spec",
68
- subtitle: "typed structure",
69
- tone: "purple",
70
- lines: ["cards", "flows", "charts", "tables"],
71
- width: 190,
72
- },
73
- {
74
- eyebrow: "render",
75
- title: "Satori frame",
76
- subtitle: "React primitives",
77
- tone: "cyan",
78
- lines: ["layout defaults", "safe text", "semantic tones"],
79
- width: 190,
80
- },
81
- {
82
- eyebrow: "output",
83
- title: "PNG / GIF",
84
- subtitle: "CI-ready asset",
85
- tone: "green",
86
- lines: ["autocrop", "overflow checks", "retina scale"],
87
- width: 190,
88
- },
89
- ]}
34
+ width = 1040
35
+ height = 560
36
+
37
+ <Scene
38
+ title="Agent visual pipeline"
39
+ subtitle="prompt -> scene spec -> verified artifact"
40
+ gap={26}
41
+ >
42
+ <Flow
43
+ connectorTone="purple"
44
+ stages={[
45
+ {
46
+ eyebrow: "input",
47
+ title: "Prompt",
48
+ subtitle: "intent and constraints",
49
+ tone: "blue",
50
+ lines: ["domain language", "audience", "theme tokens"],
51
+ width: 190,
52
+ },
53
+ {
54
+ eyebrow: "contract",
55
+ title: "Scene spec",
56
+ subtitle: "typed structure",
57
+ tone: "purple",
58
+ lines: ["cards", "flows", "charts", "tables"],
59
+ width: 190,
60
+ },
61
+ {
62
+ eyebrow: "render",
63
+ title: "Satori frame",
64
+ subtitle: "React primitives",
65
+ tone: "cyan",
66
+ lines: ["layout defaults", "safe text", "semantic tones"],
67
+ width: 190,
68
+ },
69
+ {
70
+ eyebrow: "output",
71
+ title: "PNG / GIF",
72
+ subtitle: "CI-ready asset",
73
+ tone: "green",
74
+ lines: ["autocrop", "overflow checks", "retina scale"],
75
+ width: 190,
76
+ },
77
+ ]}
78
+ />
79
+ <Row width="100%" gap={14}>
80
+ <CalloutCard
81
+ title="Model writes structure"
82
+ detail="No hand-written SVG paths or brittle x/y layout for common cases."
83
+ tone="purple"
84
+ width={470}
90
85
  />
91
- <Row width="100%" gap={14}>
92
- <CalloutCard
93
- c={c}
94
- title="Model writes structure"
95
- detail="No hand-written SVG paths or brittle x/y layout for common cases."
96
- tone="purple"
97
- width={470}
98
- />
99
- <CalloutCard
100
- c={c}
101
- title="Design system stays in control"
102
- detail="Theme tokens decide color, typography, radius, spacing, and contrast."
103
- tone="green"
104
- width={470}
105
- />
106
- </Row>
107
- </Scene>
108
- ))
109
-
110
- export const create = frame.create
111
- export default frame.default
86
+ <CalloutCard
87
+ title="Design system stays in control"
88
+ detail="Theme tokens decide color, typography, radius, spacing, and contrast."
89
+ tone="green"
90
+ width={470}
91
+ />
92
+ </Row>
93
+ </Scene>
112
94
  ```
113
95
 
114
96
  Render it:
@@ -117,6 +99,8 @@ Render it:
117
99
  pnpm exec vizmatic frames --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right
118
100
  ```
119
101
 
102
+ 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.
103
+
120
104
  Frame modules can also export a watermark element when code-owned branding is clearer than CLI flags:
121
105
 
122
106
  ```tsx
@@ -214,7 +198,8 @@ Shared values:
214
198
  - `ColorName`: `"primary" | "secondary" | "positive" | "warning" | "critical" | "info" | "accent" | "neutral"`.
215
199
  - `FlexAlign`: `"start" | "center" | "end" | "stretch"`.
216
200
  - `FlexJustify`: `"start" | "center" | "end" | "space-between" | "space-around"`.
217
- - Most visual components require `c: ThemeColors`; inside `defineIllustration((c) => ...)`, pass that same `c` down.
201
+ - In bare CLI frames, omit `c`; the CLI injects theme colors into Vizmatic components.
202
+ - In full modules, most visual components require `c: ThemeColors`; inside `defineIllustration((c) => ...)`, pass that same `c` down.
218
203
 
219
204
  ## Component API
220
205
 
@@ -336,94 +321,73 @@ Theme and render APIs:
336
321
  ### Window + code + status
337
322
 
338
323
  ```tsx
339
- import React from "react"
340
- import { CodeBlock, StatusList, WindowFrame, defineIllustration, Row, Scene } from "vizmatic"
341
-
342
- export const width = 1040
343
- export const height = 560
344
-
345
- const frame = defineIllustration((c) => (
346
- <Scene c={c} title="Release gate" subtitle="tool output and checklist">
347
- <Row gap={18} align="stretch">
348
- <WindowFrame c={c} title="ci.log" variant="terminal" tone="green" width={520}>
349
- <CodeBlock
350
- c={c}
351
- fontSize={12}
352
- showLineNumbers
353
- lines={[
354
- { text: "pnpm typecheck", tone: "green", prefix: "$" },
355
- { text: "pnpm test", tone: "green", prefix: "$" },
356
- { text: "pnpm render:examples", tone: "cyan", prefix: "$" },
357
- ]}
358
- />
359
- </WindowFrame>
360
- <StatusList
361
- c={c}
362
- width={360}
363
- rows={[
364
- { label: "Types", detail: "clean", status: "check", tone: "green" },
365
- { label: "Visuals", detail: "dark/light generated", status: "check", tone: "cyan" },
366
- { label: "NPM", detail: "auth required", status: "warn", tone: "warm" },
324
+ width = 1040
325
+ height = 560
326
+
327
+ <Scene title="Release gate" subtitle="tool output and checklist">
328
+ <Row gap={18} align="stretch">
329
+ <WindowFrame title="ci.log" variant="terminal" tone="green" width={520}>
330
+ <CodeBlock
331
+ fontSize={12}
332
+ showLineNumbers
333
+ lines={[
334
+ { text: "pnpm typecheck", tone: "green", prefix: "$" },
335
+ { text: "pnpm test", tone: "green", prefix: "$" },
336
+ { text: "pnpm render:examples", tone: "cyan", prefix: "$" },
367
337
  ]}
368
338
  />
369
- </Row>
370
- </Scene>
371
- ))
372
-
373
- export const create = frame.create
374
- export default frame.default
339
+ </WindowFrame>
340
+ <StatusList
341
+ width={360}
342
+ rows={[
343
+ { label: "Types", detail: "clean", status: "check", tone: "green" },
344
+ { label: "Visuals", detail: "dark/light generated", status: "check", tone: "cyan" },
345
+ { label: "NPM", detail: "auth required", status: "warn", tone: "warm" },
346
+ ]}
347
+ />
348
+ </Row>
349
+ </Scene>
375
350
  ```
376
351
 
377
352
  ### Matrix + chart
378
353
 
379
354
  ```tsx
380
- import React from "react"
381
- import { Heatmap, Matrix, Row, Scene, StackedBar, defineIllustration } from "vizmatic"
382
-
383
- export const width = 1040
384
- export const height = 560
385
-
386
- const frame = defineIllustration((c) => (
387
- <Scene c={c} title="Attention audit" subtitle="weights, scores, and distribution">
388
- <Row gap={18} align="stretch">
389
- <Heatmap
390
- c={c}
391
- title="Attention"
392
- xLabels={["q1", "q2", "q3"]}
393
- yLabels={["k1", "k2", "k3"]}
394
- data={[
395
- [0.9, 0.2, 0.1],
396
- [0.4, 0.8, 0.2],
397
- [0.1, 0.3, 0.7],
398
- ]}
399
- />
400
- <Matrix
401
- c={c}
402
- title="Scores"
403
- format="decimal"
404
- rowLabels={["A", "B", "C"]}
405
- colLabels={["x", "y", "z"]}
406
- data={[
407
- [0.4, 0.7, 0.2],
408
- [0.5, 0.2, 0.8],
409
- ]}
410
- />
411
- <StackedBar
412
- c={c}
413
- width={300}
414
- title="Token budget"
415
- segments={[
416
- { label: "prompt", value: 42, color: "primary" },
417
- { label: "context", value: 38, color: "info" },
418
- { label: "answer", value: 20, color: "positive" },
419
- ]}
420
- />
421
- </Row>
422
- </Scene>
423
- ))
424
-
425
- export const create = frame.create
426
- export default frame.default
355
+ width = 1040
356
+ height = 560
357
+
358
+ <Scene title="Attention audit" subtitle="weights, scores, and distribution">
359
+ <Row gap={18} align="stretch">
360
+ <Heatmap
361
+ title="Attention"
362
+ xLabels={["q1", "q2", "q3"]}
363
+ yLabels={["k1", "k2", "k3"]}
364
+ data={[
365
+ [0.9, 0.2, 0.1],
366
+ [0.4, 0.8, 0.2],
367
+ [0.1, 0.3, 0.7],
368
+ ]}
369
+ />
370
+ <Matrix
371
+ title="Scores"
372
+ format="decimal"
373
+ rowLabels={["A", "B", "C"]}
374
+ colLabels={["x", "y", "z"]}
375
+ data={[
376
+ [0.4, 0.7, 0.2],
377
+ [0.5, 0.2, 0.8],
378
+ ]}
379
+ />
380
+ <StackedBar
381
+ width={300}
382
+ title="Token budget"
383
+ segments={[
384
+ { label: "prompt", value: 42, color: "primary" },
385
+ { label: "context", value: 38, color: "info" },
386
+ { label: "answer", value: 20, color: "positive" },
387
+ ]}
388
+ />
389
+ </Row>
390
+ </Scene>
427
391
  ```
428
392
 
429
393
  ## Quality rules
@@ -442,83 +406,64 @@ export default frame.default
442
406
  ### RAG graph
443
407
 
444
408
  ```tsx
445
- import React from "react"
446
- import { defineIllustration, GraphDiagram, Scene } from "vizmatic"
447
-
448
- export const width = 1040
449
- export const height = 560
450
-
451
- const frame = defineIllustration((c) => (
452
- <Scene c={c} title="RAG control graph" subtitle="retrieval is a graph, not a prompt append" align="center">
453
- <GraphDiagram
454
- c={c}
455
- width={820}
456
- height={390}
457
- nodes={[
458
- { id: "query", label: "Query", detail: "intent", x: 0.08, y: 0.52, tone: "blue" },
459
- { id: "retrieve", label: "Retrieve", detail: "top-k docs", x: 0.40, y: 0.25, tone: "cyan" },
460
- { id: "rerank", label: "Rerank", detail: "quality gate", x: 0.68, y: 0.25, tone: "warm" },
461
- { id: "answer", label: "Answer", detail: "grounded draft", x: 0.92, y: 0.52, tone: "green" },
462
- { id: "verify", label: "Verify", detail: "citations", x: 0.52, y: 0.78, tone: "critical" },
463
- ]}
464
- edges={[
465
- { from: "query", to: "retrieve", label: "search", tone: "blue" },
466
- { from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
467
- { from: "rerank", to: "answer", label: "context", tone: "green" },
468
- { from: "answer", to: "verify", label: "claims", tone: "critical" },
469
- { from: "verify", to: "retrieve", label: "retry", dashed: true, tone: "warm" },
470
- ]}
471
- />
472
- </Scene>
473
- ))
474
-
475
- export const create = frame.create
476
- export default frame.default
409
+ width = 1040
410
+ height = 560
411
+
412
+ <Scene title="RAG control graph" subtitle="retrieval is a graph, not a prompt append" align="center">
413
+ <GraphDiagram
414
+ width={820}
415
+ height={390}
416
+ nodes={[
417
+ { id: "query", label: "Query", detail: "intent", x: 0.08, y: 0.52, tone: "blue" },
418
+ { id: "retrieve", label: "Retrieve", detail: "top-k docs", x: 0.40, y: 0.25, tone: "cyan" },
419
+ { id: "rerank", label: "Rerank", detail: "quality gate", x: 0.68, y: 0.25, tone: "warm" },
420
+ { id: "answer", label: "Answer", detail: "grounded draft", x: 0.92, y: 0.52, tone: "green" },
421
+ { id: "verify", label: "Verify", detail: "citations", x: 0.52, y: 0.78, tone: "critical" },
422
+ ]}
423
+ edges={[
424
+ { from: "query", to: "retrieve", label: "search", tone: "blue" },
425
+ { from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
426
+ { from: "rerank", to: "answer", label: "context", tone: "green" },
427
+ { from: "answer", to: "verify", label: "claims", tone: "critical" },
428
+ { from: "verify", to: "retrieve", label: "retry", dashed: true, tone: "warm" },
429
+ ]}
430
+ />
431
+ </Scene>
477
432
  ```
478
433
 
479
434
  ### Evaluation dashboard
480
435
 
481
436
  ```tsx
482
- import React from "react"
483
- import { BarChart, defineIllustration, LineChart, Row, Scene } from "vizmatic"
484
-
485
- export const width = 1040
486
- export const height = 620
487
-
488
- const frame = defineIllustration((c) => (
489
- <Scene c={c} title="Evaluation snapshot" subtitle="charts inherit theme, labels, and contrast">
490
- <Row gap={18} align="stretch">
491
- <BarChart
492
- c={c}
493
- width={440}
494
- height={260}
495
- title="Pass rate by task"
496
- format="percent"
497
- data={[
498
- { label: "tools", value: 0.82, color: "positive" },
499
- { label: "math", value: 0.71, color: "secondary" },
500
- { label: "code", value: 0.77, color: "primary" },
501
- { label: "long", value: 0.58, color: "warning" },
502
- ]}
503
- />
504
- <LineChart
505
- c={c}
506
- width={440}
507
- height={260}
508
- title="Quality over releases"
509
- format="percent"
510
- labels={["v1", "v2", "v3", "v4", "v5"]}
511
- series={[
512
- { name: "quality", points: [0.55, 0.61, 0.69, 0.74, 0.81], color: "positive", area: true },
513
- { name: "latency", points: [0.72, 0.69, 0.66, 0.62, 0.59], color: "warning" },
514
- ]}
515
- />
516
- </Row>
517
- </Scene>
518
- ))
519
-
520
- export const create = frame.create
521
- export default frame.default
437
+ width = 1040
438
+ height = 620
439
+
440
+ <Scene title="Evaluation snapshot" subtitle="charts inherit theme, labels, and contrast">
441
+ <Row gap={18} align="stretch">
442
+ <BarChart
443
+ width={440}
444
+ height={260}
445
+ title="Pass rate by task"
446
+ format="percent"
447
+ data={[
448
+ { label: "tools", value: 0.82, color: "positive" },
449
+ { label: "math", value: 0.71, color: "secondary" },
450
+ { label: "code", value: 0.77, color: "primary" },
451
+ { label: "long", value: 0.58, color: "warning" },
452
+ ]}
453
+ />
454
+ <LineChart
455
+ width={440}
456
+ height={260}
457
+ title="Quality over releases"
458
+ format="percent"
459
+ labels={["v1", "v2", "v3", "v4", "v5"]}
460
+ series={[
461
+ { name: "quality", points: [0.55, 0.61, 0.69, 0.74, 0.81], color: "positive", area: true },
462
+ { name: "latency", points: [0.72, 0.69, 0.66, 0.62, 0.59], color: "warning" },
463
+ ]}
464
+ />
465
+ </Row>
466
+ </Scene>
522
467
  ```
523
468
 
524
469
  ## Final answer checklist