vizmatic 0.1.33 → 0.1.35

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
@@ -37,7 +37,7 @@ Check the scene before publishing:
37
37
  vizmatic check ./frame.tsx --theme dark,light --json
38
38
  ```
39
39
 
40
- Fix all errors before the final render. Warnings report low contrast and asset fallbacks. Overflow errors name the affected edges and suggest dimensions.
40
+ Fix all errors before the final render. Warnings report low contrast, text below 11px, overlapping labels, uneven panel whitespace, connector congestion, and asset fallbacks. Overflow errors name the affected edges and suggest dimensions.
41
41
 
42
42
  ## Install in a project
43
43
 
@@ -258,7 +258,7 @@ Frame helpers:
258
258
 
259
259
  - `defineIllustration(build, defaultTheme?)`: `build: (c: ThemeColors) => ReactElement`, `defaultTheme?: ThemeMode = "dark"`. Returns `{ create(theme), default }`.
260
260
  - `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.
261
- - `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`. Title/subtitle are optional and the title bar is omitted when no title is provided. Use `background={c.bg}` for an opaque theme frame.
261
+ - `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Title/subtitle are optional and the title bar is omitted when no title is provided. Use `background={c.bg}` for an opaque theme frame.
262
262
  - `TitleBar`: `title`, `subtitle?`, `c`.
263
263
 
264
264
  Layout primitives:
@@ -277,26 +277,26 @@ Cards, labels, and compact UI:
277
277
  - `Icon`: `name`, `c`, `tone?: ToneName = "blue"`, `color?`, `size?: number = 24`, `strokeWidth?: number = 2`, `label?`, `muted?: boolean = false`. `IconName`: `"agent" | "chart" | "check" | "code" | "database" | "file" | "git" | "globe" | "image" | "layers" | "lock" | "play" | "spark" | "terminal" | "tool" | "warning"`.
278
278
  - `ToneStrip`: `tone`, `width?: number = 34`, `height?: number = 4`.
279
279
  - `StepCard`: `title`, `c`, `subtitle?`, `eyebrow?`, `tone?: ToneName = "blue"`, `width?: number | string = 210`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "12px 14px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`.
280
- - `MetricCard`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "10px 12px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`, `valueMono?: boolean = true`, `valueFontSize?: number = 10`, `valueColor?`.
280
+ - `MetricCard`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "10px 12px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`, `valueMono?: boolean = true`, `valueFontSize?: number = 22`, `valueColor?`.
281
281
  - `CalloutCard`: `c`, `children?`, `title?`, `detail?`, `tone?: ToneName = "blue"`, `width?`, `minHeight?`, `padding?: number | string = 12`, `titleFontSize?: number`, `detailFontSize?: number`, `filled?: boolean = true`, `align?: "left" | "center" = "center"`.
282
282
  - `ValuePill`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?: number | string = 112`, `math?: boolean = false`.
283
- - `BadgePill`: `text`, `c`, `tone?: ToneName = "blue"`, `width?`, `minWidth?: number | string = 34`, `height?: number | string = 20`, `padding?: number | string = "0 8px"`, `radius?: number = 6`, `fontSize?: number = 9`, `mono?: boolean = true`, `filled?: boolean = false`, `math?: boolean = false`.
283
+ - `BadgePill`: `text`, `c`, `tone?: ToneName = "blue"`, `width?`, `minWidth?: number | string = 34`, `height?: number | string = 20`, `padding?: number | string = "0 8px"`, `radius?: number = 6`, `fontSize?: number = 11`, `mono?: boolean = true`, `filled?: boolean = false`, `math?: boolean = false`.
284
284
  - `Badge`: `label`, `c`, `color?: ColorName = "primary"`.
285
285
  - `GradientChip`: `title`, `c`, `subtitle?`, `tone?: ToneName = "blue"`, `gradient?`, `width?`, `minWidth?`, `height?`, `minHeight?: number | string = 78`, `padding?: number | string = "0 18px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "left"`, `subtitleMono?: boolean = true`, `math?: boolean = false`.
