vizmatic 0.1.16 → 0.1.18

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
@@ -119,7 +119,7 @@ Or set it in the frame:
119
119
  </Scene>
120
120
  ```
121
121
 
122
- If a direct CLI frame omits `width` or `height`, Vizmatic starts at `960x540` and grows omitted axes when overflow is detected. Explicit dimensions stay strict and should be used when exact output size matters.
122
+ If a direct CLI frame omits `width` or `height`, Vizmatic starts at `960x540` and grows to fit content when overflow is detected. Generated wrappers that export the default `960x540` size get the same fit-to-content behavior. Add `autoSize = false` when exact dimensions should stay strict and fail on clipping.
123
123
 
124
124
  For direct CLI frames, skip imports, `defineIllustration`, and `c` props by default. The CLI injects Vizmatic primitives and theme colors. Reference `c` only when you need explicit theme tokens such as `background={c.bg}`. `Scene` title/subtitle are optional; omit both for visual-only figures, badges, inline blog diagrams, or frames where surrounding copy already supplies the title. Use the full module form when you need custom dependencies, direct renderer APIs, advanced reusable JSX helpers, or animation exports.
125
125
 
@@ -418,13 +418,13 @@ height = 560;
418
418
 
419
419
  - Use semantic tones, not hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
420
420
  - Keep canvas sizes explicit. Good defaults: `1040x560` for article figures, `1280x720` for slide frames, `900x520` for compact diagrams.
421
- - For exploratory direct CLI frames, dimensions may be omitted; Vizmatic auto-grows omitted axes if content overflows.
421
+ - For exploratory direct CLI frames, dimensions may be omitted; Vizmatic starts at `960x540` and grows to fit content if overflow is detected.
422
422
  - Prefer alpha-transparent PNG/SVG backgrounds for blog embeds and docs cards. Use theme backgrounds only when the host surface is unknown or needs full-frame fill.
423
423
  - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` props to stabilize layout.
424
424
  - Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
425
425
  - Render both dark and light when shipping reusable assets: `--theme dark,light`.
426
426
  - Use GIF only when motion explains state change. Keep scenes short, export `createScenes(theme)`, and keep a static `create(theme)` fallback.
427
- - If render fails with `Canvas overflow detected`, increase canvas dimensions or reduce content density. Do not ignore the error.
427
+ - 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.
428
428
  - Verify generated PNGs/GIFs exist and are non-empty. Open at least one rendered image before finalizing.
429
429
 
430
430
  ## Common recipes
package/README.md CHANGED
@@ -50,7 +50,7 @@ PNG and SVG renders use an alpha-transparent canvas by default. Add `--backgroun
50
50
  vizmatic ./frame.tsx --out ./dist/frames --theme dark,light --background theme
51
51
  ```
52
52
 
53
- If a CLI frame omits `width` or `height`, Vizmatic starts at `960x540` and grows omitted axes when overflow is detected. Explicit dimensions stay strict and fail on clipping.
53
+ If a CLI frame omits `width` or `height`, Vizmatic starts at `960x540` and grows to fit content when overflow is detected. Generated wrappers that export the default `960x540` size get the same fit-to-content behavior. Add `autoSize = false` when exact dimensions should stay strict and fail on clipping.
54
54
 
55
55
  Bare CLI frames auto-import Vizmatic primitives and inject theme colors. Use normal imports when a frame needs helpers, data loading, custom dependencies, or direct renderer APIs.
56
56
 
package/dist/cli.js CHANGED
@@ -4946,7 +4946,7 @@ function cropPixels(pixels, srcWidth, region) {
4946
4946
  }
4947
4947
  return out;
4948
4948
  }
