vizmatic 0.1.30 → 0.1.31

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
@@ -31,6 +31,14 @@ Render dark and light assets:
31
31
  vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
32
32
  ```
33
33
 
34
+ Validate the scene with structured diagnostics before publishing:
35
+
36
+ ```bash
37
+ vizmatic check ./frame.tsx --theme dark,light --json
38
+ ```
39
+
40
+ Fix errors before rendering final assets. Warnings identify concerns such as low text contrast or asset fallbacks; overflow errors include affected edges and suggested dimensions.
41
+
34
42
  ## Project installation
35
43
 
36
44
  Use the package manager already present in the project.
@@ -449,6 +457,7 @@ height = 560;
449
457
  - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` props to stabilize layout.
450
458
  - Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
451
459
  - Render both dark and light when shipping reusable assets: `--theme dark,light`.
460
+ - Run `vizmatic check <frame> --theme dark,light --json` before final render and fix every error.
452
461
  - Use GIF only when motion explains state change. Keep scenes short, export `createScenes(theme)`, and keep a static `create(theme)` fallback.
453
462
  - If render fails with `Canvas overflow detected`, the frame has strict dimensions. Increase canvas dimensions, reduce content density, or remove strict sizing for CLI auto-fit. Do not ignore the error.
454
463
  - Verify generated PNGs/GIFs exist and are non-empty. Open at least one rendered image before finalizing.
@@ -526,4 +535,5 @@ After creating a Vizmatic visual, report:
526
535
  - render command used
527
536
  - output image paths, including GIF paths when generated
528
537
  - whether dark/light variants rendered
538
+ - whether structured validation passed
529
539
  - any overflow or layout fixes made
package/README.md CHANGED
@@ -20,9 +20,10 @@
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
24
  <a href="examples">Examples</a> ·
24
25
  <a href="PROMPT.md">Agent Prompt</a> ·
25
- <a href="#agent-skills">Agent Skills</a> ·
26
+ <a href="#agent-skill">Agent Skill</a> ·
26
27
  <a href="#quick-start">Quick Start</a> ·
27
28
  <a href="#why-vizmatic">Why Vizmatic</a> ·
28
29
  <a href="#api">API</a>
@@ -60,6 +61,12 @@ Render it directly:
60
61
  vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
61
62
  ```
62
63
 
64
+ Validate both themes before publishing. `--json` returns structured errors, warnings, overflow edges, and suggested dimensions for agents and CI:
65
+
66
+ ```bash
67
+ vizmatic check ./frame.tsx --theme dark,light --json
68
+ ```
69
+
63
70
  PNG and SVG renders use an alpha-transparent canvas by default. Add `--background theme` when the output needs the actual dark/light theme fill:
64
71
 
65
72
  ```bash
@@ -82,75 +89,39 @@ Optional edge build from GitHub:
82
89
  pnpm add github:bvolpato/vizmatic react
83
90
  ```
84
91
 
85
- ## Agent skills
92
+ ## Agent skill
86
93
 
87
- ### Codex
88
-
89
- Vizmatic ships as a Codex plugin with a bundled `$vizmatic` skill. Add this repository as a marketplace, then install the plugin:
94
+ Install the portable Vizmatic skill globally. The installer detects Codex, Claude Code, Cursor, OpenCode, and other compatible agents:
90
95
 
91
96
  ```bash
92
- codex plugin marketplace add bvolpato/vizmatic --ref main
93
- codex plugin add vizmatic@vizmatic
94
- ```
95
-
96
- Example prompts:
97
-
98
- ```text
99
- Use $vizmatic to create a theme-aware architecture diagram and render dark/light PNG files.
100
- Use $vizmatic to turn this release workflow into an animated GIF for docs.
97
+ npx skills add bvolpato/vizmatic --skill vizmatic -g -y
101
98
  ```
102
99
 
103
- ### Claude Code
104
-
105
- Claude Code can import Vizmatic as a plugin marketplace directly from this repository:
100
+ Target specific agents when more than one is installed:
106
101
 
107
102
  ```bash
108
- claude plugin marketplace add bvolpato/vizmatic
109
- claude plugin install vizmatic@vizmatic --scope user
103
+ npx skills add bvolpato/vizmatic --skill vizmatic -g -a codex -a claude-code -a cursor -a opencode -y
110
104
  ```
111
105
 
112
- In an active Claude Code session, run `/reload-plugins`. Claude can then auto-select the Vizmatic skill, or you can invoke it with `/vizmatic:vizmatic`.
113
-
114
- ### Cursor
115
-
116
- Cursor can import skills from GitHub repositories through Remote Rule:
117
-
118
- 1. Open **Customize** in the sidebar.
119
- 2. Go to **Rules** and click **Add Rule**.
120
- 3. Select **Remote Rule (Github)**.
121
- 4. Enter `https://github.com/bvolpato/vizmatic`.
122
-
123
- The repo exposes the portable skill at `.agents/skills/vizmatic`, which Cursor discovers as a project skill. Manual install also works:
106
+ Example prompts:
124
107
 
125
- ```bash
126
- mkdir -p ~/.cursor/skills
127
- rm -rf ~/.cursor/skills/vizmatic
128
- cp -R .agents/skills/vizmatic ~/.cursor/skills/vizmatic
108
+ ```text
109
+ Use the Vizmatic skill to create a theme-aware architecture diagram and render dark/light PNG files.
110
+ Use the Vizmatic skill to turn this release workflow into an animated GIF for docs.
129
111
  ```
130
112
 
131
- ### OpenCode
113
+ The skill source lives at [`.agents/skills/vizmatic`](.agents/skills/vizmatic). Preview it before installation with `npx skills add bvolpato/vizmatic --list`.
132
114
 
133
- OpenCode discovers skills from repo and home-directory skill folders. Its plugin ecosystem is npm/config based; for Vizmatic, use the native skill directory.
134
-
135
- The GitHub-importable skill lives at `.agents/skills/vizmatic`. Copy that folder into the agent-specific skills directory:
115
+ Native Codex and Claude Code plugin marketplaces remain available:
136
116
 
137
117
  ```bash
138
- tmp="$(mktemp -d)"
139
- git clone --depth 1 https://github.com/bvolpato/vizmatic.git "$tmp/vizmatic"
140
- ```
141
-
142
- ```bash
143
- mkdir -p ~/.config/opencode/skills
144
- rm -rf ~/.config/opencode/skills/vizmatic
145
- cp -R "$tmp/vizmatic/.agents/skills/vizmatic" ~/.config/opencode/skills/vizmatic
118
+ codex plugin marketplace add bvolpato/vizmatic --ref main
119
+ codex plugin add vizmatic@vizmatic
146
120
  ```
147
121
 
148
- For a shared Cursor/OpenCode global location, use `~/.agents/skills` instead:
149
-
150
122
  ```bash