286
286
  - `EquationCard`: `title`, `formula`, `c`, `tone?: ToneName = "purple"`, `result?`, `detail?`, `width?: number | string = 190`, `height?`, `math?: boolean = false`, `align?: "left" | "center" = "left"`.
287
- - `DetailList`: `items`, `c`, `tone?`, `gap?: number = 7`, `padding?: number | string = "7px 8px"`, `fontSize?: number = 10`, `mono?: boolean = false`, `math?: boolean = false`.
287
+ - `DetailList`: `items`, `c`, `tone?`, `gap?: number = 7`, `padding?: number | string = "7px 8px"`, `fontSize?: number = 11`, `mono?: boolean = false`, `math?: boolean = false`.
288
288
 
289
289
  Lists, tables, status, and comparison:
290
290
 
291
- - `ProgressRow`: `label`, `value: number`, `valueLabel?`, `tone?: ToneName = "blue"`, `muted?: boolean = false`, `c`, `labelWidth?: number = 42`, `valueWidth?: number = 38`, `barHeight?: number = 8`, `fontSize?: number = 10`. Keep `value` in `[0, 1]`.
291
+ - `ProgressRow`: `label`, `value: number`, `valueLabel?`, `tone?: ToneName = "blue"`, `muted?: boolean = false`, `c`, `labelWidth?: number = 42`, `valueWidth?: number = 38`, `barHeight?: number = 8`, `fontSize?: number = 11`. Keep `value` in `[0, 1]`.
292
292
  - `ProgressList`: `rows: ProgressRowSpec[]`, `c`, `gap?: number = 8`, `labelWidth?`, `valueWidth?`, `barHeight?`, `fontSize?`. `ProgressRowSpec`: `label`, `value`, `valueLabel?`, `tone?`, `muted?`.
293
293
  - `StatusRow`: `label`, `detail?`, `status?: "check" | "cross" | "warn" | "info" | "pending" | "dot" = "check"`, `tone?`, `c`, `boxed?: boolean = true`, `fontSize?: number = 11`, `width?`, `math?: boolean = false`.
294
294
  - `StatusList`: `rows: StatusRowSpec[]`, `c`, `gap?: number = 7`, `boxed?: boolean = true`, `fontSize?`, `width?`, `math?: boolean = false`. `StatusRowSpec`: `label`, `detail?`, `status?`, `tone?`.
295
295
  - `Timeline`: `events: TimelineEventSpec[]`, `c`, `title?`, `subtitle?`, `direction?: "vertical" | "horizontal" = "vertical"`, `width?`, `eventWidth?`, `gap?: number = 12`, `markerSize?: number = 14`, `math?: boolean = false`. `TimelineEventSpec`: `title`, `detail?`, `time?`, `tone?`, `status?`, `width?`.
296
296
  - `KeyValueList`: `rows: KeyValueRow[]`, `c`, `title?`, `width?`, `minWidth?`, `keyWidth?`, `gap?: number = 0`, `fontSize?: number = 11`, `divider?: boolean = true`, `keyMono?: boolean = false`, `math?: boolean = false`. `KeyValueRow`: `key`, `value`, `tone?`, `valueMono?`.
297
297
  - `Comparison`: `sides: ComparisonSideSpec[]`, `c`, `divider?: ReactNode | boolean = false`, `gap?: number = 14`, `sideWidth?`, `minHeight?`, `align?: FlexAlign = "stretch"`, `math?: boolean = false`. `ComparisonSideSpec`: `title`, `subtitle?`, `eyebrow?`, `tone?`, `lines?`, `children?`, `footer?`, `width?`.