4949
- function detectOverflow(pixels, width, height, bgColor, edgeTolerance = 3, minDensity = 0.05, alphaThreshold = 128) {
4949
+ function detectOverflow(pixels, width, height, bgColor, edgeTolerance = 3, minDensity = 0.05, alphaThreshold = 10) {
4950
4950
  const isBackground = createBackgroundMatcher(bgColor);
4951
4951
  function isContentPixel(x, y) {
4952
4952
  const idx = (y * width + x) * 4;
@@ -5228,20 +5228,37 @@ async function renderToPngInContext(element, options, createFn, theme) {
5228
5228
  }
5229
5229
  }
5230
5230
  const watermark = resolveWatermark(options);
5231
- const outputElement = watermark ? wrapWithWatermark(
5232
- finalElement,
5233
- finalWidth,
5234
- finalHeight,
5235
- theme || "dark",
5236
- watermark
5237
- ) : finalElement;
5238
- let finalSvg = await satori(outputElement, {
5239
- width: finalWidth,
5240
- height: finalHeight,
5241
- fonts,
5242
- loadAdditionalAsset
5243
- });
5244
- finalSvg = sanitizeSvg(finalSvg);
5231
+ const renderFinalSvg = async (targetElement, targetWidth, targetHeight) => {
5232
+ const outputElement = watermark ? wrapWithWatermark(
5233
+ targetElement,
5234
+ targetWidth,
5235
+ targetHeight,
5236
+ theme || "dark",
5237
+ watermark
5238
+ ) : targetElement;
5239
+ const renderedSvg = await satori(outputElement, {
5240
+ width: targetWidth,
5241
+ height: targetHeight,
5242
+ fonts,
5243
+ loadAdditionalAsset
5244
+ });
5245
+ return sanitizeSvg(renderedSvg);
5246
+ };
5247
+ let finalSvg = await renderFinalSvg(finalElement, finalWidth, finalHeight);
5248
+ if (finalHeight < options.height) {
5249
+ const cropCheck = new Resvg(finalSvg, {
5250
+ fitTo: { mode: "width", value: finalWidth },
5251
+ background: "rgba(0, 0, 0, 0)"
5252
+ }).render();
5253
+ const cropPixels2 = new Uint8Array(cropCheck.pixels.buffer);
5254
+ const cropBg = detectBackgroundColor(cropPixels2);
5255
+ const cropOverflow = detectOverflow(cropPixels2, finalWidth, cropCheck.height, cropBg);
5256
+ if (cropOverflow.overflows) {
5257
+ finalHeight = options.height;
5258
+ finalElement = element;
5259
+ finalSvg = await renderFinalSvg(finalElement, finalWidth, finalHeight);
5260
+ }
5261
+ }
5245
5262
  const resvg = new Resvg(finalSvg, {
5246
5263
  fitTo: {
5247
5264
  mode: "width",
@@ -5558,13 +5575,24 @@ function resolveSelfEntry() {
5558
5575
  return void 0;
5559
5576
  }
5560
5577
  }
5561
- function resolveSelfRequireSpecifier() {
5562
- return resolveSelfEntry() ?? "vizmatic";
5578
+ function resolveSelfImportEntry() {
5579
+ const moduleDir = dirname3(fileURLToPath2(import.meta.url));
5580
+ const bundledEntry = join2(moduleDir, "index.js");
5581
+ if (existsSync2(bundledEntry)) return bundledEntry;
5582
+ const sourceEntry = join2(moduleDir, "index.ts");
5583
+ if (existsSync2(sourceEntry)) return sourceEntry;
5584
+ return void 0;
5585
+ }
5586
+ function resolveSelfImportSpecifier() {
5587
+ return resolveSelfImportEntry() ?? "vizmatic";
5563
5588
  }
5564
5589
  function resolveReactRequireSpecifier() {
5565
5590
  const reactEntry = resolveFrameDependency("react");
5566
5591
  return reactEntry ?? "react";
5567
5592
  }
5593
+ function resolveReactImportSpecifier() {
5594
+ return resolveReactRequireSpecifier();
5595
+ }
5568
5596
  function resolveFrameDependency(request) {
5569
5597
  try {
5570
5598
  if (request === "vizmatic") return resolveSelfEntry();
@@ -5637,10 +5665,10 @@ function bareFrameExportsForSource(source) {
5637
5665
  });
5638
5666
  }
5639
5667
  function buildAutoImportStatement(names) {
5640
- const specifiers = names.map((name) => ` ${name}: ${bareFrameAlias(name)}`).join(",\n");
5641
- return `const {
5668
+ const specifiers = names.map((name) => ` ${name} as ${bareFrameAlias(name)}`).join(",\n");
5669
+ return `import {
5642
5670
  ${specifiers}
5643
- } = __require(${JSON.stringify(resolveSelfRequireSpecifier())})`;
5671
+ } from ${JSON.stringify(resolveSelfImportSpecifier())}`;
5644
5672
  }
5645
5673
  function buildAutoImportDeclarations(names) {
5646
5674
  return names.map((name) => {
@@ -5684,9 +5712,7 @@ function buildBareFrameModule(framePath, source) {
5684
5712
  height ??= frameHeight ?? DEFAULT_FRAME_HEIGHT;
5685
5713
  const autoImports = bareFrameExportsForSource(body);
5686
5714
  return `/** @jsxRuntime classic */
5687
- import { createRequire as __createRequire } from 'module'
5688
- const __require = __createRequire(${JSON.stringify(import.meta.url)})
5689
- const React = __require(${JSON.stringify(resolveReactRequireSpecifier())})
5715
+ import React from ${JSON.stringify(resolveReactImportSpecifier())}
5690
5716
  ${buildAutoImportStatement(autoImports)}
5691
5717
  ${imports.join("\n")}
5692
5718
 
@@ -5710,7 +5736,7 @@ ${setup}
5710
5736
  return (${jsx})
5711
5737
  }
5712
5738
 
5713
- export default create('dark')
5739
+ export default { create, width, height }
5714
5740
  `;
5715
5741
  }
5716
5742
  function isBareFrameSource(source) {
@@ -5726,6 +5752,7 @@ async function importBareFrame(filePath, source) {
5726
5752
  if (!moduleSource) return void 0;
5727
5753
  const tempDir = await mkdtemp(join2(tmpdir(), "vizmatic-frame-"));
5728
5754
  const tempPath = join2(tempDir, `${basename(filePath).replace(/\.[^.]+$/, "")}.generated.tsx`);
5755
+ await writeFile3(join2(tempDir, "package.json"), '{"type":"module"}\n');
5729
5756
  await writeFile3(tempPath, `${moduleSource}
5730
5757
  `);
5731
5758
  try {
@@ -5901,17 +5928,20 @@ function normalizeAutoSize(value, defaults) {
5901
5928
  }
5902
5929
  function normalizeFrameModule(mod) {
5903
5930
  const defaultObject = typeof mod.default === "object" && mod.default && "create" in mod.default ? mod.default : void 0;
5931
+ const hasAutoSizeSetting = mod.autoSize != null || mod.__vizmaticAutoSize != null;
5904
5932
  const hasWidth = mod.width != null || defaultObject?.width != null;
5905
5933
  const hasHeight = mod.height != null || defaultObject?.height != null;
5934
+ const width = mod.width ?? defaultObject?.width ?? DEFAULT_FRAME_WIDTH;
5935
+ const height = mod.height ?? defaultObject?.height ?? DEFAULT_FRAME_HEIGHT;
5906
5936
  const autoSize = normalizeAutoSize(mod.autoSize ?? mod.__vizmaticAutoSize, {
5907
- width: !hasWidth,
5908
- height: !hasHeight
5937
+ width: !hasWidth || !hasAutoSizeSetting && width === DEFAULT_FRAME_WIDTH,
5938
+ height: !hasHeight || !hasAutoSizeSetting && height === DEFAULT_FRAME_HEIGHT
5909
5939
  });
5910
5940
  return {
5911
5941
  ...mod,
5912
5942
  ...defaultObject ?? {},
5913
- width: mod.width ?? defaultObject?.width ?? DEFAULT_FRAME_WIDTH,
5914
- height: mod.height ?? defaultObject?.height ?? DEFAULT_FRAME_HEIGHT,
5943
+ width,
5944
+ height,
5915
5945
  autoSize
5916
5946
  };
5917
5947
  }
@@ -6063,6 +6093,10 @@ async function main() {
6063
6093
  }
6064
6094
  }
6065
6095
  main().catch((error) => {
6066
- console.error(error instanceof Error ? error.message : String(error));
6096
+ if (process.env.VIZMATIC_DEBUG === "1" && error instanceof Error) {
6097
+ console.error(error.stack ?? error.message);
6098
+ } else {
6099
+ console.error(error instanceof Error ? error.message : String(error));
6100
+ }
6067
6101
  process.exit(1);
6068
6102
  });
package/dist/index.cjs CHANGED
@@ -4960,7 +4960,7 @@ function cropPixels(pixels, srcWidth, region) {
4960
4960
  }
4961
4961
  return out;
4962
4962
  }
4963
- function detectOverflow(pixels, width, height, bgColor, edgeTolerance = 3, minDensity = 0.05, alphaThreshold = 128) {
4963
+ function detectOverflow(pixels, width, height, bgColor, edgeTolerance = 3, minDensity = 0.05, alphaThreshold = 10) {
4964
4964
  const isBackground = createBackgroundMatcher(bgColor);
4965
4965
  function isContentPixel(x, y) {
4966
4966
  const idx = (y * width + x) * 4;
@@ -5243,20 +5243,37 @@ async function renderToPngInContext(element, options, createFn, theme) {
5243
5243
  }
5244
5244
  }
5245
5245
  const watermark = resolveWatermark(options);
5246
- const outputElement = watermark ? wrapWithWatermark(
5247
- finalElement,
5248
- finalWidth,
5249
- finalHeight,
5250
- theme || "dark",
5251
- watermark
5252
- ) : finalElement;
5253
- let finalSvg = await satori(outputElement, {
5254
- width: finalWidth,
5255
- height: finalHeight,
5256
- fonts,
5257
- loadAdditionalAsset
5258
- });
5259
- finalSvg = sanitizeSvg(finalSvg);
5246
+ const renderFinalSvg = async (targetElement, targetWidth, targetHeight) => {
5247
+ const outputElement = watermark ? wrapWithWatermark(
5248
+ targetElement,
5249
+ targetWidth,
5250
+ targetHeight,
5251
+ theme || "dark",
5252
+ watermark
5253
+ ) : targetElement;
5254
+ const renderedSvg = await satori(outputElement, {
5255
+ width: targetWidth,
5256
+ height: targetHeight,
5257
+ fonts,
5258
+ loadAdditionalAsset
5259
+ });
5260
+ return sanitizeSvg(renderedSvg);
5261
+ };
5262
+ let finalSvg = await renderFinalSvg(finalElement, finalWidth, finalHeight);
5263
+ if (finalHeight < options.height) {
5264
+ const cropCheck = new import_resvg_js.Resvg(finalSvg, {
5265
+ fitTo: { mode: "width", value: finalWidth },
5266
+ background: "rgba(0, 0, 0, 0)"
5267
+ }).render();
5268
+ const cropPixels2 = new Uint8Array(cropCheck.pixels.buffer);
5269
+ const cropBg = detectBackgroundColor(cropPixels2);
5270
+ const cropOverflow = detectOverflow(cropPixels2, finalWidth, cropCheck.height, cropBg);
5271
+ if (cropOverflow.overflows) {
5272
+ finalHeight = options.height;
5273
+ finalElement = element;
5274
+ finalSvg = await renderFinalSvg(finalElement, finalWidth, finalHeight);
5275
+ }
5276
+ }
5260
5277
  const resvg = new import_resvg_js.Resvg(finalSvg, {
5261
5278
  fitTo: {
5262
5279
  mode: "width",
package/dist/index.js CHANGED
@@ -4834,7 +4834,7 @@ function cropPixels(pixels, srcWidth, region) {
4834
4834
  }
4835
4835
  return out;
4836
4836
  }
4837
- function detectOverflow(pixels, width, height, bgColor, edgeTolerance = 3, minDensity = 0.05, alphaThreshold = 128) {
4837
+ function detectOverflow(pixels, width, height, bgColor, edgeTolerance = 3, minDensity = 0.05, alphaThreshold = 10) {
4838
4838
  const isBackground = createBackgroundMatcher(bgColor);
4839
4839
  function isContentPixel(x, y) {
4840
4840
  const idx = (y * width + x) * 4;
@@ -5116,20 +5116,37 @@ async function renderToPngInContext(element, options, createFn, theme) {
5116
5116
  }
5117
5117
  }
5118
5118
  const watermark = resolveWatermark(options);
5119
- const outputElement = watermark ? wrapWithWatermark(
5120
- finalElement,
5121
- finalWidth,
5122
- finalHeight,
5123
- theme || "dark",
5124
- watermark
5125
- ) : finalElement;
5126
- let finalSvg = await satori(outputElement, {
5127
- width: finalWidth,
5128
- height: finalHeight,
5129
- fonts,
5130
- loadAdditionalAsset
5131
- });
5132
- finalSvg = sanitizeSvg(finalSvg);
5119
+ const renderFinalSvg = async (targetElement, targetWidth, targetHeight) => {
5120
+ const outputElement = watermark ? wrapWithWatermark(
5121
+ targetElement,
5122
+ targetWidth,
5123
+ targetHeight,
5124
+ theme || "dark",
5125
+ watermark
5126
+ ) : targetElement;
5127
+ const renderedSvg = await satori(outputElement, {
5128
+ width: targetWidth,
5129
+ height: targetHeight,
5130
+ fonts,
5131
+ loadAdditionalAsset
5132
+ });
5133
+ return sanitizeSvg(renderedSvg);
5134
+ };
5135
+ let finalSvg = await renderFinalSvg(finalElement, finalWidth, finalHeight);
5136
+ if (finalHeight < options.height) {
5137
+ const cropCheck = new Resvg(finalSvg, {
5138
+ fitTo: { mode: "width", value: finalWidth },
5139
+ background: "rgba(0, 0, 0, 0)"
5140
+ }).render();
5141
+ const cropPixels2 = new Uint8Array(cropCheck.pixels.buffer);
5142
+ const cropBg = detectBackgroundColor(cropPixels2);
5143
+ const cropOverflow = detectOverflow(cropPixels2, finalWidth, cropCheck.height, cropBg);
5144
+ if (cropOverflow.overflows) {
5145
+ finalHeight = options.height;
5146
+ finalElement = element;
5147
+ finalSvg = await renderFinalSvg(finalElement, finalWidth, finalHeight);
5148
+ }
5149
+ }
5133
5150
  const resvg = new Resvg(finalSvg, {
5134
5151
  fitTo: {
5135
5152
  mode: "width",
package/docs/PROMPT.md CHANGED
@@ -119,7 +119,7 @@ Or set it in the frame:
119
119
  </Scene>
120
120
  ```
121
121
 
122
- If a direct CLI frame omits `width` or `height`, Vizmatic starts at `960x540` and grows omitted axes when overflow is detected. Explicit dimensions stay strict and should be used when exact output size matters.
122
+ If a direct CLI frame omits `width` or `height`, Vizmatic starts at `960x540` and grows to fit content when overflow is detected. Generated wrappers that export the default `960x540` size get the same fit-to-content behavior. Add `autoSize = false` when exact dimensions should stay strict and fail on clipping.
123
123
 
124
124
  For direct CLI frames, skip imports, `defineIllustration`, and `c` props by default. The CLI injects Vizmatic primitives and theme colors. Reference `c` only when you need explicit theme tokens such as `background={c.bg}`. `Scene` title/subtitle are optional; omit both for visual-only figures, badges, inline blog diagrams, or frames where surrounding copy already supplies the title. Use the full module form when you need custom dependencies, direct renderer APIs, advanced reusable JSX helpers, or animation exports.
125
125
 
@@ -418,13 +418,13 @@ height = 560;
418
418
 
419
419
  - Use semantic tones, not hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
420
420
  - Keep canvas sizes explicit. Good defaults: `1040x560` for article figures, `1280x720` for slide frames, `900x520` for compact diagrams.
421
- - For exploratory direct CLI frames, dimensions may be omitted; Vizmatic auto-grows omitted axes if content overflows.
421
+ - For exploratory direct CLI frames, dimensions may be omitted; Vizmatic starts at `960x540` and grows to fit content if overflow is detected.
422
422
  - Prefer alpha-transparent PNG/SVG backgrounds for blog embeds and docs cards. Use theme backgrounds only when the host surface is unknown or needs full-frame fill.
423
423
  - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` props to stabilize layout.
424
424
  - Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
425
425
  - Render both dark and light when shipping reusable assets: `--theme dark,light`.
426
426
  - Use GIF only when motion explains state change. Keep scenes short, export `createScenes(theme)`, and keep a static `create(theme)` fallback.
427
- - If render fails with `Canvas overflow detected`, increase canvas dimensions or reduce content density. Do not ignore the error.
427
+ - 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.
428
428
  - Verify generated PNGs/GIFs exist and are non-empty. Open at least one rendered image before finalizing.
429
429
 
430
430
  ## Common recipes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vizmatic",
3
- "version": "0.1.16",
3
+ "version": "0.1.18",
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",