151
- mkdir -p ~/.agents/skills
152
- rm -rf ~/.agents/skills/vizmatic
153
- cp -R "$tmp/vizmatic/.agents/skills/vizmatic" ~/.agents/skills/vizmatic
123
+ claude plugin marketplace add bvolpato/vizmatic
124
+ claude plugin install vizmatic@vizmatic --scope user
154
125
  ```
155
126
 
156
127
  ## Rendering options
package/dist/cli.js CHANGED
@@ -12,7 +12,7 @@ import { createRequire, Module } from "module";
12
12
  import { tmpdir } from "os";
13
13
  import { basename, dirname as dirname3, extname, isAbsolute, join as join2, relative, resolve, sep } from "path";
14
14
  import { fileURLToPath as fileURLToPath2, pathToFileURL } from "url";
15
- import { isValidElement } from "react";
15
+ import { isValidElement as isValidElement2 } from "react";
16
16
 
17
17
  // src/index.ts
18
18
  var index_exports = {};
@@ -26,6 +26,7 @@ __export(index_exports, {
26
26
  Box: () => Box,
27
27
  CalloutCard: () => CalloutCard,
28
28
  Canvas: () => Canvas,
29
+ CanvasOverflowError: () => CanvasOverflowError,
29
30
  Card: () => Card,
30
31
  ChartFrame: () => ChartFrame,
31
32
  CodeBlock: () => CodeBlock,
@@ -6121,6 +6122,18 @@ function cropSavesEnough(source, target) {
6121
6122
  if (source <= 0 || target >= source) return false;
6122
6123
  return (source - target) / source * 100 >= CROP_THRESHOLD_PERCENT;
6123
6124
  }
6125
+ var CanvasOverflowError = class extends Error {
6126
+ width;
6127
+ height;
6128
+ overflow;
6129
+ constructor(width, height, overflow) {
6130
+ super(`Canvas overflow detected (${width}\xD7${height}): ${overflow.message}`);
6131
+ this.name = "CanvasOverflowError";
6132
+ this.width = width;
6133
+ this.height = height;
6134
+ this.overflow = overflow;
6135
+ }
6136
+ };
6124
6137
  function resolveWatermark(options) {
6125
6138
  return options.watermark ?? options.brand;
6126
6139
  }
@@ -6171,9 +6184,7 @@ async function renderToPngInContext(element, options, createFn, theme) {
6171
6184
  detectedBg
6172
6185
  );
6173
6186
  if (overflow.overflows) {
6174
- throw new Error(
6175
- `Canvas overflow detected (${options.width}\xD7${options.height}): ${overflow.message}`
6176
- );
6187
+ throw new CanvasOverflowError(options.width, options.height, overflow);
6177
6188
  }
6178
6189
  let finalWidth = options.width;
6179
6190
  let finalHeight = options.height;
@@ -6478,11 +6489,171 @@ async function renderAnimatedGifWithOutput(scenes, options) {
6478
6489
  return { width: frames[0].width, height: frames[0].height };
6479
6490
  }
6480
6491
 
6492
+ // src/diagnostics.ts
6493
+ import parseCssColor2 from "parse-css-color";
6494
+ import { Children, isValidElement } from "react";
6495
+ var MAX_CONTRAST_NODES = 5e3;
6496
+ function hslToRgb2(hue, saturation, lightness) {
6497
+ const h = (hue % 360 + 360) % 360;
6498
+ const s = saturation / 100;
6499
+ const l = lightness / 100;
6500
+ const chroma = (1 - Math.abs(2 * l - 1)) * s;
6501
+ const segment = h / 60;
6502
+ const intermediate = chroma * (1 - Math.abs(segment % 2 - 1));
6503
+ let channels;
6504
+ if (segment < 1) channels = [chroma, intermediate, 0];
6505
+ else if (segment < 2) channels = [intermediate, chroma, 0];
6506
+ else if (segment < 3) channels = [0, chroma, intermediate];
6507
+ else if (segment < 4) channels = [0, intermediate, chroma];
6508
+ else if (segment < 5) channels = [intermediate, 0, chroma];
6509
+ else channels = [chroma, 0, intermediate];
6510
+ const offset = l - chroma / 2;
6511
+ return channels.map((channel) => Math.round((channel + offset) * 255));
6512
+ }
6513
+ function colorFromCss(value) {
6514
+ if (typeof value !== "string") return void 0;
6515
+ const parsed = parseCssColor2(value);
6516
+ if (!parsed || parsed.values.length < 3 || parsed.alpha < 0.95) return void 0;
6517
+ const [r, g, b] = parsed.type === "hsl" ? hslToRgb2(parsed.values[0] ?? 0, parsed.values[1] ?? 0, parsed.values[2] ?? 0) : [parsed.values[0] ?? 0, parsed.values[1] ?? 0, parsed.values[2] ?? 0];
6518
+ return {
6519
+ r,
6520
+ g,
6521
+ b,
6522
+ alpha: parsed.alpha
6523
+ };
6524
+ }
6525
+ function channelLuminance(value) {
6526
+ const normalized = value / 255;
6527
+ return normalized <= 0.04045 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
6528
+ }
6529
+ function relativeLuminance(color) {
6530
+ return 0.2126 * channelLuminance(color.r) + 0.7152 * channelLuminance(color.g) + 0.0722 * channelLuminance(color.b);
6531
+ }
6532
+ function contrastRatio(foreground, background) {
6533
+ const lighter = Math.max(relativeLuminance(foreground), relativeLuminance(background));
6534
+ const darker = Math.min(relativeLuminance(foreground), relativeLuminance(background));
6535
+ return (lighter + 0.05) / (darker + 0.05);
6536
+ }
6537
+ function numericFontWeight(value) {
6538
+ if (typeof value === "number") return value;
6539
+ if (value === "bold") return 700;
6540
+ if (typeof value === "string" && /^\d+$/.test(value)) return Number(value);
6541
+ return void 0;
6542
+ }
6543
+ function requiredContrast(context) {
6544
+ const large = (context.fontSize ?? 16) >= 24 || (context.fontSize ?? 16) >= 18.66 && (context.fontWeight ?? 400) >= 700;
6545
+ return large ? 3 : 4.5;
6546
+ }
6547
+ function styleRecord(value) {
6548
+ if (!value || typeof value !== "object" || Array.isArray(value)) return {};
6549
+ return value;
6550
+ }
6551
+ function hasDirectText(children) {
6552
+ return Children.toArray(children).some((child) => typeof child === "string" || typeof child === "number");
6553
+ }
6554
+ function resolveFunctionComponent(node, trustedComponents) {
6555
+ if (!isValidElement(node) || typeof node.type !== "function" || trustedComponents.has(node.type)) return void 0;
6556
+ const component = node.type;
6557
+ if (component.__vizmaticPrimitive) return void 0;
6558
+ if (component.prototype?.isReactComponent) return void 0;
6559
+ try {
6560
+ return component(node.props);
6561
+ } catch {
6562
+ return void 0;
6563
+ }
6564
+ }
6565
+ function analyzeContrast(element, theme, trustedComponents = /* @__PURE__ */ new Set()) {
6566
+ const diagnostics = [];
6567
+ const seen = /* @__PURE__ */ new Set();
6568
+ let visited = 0;
6569
+ function visit(node, inherited, path) {
6570
+ if (visited++ >= MAX_CONTRAST_NODES || !isValidElement(node)) return;
6571
+ const resolved = resolveFunctionComponent(node, trustedComponents);
6572
+ if (resolved !== void 0) {
6573
+ visit(resolved, inherited, path);
6574
+ return;
6575
+ }
6576
+ const props = node.props;
6577
+ const style = typeof node.type === "string" ? styleRecord(props.style) : {};
6578
+ const background = colorFromCss(style.backgroundColor) ?? colorFromCss(style.background) ?? inherited.background;
6579
+ const color = colorFromCss(style.color) ?? inherited.color;
6580
+ const fontSize = typeof style.fontSize === "number" ? style.fontSize : inherited.fontSize;
6581
+ const fontWeight = numericFontWeight(style.fontWeight) ?? inherited.fontWeight;
6582
+ const context = { background, color, fontSize, fontWeight };
6583
+ if (typeof node.type === "string" && hasDirectText(props.children) && color && background) {
6584
+ const ratio = contrastRatio(color, background);
6585
+ const required = requiredContrast(context);
6586
+ if (ratio < required) {
6587
+ const rounded = Math.round(ratio * 100) / 100;
6588
+ const key = `${rounded}:${required}:${path}`;
6589
+ if (!seen.has(key)) {
6590
+ seen.add(key);
6591
+ diagnostics.push({
6592
+ code: "accessibility.low_contrast",
6593
+ severity: "warning",
6594
+ theme,
6595
+ message: `Text contrast is ${rounded}:1 at ${path}; ${required}:1 is recommended.`,
6596
+ suggestion: "Use a stronger text or background color token."
6597
+ });
6598
+ }
6599
+ }
6600
+ }
6601
+ Children.forEach(props.children, (child, index) => visit(child, context, `${path}.${index}`));
6602
+ }
6603
+ visit(element, {}, "root");
6604
+ return diagnostics;
6605
+ }
6606
+ function diagnosticFromMessage(message, severity, theme) {
6607
+ if (/unknown preset/i.test(message)) {
6608
+ return {
6609
+ code: "frame.unknown_preset",
6610
+ severity,
6611
+ theme,
6612
+ message,
6613
+ suggestion: 'Use "default" or "engineering".'
6614
+ };
6615
+ }
6616
+ if (/unsupported prop|unknown prop|does not recognize (?:the )?.* prop/i.test(message)) {
6617
+ return {
6618
+ code: "api.unsupported_prop",
6619
+ severity,
6620
+ theme,
6621
+ message,
6622
+ suggestion: "Remove the prop or use one documented for this Vizmatic primitive."
6623
+ };
6624
+ }
6625
+ if (/invalid value for css property|unsupported (?:css|style)|not supported.*css/i.test(message)) {
6626
+ return {
6627
+ code: "style.unsupported",
6628
+ severity,
6629
+ theme,
6630
+ message,
6631
+ suggestion: "Use CSS supported by Satori or a Vizmatic primitive."
6632
+ };
6633
+ }
6634
+ if (/font|emoji|image asset|failed to (?:download|fetch)|asset .*not found/i.test(message)) {
6635
+ return {
6636
+ code: "asset.warning",
6637
+ severity,
6638
+ theme,
6639
+ message,
6640
+ suggestion: "Use a reachable asset or install it locally before rendering offline."
6641
+ };
6642
+ }
6643
+ return {
6644
+ code: severity === "error" ? "render.error" : "render.warning",
6645
+ severity,
6646
+ theme,
6647
+ message
6648
+ };
6649
+ }
6650
+
6481
6651
  // src/cli.ts
6482
6652
  var RENDER_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".mjs", ".ts", ".tsx"]);
6483
6653
  var IMPORT_RESOLUTION_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json"];
6484
6654
  var DEFAULT_FRAME_WIDTH = 960;
6485
6655
  var DEFAULT_FRAME_HEIGHT = 540;
6656
+ var CONTRAST_TRUSTED_COMPONENTS = new Set(Object.values(index_exports));
6486
6657
  var AUTO_SIZE_MAX_WIDTH = 1920;
6487
6658
  var AUTO_SIZE_MAX_HEIGHT = 1440;
6488
6659
  var AUTO_SIZE_GROWTH = 1.25;
@@ -6511,12 +6682,14 @@ function usageText() {
6511
6682
  return `Usage:
6512
6683
  vizmatic <file-or-directory...> [--out <dir>] [--theme dark,light] [--background transparent|theme|color] [--watermark Label] [--watermark-image path-or-url] [--watermark-position top-right] [--no-crop]
6513
6684
  vizmatic render <file-or-directory...> [--out <dir>] [--theme dark,light] [--background transparent|theme|color] [--watermark Label] [--watermark-image path-or-url] [--watermark-position top-right] [--no-crop]
6685
+ vizmatic check <file-or-directory...> [--theme dark,light] [--background transparent|theme|color] [--json]
6514
6686
  vizmatic gif <file-or-directory...> [--out <dir>] [--theme dark] [--watermark Label] [--watermark-image path-or-url] [--watermark-position top-right] [--scale 1]
6515
6687
 
6516
6688
  Examples:
6517
6689
  vizmatic examples/attention-head.tsx --out dist/frames --theme dark,light
6518
6690
  vizmatic ./frame.tsx --out ./dist/frames --theme dark
6519
6691
  vizmatic ./frame.tsx --out ./dist/frames --theme light --background theme
6692
+ vizmatic check ./frame.tsx --theme dark,light --json
6520
6693
  vizmatic render examples --out docs/assets/examples --theme dark --watermark Vizmatic
6521
6694
  vizmatic render frames/attention.tsx --out dist/frames --theme dark,light
6522
6695
  vizmatic gif examples/animated-pipeline.tsx --out docs/assets/examples --theme dark --watermark Vizmatic`;
@@ -6551,7 +6724,7 @@ async function imageSourceToDataUri(source) {
6551
6724
  }
6552
6725
  async function resolveWatermarkAssets(watermark) {
6553
6726
  if (watermark == null || typeof watermark !== "object") return watermark;
6554
- if (isValidElement(watermark) || !("image" in watermark) || !watermark.image) return watermark;
6727
+ if (isValidElement2(watermark) || !("image" in watermark) || !watermark.image) return watermark;
6555
6728
  if (typeof watermark.image === "string") {
6556
6729
  return {
6557
6730
  ...watermark,
@@ -6753,9 +6926,11 @@ ${imports.join("\n")}
6753
6926
 
6754
6927
  let __theme = __Vizmatic_getThemeColors('dark', ${JSON.stringify(preset)})
6755
6928
  function __withTheme(Component) {
6756
- return function VizmaticAutoTheme(props) {
6929
+ function VizmaticAutoTheme(props) {
6757
6930
  return React.createElement(Component, props?.c ? props : { ...props, c: __theme })
6758
6931
  }
6932
+ VizmaticAutoTheme.__vizmaticPrimitive = true
6933
+ return VizmaticAutoTheme
6759
6934
  }
6760
6935
  const Frame = ({ children }) => React.createElement(React.Fragment, null, children)
6761
6936
  ${buildAutoImportDeclarations(autoImports)}
@@ -6820,7 +6995,7 @@ function parseRenderArgs(argv) {
6820
6995
  let background;
6821
6996
  function mutableWatermark() {
6822
6997
  if (!watermarkOptions) {
6823
- watermarkOptions = typeof watermark === "object" && watermark !== null && !isValidElement(watermark) ? { ...watermark } : {};
6998
+ watermarkOptions = typeof watermark === "object" && watermark !== null && !isValidElement2(watermark) ? { ...watermark } : {};
6824
6999
  if (typeof watermark === "string") watermarkOptions.text = watermark;
6825
7000
  watermark = watermarkOptions;
6826
7001
  }
@@ -6912,6 +7087,33 @@ function parseRenderArgs(argv) {
6912
7087
  if (inputs.length === 0) usage();
6913
7088
  return { inputs, outDir, themes, watermark, crop, scale, background };
6914
7089
  }
7090
+ function parseCheckArgs(argv) {
7091
+ const inputs = [];
7092
+ let themes = ["dark", "light"];
7093
+ let background;
7094
+ let json = false;
7095
+ for (let index = 0; index < argv.length; index += 1) {
7096
+ const arg = argv[index];
7097
+ if (!arg) continue;
7098
+ if (arg === "--theme") {
7099
+ const raw = argv[++index] ?? usage();
7100
+ themes = raw.split(",").map((theme) => theme.trim()).filter(Boolean);
7101
+ if (themes.length === 0 || themes.some((theme) => theme !== "dark" && theme !== "light")) usage();
7102
+ } else if (arg === "--transparent" || arg === "--transparent-background") {
7103
+ background = "transparent";
7104
+ } else if (arg === "--background") {
7105
+ background = argv[++index] ?? usage();
7106
+ } else if (arg === "--json") {
7107
+ json = true;
7108
+ } else if (arg.startsWith("-")) {
7109
+ usage();
7110
+ } else {
7111
+ inputs.push(arg);
7112
+ }
7113
+ }
7114
+ if (inputs.length === 0) usage();
7115
+ return { inputs, themes, background, json };
7116
+ }
6915
7117
  async function findFrameFiles(inputs) {
6916
7118
  const files = /* @__PURE__ */ new Set();
6917
7119
  async function walk(path) {
@@ -7040,6 +7242,9 @@ function frameElement(mod, theme) {
7040
7242
  throw new Error("frame module must export create(theme) or default React element");
7041
7243
  }
7042
7244
  function overflowEdges(error) {
7245
+ if (error instanceof CanvasOverflowError) {
7246
+ return Object.entries(error.overflow.edges).filter(([, overflows]) => overflows).map(([edge]) => edge);
7247
+ }
7043
7248
  const message = error instanceof Error ? error.message : String(error);
7044
7249
  const match = message.match(/Content overflows canvas at: ([^.]+)/);
7045
7250
  if (!match?.[1]) return void 0;
@@ -7144,6 +7349,205 @@ async function renderCommand(argv) {
7144
7349
  await writeFile3(join2(args.outDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
7145
7350
  `);
7146
7351
  }