298
- - `DataTable`: `rows: ReactNode[][]`, `c`, `cellWidth?: number = 54`, `firstColWidth?: number = cellWidth`, `cellHeight?: number = 28`, `gap?: number = 5`, `headerRows?: number = 1`, `headerCols?: number = 1`, `fontSize?: number = 10`, `math?: boolean = false`.
299
- - `Grid`: `rows: Array<Array<ReactNode | GridCell>>`, `c`, `cellWidth?: number = 34`, `cellHeight?: number = 30`, `gap?: number = 5`, `radius?: number = 7`, `fontSize?: number = 10`, `math?: boolean = false`, `headerRows?: number = 0`, `headerCols?: number = 0`. `GridCell`: `label?`, `tone?`, `color?`, `backgroundColor?`, `borderColor?`, `opacity?`.
298
+ - `DataTable`: `rows: ReactNode[][]`, `c`, `cellWidth?: number = 54`, `firstColWidth?: number = cellWidth`, `cellHeight?: number = 28`, `gap?: number = 5`, `headerRows?: number = 1`, `headerCols?: number = 1`, `fontSize?: number = 11`, `math?: boolean = false`.
299
+ - `Grid`: `rows: Array<Array<ReactNode | GridCell>>`, `c`, `cellWidth?: number = 34`, `cellHeight?: number = 30`, `gap?: number = 5`, `radius?: number = 7`, `fontSize?: number = 11`, `math?: boolean = false`, `headerRows?: number = 0`, `headerCols?: number = 0`. `GridCell`: `label?`, `tone?`, `color?`, `backgroundColor?`, `borderColor?`, `opacity?`.
300
300
  - `CodeBlock`: `lines: Array<ReactNode | CodeLineSpec>`, `c`, `title?`, `tone?`, `width?`, `minWidth?`, `fontSize?: number = 12`, `showLineNumbers?: boolean = false`, `padding?: number | string = 14`, `radius?: number = 10`, `background?`, `shadow?: boolean = false`, `math?: boolean = false`. `CodeLineSpec`: `text`, `tone?`, `dim?`, `prefix?`.
301
301
 
302
302
  Tiles:
@@ -314,7 +314,7 @@ Flows and process diagrams:
314
314
  Graphs and networks:
315
315
 
316
316
  - `LayeredNetwork`: `c`, `layers: LayeredNetworkLayer[]`, `activePath?: number[] = []`, `annotations?: string[] = []`, `formula?`, `legend?: string = "highlighted path"`, `width?: number = 900`, `height?: number = 400`, `nodeSize?: number = 56`, `showFormula?: boolean = true`. `LayeredNetworkLayer`: `title`, `nodes: string[]`, `tone?`.
317
- - `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `labelFontSize?: number = 14`, `detailFontSize?: number = 9`, `arrowSize?: number = 5`, `padding?: number = 28`. `GraphDiagramNode`: `id`, `label`, `detail?`, `x`, `y`, `tone?`, `muted?`, `width?`, `height?`. `GraphDiagramEdge`: `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`.
317
+ - `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `labelFontSize?: number = 14`, `detailFontSize?: number = 11`, `arrowSize?: number = 5`, `padding?: number = 28`, `layout?: "auto" | "manual"`, `direction?: "LR" | "RL" | "TB" | "BT" = "LR"`, `nodeGap?: number = 34`, `rankGap?: number = 64`, `edgeGap?: number = 14`, `sizing?: "content" | "fixed" = "content"`. `GraphDiagramNode`: `id`, `label`, `detail?`, `x?`, `y?`, `tone?`, `muted?`, `width?`, `height?`. Omit coordinates on every node for automatic layout; array order is the stable tie-breaker and dimensions expand to fit unless `sizing="fixed"`. Set both coordinates on every node for manual normalized positioning. Mixed coordinate modes fail. `GraphDiagramEdge`: `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`.
318
318
  - `TreeDiagram`: `root: TreeNodeSpec`, `c`, `title?`, `subtitle?`, `width?`, `height?`, `nodeWidth?: number = 156`, `nodeHeight?: number = 64`, `levelGap?: number = 58`, `siblingGap?: number = 24`, `padding?: number = 28`, `math?: boolean = false`. `TreeNodeSpec`: `label`, `id?`, `detail?`, `tone?`, `muted?`, `children?`.
