Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/** The PNG chart generator (clerum__generate_chart): Chart.js drawn on a Skia canvas. */
import { type SKRSContext2D, createCanvas } from '@napi-rs/canvas'
import { Chart, type ChartConfiguration, type Plugin, type Scale, registerables } from 'chart.js'
import {
artifactResult,
claimOutputFile,
enforceQuota,
ensureDir,
outputFilename,
replacedBytes,
writeArtifact,
} from './artifactOutput'
import { ChartDataError, normalizeChartData } from './chartData'
import { type ChartDataset, paintedDatasets, positiveNumber } from './chartDatasets'
import {
type ValueFormat,
type ValueLabelOptions,
backgroundPlugin,
emptyStatePlugin,
formatValue,
gaugeCenterPlugin,
valueLabelsPlugin,
} from './chartPlugins'
import {
CHART_THEMES,
DEFAULT_CHART_HEIGHT,
DEFAULT_CHART_WIDTH,
MAX_CHART_DIMENSION,
MIN_CHART_DIMENSION,
} from './chartThemes'
import { drawnTexts, recordDrawnText } from './drawnText'
import { PNG_BASE_PPM } from './embeddedImages'
import { CHART_FONT_STACK, ensureFontsReady, sanitizeForFont } from './fonts'
import { choose } from './ownEntry'
import type { InternalToolResult } from './types'
// Register Chart.js controllers/scales/elements/plugins once. Chart.js v4 ships
// these as separate exports so we have to opt in. `registerables` includes all
// chart types we expose (line, bar, pie, doughnut, etc.) plus axes/legend/title.
Chart.register(...registerables)
/**
* Charts use the stack ./fonts registers (Roboto first), so labels render the
* same on every image, including one without system fonts. Set when a chart is
* drawn, so importing this module leaves the fonts and Chart.js as they were.
*/
function prepareChartFonts(): void {
ensureFontsReady()
Chart.defaults.font.family = CHART_FONT_STACK
Chart.defaults.color = '#0f172a'
}
/** Widest a single bar may be drawn, in nominal pixels. */
const MAX_BAR_THICKNESS = 120
/** A plot area narrower or shorter than this, in px, shows too little of the data to read. */
const MIN_PLOT_SIDE = 40
const SUPPORTED_CHART_TYPES = new Set([
// Core Chart.js types (one-to-one mapping):
'line',
'bar',
'horizontalBar',
'pie',
'doughnut',
'area',
'scatter',
'radar',
'polarArea',
'bubble',
// Extended types built by composing options on top of base types:
'stackedBar', // bar with stacked x/y scales
'stackedArea', // line with fill stacking
'mixedBarLine', // bar primary + line overlay datasets (combo charts)
'gauge', // doughnut hack: half-circle dial for a single 0..max value
'waterfall', // bar with floating tuples to show step-by-step deltas
'funnel', // horizontal bar sorted descending — conversion / pipeline
])
/**
* A mark that reaches the end of the plot has nowhere to put its value label
* and reads as clipped, so a value axis runs 4% of its range past the data on
* each side. Not past zero: values from 0 get an axis from 0, not from -20.
* A bound set in the chart options stays as set.
*/
function addHeadroom(scale: Scale): void {
const { min, max } = scale
const room = (max - min) * 0.04
if (!(room > 0)) return
const set = scale.options as { min?: unknown; max?: unknown }
if (set.max === undefined) scale.max = max <= 0 && max + room > 0 ? 0 : max + room
if (set.min === undefined) scale.min = min >= 0 && min - room < 0 ? 0 : min - room
}
/**
* Room past the data for the marks of a scatter or bubble chart, whose largest
* mark reaches `radius` pixels from its value. The axis runs on past its end
* ticks until a mark on the outermost value is drawn whole inside the plot,
* clear of the tick labels, while the ticks stay where the data put them, so
* an axis from 0 shows no -1. A bound set in the chart options stays as set.
* Each axis takes its own pair of callbacks.
*/
function markRoom(radius: number): {
afterDataLimits(scale: Scale): void
afterBuildTicks(scale: Scale): void
} {
let low = 0
let high = 0
return {
afterDataLimits(scale) {
low = scale.min
high = scale.max
},
afterBuildTicks(scale) {
const length = scale.isHorizontal() ? scale.width : scale.height
// A mark wider than half the plot is not given room it cannot use.
const r = Math.min(radius, length / 4)
if (!(r > 0)) return
const set = scale.options as { min?: unknown; max?: unknown }
const first = scale.min
const last = scale.max
let min = first
let max = last
// The room a mark needs grows with the span it widens, so it is found by
// iteration; each step changes the span by at most half the last one.
for (let i = 0; i < 40; i++) {
const need = (r * (max - min)) / length
const nextMin = set.min === undefined ? Math.min(first, low - need) : first
const nextMax = set.max === undefined ? Math.max(last, high + need) : last
if (nextMin === min && nextMax === max) break
min = nextMin
max = nextMax
}
scale.min = min
scale.max = max
scale.ticks = spacedTicks(scale.ticks, (last - first) / (max - min))
},
}
}
/**
* `ticks` for an axis they now span only `share` of. Chart.js spaced them for
* the whole length, so when the room takes much of it every other one is
* dropped, keeping the multiples of the doubled step so the values stay round.
*/
function spacedTicks<T extends { value: number }>(ticks: T[], share: number): T[] {
if (!(share < 0.75) || ticks.length < 3) return ticks
const step = 2 * (ticks[1].value - ticks[0].value)
const kept = ticks.filter(t => Math.abs(t.value / step - Math.round(t.value / step)) < 1e-6)
return kept.length >= 2 ? kept : ticks
}
/** Radius in pixels of the largest mark a scatter or bubble chart draws, its border included. */
function largestMark(chartType: string, datasets: ChartDataset[]): number {
const size = (value: unknown, fallback: number) =>
typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback
let largest = 0
for (const ds of datasets) {
const d = ds as unknown as Record<string, unknown>
if (chartType === 'bubble') {
const border = size(d.borderWidth, 1) / 2
for (const point of ds.data as unknown[]) {
const r = (point as { r?: unknown } | null)?.r
largest = Math.max(largest, size(r, size(d.radius, 3)) + border)
}
} else {
const border = size(d.pointBorderWidth, 1) / 2
for (const r of [d.pointRadius ?? 3].flat()) largest = Math.max(largest, size(r, 0) + border)
}
}
return largest
}
/** Nominal pixels are multiplied by this to keep charts sharp when scaled down. */
const CHART_PIXEL_RATIO = 2
/** Longest side a chart is laid out at, in nominal pixels. */
const MAX_LAYOUT_SIDE = 1600
/** Largest canvas drawn, in device pixels: 50 MiB of RGBA. */
const MAX_CANVAS_PIXELS = 13_107_200
/**
* Pixel ratio for a chart of the requested size. A large chart is drawn at a
* lower density rather than refused, down to 1; undefined when even that would
* exceed MAX_CANVAS_PIXELS.
*/
function chartPixelRatio(width: number, height: number): number | undefined {
const area = width * height
if (area > MAX_CANVAS_PIXELS) return undefined
return Math.min(CHART_PIXEL_RATIO, Math.sqrt(MAX_CANVAS_PIXELS / area))
}
/** Types where per-point labels would collide more than they inform. */
const VALUE_LABELS_OFF_BY_DEFAULT = new Set([
'scatter',
'bubble',
'radar',
'gauge',
'stackedArea',
'stackedBar',
])
function shouldLabelValues(chartType: string, requested: unknown): boolean {
if (typeof requested === 'boolean') return requested
return !VALUE_LABELS_OFF_BY_DEFAULT.has(chartType)
}
function resolveValueFormat(raw: unknown): ValueFormat {
const allowed: ValueFormat[] = ['auto', 'plain', 'compact', 'currency', 'percent']
const v = String(raw ?? 'auto') as ValueFormat
return allowed.includes(v) ? v : 'auto'
}
/**
* True when nothing would be drawn: every plotted number is absent or zero,
* or, on a scatter or bubble chart (`xy`), no point has both coordinates. A
* point is drawn wherever it sits, at zero too.
*/
function isVisuallyEmpty(datasets: ChartDataset[], xy: boolean): boolean {
if (xy) {
return !datasets.some(ds =>
(ds.data as unknown[]).some(point => {
const at = point as { x?: unknown; y?: unknown } | null
return (
typeof at === 'object' && at !== null && Number.isFinite(at.x) && Number.isFinite(at.y)
)
})
)
}
let sawNumber = false
for (const ds of datasets) {
for (const point of ds.data as unknown[]) {
const value =
typeof point === 'number'
? point
: point && typeof point === 'object' && 'y' in point
? (point as { y: number }).y
: Array.isArray(point)
? Number(point[1]) - Number(point[0])
: null
if (typeof value === 'number' && Number.isFinite(value)) {
sawNumber = true
if (value !== 0) return false
}
}
}
return sawNumber
}
function clampDimension(
field: 'width' | 'height',
value: unknown,
fallback: number,
warnings: string[]
): number {
const n = positiveNumber(field, value, fallback, warnings)
if (n > MAX_CHART_DIMENSION) {
warnings.push(
`${field} ${n} is over the ${MAX_CHART_DIMENSION} maximum; used ${MAX_CHART_DIMENSION}.`
)
return MAX_CHART_DIMENSION
}
if (n < MIN_CHART_DIMENSION) {
warnings.push(
`${field} ${n} is under the ${MIN_CHART_DIMENSION} minimum, too small to read; ` +
`used ${MIN_CHART_DIMENSION}.`
)
return MIN_CHART_DIMENSION
}
return Math.floor(n)
}
// ─── generate_markdown ───────────────────────────────────────────────
/**
* Stamp a PNG's pHYs chunk so consumers know the image is oversampled.
*
* Charts are rasterized above their layout size to stay sharp in print. Every
* embedder sizes an image from its pixel count, so without this the extra
* pixels are read as extra size and the whole chart — its type included — is
* scaled down to fit, landing at about a third of the surrounding body text.
* Recording the density lets `imageDisplaySize` recover the size the chart was
* laid out for.
*/
function stampPngDensity(png: Buffer, ratio: number): Buffer {
const ppm = Math.round(PNG_BASE_PPM * ratio)
const data = Buffer.alloc(9)
data.writeUInt32BE(ppm, 0)
data.writeUInt32BE(ppm, 4)
data.writeUInt8(1, 8) // unit: metres
const type = Buffer.from('pHYs', 'latin1')
const chunk = Buffer.alloc(12 + data.length)
chunk.writeUInt32BE(data.length, 0)
type.copy(chunk, 4)
data.copy(chunk, 8)
chunk.writeUInt32BE(crc32(Buffer.concat([type, data])), 8 + data.length)
// IHDR is always the first chunk: 8-byte signature + 4 length + 4 type + 13
// data + 4 CRC. The new chunk goes straight after it.
const insertAt = 8 + 25
if (png.length < insertAt) return png
return Buffer.concat([png.subarray(0, insertAt), chunk, png.subarray(insertAt)])
}
let crcTable: Uint32Array | undefined
function crc32(buf: Buffer): number {
if (!crcTable) {
crcTable = new Uint32Array(256)
for (let n = 0; n < 256; n++) {
let c = n
for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
crcTable[n] = c >>> 0
}
}
let crc = 0xffffffff
for (const byte of buf) crc = crcTable[(crc ^ byte) & 0xff] ^ (crc >>> 8)
return (crc ^ 0xffffffff) >>> 0
}
export async function runGenerateChart(
args: Record<string, unknown>,
outputDir: string
): Promise<InternalToolResult> {
let chart: Chart | undefined
try {
prepareChartFonts()
const filename = outputFilename(args.filename, 'png', 'chart')
const chartTypeRaw = String(args.type ?? 'bar')
if (!SUPPORTED_CHART_TYPES.has(chartTypeRaw)) {
return {
success: false,
error:
`Unsupported chart type "${chartTypeRaw}". Supported types: ` +
`${[...SUPPORTED_CHART_TYPES].join(', ')}.`,
}
}
// Repair what the caller sent before anything is drawn, so an unusable
// dataset fails with a message instead of rendering an empty plot.
const normalized = normalizeChartData(args.data, { chartType: chartTypeRaw })
const warnings = [...normalized.warnings]
const width = clampDimension('width', args.width, DEFAULT_CHART_WIDTH, warnings)
const height = clampDimension('height', args.height, DEFAULT_CHART_HEIGHT, warnings)
// Pixel density for the requested size; the layout itself is capped below.
const pixelRatio = chartPixelRatio(width, height)
if (pixelRatio === undefined) {
return {
success: false,
error:
`Chart too large: ${width}x${height} is over the ` +
`${(MAX_CANVAS_PIXELS / 1e6).toFixed(1)} megapixel limit. Reduce width or height.`,
}
}
const theme =
CHART_THEMES[choose(args.theme, Object.keys(CHART_THEMES), 'light', 'theme', warnings)]
const title = args.title ? sanitizeForFont(String(args.title)) : undefined
const yAxisLabel = args.yAxisLabel ? sanitizeForFont(String(args.yAxisLabel)) : undefined
const xAxisLabel = args.xAxisLabel ? sanitizeForFont(String(args.xAxisLabel)) : undefined
let labels = normalized.labels ? normalized.labels.map(l => sanitizeForFont(l)) : undefined
const datasets: ChartDataset[] = normalized.datasets.map(ds => ({
...ds,
...(ds.label ? { label: sanitizeForFont(ds.label) } : {}),
})) as ChartDataset[]
const { datasets: themedDatasets, resolved } = paintedDatasets(
chartTypeRaw,
datasets,
labels,
theme,
args,
warnings
)
const chartType = resolved.chartType
if (resolved.labels !== undefined) labels = resolved.labels
warnings.push(...resolved.notes)
// Past MAX_LAYOUT_SIDE the chart is laid out smaller and drawn at a higher
// density, so type, lines and bars keep their share of the image.
const layoutScale = Math.max(1, Math.max(width, height) / MAX_LAYOUT_SIDE)
const layoutWidth = Math.round(width / layoutScale)
const layoutHeight = Math.round(height / layoutScale)
// Type sized for the default canvas turns unreadable on a much larger
// one, so every font size follows the canvas area.
const fontScale = Math.min(
2,
Math.max(
0.85,
Math.sqrt((layoutWidth * layoutHeight) / (DEFAULT_CHART_WIDTH * DEFAULT_CHART_HEIGHT))
)
)
const px = (base: number): number => Math.round(base * fontScale)
const indexAxis = resolved.optionsOverrides?.indexAxis === 'y' ? 'y' : 'x'
const decimals =
typeof args.decimals === 'number' &&
Number.isInteger(args.decimals) &&
args.decimals >= 0 &&
args.decimals <= 20
? args.decimals
: undefined
if (args.decimals !== undefined && decimals === undefined) {
warnings.push(
`decimals ${JSON.stringify(args.decimals)} is not a whole number from 0 to 20, so ` +
'each value got the places it needs.'
)
}
const valueOptions: ValueLabelOptions = {
format: resolveValueFormat(args.valueFormat),
...(args.currencySymbol ? { currencySymbol: String(args.currencySymbol) } : {}),
...(decimals !== undefined ? { decimals } : {}),
textColor: theme.textColor,
backgroundColor: theme.backgroundColor,
indexAxis,
fontScale,
}
const cartesian =
chartType === 'bar' ||
chartType === 'line' ||
chartType === 'scatter' ||
chartType === 'bubble'
const showAxes = cartesian && chartTypeRaw !== 'gauge'
const radial = chartType === 'radar' || chartType === 'polarArea'
const sliceChart =
chartTypeRaw === 'pie' || chartTypeRaw === 'doughnut' || chartTypeRaw === 'polarArea'
const legendEntries = sliceChart ? (labels?.length ?? 0) : themedDatasets.length
// One series needs a legend only when its name says what the titles do not.
const only = legendEntries === 1 && !sliceChart ? themedDatasets[0]?.label : undefined
const namesMore =
typeof only === 'string' &&
only.trim() !== '' &&
![title, yAxisLabel, xAxisLabel].some(t =>
t?.toLowerCase().includes(only.trim().toLowerCase())
)
const legendDisplay =
args.showLegend === undefined
? resolved.optionsOverrides?.plugins?.legend?.display !== false &&
(legendEntries > 1 || namesMore)
: Boolean(args.showLegend)
const labelValues = shouldLabelValues(chartTypeRaw, args.showValues)
const plugins: Plugin[] = [backgroundPlugin(theme.backgroundColor)]
const unlabelled = { count: 0 }
const failed: string[] = []
if (labelValues) plugins.push(valueLabelsPlugin({ ...valueOptions, unlabelled, failed }))
if (chartTypeRaw === 'gauge') {
plugins.push(
gaugeCenterPlugin({
value: resolved.gaugeValue ?? 0,
max: resolved.gaugeMax ?? 100,
textColor: theme.textColor,
mutedColor: theme.mutedTextColor,
format: valueOptions,
failed,
})
)
}
if (isVisuallyEmpty(themedDatasets, chartTypeRaw === 'scatter' || chartTypeRaw === 'bubble')) {
plugins.push(emptyStatePlugin('No data to display', theme.textColor))
}
const axisTicks = {
color: theme.textColor,
font: { family: CHART_FONT_STACK, size: px(12) },
}
// Applied to whichever axis carries the values, never to the one carrying
// the category names. The decision to abbreviate is taken from the whole
// tick range, so one axis never mixes "$350K" with "$50,000".
const valueTick = {
callback: (value: string | number, _i: number, ticks: Array<{ value: number }>) => {
const peak = Math.max(...ticks.map(t => Math.abs(t.value)), 0)
const scaled =
peak >= 10_000 ? { ...valueOptions, format: 'compact' as const } : valueOptions
const prefix =
valueOptions.format === 'currency' ? (valueOptions.currencySymbol ?? '$') : ''
const suffix = valueOptions.format === 'percent' ? '%' : ''
return peak >= 10_000
? `${Number(value) < 0 ? '-' : ''}${prefix}${formatValue(Math.abs(Number(value)), scaled)}${suffix}`
: formatValue(Number(value), valueOptions)
},
}
const headroom = { afterDataLimits: addHeadroom }
const marks = chartTypeRaw === 'scatter' || chartTypeRaw === 'bubble'
const radius = marks ? largestMark(chartTypeRaw, themedDatasets) : 0
const config: ChartConfiguration = {
type: chartType,
data: { labels, datasets: themedDatasets as ChartConfiguration['data']['datasets'] },
options: {
responsive: false,
animation: false,
devicePixelRatio: pixelRatio * layoutScale,
maintainAspectRatio: false,
// Room for value labels that sit just outside the outermost marks.
layout: { padding: { top: 12, right: 16, bottom: 4, left: 4 } },
// Without a cap, a chart with one or two categories draws bars as
// wide as the plot, which reads as a block rather than a measurement.
datasets: { bar: { maxBarThickness: MAX_BAR_THICKNESS } },
...resolved.optionsOverrides,
plugins: {
title: title
? {
display: true,
text: title,
color: theme.textColor,
font: { family: CHART_FONT_STACK, size: px(17), weight: 'bold' as const },
padding: { top: 6, bottom: 14 },
}
: { display: false },
legend: {
display: legendDisplay,
position: 'top' as const,
labels: {
color: theme.textColor,
font: { family: CHART_FONT_STACK, size: px(12) },
usePointStyle: true,
boxWidth: 10,
boxHeight: 10,
},
},
...(resolved.optionsOverrides?.plugins ?? {}),
},
scales: showAxes
? {
x: {
ticks: {
...axisTicks,
autoSkip: true,
maxRotation: 45,
minRotation: 0,
...(indexAxis === 'y' ? valueTick : {}),
},
grid: { color: theme.gridColor },
...(marks ? markRoom(radius) : indexAxis === 'y' ? headroom : {}),
title: xAxisLabel
? {
display: true,
text: xAxisLabel,
color: theme.textColor,
font: { family: CHART_FONT_STACK, size: px(13) },
}
: { display: false },
...(resolved.optionsOverrides?.scales?.x ?? {}),
},
y: {
ticks: {
...axisTicks,
...(indexAxis === 'x' ? valueTick : {}),
},
grid: { color: theme.gridColor },
...(marks ? markRoom(radius) : indexAxis === 'x' ? headroom : {}),
title: yAxisLabel
? {
display: true,
text: yAxisLabel,
color: theme.textColor,
font: { family: CHART_FONT_STACK, size: px(13) },
}
: { display: false },
...(resolved.optionsOverrides?.scales?.y ?? {}),
},
...(resolved.optionsOverrides?.scales?.y1
? {
y1: {
ticks: axisTicks,
...resolved.optionsOverrides.scales.y1,
},
}
: {}),
}
: radial
? {
r: {
// Above the data, so slices and fills do not cover the scale.
ticks: { ...axisTicks, backdropColor: theme.backgroundColor, z: 1 },
grid: { color: theme.gridColor },
angleLines: { color: theme.gridColor },
pointLabels: {
color: theme.textColor,
font: { family: CHART_FONT_STACK, size: px(12) },
},
},
}
: undefined,
},
plugins,
}
// The canvas is created at the layout size and Chart.js is told the pixel
// ratio, so it lays out in nominal units and rasterizes the backing store
// at the higher density itself. Scaling the context by hand instead does
// not work: Chart.js resets the transform, so the layout silently becomes
// the full device size and every font ends up half its intended size
// relative to the image.
const canvas = createCanvas(layoutWidth, layoutHeight)
const ctx = canvas.getContext('2d') as SKRSContext2D
const shownText = recordDrawnText(ctx)
// Chart.js types target a browser CanvasRenderingContext2D; the Skia
// context is API-compatible for the subset Chart.js uses.
chart = new Chart(ctx as any, config)
chart.update('none')
if (args.showValues === true && unlabelled.count > 0) {
const n = unlabelled.count
warnings.push(
`showValues: ${n} value${n === 1 ? '' : 's'} got no label, since at this size ` +
`${n === 1 ? 'its label' : 'the labels'} would cover another bar or label, or the ` +
'series is too dense; a larger chart or fewer series leaves room.'
)
}
for (const what of new Set(failed)) {
warnings.push(`The chart was drawn without ${what}.`)
}
// The plot area in requested pixels; the layout may run at a smaller scale.
const plotWidth = Math.max(0, Math.round(chart.chartArea.width * layoutScale))
const plotHeight = Math.max(0, Math.round(chart.chartArea.height * layoutScale))
if (plotWidth < MIN_PLOT_SIDE || plotHeight < MIN_PLOT_SIDE) {
warnings.push(
`At ${width}x${height} px the title, legend and axes leave the data ` +
`${plotWidth}x${plotHeight} px; use a larger width and height, or leave out the ` +
'title or legend.'
)
}
const pngBuffer = stampPngDensity(canvas.toBuffer('image/png'), pixelRatio)
ensureDir(outputDir)
const target = claimOutputFile(outputDir, filename)
enforceQuota(outputDir, pngBuffer.byteLength, replacedBytes(target))
writeArtifact(target, pngBuffer)
const summary =
`Chart written: ${target.filename} (${canvas.width}x${canvas.height} px, ` +
`${chartTypeRaw}, ${themedDatasets.length} series). To embed it, pass ` +
`images: [{ path: '${target.filename}' }] to the PDF or DOCX generator, ` +
`sheets[].images: [{ path: '${target.filename}' }] to the XLSX generator, or ` +
`image: { path: '${target.filename}' } or chart: { path: '${target.filename}' } ` +
'on a PPTX slide.'
return {
...artifactResult(target, 'png', { summary, warnings }),
shownText: drawnTexts(shownText),
}
} catch (err) {
if (err instanceof ChartDataError) return { success: false, error: err.message }
return { success: false, error: err instanceof Error ? err.message : String(err) }
} finally {
if (chart) chart.destroy()
}
}