7352
+ function formatConsoleArgs(args) {
7353
+ return args.map((value) => {
7354
+ if (value instanceof Error) return value.message;
7355
+ if (typeof value === "string") return value;
7356
+ try {
7357
+ return JSON.stringify(value);
7358
+ } catch {
7359
+ return String(value);
7360
+ }
7361
+ }).join(" ");
7362
+ }
7363
+ async function captureConsole(run) {
7364
+ const messages = [];
7365
+ const original = {
7366
+ error: console.error,
7367
+ log: console.log,
7368
+ warn: console.warn
7369
+ };
7370
+ console.log = () => void 0;
7371
+ console.warn = (...args) => messages.push({ severity: "warning", message: formatConsoleArgs(args) });
7372
+ console.error = (...args) => messages.push({ severity: "error", message: formatConsoleArgs(args) });
7373
+ try {
7374
+ return { value: await run(), messages };
7375
+ } catch (error) {
7376
+ return { error, messages };
7377
+ } finally {
7378
+ console.error = original.error;
7379
+ console.log = original.log;
7380
+ console.warn = original.warn;
7381
+ }
7382
+ }
7383
+ function checkDiagnosticCounts(files) {
7384
+ const diagnostics = files.flatMap((file) => [
7385
+ ...file.diagnostics,
7386
+ ...file.themes.flatMap((theme) => theme.diagnostics)
7387
+ ]);
7388
+ return {
7389
+ errors: diagnostics.filter((diagnostic) => diagnostic.severity === "error").length,
7390
+ warnings: diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length,
7391
+ info: diagnostics.filter((diagnostic) => diagnostic.severity === "info").length
7392
+ };
7393
+ }
7394
+ function printCheckReport(files) {
7395
+ for (const file of files) {
7396
+ console.log(`${file.ok ? "ok" : "error"} ${file.source}`);
7397
+ for (const theme of file.themes) {
7398
+ const resolved = theme.dimensions.resolved ?? theme.dimensions.input;
7399
+ const output = theme.dimensions.output;
7400
+ const outputLabel = output ? ` -> ${output.width}\xD7${output.height}` : "";
7401
+ console.log(` ${theme.ok ? "ok" : "error"} ${theme.theme} ${resolved.width}\xD7${resolved.height}${outputLabel}`);
7402
+ for (const diagnostic of theme.diagnostics) {
7403
+ console.log(` ${diagnostic.severity} ${diagnostic.code}: ${diagnostic.message}`);
7404
+ if (diagnostic.suggestion) console.log(` ${diagnostic.suggestion}`);
7405
+ }
7406
+ }
7407
+ for (const diagnostic of file.diagnostics) {
7408
+ console.log(` ${diagnostic.severity} ${diagnostic.code}: ${diagnostic.message}`);
7409
+ }
7410
+ }
7411
+ }
7412
+ async function checkCommand(argv) {
7413
+ const args = parseCheckArgs(argv);
7414
+ const files = await findFrameFiles(args.inputs);
7415
+ if (files.length === 0) throw new Error("no frame files found");
7416
+ const tempDir = await mkdtemp(join2(tmpdir(), "vizmatic-check-"));
7417
+ const reports = [];
7418
+ try {
7419
+ for (const [fileIndex, file] of files.entries()) {
7420
+ const source = relative(process.cwd(), file);
7421
+ const imported = await captureConsole(() => importFrame(file));
7422
+ const diagnostics = imported.messages.map(
7423
+ (message) => diagnosticFromMessage(message.message, message.severity)
7424
+ );
7425
+ if (!imported.value) {
7426
+ diagnostics.push({
7427
+ code: "frame.load_error",
7428
+ severity: "error",
7429
+ message: imported.error instanceof Error ? imported.error.message : String(imported.error)
7430
+ });
7431
+ reports.push({ source, ok: false, diagnostics, themes: [] });
7432
+ continue;
7433
+ }
7434
+ const mod = normalizeFrameModule(imported.value);
7435
+ const themes = [];
7436
+ for (const [themeIndex, theme] of args.themes.entries()) {
7437
+ const input = { width: mod.width, height: mod.height };
7438
+ const themeDiagnostics = [];
7439
+ const prepared = await captureConsole(async () => {
7440
+ const element = frameElement(mod, theme);
7441
+ return analyzeContrast(element, theme, CONTRAST_TRUSTED_COMPONENTS);
7442
+ });
7443
+ themeDiagnostics.push(...prepared.messages.map(
7444
+ (message) => diagnosticFromMessage(message.message, message.severity, theme)
7445
+ ));
7446
+ if (!prepared.value) {
7447
+ themeDiagnostics.push(diagnosticFromMessage(
7448
+ prepared.error instanceof Error ? prepared.error.message : String(prepared.error),
7449
+ "error",
7450
+ theme
7451
+ ));
7452
+ themes.push({ theme, ok: false, dimensions: { input }, diagnostics: themeDiagnostics });
7453
+ continue;
7454
+ }
7455
+ themeDiagnostics.push(...prepared.value);
7456
+ const outputPath = join2(tempDir, `${fileIndex}-${themeIndex}.png`);
7457
+ const rendered = await captureConsole(() => renderFrameToPng(mod, theme, {
7458
+ ...input,
7459
+ outputPath,
7460
+ crop: true,
7461
+ scale: 1,
7462
+ background: args.background
7463
+ }));
7464
+ themeDiagnostics.push(...rendered.messages.map(
7465
+ (message) => diagnosticFromMessage(message.message, message.severity, theme)
7466
+ ));
7467
+ if (rendered.value) {
7468
+ if (rendered.value.width !== input.width || rendered.value.height !== input.height) {
7469
+ themeDiagnostics.push({
7470
+ code: "layout.auto_size",
7471
+ severity: "info",
7472
+ theme,
7473
+ message: `Canvas auto-sized from ${input.width}\xD7${input.height} to ${rendered.value.width}\xD7${rendered.value.height}.`,
7474
+ suggestedDimensions: {
7475
+ width: rendered.value.width,
7476
+ height: rendered.value.height
7477
+ }
7478
+ });
7479
+ }
7480
+ themes.push({
7481
+ theme,
7482
+ ok: !themeDiagnostics.some((diagnostic) => diagnostic.severity === "error"),
7483
+ dimensions: {
7484
+ input,
7485
+ resolved: { width: rendered.value.width, height: rendered.value.height },
7486
+ output: { width: rendered.value.outputWidth, height: rendered.value.outputHeight }
7487
+ },
7488
+ diagnostics: themeDiagnostics
7489
+ });
7490
+ continue;
7491
+ }
7492
+ const edges = overflowEdges(rendered.error);
7493
+ if (edges) {
7494
+ const suggestionMod = { ...mod, autoSize: { width: true, height: true } };
7495
+ const suggestion = await captureConsole(() => renderFrameToPng(suggestionMod, theme, {
7496
+ ...input,
7497
+ outputPath: join2(tempDir, `${fileIndex}-${themeIndex}-suggestion.png`),
7498
+ crop: true,
7499
+ scale: 1,
7500
+ background: args.background
7501
+ }));
7502
+ const suggestedDimensions = suggestion.value ? { width: suggestion.value.width, height: suggestion.value.height } : void 0;
7503
+ themeDiagnostics.push({
7504
+ code: "layout.overflow",
7505
+ severity: "error",
7506
+ theme,
7507
+ edges,
7508
+ message: rendered.error instanceof Error ? rendered.error.message : String(rendered.error),
7509
+ suggestion: suggestedDimensions ? `Increase the canvas to at least ${suggestedDimensions.width}\xD7${suggestedDimensions.height}, or remove fixed dimensions to enable auto-sizing.` : "Increase the canvas dimensions or remove fixed dimensions to enable auto-sizing.",
7510
+ suggestedDimensions
7511
+ });
7512
+ } else {
7513
+ themeDiagnostics.push(diagnosticFromMessage(
7514
+ rendered.error instanceof Error ? rendered.error.message : String(rendered.error),
7515
+ "error",
7516
+ theme
7517
+ ));
7518
+ }
7519
+ themes.push({
7520
+ theme,
7521
+ ok: false,
7522
+ dimensions: { input },
7523
+ diagnostics: themeDiagnostics
7524
+ });
7525
+ }
7526
+ const ok = !diagnostics.some((diagnostic) => diagnostic.severity === "error") && themes.every((theme) => theme.ok);
7527
+ reports.push({ source, ok, autoSize: mod.autoSize, diagnostics, themes });
7528
+ }
7529
+ } finally {
7530
+ await rm(tempDir, { recursive: true, force: true });
7531
+ }
7532
+ const summary = checkDiagnosticCounts(reports);
7533
+ const report = {
7534
+ schemaVersion: 1,
7535
+ command: "check",
7536
+ ok: summary.errors === 0,
7537
+ files: reports,
7538
+ summary: {
7539
+ files: reports.length,
7540
+ ...summary
7541
+ }
7542
+ };
7543
+ if (args.json) {
7544
+ console.log(JSON.stringify(report, null, 2));
7545
+ } else {
7546
+ printCheckReport(reports);
7547
+ console.log(`checked ${report.summary.files} file(s): ${summary.errors} error(s), ${summary.warnings} warning(s), ${summary.info} info`);
7548
+ }
7549
+ if (!report.ok) process.exitCode = 1;
7550
+ }
7147
7551
  async function gifCommand(argv) {
7148
7552
  const args = parseRenderArgs(argv);
7149
7553
  const cliWatermark = await resolveWatermarkAssets(args.watermark);
@@ -7201,6 +7605,8 @@ async function main() {
7201
7605
  const [command, ...rest] = args;
7202
7606
  if (command === "render") {
7203
7607
  await renderCommand(rest);
7608
+ } else if (command === "check") {
7609
+ await checkCommand(rest);
7204
7610
  } else if (command === "gif") {
7205
7611
  await gifCommand(rest);
7206
7612
  } else if (!command || command === "help" || command === "--help" || command === "-h") {
package/dist/index.cjs CHANGED
@@ -39,6 +39,7 @@ __export(index_exports, {
39
39
  Box: () => Box,
40
40
  CalloutCard: () => CalloutCard,
41
41
  Canvas: () => Canvas,
42
+ CanvasOverflowError: () => CanvasOverflowError,
42
43
  Card: () => Card,
43
44
  ChartFrame: () => ChartFrame,
44
45
  CodeBlock: () => CodeBlock,
@@ -6135,6 +6136,18 @@ function cropSavesEnough(source, target) {
6135
6136
  if (source <= 0 || target >= source) return false;
6136
6137
  return (source - target) / source * 100 >= CROP_THRESHOLD_PERCENT;
6137
6138
  }
6139
+ var CanvasOverflowError = class extends Error {
6140
+ width;
6141
+ height;
6142
+ overflow;
6143
+ constructor(width, height, overflow) {
6144
+ super(`Canvas overflow detected (${width}\xD7${height}): ${overflow.message}`);
6145
+ this.name = "CanvasOverflowError";
6146
+ this.width = width;
6147
+ this.height = height;
6148
+ this.overflow = overflow;
6149
+ }
6150
+ };
6138
6151
  function resolveWatermark(options) {
6139
6152
  return options.watermark ?? options.brand;
6140
6153
  }
@@ -6185,9 +6198,7 @@ async function renderToPngInContext(element, options, createFn, theme) {
6185
6198
  detectedBg
6186
6199
  );
6187
6200
  if (overflow.overflows) {
6188
- throw new Error(
6189
- `Canvas overflow detected (${options.width}\xD7${options.height}): ${overflow.message}`
6190
- );
6201
+ throw new CanvasOverflowError(options.width, options.height, overflow);
6191
6202
  }
6192
6203
  let finalWidth = options.width;
6193
6204
  let finalHeight = options.height;
@@ -6502,6 +6513,7 @@ async function renderAnimatedGifWithOutput(scenes, options) {
6502
6513
  Box,
6503
6514
  CalloutCard,
6504
6515
  Canvas,
6516
+ CanvasOverflowError,
6505
6517
  Card,
6506
6518
  ChartFrame,
6507
6519
  CodeBlock,
package/dist/index.d.cts CHANGED
@@ -1318,6 +1318,85 @@ declare function Watermark(_props: WatermarkElementProps): null;
1318
1318
  declare function wrapWithWatermark(element: React.ReactNode, width: number, height: number, theme?: 'dark' | 'light', watermark?: WatermarkInput): React.ReactElement;
1319
1319
  declare function wrapWithBrand(element: React.ReactNode, width: number, height: number, theme?: 'dark' | 'light', label?: string): React.ReactElement;
1320
1320
 
1321
+ /**
1322
+ * Vizmatic — Auto-Crop
1323
+ *
1324
+ * Detects the content bounding box in a rendered illustration
1325
+ * and returns the crop region needed to trim blank space.
1326
+ *
1327
+ * Works by scanning the raw RGBA pixel buffer from resvg to find
1328
+ * rows/columns that differ from the background color.
1329
+ */
1330
+ interface CropRegion {
1331
+ /** Left edge of content (px from left, in source pixel space) */
1332
+ x: number;
1333
+ /** Top edge of content (px from top, in source pixel space) */
1334
+ y: number;
1335
+ /** Width of the content region */
1336
+ width: number;
1337
+ /** Height of the content region */
1338
+ height: number;
1339
+ }
1340
+ /**
1341
+ * Detect background color from top-left corner pixel.
1342
+ *
1343
+ * Transparent canvases are tracked separately so opaque black content is not
1344
+ * mistaken for a transparent background.
1345
+ */
1346
+ declare function detectBackgroundColor(pixels: Uint8Array): string;
1347
+ /**
1348
+ * Detect the bounding box of non-background content in an RGBA pixel buffer.
1349
+ *
1350
+ * @param pixels - Raw RGBA pixel data (Uint8Array, 4 bytes per pixel)
1351
+ * @param width - Image width in pixels
1352
+ * @param height - Image height in pixels
1353
+ * @param bgColor - Background color as hex string (e.g., '#0f1117')
1354
+ * @param padding - Extra padding to add around the detected content
1355
+ * @returns CropRegion with the content bounding box (including padding)
1356
+ */
1357
+ declare function detectContentBounds(pixels: Uint8Array, width: number, height: number, bgColor: string, padding?: number): CropRegion;
1358
+ /**
1359
+ * Crop an RGBA pixel buffer to a given region.
1360
+ *
1361
+ * @param pixels - Source RGBA pixel data
1362
+ * @param srcWidth - Source image width
1363
+ * @param region - Region to crop to
1364
+ * @returns New RGBA pixel buffer with just the cropped region
1365
+ */
1366
+ declare function cropPixels(pixels: Uint8Array, srcWidth: number, region: CropRegion): Uint8Array;
1367
+ interface OverflowResult {
1368
+ /** True if content is likely being clipped by the canvas */
1369
+ overflows: boolean;
1370
+ /** Which edges have content touching them */
1371
+ edges: {
1372
+ top: boolean;
1373
+ right: boolean;
1374
+ bottom: boolean;
1375
+ left: boolean;
1376
+ };
1377
+ /** Human-readable description of the overflow */
1378
+ message: string;
1379
+ }
1380
+ /**
1381
+ * Detect if illustration content overflows the canvas.
1382
+ *
1383
+ * Content that touches the very edge of the canvas (within `edgeTolerance` px)
1384
+ * likely extends beyond it and is being clipped. This function scans the edge
1385
+ * rows/columns for non-background pixels.
1386
+ *
1387
+ * To avoid false positives from decorative elements that intentionally touch
1388
+ * the border (e.g. full-width bars), we require at least `minDensity` % of
1389
+ * the edge to contain content pixels.
1390
+ *
1391
+ * @param pixels - Raw RGBA pixel data
1392
+ * @param width - Image width in pixels
1393
+ * @param height - Image height in pixels
1394
+ * @param bgColor - Background color as hex string
1395
+ * @param edgeTolerance - Number of pixels from the edge to check (default 3)
1396
+ * @param minDensity - Minimum fraction of edge with content to flag (default 0.05)
1397
+ */
1398
+ declare function detectOverflow(pixels: Uint8Array, width: number, height: number, bgColor: string, edgeTolerance?: number, minDensity?: number, alphaThreshold?: number): OverflowResult;
1399
+
1321
1400
  type RenderBackground = 'transparent' | 'theme' | (string & {});
1322
1401
 
1323
1402
  /**
@@ -1375,6 +1454,12 @@ interface RenderOutput {
1375
1454
  /** PNG height in physical pixels after scale is applied. */
1376
1455
  pixelHeight: number;
1377
1456
  }
1457
+ declare class CanvasOverflowError extends Error {
1458
+ readonly width: number;
1459
+ readonly height: number;
1460
+ readonly overflow: OverflowResult;
1461
+ constructor(width: number, height: number, overflow: OverflowResult);
1462
+ }
1378
1463
  /**
1379
1464
  * Render a JSX element to a PNG file, with auto-crop and optional watermark.
1380
1465
  *
@@ -1427,83 +1512,4 @@ interface AnimationOutput {
1427
1512
  declare function renderAnimatedGif(scenes: AnimatedScene[], options: AnimationOptions): Promise<void>;
1428
1513
  declare function renderAnimatedGifWithOutput(scenes: AnimatedScene[], options: AnimationOptions): Promise<AnimationOutput>;
1429
1514
 
1430
- /**
1431
- * Vizmatic — Auto-Crop
1432
- *
1433
- * Detects the content bounding box in a rendered illustration
1434
- * and returns the crop region needed to trim blank space.
1435
- *
1436
- * Works by scanning the raw RGBA pixel buffer from resvg to find
1437
- * rows/columns that differ from the background color.
1438
- */
1439
- interface CropRegion {
1440
- /** Left edge of content (px from left, in source pixel space) */
1441
- x: number;
1442
- /** Top edge of content (px from top, in source pixel space) */
1443
- y: number;
1444
- /** Width of the content region */
1445
- width: number;
1446
- /** Height of the content region */
1447
- height: number;
1448
- }
1449
- /**
1450
- * Detect background color from top-left corner pixel.
1451
- *
1452
- * Transparent canvases are tracked separately so opaque black content is not
1453
- * mistaken for a transparent background.
1454
- */
1455
- declare function detectBackgroundColor(pixels: Uint8Array): string;
1456
- /**
1457
- * Detect the bounding box of non-background content in an RGBA pixel buffer.
1458
- *
1459
- * @param pixels - Raw RGBA pixel data (Uint8Array, 4 bytes per pixel)
1460
- * @param width - Image width in pixels
1461
- * @param height - Image height in pixels
1462
- * @param bgColor - Background color as hex string (e.g., '#0f1117')
1463
- * @param padding - Extra padding to add around the detected content
1464
- * @returns CropRegion with the content bounding box (including padding)
1465
- */
1466
- declare function detectContentBounds(pixels: Uint8Array, width: number, height: number, bgColor: string, padding?: number): CropRegion;
1467
- /**
1468
- * Crop an RGBA pixel buffer to a given region.
1469
- *
1470
- * @param pixels - Source RGBA pixel data
1471
- * @param srcWidth - Source image width
1472
- * @param region - Region to crop to
1473
- * @returns New RGBA pixel buffer with just the cropped region
1474
- */
1475
- declare function cropPixels(pixels: Uint8Array, srcWidth: number, region: CropRegion): Uint8Array;
1476
- interface OverflowResult {
1477
- /** True if content is likely being clipped by the canvas */
1478
- overflows: boolean;
1479
- /** Which edges have content touching them */
1480
- edges: {
1481
- top: boolean;
1482
- right: boolean;
1483
- bottom: boolean;
1484
- left: boolean;
1485
- };
1486
- /** Human-readable description of the overflow */
1487
- message: string;
1488
- }
1489
- /**
1490
- * Detect if illustration content overflows the canvas.
1491
- *
1492
- * Content that touches the very edge of the canvas (within `edgeTolerance` px)
1493
- * likely extends beyond it and is being clipped. This function scans the edge
1494
- * rows/columns for non-background pixels.
1495
- *
1496
- * To avoid false positives from decorative elements that intentionally touch
1497
- * the border (e.g. full-width bars), we require at least `minDensity` % of
1498
- * the edge to contain content pixels.
1499
- *
1500
- * @param pixels - Raw RGBA pixel data
1501
- * @param width - Image width in pixels
1502
- * @param height - Image height in pixels
1503
- * @param bgColor - Background color as hex string
1504
- * @param edgeTolerance - Number of pixels from the edge to check (default 3)
1505
- * @param minDensity - Minimum fraction of edge with content to flag (default 0.05)
1506
- */
1507
- declare function detectOverflow(pixels: Uint8Array, width: number, height: number, bgColor: string, edgeTolerance?: number, minDensity?: number, alphaThreshold?: number): OverflowResult;
1508
-
1509
- export { type AnimatedScene, type AnimationOptions, type AnimationOutput, Arrow, ArrowMarkerDef, AxisPlot, type AxisPlotPath, Badge, BadgePill, BarChart, type BarChartDatum, Box, CalloutCard, Canvas, Card, ChartFrame, type ChartLegendItem, type ChartMargins, type ChartValueFormat, CodeBlock, type CodeLineSpec, type ColorName, Column, Comparison, type ComparisonSideSpec, Connector, type CropMode, type CropRegion, DashedLine, DataTable, DetailList, DonutChart, type DonutChartSegment, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramNode, Grid, Heatmap, Icon, type IconName, type IconProps, type IllustrationBuilder, type IntervalDatum, IntervalPlot, KeyValueList, type KeyValueRow, LayeredNetwork, type LayeredNetworkLayer, Legend, LineChart, type LineChartSeries, MathText, Matrix, MetricCard, MiniBarChart, type MiniBarDatum, type OverflowResult, Panel, Pipeline, type PlotArea, ProgressList, ProgressRow, type ProgressRowSpec, QuadrantChart, type QuadrantRegion, type RenderBackground, type RenderOptions, type RenderOutput, Row, ScatterPlot, type ScatterPoint, Scene, Stack, StackedBar, type StackedBarSegment, type StatusKind, StatusList, StatusRow, type StatusRowSpec, StepCard, SvgFrame, SvgMathText, SvgPoint, TextLabel, type ThemeColors, type ThemeMode, type ThemePreset, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, Timeline, type TimelineEventSpec, TitleBar, type ToneName, ToneStrip, type TransitionType, TreeDiagram, type TreeNodeSpec, ValuePill, VectorArrow, VectorSegment, Watermark, type WatermarkElementProps, type WatermarkImageOptions, type WatermarkInput, type WatermarkOptions, type WatermarkPosition, WindowFrame, canvas, colors, createPlotArea, cropPixels, defineIllustration, detectBackgroundColor, detectContentBounds, detectOverflow, formatMathText, getColor, getFonts, getGradient, getStyles, getThemeColors, getToneColor, getToneFill, getToneGradient, gradients, heatColor, loadAdditionalAsset, normalizeWatermark, renderAnimatedGif, renderAnimatedGifWithOutput, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, styles, toneGradients, typography, wrapWithBrand, wrapWithWatermark };
1515
+ export { type AnimatedScene, type AnimationOptions, type AnimationOutput, Arrow, ArrowMarkerDef, AxisPlot, type AxisPlotPath, Badge, BadgePill, BarChart, type BarChartDatum, Box, CalloutCard, Canvas, CanvasOverflowError, Card, ChartFrame, type ChartLegendItem, type ChartMargins, type ChartValueFormat, CodeBlock, type CodeLineSpec, type ColorName, Column, Comparison, type ComparisonSideSpec, Connector, type CropMode, type CropRegion, DashedLine, DataTable, DetailList, DonutChart, type DonutChartSegment, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramNode, Grid, Heatmap, Icon, type IconName, type IconProps, type IllustrationBuilder, type IntervalDatum, IntervalPlot, KeyValueList, type KeyValueRow, LayeredNetwork, type LayeredNetworkLayer, Legend, LineChart, type LineChartSeries, MathText, Matrix, MetricCard, MiniBarChart, type MiniBarDatum, type OverflowResult, Panel, Pipeline, type PlotArea, ProgressList, ProgressRow, type ProgressRowSpec, QuadrantChart, type QuadrantRegion, type RenderBackground, type RenderOptions, type RenderOutput, Row, ScatterPlot, type ScatterPoint, Scene, Stack, StackedBar, type StackedBarSegment, type StatusKind, StatusList, StatusRow, type StatusRowSpec, StepCard, SvgFrame, SvgMathText, SvgPoint, TextLabel, type ThemeColors, type ThemeMode, type ThemePreset, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, Timeline, type TimelineEventSpec, TitleBar, type ToneName, ToneStrip, type TransitionType, TreeDiagram, type TreeNodeSpec, ValuePill, VectorArrow, VectorSegment, Watermark, type WatermarkElementProps, type WatermarkImageOptions, type WatermarkInput, type WatermarkOptions, type WatermarkPosition, WindowFrame, canvas, colors, createPlotArea, cropPixels, defineIllustration, detectBackgroundColor, detectContentBounds, detectOverflow, formatMathText, getColor, getFonts, getGradient, getStyles, getThemeColors, getToneColor, getToneFill, getToneGradient, gradients, heatColor, loadAdditionalAsset, normalizeWatermark, renderAnimatedGif, renderAnimatedGifWithOutput, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, styles, toneGradients, typography, wrapWithBrand, wrapWithWatermark };
package/dist/index.d.ts CHANGED
@@ -1318,6 +1318,85 @@ declare function Watermark(_props: WatermarkElementProps): null;
1318
1318
  declare function wrapWithWatermark(element: React.ReactNode, width: number, height: number, theme?: 'dark' | 'light', watermark?: WatermarkInput): React.ReactElement;
1319
1319
  declare function wrapWithBrand(element: React.ReactNode, width: number, height: number, theme?: 'dark' | 'light', label?: string): React.ReactElement;
1320
1320
 
1321
+ /**
1322
+ * Vizmatic — Auto-Crop
1323
+ *
1324
+ * Detects the content bounding box in a rendered illustration
1325
+ * and returns the crop region needed to trim blank space.
1326
+ *
1327
+ * Works by scanning the raw RGBA pixel buffer from resvg to find
1328
+ * rows/columns that differ from the background color.
1329
+ */
1330
+ interface CropRegion {
1331
+ /** Left edge of content (px from left, in source pixel space) */
1332
+ x: number;
1333
+ /** Top edge of content (px from top, in source pixel space) */
1334
+ y: number;
1335
+ /** Width of the content region */
1336
+ width: number;
1337
+ /** Height of the content region */
1338
+ height: number;
1339
+ }
1340
+ /**
1341
+ * Detect background color from top-left corner pixel.
1342
+ *
1343
+ * Transparent canvases are tracked separately so opaque black content is not
1344
+ * mistaken for a transparent background.
1345
+ */
1346
+ declare function detectBackgroundColor(pixels: Uint8Array): string;
1347
+ /**
1348
+ * Detect the bounding box of non-background content in an RGBA pixel buffer.
1349
+ *
1350
+ * @param pixels - Raw RGBA pixel data (Uint8Array, 4 bytes per pixel)
1351
+ * @param width - Image width in pixels
1352
+ * @param height - Image height in pixels
1353
+ * @param bgColor - Background color as hex string (e.g., '#0f1117')
1354
+ * @param padding - Extra padding to add around the detected content
1355
+ * @returns CropRegion with the content bounding box (including padding)
1356
+ */
1357
+ declare function detectContentBounds(pixels: Uint8Array, width: number, height: number, bgColor: string, padding?: number): CropRegion;
1358
+ /**
1359
+ * Crop an RGBA pixel buffer to a given region.
1360
+ *
1361
+ * @param pixels - Source RGBA pixel data
1362
+ * @param srcWidth - Source image width
1363
+ * @param region - Region to crop to
1364
+ * @returns New RGBA pixel buffer with just the cropped region
1365
+ */
1366
+ declare function cropPixels(pixels: Uint8Array, srcWidth: number, region: CropRegion): Uint8Array;
1367
+ interface OverflowResult {
1368
+ /** True if content is likely being clipped by the canvas */
1369
+ overflows: boolean;
1370
+ /** Which edges have content touching them */
1371
+ edges: {
1372
+ top: boolean;
1373
+ right: boolean;
1374
+ bottom: boolean;
1375
+ left: boolean;
1376
+ };
1377
+ /** Human-readable description of the overflow */
1378
+ message: string;
1379
+ }
1380
+ /**
1381
+ * Detect if illustration content overflows the canvas.
1382
+ *
1383
+ * Content that touches the very edge of the canvas (within `edgeTolerance` px)
1384
+ * likely extends beyond it and is being clipped. This function scans the edge
1385
+ * rows/columns for non-background pixels.
1386
+ *
1387
+ * To avoid false positives from decorative elements that intentionally touch
1388
+ * the border (e.g. full-width bars), we require at least `minDensity` % of
1389
+ * the edge to contain content pixels.
1390
+ *
1391
+ * @param pixels - Raw RGBA pixel data
1392
+ * @param width - Image width in pixels
1393
+ * @param height - Image height in pixels
1394
+ * @param bgColor - Background color as hex string
1395
+ * @param edgeTolerance - Number of pixels from the edge to check (default 3)
1396
+ * @param minDensity - Minimum fraction of edge with content to flag (default 0.05)
1397
+ */
1398
+ declare function detectOverflow(pixels: Uint8Array, width: number, height: number, bgColor: string, edgeTolerance?: number, minDensity?: number, alphaThreshold?: number): OverflowResult;
1399
+
1321
1400
  type RenderBackground = 'transparent' | 'theme' | (string & {});
1322
1401
 
1323
1402
  /**
@@ -1375,6 +1454,12 @@ interface RenderOutput {
1375
1454
  /** PNG height in physical pixels after scale is applied. */
1376
1455
  pixelHeight: number;
1377
1456
  }
1457
+ declare class CanvasOverflowError extends Error {
1458
+ readonly width: number;
1459
+ readonly height: number;
1460
+ readonly overflow: OverflowResult;
1461
+ constructor(width: number, height: number, overflow: OverflowResult);
1462
+ }
1378
1463
  /**
1379
1464
  * Render a JSX element to a PNG file, with auto-crop and optional watermark.
1380
1465
  *
@@ -1427,83 +1512,4 @@ interface AnimationOutput {
1427
1512
  declare function renderAnimatedGif(scenes: AnimatedScene[], options: AnimationOptions): Promise<void>;
1428
1513
  declare function renderAnimatedGifWithOutput(scenes: AnimatedScene[], options: AnimationOptions): Promise<AnimationOutput>;
1429
1514
 
1430
- /**
1431
- * Vizmatic — Auto-Crop
1432
- *
1433
- * Detects the content bounding box in a rendered illustration
1434
- * and returns the crop region needed to trim blank space.
1435
- *
1436
- * Works by scanning the raw RGBA pixel buffer from resvg to find
1437
- * rows/columns that differ from the background color.
1438
- */
1439
- interface CropRegion {
1440
- /** Left edge of content (px from left, in source pixel space) */
1441
- x: number;
1442
- /** Top edge of content (px from top, in source pixel space) */
1443
- y: number;
1444
- /** Width of the content region */
1445
- width: number;
1446
- /** Height of the content region */
1447
- height: number;
1448
- }
1449
- /**
1450
- * Detect background color from top-left corner pixel.
1451
- *
1452
- * Transparent canvases are tracked separately so opaque black content is not
1453
- * mistaken for a transparent background.
1454
- */
1455
- declare function detectBackgroundColor(pixels: Uint8Array): string;
1456
- /**
1457
- * Detect the bounding box of non-background content in an RGBA pixel buffer.
1458
- *
1459
- * @param pixels - Raw RGBA pixel data (Uint8Array, 4 bytes per pixel)
1460
- * @param width - Image width in pixels
1461
- * @param height - Image height in pixels
1462
- * @param bgColor - Background color as hex string (e.g., '#0f1117')
1463
- * @param padding - Extra padding to add around the detected content
1464
- * @returns CropRegion with the content bounding box (including padding)
1465
- */
1466
- declare function detectContentBounds(pixels: Uint8Array, width: number, height: number, bgColor: string, padding?: number): CropRegion;
1467
- /**
1468
- * Crop an RGBA pixel buffer to a given region.
1469
- *
1470
- * @param pixels - Source RGBA pixel data
1471
- * @param srcWidth - Source image width
1472
- * @param region - Region to crop to
1473
- * @returns New RGBA pixel buffer with just the cropped region
1474
- */
1475
- declare function cropPixels(pixels: Uint8Array, srcWidth: number, region: CropRegion): Uint8Array;
1476
- interface OverflowResult {
1477
- /** True if content is likely being clipped by the canvas */
1478
- overflows: boolean;
1479
- /** Which edges have content touching them */
1480
- edges: {
1481
- top: boolean;
1482
- right: boolean;
1483
- bottom: boolean;
1484
- left: boolean;
1485
- };
1486
- /** Human-readable description of the overflow */
1487
- message: string;
1488
- }
1489
- /**
1490
- * Detect if illustration content overflows the canvas.
1491
- *
1492
- * Content that touches the very edge of the canvas (within `edgeTolerance` px)
1493
- * likely extends beyond it and is being clipped. This function scans the edge
1494
- * rows/columns for non-background pixels.
1495
- *
1496
- * To avoid false positives from decorative elements that intentionally touch
1497
- * the border (e.g. full-width bars), we require at least `minDensity` % of
1498
- * the edge to contain content pixels.
1499
- *
1500
- * @param pixels - Raw RGBA pixel data
1501
- * @param width - Image width in pixels
1502
- * @param height - Image height in pixels
1503
- * @param bgColor - Background color as hex string
1504
- * @param edgeTolerance - Number of pixels from the edge to check (default 3)
1505
- * @param minDensity - Minimum fraction of edge with content to flag (default 0.05)
1506
- */
1507
- declare function detectOverflow(pixels: Uint8Array, width: number, height: number, bgColor: string, edgeTolerance?: number, minDensity?: number, alphaThreshold?: number): OverflowResult;
1508
-
1509
- export { type AnimatedScene, type AnimationOptions, type AnimationOutput, Arrow, ArrowMarkerDef, AxisPlot, type AxisPlotPath, Badge, BadgePill, BarChart, type BarChartDatum, Box, CalloutCard, Canvas, Card, ChartFrame, type ChartLegendItem, type ChartMargins, type ChartValueFormat, CodeBlock, type CodeLineSpec, type ColorName, Column, Comparison, type ComparisonSideSpec, Connector, type CropMode, type CropRegion, DashedLine, DataTable, DetailList, DonutChart, type DonutChartSegment, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramNode, Grid, Heatmap, Icon, type IconName, type IconProps, type IllustrationBuilder, type IntervalDatum, IntervalPlot, KeyValueList, type KeyValueRow, LayeredNetwork, type LayeredNetworkLayer, Legend, LineChart, type LineChartSeries, MathText, Matrix, MetricCard, MiniBarChart, type MiniBarDatum, type OverflowResult, Panel, Pipeline, type PlotArea, ProgressList, ProgressRow, type ProgressRowSpec, QuadrantChart, type QuadrantRegion, type RenderBackground, type RenderOptions, type RenderOutput, Row, ScatterPlot, type ScatterPoint, Scene, Stack, StackedBar, type StackedBarSegment, type StatusKind, StatusList, StatusRow, type StatusRowSpec, StepCard, SvgFrame, SvgMathText, SvgPoint, TextLabel, type ThemeColors, type ThemeMode, type ThemePreset, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, Timeline, type TimelineEventSpec, TitleBar, type ToneName, ToneStrip, type TransitionType, TreeDiagram, type TreeNodeSpec, ValuePill, VectorArrow, VectorSegment, Watermark, type WatermarkElementProps, type WatermarkImageOptions, type WatermarkInput, type WatermarkOptions, type WatermarkPosition, WindowFrame, canvas, colors, createPlotArea, cropPixels, defineIllustration, detectBackgroundColor, detectContentBounds, detectOverflow, formatMathText, getColor, getFonts, getGradient, getStyles, getThemeColors, getToneColor, getToneFill, getToneGradient, gradients, heatColor, loadAdditionalAsset, normalizeWatermark, renderAnimatedGif, renderAnimatedGifWithOutput, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, styles, toneGradients, typography, wrapWithBrand, wrapWithWatermark };
1515
+ export { type AnimatedScene, type AnimationOptions, type AnimationOutput, Arrow, ArrowMarkerDef, AxisPlot, type AxisPlotPath, Badge, BadgePill, BarChart, type BarChartDatum, Box, CalloutCard, Canvas, CanvasOverflowError, Card, ChartFrame, type ChartLegendItem, type ChartMargins, type ChartValueFormat, CodeBlock, type CodeLineSpec, type ColorName, Column, Comparison, type ComparisonSideSpec, Connector, type CropMode, type CropRegion, DashedLine, DataTable, DetailList, DonutChart, type DonutChartSegment, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramNode, Grid, Heatmap, Icon, type IconName, type IconProps, type IllustrationBuilder, type IntervalDatum, IntervalPlot, KeyValueList, type KeyValueRow, LayeredNetwork, type LayeredNetworkLayer, Legend, LineChart, type LineChartSeries, MathText, Matrix, MetricCard, MiniBarChart, type MiniBarDatum, type OverflowResult, Panel, Pipeline, type PlotArea, ProgressList, ProgressRow, type ProgressRowSpec, QuadrantChart, type QuadrantRegion, type RenderBackground, type RenderOptions, type RenderOutput, Row, ScatterPlot, type ScatterPoint, Scene, Stack, StackedBar, type StackedBarSegment, type StatusKind, StatusList, StatusRow, type StatusRowSpec, StepCard, SvgFrame, SvgMathText, SvgPoint, TextLabel, type ThemeColors, type ThemeMode, type ThemePreset, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, Timeline, type TimelineEventSpec, TitleBar, type ToneName, ToneStrip, type TransitionType, TreeDiagram, type TreeNodeSpec, ValuePill, VectorArrow, VectorSegment, Watermark, type WatermarkElementProps, type WatermarkImageOptions, type WatermarkInput, type WatermarkOptions, type WatermarkPosition, WindowFrame, canvas, colors, createPlotArea, cropPixels, defineIllustration, detectBackgroundColor, detectContentBounds, detectOverflow, formatMathText, getColor, getFonts, getGradient, getStyles, getThemeColors, getToneColor, getToneFill, getToneGradient, gradients, heatColor, loadAdditionalAsset, normalizeWatermark, renderAnimatedGif, renderAnimatedGifWithOutput, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, styles, toneGradients, typography, wrapWithBrand, wrapWithWatermark };
package/dist/index.js CHANGED
@@ -6002,6 +6002,18 @@ function cropSavesEnough(source, target) {
6002
6002
  if (source <= 0 || target >= source) return false;
6003
6003
  return (source - target) / source * 100 >= CROP_THRESHOLD_PERCENT;
6004
6004
  }
6005
+ var CanvasOverflowError = class extends Error {
6006
+ width;
6007
+ height;
6008
+ overflow;
6009
+ constructor(width, height, overflow) {
6010
+ super(`Canvas overflow detected (${width}\xD7${height}): ${overflow.message}`);
6011
+ this.name = "CanvasOverflowError";
6012
+ this.width = width;
6013
+ this.height = height;
6014
+ this.overflow = overflow;
6015
+ }
6016
+ };
6005
6017
  function resolveWatermark(options) {
6006
6018
  return options.watermark ?? options.brand;
6007
6019
  }
@@ -6052,9 +6064,7 @@ async function renderToPngInContext(element, options, createFn, theme) {
6052
6064
  detectedBg
6053
6065
  );
6054
6066
  if (overflow.overflows) {
6055
- throw new Error(
6056
- `Canvas overflow detected (${options.width}\xD7${options.height}): ${overflow.message}`
6057
- );
6067
+ throw new CanvasOverflowError(options.width, options.height, overflow);
6058
6068
  }
6059
6069
  let finalWidth = options.width;
6060
6070
  let finalHeight = options.height;
@@ -6368,6 +6378,7 @@ export {
6368
6378
  Box,
6369
6379
  CalloutCard,
6370
6380
  Canvas,
6381
+ CanvasOverflowError,
6371
6382
  Card,
6372
6383
  ChartFrame,
6373
6384
  CodeBlock,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vizmatic",
3
- "version": "0.1.30",
3
+ "version": "0.1.31",
4
4
  "description": "Theme-aware visual primitives and render pipeline for AI-generated diagrams, figures, and presentation frames.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -60,6 +60,7 @@
60
60
  "typecheck": "tsc --noEmit",
61
61
  "test": "vitest run",
62
62
  "render:examples": "pnpm build && tsx scripts/render-examples.ts && pnpm site:build",
63
+ "playground:build": "tsx scripts/build-playground.ts",
63
64
  "site:build": "tsx scripts/build-site.ts",
64
65
  "docs:check": "tsx scripts/check-docs.ts",
65
66
  "workflows:check": "github-actionlint .github/workflows/*.yml",
@@ -82,10 +83,13 @@
82
83
  "react": ">=18"
83
84
  },
84
85
  "devDependencies": {
86
+ "@resvg/resvg-wasm": "2.6.2",
85
87
  "@types/node": "^26.0.1",
86
88
  "@types/react": "^19.1.8",
89
+ "esbuild": "0.28.1",
87
90
  "github-actionlint": "1.7.12",
88
91
  "shiki": "^4.3.0",
92
+ "sucrase": "3.35.1",
89
93
  "tsup": "^8.5.0",
90
94
  "typescript": "^6.0.3",
91
95
  "vitest": "^4.1.9"