319
319
 
320
320
  Matrices and heatmaps:
@@ -333,7 +333,7 @@ Charts and plots:
333
333
  - `QuadrantChart`: `points: ScatterPoint[]`, `regions`, `c`, `title?`, `subtitle?`, `width?: number = 700`, `height?: number = 360`, `xAxisLabel?`, `yAxisLabel?`, `footer?`. `regions`: `{ topLeft, topRight, bottomLeft, bottomRight }`, each `QuadrantRegion`: `label`, `detail?`, `color?`.
334
334
  - `IntervalPlot`: `data: IntervalDatum[]`, `c`, `title?`, `subtitle?`, `width?: number = 640`, `height?: number = 220`, `min?`, `max?`, `format?: ChartValueFormat = "decimal"`, `axisLabel?`, `footer?`. `IntervalDatum`: `label`, `low`, `mid`, `high`, `color?`, `lowLabel?`, `midLabel?`, `highLabel?`.
335
335
  - `StackedBar`: `segments: StackedBarSegment[]`, `c`, `width?: number = 480`, `height?: number = 68`, `title?`, `subtitle?`, `showLegend?: boolean = true`. `StackedBarSegment`: `label`, `value`, `color?`, `valueLabel?`.
336
- - `MiniBarChart`: `data: MiniBarDatum[]`, `c`, `max?`, `minBarHeight?: number = 8`, `height?: number = 92`, `barWidth?: number = 22`, `gap?: number = 10`, `radius?: number = 7`, `fontSize?: number = 9`, `showValues?: boolean = false`. `MiniBarDatum`: `label`, `value`, `tone?`, `color?`, `valueLabel?`, `opacity?`.
336
+ - `MiniBarChart`: `data: MiniBarDatum[]`, `c`, `max?`, `minBarHeight?: number = 8`, `height?: number = 92`, `barWidth?: number = 22`, `gap?: number = 10`, `radius?: number = 7`, `fontSize?: number = 11`, `showValues?: boolean = false`. `MiniBarDatum`: `label`, `value`, `tone?`, `color?`, `valueLabel?`, `opacity?`.
337
337
  - `AxisPlot`: `c`, `width`, `height`, `xMin?: number = -1`, `xMax?: number = 1`, `yMin?: number = -1`, `yMax?: number = 1`, `padding?: number = 18`, `showFrame?: boolean = true`, `showAxes?: boolean = true`, `showGrid?: boolean = false`, `gridCount?: number = 5`, `frameRx?: number = 8`, `frameFill?`, `frameStroke?`, `axisColor?`, `points?: AxisPlotPoint[] = []`, `vectors?: AxisPlotVector[] = []`, `paths?: AxisPlotPath[] = []`, `xAxisLabel?`, `yAxisLabel?`, `children?`.
338
338
  - `AxisPlotPoint`: `x`, `y`, `fill?`, `tone?`, `r?`, `stroke?`, `strokeWidth?`, `opacity?`.
339
339
  - `AxisPlotVector`: `x1`, `y1`, `x2`, `y2`, `color?`, `tone?`, `strokeWidth?`, `opacity?`, `arrow?`, `arrowSize?`, `showStartDot?`, `showEndDot?`, `dotRadius?`.
@@ -359,12 +359,20 @@ Theme and render APIs:
359
359
 
