vizmatic 0.1.20 → 0.1.21

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
@@ -333,7 +333,7 @@ Theme and render APIs:
333
333
  - `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.
334
334
  - `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.
335
335
  - `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`.
336
- - `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean = true`, `scale?: number = 2`.
336
+ - `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean | "height" | "both" = true`, `scale?: number = 2`. Use `crop: "height"` when host layouts require stable width but should still trim extra vertical whitespace.
337
337
  - `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `watermark?`, `brand?`, `scale?`.
338
338
  - `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `watermark?`, `brand?`.
339
339
  - `renderAnimatedGif(scenes, options)`: `scenes: AnimatedScene[]`, `options: AnimationOptions`.
package/README.md CHANGED
@@ -571,7 +571,7 @@ Vizmatic exports a fairly complete visual kit. Common cases should use these pri
571
571
  import { renderAnimatedGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
572
572
  ```
573
573
 
574
- `renderToPng` renders at 2x scale by default, uses alpha transparency unless `background` is set, checks for clipped content, crops extra vertical whitespace, and can apply an optional watermark. Use `background: "theme"` to paint `c.bg`, or any CSS color string for a fixed fill. Use `watermark.image` for a URL or data URI; the CLI also accepts local image paths through `--watermark-image`. For frame-owned branding, export `watermark = <Watermark>...</Watermark>` from the frame module. `brand` still works as a compatibility alias.
574
+ `renderToPng` renders at 2x scale by default, uses alpha transparency unless `background` is set, checks for clipped content, crops extra vertical whitespace, and can apply an optional watermark. Use `background: "theme"` to paint `c.bg`, or any CSS color string for a fixed fill. Use `crop: "height"` when a downstream layout needs fixed width but still wants vertical whitespace trimmed. Use `watermark.image` for a URL or data URI; the CLI also accepts local image paths through `--watermark-image`. For frame-owned branding, export `watermark = <Watermark>...</Watermark>` from the frame module. `brand` still works as a compatibility alias.
575
575
 
576
576
  ```ts
577
577
  await renderToPng(element, {
@@ -580,7 +580,7 @@ await renderToPng(element, {
580
580
  outputPath: "dist/frame.png",
581
581
  background: "theme",
582
582
  watermark: { text: "Your Product", image: "https://example.com/logo.svg", position: "top-right" },
583
- crop: true,
583
+ crop: "height",
584
584
  scale: 2,
585
585
  })
586
586
  ```
package/dist/cli.js CHANGED
@@ -5206,6 +5206,12 @@ function cropSavesEnough(source, target) {
5206
5206
  function resolveWatermark(options) {
5207
5207
  return options.watermark ?? options.brand;
5208
5208
  }
5209
+ function shouldCropHeight(crop) {
5210
+ return crop !== false;
5211
+ }
5212
+ function shouldCropViewport(crop) {
5213
+ return crop !== false && crop !== "height";
5214
+ }
5209
5215
  async function renderToPng(element, options, createFn, theme) {
5210
5216
  await renderToPngWithOutput(element, options, createFn, theme);
5211
5217
  }
@@ -5255,7 +5261,7 @@ async function renderToPngInContext(element, options, createFn, theme) {
5255
5261
  let finalElement = element;
5256
5262
  const heightSaved = options.height - bounds.height;
5257
5263
  const heightSavedPercent = heightSaved / options.height * 100;
5258
- if (options.crop !== false && heightSavedPercent >= CROP_THRESHOLD_PERCENT) {
5264
+ if (shouldCropHeight(options.crop) && heightSavedPercent >= CROP_THRESHOLD_PERCENT) {
5259
5265
  finalHeight = bounds.height;
5260
5266
  if (createFn && theme) {
5261
5267
  finalElement = createFn(theme);
@@ -5293,7 +5299,7 @@ async function renderToPngInContext(element, options, createFn, theme) {
5293
5299
  finalSvg = await renderFinalSvg(finalElement, finalWidth, finalHeight);
5294
5300
  }
5295
5301
  }
5296
- if (options.crop !== false) {
5302
+ if (shouldCropViewport(options.crop)) {
5297
5303
  const viewportCheck = new Resvg(finalSvg, {
5298
5304
  fitTo: { mode: "width", value: finalWidth },
5299
5305
  background: "rgba(0, 0, 0, 0)"
package/dist/index.cjs CHANGED
@@ -5221,6 +5221,12 @@ function cropSavesEnough(source, target) {
5221
5221
  function resolveWatermark(options) {
5222
5222
  return options.watermark ?? options.brand;
5223
5223
  }
5224
+ function shouldCropHeight(crop) {
5225
+ return crop !== false;
5226
+ }
5227
+ function shouldCropViewport(crop) {
5228
+ return crop !== false && crop !== "height";
5229
+ }
5224
5230
  async function renderToPng(element, options, createFn, theme) {
5225
5231
  await renderToPngWithOutput(element, options, createFn, theme);
5226
5232
  }
@@ -5270,7 +5276,7 @@ async function renderToPngInContext(element, options, createFn, theme) {
5270
5276
  let finalElement = element;
5271
5277
  const heightSaved = options.height - bounds.height;
5272
5278
  const heightSavedPercent = heightSaved / options.height * 100;
5273
- if (options.crop !== false && heightSavedPercent >= CROP_THRESHOLD_PERCENT) {
5279
+ if (shouldCropHeight(options.crop) && heightSavedPercent >= CROP_THRESHOLD_PERCENT) {
5274
5280
  finalHeight = bounds.height;
5275
5281
  if (createFn && theme) {
5276
5282
  finalElement = createFn(theme);
@@ -5308,7 +5314,7 @@ async function renderToPngInContext(element, options, createFn, theme) {
5308
5314
  finalSvg = await renderFinalSvg(finalElement, finalWidth, finalHeight);
5309
5315
  }
5310
5316
  }
5311
- if (options.crop !== false) {
5317
+ if (shouldCropViewport(options.crop)) {
5312
5318
  const viewportCheck = new import_resvg_js.Resvg(finalSvg, {
5313
5319
  fitTo: { mode: "width", value: finalWidth },
5314
5320
  background: "rgba(0, 0, 0, 0)"
package/dist/index.d.cts CHANGED
@@ -1298,6 +1298,7 @@ interface FontData {
1298
1298
  */
1299
1299
  declare function loadAdditionalAsset(code: string, segment: string): Promise<string | Font[]>;
1300
1300
  declare function getFonts(): Promise<FontData[]>;
1301
+ type CropMode = boolean | 'both' | 'height';
1301
1302
  interface RenderOptions {
1302
1303
  width: number;
1303
1304
  height: number;
@@ -1307,8 +1308,8 @@ interface RenderOptions {
1307
1308
  watermark?: WatermarkInput;
1308
1309
  /** Backward-compatible alias for watermark. */
1309
1310
  brand?: boolean | string;
1310
- /** Disable height autocrop for fixed-size frames. */
1311
- crop?: boolean;
1311
+ /** Auto-crop mode. true/"both" crops height and transparent gutters; "height" preserves declared width; false disables crop. */
1312
+ crop?: CropMode;
1312
1313
  /** Retina output scale. */
1313
1314
  scale?: number;
1314
1315
  /** Root background for Vizmatic primitives. Defaults to alpha-transparent PNG/SVG output. */
@@ -1446,4 +1447,4 @@ interface OverflowResult {
1446
1447
  */
1447
1448
  declare function detectOverflow(pixels: Uint8Array, width: number, height: number, bgColor: string, edgeTolerance?: number, minDensity?: number, alphaThreshold?: number): OverflowResult;
1448
1449
 
1449
- export { type AnimatedScene, type AnimationOptions, 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 CropRegion, DashedLine, DataTable, DetailList, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramNode, Grid, Heatmap, 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, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, TitleBar, type ToneName, ToneStrip, type TransitionType, 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, getToneGradient, gradients, heatColor, loadAdditionalAsset, normalizeWatermark, renderAnimatedGif, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, styles, toneGradients, typography, wrapWithBrand, wrapWithWatermark };
1450
+ export { type AnimatedScene, type AnimationOptions, 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, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramNode, Grid, Heatmap, 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, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, TitleBar, type ToneName, ToneStrip, type TransitionType, 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, getToneGradient, gradients, heatColor, loadAdditionalAsset, normalizeWatermark, renderAnimatedGif, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, styles, toneGradients, typography, wrapWithBrand, wrapWithWatermark };
package/dist/index.d.ts CHANGED
@@ -1298,6 +1298,7 @@ interface FontData {
1298
1298
  */
1299
1299
  declare function loadAdditionalAsset(code: string, segment: string): Promise<string | Font[]>;
1300
1300
  declare function getFonts(): Promise<FontData[]>;
1301
+ type CropMode = boolean | 'both' | 'height';
1301
1302
  interface RenderOptions {
1302
1303
  width: number;
1303
1304
  height: number;
@@ -1307,8 +1308,8 @@ interface RenderOptions {
1307
1308
  watermark?: WatermarkInput;
1308
1309
  /** Backward-compatible alias for watermark. */
1309
1310
  brand?: boolean | string;
1310
- /** Disable height autocrop for fixed-size frames. */
1311
- crop?: boolean;
1311
+ /** Auto-crop mode. true/"both" crops height and transparent gutters; "height" preserves declared width; false disables crop. */
1312
+ crop?: CropMode;
1312
1313
  /** Retina output scale. */
1313
1314
  scale?: number;
1314
1315
  /** Root background for Vizmatic primitives. Defaults to alpha-transparent PNG/SVG output. */
@@ -1446,4 +1447,4 @@ interface OverflowResult {
1446
1447
  */
1447
1448
  declare function detectOverflow(pixels: Uint8Array, width: number, height: number, bgColor: string, edgeTolerance?: number, minDensity?: number, alphaThreshold?: number): OverflowResult;
1448
1449
 
1449
- export { type AnimatedScene, type AnimationOptions, 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 CropRegion, DashedLine, DataTable, DetailList, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramNode, Grid, Heatmap, 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, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, TitleBar, type ToneName, ToneStrip, type TransitionType, 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, getToneGradient, gradients, heatColor, loadAdditionalAsset, normalizeWatermark, renderAnimatedGif, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, styles, toneGradients, typography, wrapWithBrand, wrapWithWatermark };
1450
+ export { type AnimatedScene, type AnimationOptions, 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, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramNode, Grid, Heatmap, 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, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, TitleBar, type ToneName, ToneStrip, type TransitionType, 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, getToneGradient, gradients, heatColor, loadAdditionalAsset, normalizeWatermark, renderAnimatedGif, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, styles, toneGradients, typography, wrapWithBrand, wrapWithWatermark };
package/dist/index.js CHANGED
@@ -5093,6 +5093,12 @@ function cropSavesEnough(source, target) {
5093
5093
  function resolveWatermark(options) {
5094
5094
  return options.watermark ?? options.brand;
5095
5095
  }
5096
+ function shouldCropHeight(crop) {
5097
+ return crop !== false;
5098
+ }
5099
+ function shouldCropViewport(crop) {
5100
+ return crop !== false && crop !== "height";
5101
+ }
5096
5102
  async function renderToPng(element, options, createFn, theme) {
5097
5103
  await renderToPngWithOutput(element, options, createFn, theme);
5098
5104
  }
@@ -5142,7 +5148,7 @@ async function renderToPngInContext(element, options, createFn, theme) {
5142
5148
  let finalElement = element;
5143
5149
  const heightSaved = options.height - bounds.height;
5144
5150
  const heightSavedPercent = heightSaved / options.height * 100;
5145
- if (options.crop !== false && heightSavedPercent >= CROP_THRESHOLD_PERCENT) {
5151
+ if (shouldCropHeight(options.crop) && heightSavedPercent >= CROP_THRESHOLD_PERCENT) {
5146
5152
  finalHeight = bounds.height;
5147
5153
  if (createFn && theme) {
5148
5154
  finalElement = createFn(theme);
@@ -5180,7 +5186,7 @@ async function renderToPngInContext(element, options, createFn, theme) {
5180
5186
  finalSvg = await renderFinalSvg(finalElement, finalWidth, finalHeight);
5181
5187
  }
5182
5188
  }
5183
- if (options.crop !== false) {
5189
+ if (shouldCropViewport(options.crop)) {
5184
5190
  const viewportCheck = new Resvg(finalSvg, {
5185
5191
  fitTo: { mode: "width", value: finalWidth },
5186
5192
  background: "rgba(0, 0, 0, 0)"
package/docs/PROMPT.md CHANGED
@@ -333,7 +333,7 @@ Theme and render APIs:
333
333
  - `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.
334
334
  - `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.
335
335
  - `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`.
336
- - `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean = true`, `scale?: number = 2`.
336
+ - `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean | "height" | "both" = true`, `scale?: number = 2`. Use `crop: "height"` when host layouts require stable width but should still trim extra vertical whitespace.
337
337
  - `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `watermark?`, `brand?`, `scale?`.
338
338
  - `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `watermark?`, `brand?`.
339
339
  - `renderAnimatedGif(scenes, options)`: `scenes: AnimatedScene[]`, `options: AnimationOptions`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vizmatic",
3
- "version": "0.1.20",
3
+ "version": "0.1.21",
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",