Sizing and output

Sizing belongs to size, beside config and data. This keeps chart meaning independent from where the result will be delivered.

Automatic sizing

Omit size for automatic sizing. It adapts to the chart type and category count and is the default. After choosing the outer size, Szum measures the title, subtitle, axes, legends, labels, caption, and attribution before allocating the plot. It never truncates source data to make a chart fit.

Auto grows up to 4096 logical pixels in either dimension. Beyond that, the complete dataset is laid out inside the bounded canvas; more categories do not produce an oversized frame or an Auto-size error. Existing label placement and collision rules still apply. Explicit canvas and plot sizes keep their authored meaning. Figma's smaller, reflowed preview remains independent of the insertion size.

Auto is the best starting point for API renders, MCP previews, examples, and first insertion into Figma.

Fixed canvas

{ "size": { "type": "canvas", "width": 720, "height": 480 } }

Canvas dimensions describe the complete output. Chart chrome and plot share that space. Use this for email slots, social cards, report figures, and other destinations with a fixed outer box.

Canvas sizing preserves the requested outer dimensions. A very small canvas can compress the plot or truncate fitted text, so review the smallest real destination visually. Source rows are not dropped to make the canvas fit.

Fixed plot

{
  "size": {
    "type": "plot",
    "width": 560,
    "height": 320,
    "margin": { "left": 16, "right": 24 }
  }
}

Plot dimensions describe the data area. Titles, axes, legends, labels, caption, and attribution grow around it. Use plot sizing when the data region must remain comparable across charts with different labels or chrome.

Optional margins override individual computed plot margins. Omitted sides remain automatic. Margins are not available with canvas sizing because canvas already fixes the whole output.

Wide and narrow destinations

A wide chart can carry more time points, horizontal labels, and direct series labels. A narrow chart needs fewer competing labels and may benefit from a bar orientation or visible legend instead of line-end labels.

Interactive embeds fill their container and re-run responsive layout from the same document. PNG and SVG use the authored or derived size. Test both the smallest and largest real destination rather than assuming one aspect ratio works everywhere.

Output format

Output policy is separate from size:

{ "output": { "format": "png", "scale": 2 } }

• SVG is vector output and remains sharp at any display density.
• PNG rasterizes the resolved size. scale accepts 1, 2, 3, or 4, defaults to 2 when omitted, and changes pixel resolution without changing authored layout dimensions.

Omit output to use SVG. A saved document can retain an output preference, while a request can choose output for one immediate render.

SVG responses include a viewBox, so they can scale proportionally through CSS or an image width without distorting the authored layout. Leave the display height automatic when preserving that aspect ratio.

Attribution credit

Attribution is delivery and plan policy, not semantic chart config. Anonymous and Free hosted output carries the Szum credit. Creator and Pro output omits it by default. Szum reserves space when attribution is required so the credit does not overlap the plot.

Local authoring previews and Figma insertion remain credit-free. Existing saved charts stay live after a downgrade; their delivery presentation follows current plan policy without rewriting the authored document.

Where sizing applies

• POST /chart, GET /chart, and MCP previews render the request size.
• Saved image URLs render the size stored in the published document.
• Figma inserts the rendered frame, then uses the resized Figma frame for subsequent edits.
• Interactive embeds use the stored document but respond to their live container.
• Studio and docs previews are produced locally and do not consume hosted render quota.

Size width and height must be integer values from 1 to 4096. Output-resource checks may reject a raster request whose scaled pixel area is unsafe even when its authored size dimensions are valid.