360
360
  - `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.
361
361
  - `getToneColor(tone, c)`, `getToneFill(tone, c)`, `getToneGradient(tone)`, `getColor(name, c?)`, `getGradient(name)`, `heatColor(value)`.
362
+ - `getReadableColor(name, c)`: returns the semantic color variant with greatest contrast against `c.bgCard`.
363
+ - `getReadableToneColor(tone, c, background?)`: maps a tone to a readable semantic color and falls back to readable foreground text when contrast is below 4.5:1. `background` defaults to `c.bgCard`.
364
+ - `getReadableTextColor(background, c)`: parses solid or alpha CSS colors and chooses a theme foreground meeting 4.5:1 contrast when possible.
365
+ - `createPlotArea(width, height, margin)`: returns `PlotArea` geometry with inner width and height clamped to at least one pixel.
362
366
  - `renderToPng(element, options, createFn?, theme?)`: `element`, `options: RenderOptions`, `createFn?: (theme: "dark" | "light") => ReactNode`, `theme?: "dark" | "light"`.
363
367
  - `renderToPngWithOutput(...)`: same arguments as `renderToPng`; returns logical `width` / `height` and physical `pixelWidth` / `pixelHeight`.
364
368
  - `Watermark`: JSX marker component for frame-module exports. Props are `WatermarkOptions` plus `children?: ReactNode`; children become the complete watermark body.
365
369
  - `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.
366
370
  - `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.
367
371
  - `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`.
372
+ - `normalizeWatermark(input)`: converts boolean, string, object, or React-element `WatermarkInput` to `WatermarkOptions | undefined`.
373
+ - `wrapWithBrand(element, width, height, theme?, label?)`: compatibility wrapper around `wrapWithWatermark`; theme defaults to `"dark"` and label defaults to `"Vizmatic"`.
374
+ - `getFonts()`: lazily loads and caches bundled Satori font data for advanced integrations.
375
+ - `loadAdditionalAsset(code, segment)`: Satori missing-glyph callback; resolves emoji segments to Twemoji data URIs and returns an empty font list for other codes.
368
376
  - `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.
369
377
  - `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`, `scale?`.
370
378
  - `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`.
@@ -456,6 +464,7 @@ height = 560;
456
464
  - 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.
457
465
  - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` to keep layout stable.
458
466
  - Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
467
+ - Omit `x` and `y` from `GraphDiagram` nodes for automatic layered layout. Add both only when editorial composition needs manual control.
459
468
  - Render reusable assets in both themes with `--theme dark,light`.
460
469
  - Run `vizmatic check <frame> --theme dark,light --json` before final render and fix every error.
461
470
  - Use GIF only when motion explains state change. Keep scenes short, export `createScenes(theme)`, and keep a static `create(theme)` fallback.
@@ -474,19 +483,20 @@ height = 560;
474
483
  <GraphDiagram
475
484
  width={820}
476
485
  height={390}
486
+ nodeWidth={132}
487
+ rankGap={44}
477
488
  nodes={[
478
- { id: "query", label: "Query", detail: "intent", x: 0.08, y: 0.52, tone: "blue" },
479
- { id: "retrieve", label: "Retrieve", detail: "top-k docs", x: 0.40, y: 0.25, tone: "cyan" },
480
- { id: "rerank", label: "Rerank", detail: "quality gate", x: 0.68, y: 0.25, tone: "warm" },
481
- { id: "answer", label: "Answer", detail: "grounded draft", x: 0.92, y: 0.52, tone: "green" },
482
- { id: "verify", label: "Verify", detail: "citations", x: 0.52, y: 0.78, tone: "critical" },
489
+ { id: "query", label: "Query", detail: "intent", tone: "blue" },
490
+ { id: "retrieve", label: "Retrieve", detail: "top-k docs", tone: "cyan" },
491
+ { id: "rerank", label: "Rerank", detail: "quality gate", tone: "warm" },
492
+ { id: "answer", label: "Answer", detail: "grounded draft", tone: "green" },
493
+ { id: "verify", label: "Verify", detail: "citations", tone: "critical" },
483
494
  ]}
484
495
  edges={[
485
496
  { from: "query", to: "retrieve", label: "search", tone: "blue" },
486
497
  { from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
487
498
  { from: "rerank", to: "answer", label: "context", tone: "green" },
488
499
  { from: "answer", to: "verify", label: "claims", tone: "critical" },
489
- { from: "verify", to: "retrieve", label: "retry", dashed: true, tone: "warm" },
490
500
  ]}
491
501
  />
492
502
  </Scene>
package/README.md CHANGED
@@ -20,7 +20,7 @@
20
20
 
21
21
  <p align="center">
22
22
  <a href="https://bvolpato.github.io/vizmatic/">Website</a> ·
23
- <a href="https://bvolpato.github.io/vizmatic/#playground">Playground</a> ·
23
+ <a href="https://bvolpato.github.io/vizmatic/playground.html">Playground</a> ·
24
24
  <a href="examples">Examples</a> ·
25
25
  <a href="PROMPT.md">Agent Prompt</a> ·
26
26
  <a href="#api">API</a>
@@ -58,7 +58,7 @@ Render it directly:
58
58
  vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
59
59
  ```
60
60
 
61
- Check both themes before publishing. `--json` returns machine-readable errors, warnings, overflow edges, and suggested dimensions:
61
+ Check both themes before publishing. `--json` reports overflow, contrast, small text, overlapping labels, uneven panel whitespace, connector congestion, asset failures, and suggested dimensions:
62
62
 
63
63
  ```bash
64
64
  vizmatic check ./frame.tsx --theme dark,light --json
@@ -179,7 +179,7 @@ Vizmatic provides reusable layout, diagram, and chart primitives:
179
179
  | Editable output | Source-controlled TSX stays inspectable and renders consistently |
180
180
  | Headless rendering | Node produces assets directly in local workflows and CI |
181
181
  | Theme variants | One command renders dark and light output from semantic color tokens |
182
- | Layout checks | Overflow detection, autocrop, and wrapping-safe labels catch common failures |
182
+ | Layout checks | Overflow, contrast, small text, label overlap, uneven panel whitespace, and connector congestion |
183
183
  | Animation | Ordered scene states export as GIFs |
184
184
 
185
185
  ## Gallery
@@ -200,7 +200,7 @@ Vizmatic provides reusable layout, diagram, and chart primitives:
200
200
  <img src="https://bvolpato.github.io/vizmatic/assets/examples/presentation-frame_dark.png" alt="Presentation frame" width="380" />
201
201
  </p>
202
202
 
203
- More examples live in [`examples/`](examples) and on the [website](https://bvolpato.github.io/vizmatic/). [`PROMPT.md`](PROMPT.md) contains the full install, syntax, component, and verification reference for coding agents.
203
+ More examples live in [`examples/`](examples). The website has a searchable [component catalog](https://bvolpato.github.io/vizmatic/components.html) with a rendered preview and source for every public component. [`PROMPT.md`](PROMPT.md) contains the full install, syntax, component, and verification reference for coding agents.
204
204
 
205
205
  ## Repository checks
206
206
 
@@ -211,8 +211,9 @@ Generated examples and website files are committed. CI fails when a build change
211
211
  | `pnpm lint` | TypeScript coverage plus GitHub Actions validation with actionlint |
212
212
  | `pnpm test` | Render pipeline behavior, watermark options, and output validation |
213
213
  | `pnpm render:examples` | Dark/light PNGs, animated GIFs, source snippets, and website HTML |
214
+ | `pnpm check:examples` | Every example renders in both themes without errors or visual warnings |
214
215
  | `pnpm docs:check` | Local asset references, `PROMPT.md` sync, source modal themes, and homepage affordances |
215
- | `pnpm deps:check` | npm audit plus package tarball contents before release |
216
+ | `pnpm deps:check` | npm audit plus package tarball contents, size, and file-count budgets before release |
216
217
  | `./test.sh` drift check | Confirms render and docs commands leave no uncommitted output |
217
218
 
218
219
  Run the full local gate:
@@ -227,6 +228,8 @@ Vizmatic uses `react` for JSX frames, `satori` for layout, `@resvg/resvg-js` for
227
228
 
228
229
  Published packages include Inter, JetBrains Mono, Noto Sans, Noto Sans Math, and Twemoji SVGs under `assets/`, so normal CLI rendering does not fetch them at runtime. Set `VIZMATIC_FONT_DIR` or `VIZMATIC_ASSET_DIR` to use other local assets. Set `VIZMATIC_DISABLE_NETWORK=1` or `VIZMATIC_OFFLINE=1` to disable public fallbacks.
229
230
 
231
+ The complete Twemoji set is intentionally bundled so arbitrary emoji render offline. `pnpm deps:check` keeps that tradeoff bounded: the package must stay below 3.25 MB compressed, 12.5 MB unpacked, and 4,000 files.
232
+
230
233
  ## API
231
234
 
232
235
  ### Themes
@@ -314,9 +317,27 @@ Use these primitives before writing raw SVG or absolute-positioned layouts.
314
317
  | `Flow` | Horizontal or vertical staged process diagram with optional detail rows. |
315
318
  | `Pipeline` | Process pipeline with stage labels and a shared title. |
316
319
  | `LayeredNetwork` | Neural-network/DAG diagram with layers, nodes, active path, annotations, and formula. |
317
- | `GraphDiagram` | Positioned node-edge graph with labels, dashed/muted edges, and tone-aware nodes. |
320
+ | `GraphDiagram` | Auto-laid or manually positioned node-edge graph with routed paths, labels, and tone-aware nodes. |
318
321
  | `TreeDiagram` | Auto-laid parent/child hierarchy for ownership, routing, taxonomy, and decision trees. |
319
322
 
323
+ `GraphDiagram` uses deterministic layered layout when node coordinates are omitted:
324
+
325
+ ```tsx
326
+ <GraphDiagram
327
+ nodes={[
328
+ { id: "prompt", label: "Prompt", tone: "blue" },
329
+ { id: "render", label: "Render", tone: "purple" },
330
+ { id: "asset", label: "PNG / SVG / GIF", tone: "green" },
331
+ ]}
332
+ edges={[
333
+ { from: "prompt", to: "render" },
334
+ { from: "render", to: "asset" },
335
+ ]}
336
+ />
337
+ ```
338
+
339
+ Set `x` and `y` on every node for normalized manual positioning. Mixed coordinate modes fail with a clear error. Automatic layout treats node and edge array order as its stable tie-breaker and expands `width` or `height` when needed. Set `sizing="fixed"` to keep exact graph dimensions and let overflow checks report a canvas that is too small. Use `direction`, `nodeGap`, `rankGap`, and `edgeGap` to tune the result.
340
+
320
341
  #### Matrices, tables, and grids
321
342
 
322
343
  | Component | Use |
@@ -354,11 +375,17 @@ Use these primitives before writing raw SVG or absolute-positioned layouts.
354
375
  | `renderToSvg` | Render SVG markup directly. |
355
376
  | `Watermark` | JSX marker component for expressive frame-module watermarks. |
356
377
  | `wrapWithWatermark` | Add optional watermark text, image/icon, custom element, and position to a frame. |
378
+ | `normalizeWatermark` | Normalize boolean, string, object, or React-element watermark input to `WatermarkOptions`. |
379
+ | `wrapWithBrand` | Compatibility wrapper for adding a text watermark through `wrapWithWatermark`. |
380
+ | `getFonts` | Load and cache bundled Satori font data for advanced renderer integrations. |
381
+ | `loadAdditionalAsset` | Resolve Satori missing-glyph requests, including bundled or cached Twemoji assets. |
357
382
  | `detectBackgroundColor` | Find dominant transparent/background color for cropping. |
358
383
  | `detectContentBounds` | Compute non-background bounds for autocrop. |
359
384
  | `cropPixels` | Crop raw pixel buffers. |
360
385
  | `detectOverflow` | Fail frames that clip content at canvas edges. |
361
386
 
387
+ Theme and chart helpers are public for custom primitives: `getReadableColor(name, c)` selects the highest-contrast semantic variant, `getReadableToneColor(tone, c, background?)` adapts tone text to a background, and `getReadableTextColor(background, c)` chooses a foreground meeting 4.5:1 contrast when possible. `createPlotArea(width, height, margin)` returns clamped chart geometry for custom axes and marks.
388
+
362
389
  ### Rendering
363
390
 
364
391
  ```ts