Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

refactor(mcp-host): move each generator's implementation out of internalTools.ts

marcotebc6841276143a
diff --git a/mcp-host/src/workflow/artifactOutput.ts b/mcp-host/src/workflow/artifactOutput.ts
index 77b5315e4..1ab407e37 100644
--- a/mcp-host/src/workflow/artifactOutput.ts
+++ b/mcp-host/src/workflow/artifactOutput.ts
@@ -160,3 +160,72 @@ export function artifactResult(
content: parts.join('\n'),
}
}
+
+export function ensureDir(dir: string): void {
+ if (!fs.existsSync(dir)) {
+ fs.mkdirSync(dir, { recursive: true })
+ }
+}
+
+// A dashboard with charts inlines the Chart.js UMD bundle (~210 KB) so the
+// HTML works offline: about 250 of them fit in the default quota.
+const DEFAULT_QUOTA_MB = 50
+
+/**
+ * Recursively sum the size of all regular files under `dir`.
+ * Returns 0 if the directory does not exist.
+ */
+export function getDirectorySize(dir: string): number {
+ if (!fs.existsSync(dir)) return 0
+ let total = 0
+ const entries = fs.readdirSync(dir, { withFileTypes: true })
+ for (const entry of entries) {
+ const full = path.join(dir, entry.name)
+ if (entry.isDirectory()) {
+ total += getDirectorySize(full)
+ } else if (entry.isFile()) {
+ try {
+ total += fs.statSync(full).size
+ } catch {
+ // file may have been removed between readdir and stat — ignore
+ }
+ }
+ }
+ return total
+}
+
+/**
+ * Enforce the per-recipe output quota before a file is written.
+ *
+ * Reads the ceiling from `CLERUM_WORKFLOW_OUTPUT_QUOTA_MB` (default: 50 MB).
+ * Throws if the current directory usage + `incomingBytes` would exceed the cap.
+ * `replacingBytes` is the size of a file the write overwrites, which stops
+ * counting once it is replaced.
+ *
+ * Known limitation (race condition): When the LLM issues multiple tool calls
+ * concurrently (e.g., generate_pdf + generate_xlsx in the same turn), both
+ * calls read the directory size before either has written its file. Both see
+ * the same "current" size and both pass the quota check, even though the
+ * combined output would exceed the 50 MB cap. This is a best-effort soft
+ * quota; the 1Gi PVC hard cap enforced by kubelet is the primary defense.
+ */
+export function enforceQuota(outputDir: string, incomingBytes: number, replacingBytes = 0): void {
+ const raw = process.env.CLERUM_WORKFLOW_OUTPUT_QUOTA_MB
+ const parsed = raw ? parseInt(raw, 10) : NaN
+ const quotaMB = Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_QUOTA_MB
+ const quotaBytes = quotaMB * 1024 * 1024
+
+ const current = getDirectorySize(outputDir) - replacingBytes
+ const projected = current + incomingBytes
+ if (projected > quotaBytes) {
+ const mb = (bytes: number) => (bytes / (1024 * 1024)).toFixed(1)
+ throw new Error(
+ `Output quota exceeded: the output folder holds ${mb(current)} MB and this file needs ` +
+ `${mb(incomingBytes)} MB, over the ${quotaMB} MB limit. Make the file smaller, or ask ` +
+ 'the user to remove earlier generated files or an operator to raise ' +
+ 'CLERUM_WORKFLOW_OUTPUT_QUOTA_MB.'
+ )
+ }
+}
+
+// ─── generate_chart ──────────────────────────────────────────────────
diff --git a/mcp-host/src/workflow/chartGenerator.ts b/mcp-host/src/workflow/chartGenerator.ts
new file mode 100644
index 000000000..5eeafe56f
--- /dev/null
+++ b/mcp-host/src/workflow/chartGenerator.ts
@@ -0,0 +1,939 @@
+/** 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 ChartType,
+ type Plugin,
+ type Scale,
+ registerables,
+} from 'chart.js'
+import * as fs from 'fs'
+import * as path from 'path'
+import { config } from '../config'
+import {
+ artifactResult,
+ claimOutputFile,
+ enforceQuota,
+ ensureDir,
+ outputFilename,
+ replacedBytes,
+} from './artifactOutput'
+import { ChartDataError, type NormalizedPoint, normalizeChartData } from './chartData'
+import {
+ type ValueFormat,
+ type ValueLabelOptions,
+ backgroundPlugin,
+ emptyStatePlugin,
+ formatValue,
+ gaugeCenterPlugin,
+ sliceColors,
+ valueLabelsPlugin,
+} from './chartPlugins'
+import { CHART_THEMES, ChartTheme } from './chartThemes'
+import { PNG_BASE_PPM } from './embeddedImages'
+import { CHART_FONT_STACK, ensureFontsReady, sanitizeForFont } from './fonts'
+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'
+}
+
+/** Types whose series overlap, so their fill has to let the one below show. */
+const TRANSLUCENT_FILL_TYPES = new Set(['line', 'area', 'radar'])
+
+/** Widest a single bar may be drawn, in nominal pixels. */
+const MAX_BAR_THICKNESS = 120
+
+export const DEFAULT_CHART_WIDTH = 800
+export const DEFAULT_CHART_HEIGHT = 400
+export const MAX_CHART_DIMENSION = 4000
+export const MIN_CHART_DIMENSION = 100
+/** 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
+])
+
+interface ChartDataset {
+ label?: string
+ /**
+ * Numbers for category charts, {x,y[,r]} for scatter/bubble, and [from,to]
+ * tuples once a waterfall has been expanded into floating bars.
+ */
+ data: Array<number | null> | NormalizedPoint[] | number[][]
+ backgroundColor?: string | string[]
+ borderColor?: string | string[]
+ fill?: boolean
+}
+
+/**
+ * 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
+}
+
+/**
+ * Default radius of a series' points: `full` up to `crowd` points, and smaller
+ * past that so a dense series keeps the ink of `crowd` points instead of
+ * merging into one blot. Never under 1.5 px, so a lone point still shows.
+ */
+function pointRadius(full: number, crowd: number, points: number): number {
+ return points <= crowd ? full : Math.max(1.5, full * Math.sqrt(crowd / points))
+}
+
+/**
+ * Apply theme colors to datasets that don't specify their own. Each dataset gets
+ * a different color from the palette by index. For pie/doughnut/polarArea where
+ * each slice is a separate color, every slice gets its own color: a caller's
+ * short list is completed from the theme, and slices past the palette get
+ * shades of it.
+ *
+ * Palettes have 7 colors; with more datasets the palette wraps via
+ * `idx % palette.length`, so series i and i+7 share a color. Callers who need
+ * more distinct series pass `borderColor` / `backgroundColor` per dataset.
+ */
+function applyThemePalette(
+ datasets: ChartDataset[],
+ theme: ChartTheme,
+ chartType: string,
+ warnings: string[]
+): ChartDataset[] {
+ const sliceTypes = new Set(['pie', 'doughnut', 'polarArea'])
+ const isSliceType = sliceTypes.has(chartType)
+
+ return datasets.map((ds, idx) => {
+ const out: ChartDataset = { ...ds }
+ if (isSliceType) {
+ if (typeof out.backgroundColor !== 'string') {
+ const requested = out.backgroundColor
+ const { colors, padded, repeated } = sliceColors(
+ ds.data.length,
+ requested,
+ theme.palette,
+ theme.backgroundColor
+ )
+ out.backgroundColor = colors
+ const where = `data.datasets[${idx}]`
+ if (padded) {
+ warnings.push(
+ `${where}.backgroundColor had ${requested!.length} color(s) for ${ds.data.length} ` +
+ 'slices; the rest were taken from the theme. Send one color per slice.'
+ )
+ }
+ if (repeated) {
+ warnings.push(
+ `${where} has ${ds.data.length} slices, more than there are distinct colors, so ` +
+ 'some colors repeat. Group the smallest slices into "Other".'
+ )
+ }
+ }
+ } else {
+ const color = theme.palette[idx % theme.palette.length]
+ if (!out.borderColor) out.borderColor = color
+ if (!out.backgroundColor) {
+ // Translucent wherever series are drawn over one another — a solid
+ // radar fill hides every series behind the first.
+ out.backgroundColor = TRANSLUCENT_FILL_TYPES.has(chartType) ? `${color}33` : color
+ }
+ if (chartType === 'area' && out.fill === undefined) {
+ out.fill = true
+ }
+ const point = out as unknown as Record<string, unknown>
+ const points = Array.isArray(ds.data) ? ds.data.length : 0
+ if (chartType === 'scatter') {
+ if (point.pointRadius === undefined) point.pointRadius = pointRadius(6, 100, points)
+ } else if (chartType === 'line' || chartType === 'area' || chartType === 'stackedArea') {
+ // A value with a gap on both sides gets no segment, so its point is
+ // its only mark.
+ if (point.pointRadius === undefined) point.pointRadius = pointRadius(4, 60, points)
+ if (point.pointBackgroundColor === undefined) point.pointBackgroundColor = color
+ }
+ }
+ return out
+ })
+}
+
+interface ResolvedChartType {
+ chartType: ChartType
+ // Loosely typed because Chart.js options that are valid only for specific
+ // chart kinds (rotation/circumference/cutout for doughnut, indexAxis for
+ // bar, etc.) don't satisfy the general ChartConfiguration['options'] union.
+ // The cast happens once at config-merge time.
+ optionsOverrides: Record<string, unknown> & {
+ scales?: {
+ x?: Record<string, unknown>
+ y?: Record<string, unknown>
+ y1?: Record<string, unknown>
+ }
+ plugins?: { legend?: { display?: boolean } }
+ indexAxis?: 'x' | 'y'
+ }
+ /** When set, the caller should replace the labels array with this value. */
+ labels?: string[]
+ /** Gauge only: the reading as sent and the dial's ceiling, for the centre readout. */
+ gaugeValue?: number
+ gaugeMax?: number
+ /** What the type changed about the data, for the caller. */
+ notes: string[]
+}
+
+/**
+ * Resolve our user-facing chart-type string to the underlying Chart.js
+ * type AND compute per-type option overrides + dataset mutations.
+ *
+ * For composed types (gauge / waterfall / funnel / mixedBarLine / stacked*)
+ * this function MUTATES `datasets` (and sometimes `labels`) in-place so
+ * the caller can pass the result straight into the Chart.js config.
+ */
+function resolveChartType(
+ raw: string,
+ datasets: ChartDataset[],
+ labels: string[] | undefined,
+ theme: ChartTheme,
+ args: Record<string, unknown>
+): ResolvedChartType {
+ const o: ResolvedChartType = { chartType: 'bar', optionsOverrides: {}, notes: [] }
+ switch (raw) {
+ case 'horizontalBar':
+ o.chartType = 'bar'
+ o.optionsOverrides.indexAxis = 'y'
+ return o
+ case 'area':
+ o.chartType = 'line'
+ // applyThemePalette already set fill=true for area datasets.
+ return o
+ case 'stackedBar':
+ o.chartType = 'bar'
+ o.optionsOverrides.scales = {
+ x: { stacked: true },
+ y: { stacked: true },
+ }
+ return o
+ case 'stackedArea':
+ o.chartType = 'line'
+ o.optionsOverrides.scales = { y: { stacked: true } }
+ datasets.forEach((d, i) => {
+ if (d.fill === undefined) d.fill = (i === 0 ? 'origin' : '-1') as unknown as boolean
+ })
+ return o
+ case 'mixedBarLine': {
+ o.chartType = 'bar'
+ // First dataset stays as bar (default for mixed); subsequent
+ // datasets render as line overlays via Chart.js per-dataset `type`.
+ const dual = args.dualAxis === true
+ datasets.forEach((d, i) => {
+ if (i > 0) {
+ ;(d as any).type = 'line'
+ ;(d as any).fill = false
+ if (dual) (d as unknown as Record<string, unknown>).yAxisID = 'y1'
+ }
+ })
+ if (dual) {
+ o.optionsOverrides.scales = {
+ y1: { position: 'right', grid: { drawOnChartArea: false } },
+ }
+ }
+ return o
+ }
+ case 'bubble':
+ o.chartType = 'bubble'
+ return o
+ case 'gauge': {
+ o.chartType = 'doughnut'
+ // Single-value 0..max. Take datasets[0].data[0] as the value;
+ // build a 2-segment doughnut [value, max-value] and rotate it
+ // 180° so the cut shows as a half-circle dial at the bottom.
+ const ds = datasets[0]
+ if (!ds) return o
+ const values = (ds.data as unknown[]).filter((v): v is number => typeof v === 'number')
+ const reading = values[0] ?? 0
+ const max = Math.max(0, Number(args.gaugeMax) || 100)
+ // Only the arc is bounded by the dial; the readout prints the reading.
+ const arc = Math.min(Math.max(reading, 0), max)
+ if (reading > max) {
+ o.notes.push(
+ `the gauge value ${reading} exceeds gaugeMax ${max}, so the dial is shown full; ` +
+ 'the readout prints the value. Raise gaugeMax to show it on the scale.'
+ )
+ } else if (reading < 0) {
+ o.notes.push(`the gauge value ${reading} is below 0, so the dial is shown empty.`)
+ }
+ if (values.length > 1) {
+ o.notes.push(
+ `the gauge shows one value, so ${values.length - 1} more in data.datasets[0].data ` +
+ `${values.length > 2 ? 'were' : 'was'} left out.`
+ )
+ }
+ const fill = theme.palette[0]
+ const remainder = theme.gridColor
+ ds.data = [arc, max - arc]
+ ds.backgroundColor = [fill, remainder]
+ ds.borderColor = [fill, remainder]
+ // Drop any extra datasets — gauge is single-value.
+ datasets.length = 1
+ o.gaugeValue = reading
+ o.gaugeMax = max
+ o.labels = ['Value', 'Remainder']
+ o.optionsOverrides = {
+ rotation: -90,
+ circumference: 180,
+ cutout: '70%',
+ // The bottom padding leaves room under the dial's flat edge for the
+ // "/ max" line the readout prints below it.
+ radius: '88%',
+ layout: { padding: { top: 12, right: 16, bottom: 90, left: 16 } },
+ plugins: { legend: { display: false } },
+ }
+ return o
+ }
+ case 'waterfall': {
+ o.chartType = 'bar'
+ const ds = datasets[0]
+ if (!ds || !Array.isArray(ds.data)) return o
+ const deltas = ds.data as number[]
+ const floats: number[][] = []
+ const colors: string[] = []
+ let cumulative = 0
+ for (const delta of deltas) {
+ const start = cumulative
+ cumulative += Number(delta) || 0
+ floats.push([start, cumulative])
+ colors.push((Number(delta) || 0) >= 0 ? theme.positive : theme.negative)
+ }
+ // Final cumulative-total bar in primary color.
+ floats.push([0, cumulative])
+ colors.push(theme.palette[0])
+ ds.data = floats as any
+ ds.backgroundColor = colors
+ ds.borderColor = colors
+ // Append "Total" to labels (or synthesize labels if absent).
+ const newLabels = labels ? [...labels] : deltas.map((_, i) => `Step ${i + 1}`)
+ newLabels.push('Total')
+ o.labels = newLabels
+ // Drop extra datasets — waterfall is single-series.
+ datasets.length = 1
+ o.optionsOverrides = { plugins: { legend: { display: false } } }
+ return o
+ }
+ case 'funnel': {
+ o.chartType = 'bar'
+ const ds = datasets[0]
+ if (!ds || !Array.isArray(ds.data)) return o
+ // Sort descending while keeping label/data alignment.
+ const lbls = labels ?? (ds.data as number[]).map((_, i) => `Stage ${i + 1}`)
+ const paired = (ds.data as number[]).map((v, i) => ({
+ v: Number(v) || 0,
+ l: lbls[i] ?? '',
+ i,
+ }))
+ paired.sort((a, b) => b.v - a.v)
+ ds.data = paired.map(p => p.v)
+ o.labels = paired.map(p => p.l)
+ // Per-stage colors follow their stage through the sort.
+ const follow = (colors: string | string[] | undefined) =>
+ Array.isArray(colors) ? paired.map(p => colors[p.i % colors.length]) : colors
+ ds.backgroundColor = follow(ds.backgroundColor)
+ ds.borderColor = follow(ds.borderColor)
+ // Drop extra datasets — funnel is single-series.
+ datasets.length = 1
+ o.optionsOverrides = {
+ indexAxis: 'y',
+ plugins: { legend: { display: false } },
+ }
+ return o
+ }
+ default:
+ o.chartType = raw as ChartType
+ return o
+ }
+}
+
+// ─── Portable schema fragments ───────────────────────────────────────
+//
+// A tool schema does two jobs. The workflow path (stepRouter) compiles it with
+// AJV and REJECTS arguments that do not match before execute() runs, so it must
+// accept everything the runtime handles. And it reaches every provider
+// verbatim, so it must survive each SDK's translation. Unions are therefore
+// written as scalar type lists or `anyOf` branches — @google/genai turns both
+// into its own schema — and never as `oneOf`, which it passes through
+// untranslated for the Gemini API to reject. Every array declares `items`.
+
+/** 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 every plotted number is absent or zero, so nothing would be drawn. */
+function isVisuallyEmpty(datasets: ChartDataset[]): boolean {
+ 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 {
+ if (value === undefined || value === null) return fallback
+ const n = typeof value === 'number' ? value : Number(value)
+ if (!Number.isFinite(n) || n <= 0) {
+ warnings.push(`${field} ${String(value)} is not a positive number; used ${fallback}.`)
+ return fallback
+ }
+ 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 themeName = String(args.theme ?? 'light')
+ const theme = CHART_THEMES[themeName] ?? CHART_THEMES.light
+
+ 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 themedDatasets = applyThemePalette(datasets, theme, chartTypeRaw, warnings)
+ const resolved = resolveChartType(chartTypeRaw, themedDatasets, labels, theme, args)
+ 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 }
+ if (labelValues) plugins.push(valueLabelsPlugin({ ...valueOptions, unlabelled }))
+ if (chartTypeRaw === 'gauge') {
+ plugins.push(
+ gaugeCenterPlugin({
+ value: resolved.gaugeValue ?? 0,
+ max: resolved.gaugeMax ?? 100,
+ textColor: theme.textColor,
+ mutedColor: theme.mutedTextColor,
+ format: valueOptions,
+ })
+ )
+ }
+ if (isVisuallyEmpty(themedDatasets)) {
+ 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
+ // 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.'
+ )
+ }
+ // 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))
+ fs.writeFileSync(target.filePath, 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 })
+ } 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()
+ }
+}
diff --git a/mcp-host/src/workflow/chartThemes.ts b/mcp-host/src/workflow/chartThemes.ts
new file mode 100644
index 000000000..bb774c100
--- /dev/null
+++ b/mcp-host/src/workflow/chartThemes.ts
@@ -0,0 +1,61 @@
+/** Chart colour themes shared by the chart tool, the dashboard and the tool schemas. */
+
+export interface ChartTheme {
+ backgroundColor: string
+ textColor: string
+ /** Secondary text, such as a gauge's maximum: at least 4.5:1 on the background. */
+ mutedTextColor: string
+ gridColor: string
+ palette: string[]
+ /** Semantic colors used by waterfall (positive/negative deltas) and gauge. */
+ positive: string
+ negative: string
+}
+
+export const CHART_THEMES: Record<string, ChartTheme> = {
+ light: {
+ backgroundColor: '#ffffff',
+ textColor: '#0f172a',
+ mutedTextColor: '#64748b',
+ gridColor: '#e2e8f0',
+ palette: ['#0f172a', '#22c55e', '#f59e0b', '#ef4444', '#3b82f6', '#a855f7', '#06b6d4'],
+ positive: '#16a34a',
+ negative: '#dc2626',
+ },
+ dark: {
+ backgroundColor: '#0f172a',
+ textColor: '#e2e8f0',
+ mutedTextColor: '#94a3b8',
+ gridColor: '#334155',
+ palette: ['#22c55e', '#3b82f6', '#a855f7', '#f59e0b', '#ef4444', '#06b6d4', '#ec4899'],
+ positive: '#22c55e',
+ negative: '#f87171',
+ },
+ corporate: {
+ backgroundColor: '#ffffff',
+ textColor: '#1e293b',
+ mutedTextColor: '#64748b',
+ gridColor: '#cbd5e1',
+ palette: ['#1e40af', '#0891b2', '#0d9488', '#059669', '#65a30d', '#ca8a04', '#dc2626'],
+ positive: '#059669',
+ negative: '#b91c1c',
+ },
+ warm: {
+ backgroundColor: '#f7f7f5',
+ textColor: '#2f2823',
+ mutedTextColor: '#716961',
+ gridColor: '#d6d2cc',
+ palette: ['#b45309', '#2f2823', '#0d9488', '#1e40af', '#9f1239', '#65a30d', '#7c3aed'],
+ positive: '#65a30d',
+ negative: '#9f1239',
+ },
+ 'warm-dark': {
+ backgroundColor: '#0e0f10',
+ textColor: '#f2f2ef',
+ mutedTextColor: '#9b958f',
+ gridColor: '#2a2c2f',
+ palette: ['#ca6e1e', '#f2f2ef', '#34d399', '#60a5fa', '#fb7185', '#a3e635', '#c4b5fd'],
+ positive: '#a3e635',
+ negative: '#fb7185',
+ },
+}
diff --git a/mcp-host/src/workflow/dashboardHtml.ts b/mcp-host/src/workflow/dashboardHtml.ts
index eb93f4ad5..2f400801f 100644
--- a/mcp-host/src/workflow/dashboardHtml.ts
+++ b/mcp-host/src/workflow/dashboardHtml.ts
@@ -21,3 +21,31 @@ export function oneOf<T extends string>(value: unknown, allowed: readonly T[], f
? (value as T)
: fallback
}
+
+/**
+ * JSON.stringify with HTML-sensitive characters escaped, safe to embed
+ * inside a `<script>` block. Prevents `</script>...<script>alert(1)...`
+ * breakouts via attacker-controlled string content.
+ */
+export function safeJsonForScript(v: unknown): string {
+ return JSON.stringify(v)
+ .replace(/</g, '\\u003c')
+ .replace(/>/g, '\\u003e')
+ .replace(/&/g, '\\u0026')
+ .replace(/\u2028/g, '\\u2028')
+ .replace(/\u2029/g, '\\u2029')
+}
+
+/**
+ * Escape a value for use inside an HTML attribute (single OR double
+ * quoted). Defends against attribute-breakout XSS like
+ * `data-foo='${val}'` where `val` contains `'`.
+ */
+export function escapeHtmlAttr(s: unknown): string {
+ return String(s ?? '')
+ .replace(/&/g, '&amp;')
+ .replace(/"/g, '&quot;')
+ .replace(/'/g, '&#39;')
+ .replace(/</g, '&lt;')
+ .replace(/>/g, '&gt;')
+}
diff --git a/mcp-host/src/workflow/dashboardRender.ts b/mcp-host/src/workflow/dashboardRender.ts
new file mode 100644
index 000000000..216fc73f9
--- /dev/null
+++ b/mcp-host/src/workflow/dashboardRender.ts
@@ -0,0 +1,1786 @@
+/** The HTML dashboard renderer (clerum__generate_dashboard): templates, blocks, CSS and the page wrapper. */
+import * as fs from 'fs'
+import * as path from 'path'
+import {
+ artifactResult,
+ claimOutputFile,
+ enforceQuota,
+ ensureDir,
+ outputFilename,
+ replacedBytes,
+} from './artifactOutput'
+import { coerceNumber } from './chartData'
+import { DashboardCharts } from './dashboardCharts'
+import { escapeHtml, escapeHtmlAttr, oneOf, safeJsonForScript } from './dashboardHtml'
+import { dashboardScript } from './dashboardScript'
+import {
+ DASHBOARD_THEMES,
+ type DashboardTheme,
+ type DashboardThemeColors,
+ type ThemeName,
+} from './dashboardThemes'
+import { headerText, normalizeTableRows } from './tableRows'
+import type { InternalToolResult } from './types'
+
+function dashboardColorVars(c: DashboardThemeColors): string {
+ return `
+ --bg: ${c.bg};
+ --surface: ${c.surface};
+ --surface-muted: ${c.surfaceMuted};
+ --text: ${c.text};
+ --text-muted: ${c.textMuted};
+ --text-soft: ${c.textSoft};
+ --border: ${c.border};
+ --primary: ${c.primary};
+ --primary-hover: ${c.primaryHover};
+ --accent: ${c.accent};
+ --success: ${c.success};
+ --warning: ${c.warning};
+ --danger: ${c.danger};
+ --success-bg: ${c.successBg};
+ --warning-bg: ${c.warningBg};
+ --danger-bg: ${c.dangerBg};
+ --neutral-bg: ${c.neutralBg};
+ ${c.chart.map((color, i) => `--chart-${i + 1}: ${color};`).join('\n ')}`.trim()
+}
+
+/**
+ * The page's styles. With no `mode` the page follows the viewer's color
+ * scheme; a mode given is kept whatever the viewer's scheme. Print is light.
+ */
+function buildDashboardCss(theme: DashboardTheme, mode?: 'light' | 'dark'): string {
+ const lightVars = dashboardColorVars(theme.light)
+ const darkVars = dashboardColorVars(theme.dark)
+ const baseVars = mode === 'dark' ? darkVars : lightVars
+ const oppositeVars = mode === 'dark' ? lightVars : darkVars
+ const oppositeKey = mode === 'dark' ? 'light' : 'dark'
+ const viewerScheme =
+ mode === undefined
+ ? `
+@media (prefers-color-scheme: dark) {
+ :root:not([data-theme]) {
+ ${darkVars}
+ }
+}
+`
+ : ''
+
+ return `
+*, *::before, *::after { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+
+:root {
+ ${baseVars}
+ --font: ${theme.fontFamily};
+ --radius-sm: 6px;
+ --radius: 10px;
+ --radius-lg: 14px;
+ --shadow: 0 1px 2px rgba(0,0,0,0.05), 0 4px 12px rgba(0,0,0,0.04);
+ --shadow-lg: 0 8px 24px rgba(0,0,0,0.08), 0 2px 6px rgba(0,0,0,0.04);
+}
+
+[data-theme="${oppositeKey}"] {
+ ${oppositeVars}
+}
+${viewerScheme}
+body {
+ font-family: var(--font);
+ font-size: 15px;
+ line-height: 1.55;
+ color: var(--text);
+ background: var(--bg);
+ -webkit-font-smoothing: antialiased;
+ -moz-osx-font-smoothing: grayscale;
+}
+
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+code {
+ font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+ font-size: 0.9em;
+ background: var(--surface-muted);
+ padding: 0.1em 0.3em;
+ border-radius: 4px;
+ color: var(--text);
+}
+strong, b { color: var(--text); font-weight: 600; }
+em, i { font-style: italic; }
+
+/* ─── Layout ──────────────────────────────────────────────────────── */
+
+.dashboard {
+ max-width: 1180px;
+ margin: 0 auto;
+ padding: 32px 24px 64px;
+}
+
+.hero {
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+ padding: 32px;
+ margin-bottom: 28px;
+ background: var(--surface);
+ border-radius: var(--radius-lg);
+ border: 1px solid var(--border);
+ box-shadow: var(--shadow);
+ position: relative;
+ overflow: hidden;
+}
+.hero::before {
+ content: '';
+ position: absolute;
+ inset: 0 0 auto 0;
+ height: 6px;
+ background: var(--primary);
+}
+.hero[data-status="green"]::before { background: var(--success); }
+.hero[data-status="yellow"]::before { background: var(--warning); }
+.hero[data-status="red"]::before { background: var(--danger); }
+
+.hero__eyebrow {
+ font-size: 12px;
+ font-weight: 600;
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+ color: var(--text-soft);
+}
+.hero__title, .hero__headline, .kpi-card__label, .kpi-card__value, .kpi-card__delta,
+.chart-card__title, .health-card__name, .health-card__metric, .timeline-item__title {
+ overflow-wrap: anywhere;
+}
+.kpi-card, .chart-card, .health-card, .timeline-item__body { min-width: 0; }
+.hero__title {
+ font-size: 32px;
+ font-weight: 700;
+ letter-spacing: -0.02em;
+ color: var(--text);
+ margin: 0;
+}
+.hero__headline {
+ font-size: 18px;
+ color: var(--text-muted);
+ margin: 0;
+ line-height: 1.4;
+}
+
+.status-badge {
+ display: inline-flex;
+ align-items: center;
+ gap: 8px;
+ padding: 6px 14px;
+ border-radius: 999px;
+ font-size: 12px;
+ font-weight: 600;
+ letter-spacing: 0.05em;
+ text-transform: uppercase;
+ align-self: flex-start;
+}
+.status-badge[data-status="green"] { background: var(--success-bg); color: var(--success); }
+.status-badge[data-status="yellow"] { background: var(--warning-bg); color: var(--warning); }
+.status-badge[data-status="red"] { background: var(--danger-bg); color: var(--danger); }
+.status-badge[data-status="neutral"] { background: var(--neutral-bg); color: var(--text-muted); }
+.status-badge::before {
+ content: '';
+ width: 8px; height: 8px;
+ border-radius: 50%;
+ background: currentColor;
+}
+
+/* ─── Section ─────────────────────────────────────────────────────── */
+
+.section {
+ margin-bottom: 28px;
+}
+.section > :last-child { margin-bottom: 0; }
+.section__title {
+ display: flex;
+ align-items: baseline;
+ justify-content: space-between;
+ gap: 16px;
+ margin: 0 0 12px;
+ font-size: 18px;
+ font-weight: 600;
+ color: var(--text);
+}
+.section__subtitle {
+ font-size: 13px;
+ color: var(--text-soft);
+ font-weight: 400;
+}
+
+/* ─── KPI grid ────────────────────────────────────────────────────── */
+
+.kpi-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(min(220px, 100%), 1fr));
+ gap: 16px;
+ margin-bottom: 28px;
+}
+
+.kpi-card {
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ padding: 20px;
+ box-shadow: var(--shadow);
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+ transition: transform 0.12s ease;
+}
+.kpi-card:hover { transform: translateY(-2px); }
+
+.kpi-card__label {
+ font-size: 12px;
+ font-weight: 600;
+ letter-spacing: 0.06em;
+ text-transform: uppercase;
+ color: var(--text-soft);
+ margin: 0;
+}
+.kpi-card__value {
+ font-size: 28px;
+ font-weight: 700;
+ letter-spacing: -0.02em;
+ color: var(--text);
+ margin: 0;
+ line-height: 1.1;
+}
+.kpi-card__delta {
+ display: inline-flex;
+ align-items: center;
+ gap: 4px;
+ font-size: 13px;
+ font-weight: 600;
+ margin: 0;
+}
+.kpi-card__delta[data-sentiment="good"] { color: var(--success); }
+.kpi-card__delta[data-sentiment="bad"] { color: var(--danger); }
+.kpi-card__delta[data-sentiment="neutral"] { color: var(--text-muted); }
+.kpi-card__delta::before {
+ font-size: 11px;
+}
+.kpi-card__delta[data-direction="up"]::before { content: '▲'; }
+.kpi-card__delta[data-direction="down"]::before { content: '▼'; }
+.kpi-card__delta[data-direction="neutral"]::before { content: '·'; }
+
+.kpi-card__sparkline-wrap {
+ position: relative;
+ margin-top: 8px;
+ height: 36px;
+ max-height: 36px;
+ width: 100%;
+ overflow: hidden;
+ contain: size layout;
+}
+.kpi-card__sparkline {
+ position: absolute !important;
+ inset: 0 !important;
+ width: 100% !important;
+ height: 100% !important;
+ max-width: 100% !important;
+ max-height: 100% !important;
+}
+
+/* ─── Chart cards ─────────────────────────────────────────────────── */
+
+.chart-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(min(360px, 100%), 1fr));
+ gap: 16px;
+ margin-bottom: 28px;
+}
+
+.chart-card {
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ padding: 20px;
+ box-shadow: var(--shadow);
+}
+.chart-card__table {
+ overflow-x: auto;
+}
+.chart-card__table .data-table {
+ font-size: 13px;
+}
+.chart-card__note {
+ margin: 0;
+ padding: 24px 12px;
+ text-align: center;
+ color: var(--text-muted);
+ font-size: 13px;
+ line-height: 1.5;
+}
+
+.chart-card__caption {
+ margin: 8px 0 0;
+ text-align: center;
+ color: var(--text-muted);
+ font-size: 13px;
+ font-weight: 600;
+ overflow-wrap: anywhere;
+}
+
+.chart-card__title {
+ font-size: 14px;
+ font-weight: 600;
+ color: var(--text);
+ margin: 0 0 12px;
+}
+.chart-card__container {
+ position: relative;
+ height: 280px;
+ max-height: 280px;
+ width: 100%;
+ overflow: hidden;
+ contain: size layout;
+}
+.chart-card__container > canvas {
+ position: absolute !important;
+ inset: 0 !important;
+ width: 100% !important;
+ height: 100% !important;
+ max-width: 100% !important;
+ max-height: 100% !important;
+}
+
+/* ─── Data tables ─────────────────────────────────────────────────── */
+
+.data-table-wrap {
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ overflow-x: auto;
+ box-shadow: var(--shadow);
+ margin-bottom: 28px;
+}
+
+.data-table {
+ width: 100%;
+ border-collapse: collapse;
+ font-size: 14px;
+}
+.data-table thead th {
+ background: var(--primary);
+ color: white;
+ font-weight: 600;
+ text-align: left;
+ padding: 12px 16px;
+ letter-spacing: 0.02em;
+}
+.data-table tbody td {
+ padding: 12px 16px;
+ border-top: 1px solid var(--border);
+ color: var(--text);
+ vertical-align: top;
+}
+.data-table tbody tr:nth-child(even) td {
+ background: var(--surface-muted);
+}
+.severity-badge {
+ display: inline-block;
+ padding: 2px 8px;
+ border-radius: 999px;
+ font-size: 11px;
+ font-weight: 700;
+ letter-spacing: 0.04em;
+ text-transform: uppercase;
+}
+.severity-critical, .severity-p0 { background: var(--danger-bg); color: var(--danger); }
+.severity-high, .severity-p1 { background: var(--warning-bg); color: var(--warning); }
+.severity-med { background: var(--neutral-bg); color: var(--text-muted); }
+.severity-low, .severity-p2 { background: var(--success-bg); color: var(--success); }
+.severity-info { background: var(--neutral-bg); color: var(--text-soft); }
+
+/* ─── Callouts / risks / narrative ───────────────────────────────── */
+
+.callout {
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-left: 4px solid var(--accent);
+ border-radius: var(--radius);
+ padding: 16px 20px;
+ margin: 0 0 16px;
+}
+.callout[data-tone="warning"] { border-left-color: var(--warning); }
+.callout[data-tone="danger"] { border-left-color: var(--danger); }
+.callout[data-tone="success"] { border-left-color: var(--success); }
+.kpi-grid > .callout, .health-grid > .callout { margin: 0; }
+.timeline-item > .callout { margin: 0 0 0 12px; }
+
+.bullets {
+ margin: 0;
+ padding: 0 0 0 20px;
+ color: var(--text);
+}
+.bullets li {
+ margin-bottom: 8px;
+ line-height: 1.55;
+}
+.bullets li::marker {
+ color: var(--accent);
+}
+
+.narrative {
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ padding: 20px 24px;
+ font-size: 15px;
+ line-height: 1.65;
+ color: var(--text);
+ box-shadow: var(--shadow);
+}
+.narrative p { margin: 0 0 12px; }
+.narrative p:last-child { margin-bottom: 0; }
+
+/* ─── Service health grid (operations-pulse) ─────────────────────── */
+
+.health-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(min(200px, 100%), 1fr));
+ gap: 12px;
+ margin-bottom: 28px;
+}
+
+.health-card {
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-left: 4px solid var(--text-muted);
+ border-radius: var(--radius);
+ padding: 14px 16px;
+ box-shadow: var(--shadow);
+}
+.health-card[data-status="healthy"] { border-left-color: var(--success); }
+.health-card[data-status="degraded"] { border-left-color: var(--warning); }
+.health-card[data-status="down"] { border-left-color: var(--danger); }
+.health-card[data-status="maintenance"] { border-left-color: var(--text-muted); }
+
+.health-card__head {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ margin-bottom: 6px;
+}
+.health-card__dot {
+ width: 8px; height: 8px;
+ border-radius: 50%;
+ background: var(--text-muted);
+}
+.health-card[data-status="healthy"] .health-card__dot { background: var(--success); }
+.health-card[data-status="degraded"] .health-card__dot { background: var(--warning); }
+.health-card[data-status="down"] .health-card__dot { background: var(--danger); }
+.health-card[data-status="maintenance"] .health-card__dot { background: var(--text-soft); }
+
+.health-card__name {
+ font-size: 14px;
+ font-weight: 600;
+ color: var(--text);
+ margin: 0;
+}
+.health-card__status {
+ font-size: 11px;
+ font-weight: 700;
+ letter-spacing: 0.06em;
+ color: var(--text-muted);
+ margin: 0 0 6px;
+}
+.health-card__metric {
+ font-size: 14px;
+ font-weight: 500;
+ color: var(--text);
+ margin: 0;
+ font-variant-numeric: tabular-nums;
+}
+
+/* ─── Incidents timeline (operations-pulse) ───────────────────────── */
+
+.timeline {
+ list-style: none;
+ margin: 0 0 28px;
+ padding: 0;
+ position: relative;
+}
+.timeline::before {
+ content: '';
+ position: absolute;
+ left: 88px;
+ top: 8px;
+ bottom: 8px;
+ width: 2px;
+ background: var(--border);
+}
+
+.timeline-item {
+ display: grid;
+ grid-template-columns: 80px 1fr;
+ gap: 16px;
+ padding: 12px 0;
+ position: relative;
+}
+.timeline-item__time {
+ font-size: 12px;
+ color: var(--text-muted);
+ font-variant-numeric: tabular-nums;
+ text-align: right;
+ padding-top: 4px;
+}
+.timeline-item::before {
+ content: '';
+ position: absolute;
+ left: 84px;
+ top: 18px;
+ width: 10px; height: 10px;
+ border-radius: 50%;
+ background: var(--text-muted);
+ border: 2px solid var(--surface);
+ z-index: 1;
+}
+.timeline-item[data-severity="critical"]::before { background: var(--danger); }
+.timeline-item[data-severity="high"]::before { background: var(--warning); }
+.timeline-item[data-severity="med"]::before { background: var(--accent); }
+.timeline-item[data-severity="low"]::before { background: var(--success); }
+.timeline-item[data-severity="info"]::before { background: var(--text-soft); }
+
+.timeline-item__body {
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ padding: 12px 16px;
+ box-shadow: var(--shadow);
+ margin-left: 12px;
+}
+.timeline-item__head {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ flex-wrap: wrap;
+ margin-bottom: 4px;
+}
+.timeline-item__title {
+ font-size: 14px;
+ font-weight: 600;
+ color: var(--text);
+ margin: 0;
+ flex: 1;
+}
+.timeline-item__open,
+.timeline-item__resolved {
+ font-size: 11px;
+ font-weight: 600;
+ letter-spacing: 0.04em;
+ text-transform: uppercase;
+ padding: 2px 8px;
+ border-radius: 999px;
+}
+.timeline-item__open { background: var(--warning-bg); color: var(--warning); }
+.timeline-item__resolved { background: var(--success-bg); color: var(--success); }
+.timeline-item__desc {
+ margin: 4px 0 0;
+ font-size: 13px;
+ color: var(--text-muted);
+}
+
+/* ─── Code block (technical-report) ───────────────────────────────── */
+
+.code-block {
+ background: var(--surface-muted);
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ margin: 0 0 16px;
+ overflow: hidden;
+}
+.code-block__lang {
+ font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+ font-size: 11px;
+ font-weight: 600;
+ color: var(--text-muted);
+ background: var(--surface);
+ padding: 6px 14px;
+ border-bottom: 1px solid var(--border);
+ text-transform: uppercase;
+ letter-spacing: 0.06em;
+}
+.code-block pre {
+ margin: 0;
+ padding: 14px 16px;
+ overflow-x: auto;
+ font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+ font-size: 13px;
+ line-height: 1.55;
+ color: var(--text);
+ background: transparent;
+}
+.code-block pre code {
+ background: transparent;
+ padding: 0;
+ font-size: inherit;
+ border-radius: 0;
+}
+
+/* ─── Wide / stacked chart layout (financial-review hero chart) ──── */
+
+.chart-stack {
+ display: grid;
+ grid-template-columns: 1fr;
+ gap: 16px;
+ margin-bottom: 28px;
+}
+.chart-card--wide {
+ /* spans full available width even inside a grid row */
+}
+.chart-card__container--tall {
+ height: 360px;
+ max-height: 360px;
+}
+
+/* ─── KPI accent overrides ────────────────────────────────────────── */
+
+.kpi-card[data-accent="success"] { border-top: 3px solid var(--success); }
+.kpi-card[data-accent="warning"] { border-top: 3px solid var(--warning); }
+.kpi-card[data-accent="danger"] { border-top: 3px solid var(--danger); }
+.kpi-card[data-accent="neutral"] { border-top: 3px solid var(--text-soft); }
+
+/* ─── Divider / spacer (custom template) ──────────────────────────── */
+
+.dashboard-divider {
+ border: none;
+ border-top: 1px solid var(--border);
+ margin: 28px 0;
+}
+.dashboard-spacer { display: block; }
+.dashboard-spacer--sm { height: 12px; }
+.dashboard-spacer--md { height: 28px; }
+.dashboard-spacer--lg { height: 56px; }
+
+/* ─── Footer ──────────────────────────────────────────────────────── */
+
+.dash-footer {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+ padding: 24px 0 0;
+ border-top: 1px solid var(--border);
+ margin-top: 40px;
+ font-size: 12px;
+ color: var(--text-soft);
+}
+.dash-footer__brand {
+ font-weight: 600;
+ color: var(--text-muted);
+}
+
+/* ─── Print ───────────────────────────────────────────────────────── */
+
+@media print {
+ :root, :root:not([data-theme]), [data-theme] {
+ ${lightVars}
+ }
+ body { background: white; }
+ .dashboard { max-width: 100%; padding: 0; }
+ .kpi-card, .chart-card, .data-table-wrap, .narrative, .callout {
+ box-shadow: none;
+ break-inside: avoid;
+ }
+ .hero { box-shadow: none; }
+ .section__title { break-after: avoid; }
+ .data-table-wrap { overflow: visible; }
+ .data-table { font-size: 11px; }
+ .data-table thead th, .data-table tbody td { padding: 6px 8px; }
+ .data-table--wide { font-size: 9px; }
+ .data-table--wide thead th, .data-table--wide tbody td { padding: 4px; overflow-wrap: anywhere; }
+}
+
+/* ─── Responsive ──────────────────────────────────────────────────── */
+
+@media (max-width: 640px) {
+ .dashboard { padding: 16px 12px 40px; }
+ .hero { padding: 24px; }
+ .hero__title { font-size: 24px; }
+ .hero__headline { font-size: 16px; }
+ .kpi-card__value { font-size: 22px; }
+ .chart-card__container { height: 220px; }
+}
+`.trim()
+}
+
+// ─── Render helpers (shared across templates) ──────────────────────
+//
+// The schema cannot say which fields each template or block type needs, so
+// every helper reads its input defensively. A part that cannot be read throws
+// an error naming the field; the caller replaces that part with a notice and
+// reports it, and the rest still renders.
+
+interface DashboardBranding {
+ companyName?: string
+ footerText?: string
+}
+
+/** State gathered while one dashboard renders. */
+interface DashRender {
+ charts: DashboardCharts
+ warnings: string[]
+ sparklines: number
+ drawSparklines: boolean
+ skippedSparklines: number
+ /** Parts that rendered, to tell a partial page from an empty one. */
+ rendered: number
+ /** Why each part that could not be shown failed. */
+ failures: string[]
+}
+
+function renderInlineMd(s: string): string {
+ return escapeHtml(s)
+ .replace(/\*\*([\s\S]+?)\*\*(?!\*)/g, '<strong>$1</strong>')
+ .replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, '<em>$1</em>')
+ .replace(/`([^`]+)`/g, '<code>$1</code>')
+}
+
+function isDashRecord(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function describeDashValue(value: unknown): string {
+ if (value === undefined) return 'nothing'
+ if (value === null) return 'null'
+ if (Array.isArray(value)) return 'an array'
+ if (typeof value === 'string') return `a string (${JSON.stringify(value.slice(0, 40))})`
+ return typeof value === 'object' ? 'an object' : `a ${typeof value} (${String(value)})`
+}
+
+function dashRecord(value: unknown, where: string, shape: string): Record<string, unknown> {
+ if (!isDashRecord(value)) {
+ throw new Error(`${where} must be ${shape}; received ${describeDashValue(value)}.`)
+ }
+ return value
+}
+
+function dashList(value: unknown, where: string, shape: string): unknown[] {
+ if (value === undefined || value === null) return []
+ if (!Array.isArray(value)) {
+ throw new Error(`${where} must be an array of ${shape}; received ${describeDashValue(value)}.`)
+ }
+ return value
+}
+
+/** Text of a scalar; anything else reads as empty. */
+function dashText(value: unknown): string {
+ return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+ ? String(value)
+ : ''
+}
+
+/** One paragraph or a list of them, rejecting what would print as "[object Object]". */
+function dashTextList(value: unknown, where: string): string[] {
+ const items = Array.isArray(value) ? value : [value]
+ const out = items.map((item, i) => {
+ if (typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean') {
+ return String(item)
+ }
+ const at = Array.isArray(value) ? `${where}[${i}]` : where
+ throw new Error(`${at} must be text; received ${describeDashValue(item)}.`)
+ })
+ if (out.every(t => t.trim() === '')) throw new Error(`${where} is empty; pass the text to show.`)
+ return out
+}
+
+/** `body` under its heading, in one section so a printed page never ends on the heading. */
+function titledSection(title: string | undefined, body: string): string {
+ return title
+ ? `<section class="section"><h2 class="section__title">${escapeHtml(title)}</h2>${body}</section>`
+ : body
+}
+
+/** A number as a reader expects it: grouped, without floating-point noise. */
+function formatDashNumber(n: number): string {
+ if (Number.isInteger(n)) return n.toLocaleString('en-US')
+ return Math.abs(n) >= 1
+ ? n.toLocaleString('en-US', { maximumFractionDigits: 2 })
+ : n.toLocaleString('en-US', { maximumSignificantDigits: 4 })
+}
+
+/** A figure: numbers are formatted, text is shown as written. */
+function dashFigure(value: unknown): string {
+ return typeof value === 'number' ? formatDashNumber(value) : dashText(value)
+}
+
+type DeltaDirection = 'up' | 'down' | 'neutral'
+
+/** A delta's text and arrow; a numeric delta is signed and, unless told otherwise, points its own way. */
+function dashDelta(
+ delta: unknown,
+ direction: unknown
+): { text: string; direction: DeltaDirection } {
+ const directions = ['up', 'down', 'neutral'] as const
+ if (typeof delta !== 'number') {
+ return { text: dashText(delta), direction: oneOf(direction, directions, 'neutral') }
+ }
+ const own = delta > 0 ? 'up' : delta < 0 ? 'down' : 'neutral'
+ return {
+ text: `${delta > 0 ? '+' : ''}${formatDashNumber(delta)}`,
+ direction: oneOf(direction, directions, own),
+ }
+}
+
+function deltaHtml(text: string, direction: DeltaDirection, sentiment: string): string {
+ if (!text) return ''
+ return `<p class="kpi-card__delta" data-direction="${direction}" data-sentiment="${sentiment}">${escapeHtml(text)}</p>`
+}
+
+function failureCallout(heading: string, message: string): string {
+ return `<section class="section"><h2 class="section__title">${escapeHtml(heading)}</h2><div class="callout" data-tone="danger">${escapeHtml(message)}</div></section>`
+}
+
+function recordFailure(ctx: DashRender, where: string, e: unknown): string {
+ const message = e instanceof Error ? e.message : String(e)
+ ctx.failures.push(message.includes(where) ? message : `${where}: ${message}`)
+ return message
+}
+
+/**
+ * Render one part of the page. A part that throws is replaced by a notice and
+ * reported, so one malformed entry never takes the dashboard down. `counts`
+ * is false for parts that are not content of their own (the hero, a divider)
+ * and for parts that count their own entries (charts, card groups).
+ */
+function dashPart(ctx: DashRender, where: string, counts: boolean, render: () => string): string {
+ try {
+ const html = render()
+ if (counts && html) ctx.rendered++
+ return html
+ } catch (e) {
+ const message = recordFailure(ctx, where, e)
+ return failureCallout(`${where} could not be shown`, message)
+ }
+}
+
+/**
+ * Render each entry of a card group on its own: a bad entry becomes a notice
+ * in its place and the other cards stay. The group counts as content when at
+ * least one entry rendered.
+ */
+function dashItems(
+ ctx: DashRender,
+ list: unknown[],
+ where: string,
+ render: (item: unknown, at: string) => string,
+ notice: (message: string) => string
+): string {
+ let shown = 0
+ const html = list
+ .map((item, i) => {
+ const at = `${where}[${i}]`
+ try {
+ const out = render(item, at)
+ shown++
+ return out
+ } catch (e) {
+ return notice(recordFailure(ctx, at, e))
+ }
+ })
+ .join('\n')
+ if (shown > 0) ctx.rendered++
+ return html
+}
+
+const cardNotice = (message: string) =>
+ `<div class="callout" data-tone="danger">${escapeHtml(message)}</div>`
+
+export const HERO_STATUSES = ['green', 'yellow', 'red', 'neutral'] as const
+
+function renderHero(o: Record<string, unknown>): string {
+ const eyebrowText = dashText(o.eyebrow)
+ const eyebrow = eyebrowText ? `<div class="hero__eyebrow">${escapeHtml(eyebrowText)}</div>` : ''
+ const status = oneOf(dashText(o.status).trim().toLowerCase(), HERO_STATUSES, 'neutral')
+ const statusLabel = dashText(o.statusLabel) || status.toUpperCase()
+ const statusBadge =
+ o.status !== undefined || dashText(o.statusLabel)
+ ? `<span class="status-badge" data-status="${status}">${escapeHtml(statusLabel)}</span>`
+ : ''
+ const headlineText = dashText(o.headline)
+ const headline = headlineText
+ ? `<p class="hero__headline">${renderInlineMd(headlineText)}</p>`
+ : ''
+ return `
+<header class="hero" data-status="${status}">
+ ${eyebrow}
+ <h1 class="hero__title">${escapeHtml(dashText(o.title))}</h1>
+ ${headline}
+ ${statusBadge}
+</header>`.trim()
+}
+
+function renderSparkline(value: unknown, where: string, ctx: DashRender): string {
+ if (value === undefined || value === null) return ''
+ if (!Array.isArray(value)) {
+ ctx.warnings.push(`${where} must be an array of numbers; the trend was left out.`)
+ return ''
+ }
+ const points = value.map(v => (v === null ? null : coerceNumber(v)))
+ const values = points.filter((v): v is number | null => v !== undefined)
+ if (values.filter(v => v !== null).length < 2) {
+ ctx.warnings.push(`${where} needs at least two numbers to draw a trend; it was left out.`)
+ return ''
+ }
+ if (!ctx.drawSparklines) {
+ ctx.skippedSparklines++
+ return ''
+ }
+ if (values.length < points.length) {
+ ctx.warnings.push(`${where}: entries that were not numbers were left out of the trend.`)
+ }
+ return `<div class="kpi-card__sparkline-wrap"><canvas class="kpi-card__sparkline" id="sparkline-${ctx.sparklines++}" data-spark="${escapeHtmlAttr(
+ JSON.stringify(values)
+ )}"></canvas></div>`
+}
+
+const YEAR_LABEL = /\b(year|years|yr|fy|a[nñ]o|anio)\b/i
+
+function renderKpis(items: unknown, where: string, ctx: DashRender, title?: string): string {
+ const kpis = dashList(items, where, 'KPI objects {label, value}')
+ if (kpis.length === 0) return ''
+ const cards = dashItems(
+ ctx,
+ kpis,
+ where,
+ (item, at) => {
+ const kpi = dashRecord(item, at, 'a KPI object {label, value}')
+ // A year is not grouped: 2026, not 2,026. Only a figure that could be one
+ // is taken for it; revenue per year is still grouped.
+ const year =
+ typeof kpi.value === 'number' &&
+ Number.isInteger(kpi.value) &&
+ kpi.value >= 1000 &&
+ kpi.value <= 9999 &&
+ YEAR_LABEL.test(dashText(kpi.label))
+ const value = year ? String(kpi.value) : dashFigure(kpi.value)
+ if (!value) {
+ throw new Error(`${at}.value is missing; pass the figure to show, e.g. "$1.2M" or 48.`)
+ }
+ const { text, direction } = dashDelta(kpi.delta, kpi.deltaDirection)
+ const sentiment = oneOf(
+ kpi.deltaSentiment,
+ ['good', 'bad', 'neutral'] as const,
+ direction === 'up' ? 'good' : direction === 'down' ? 'bad' : 'neutral'
+ )
+ const delta = deltaHtml(text, direction, sentiment)
+ const accent =
+ kpi.accent === undefined
+ ? ''
+ : ` data-accent="${oneOf(kpi.accent, ['success', 'warning', 'danger', 'neutral'] as const, 'neutral')}"`
+ return `
+<div class="kpi-card"${accent}>
+ <p class="kpi-card__label">${escapeHtml(dashText(kpi.label))}</p>
+ <p class="kpi-card__value">${escapeHtml(value)}</p>
+ ${delta}
+ ${renderSparkline(kpi.sparkline, `${at}.sparkline`, ctx)}
+</div>`.trim()
+ },
+ cardNotice
+ )
+ return titledSection(title, `<section class="kpi-grid">${cards}</section>`)
+}
+
+function renderChartCards(charts: unknown, where: string, ctx: DashRender, title?: string): string {
+ const list = dashList(charts, where, 'chart objects {type, labels, datasets}')
+ if (list.length === 0) return ''
+ const cards = list.map((chart, i) => ctx.charts.card(chart, `${where}[${i}]`)).join('\n')
+ return titledSection(title, `<section class="chart-grid">${cards}</section>`)
+}
+
+const BADGE_COLUMN_TYPES = new Set(['severity', 'priority', 'status'])
+
+function dashSeverityClass(value: unknown): string {
+ const v = String(value ?? '')
+ .trim()
+ .toLowerCase()
+ const map: Record<string, string> = {
+ critical: 'severity-critical',
+ high: 'severity-high',
+ med: 'severity-med',
+ medium: 'severity-med',
+ low: 'severity-low',
+ info: 'severity-info',
+ p0: 'severity-p0',
+ p1: 'severity-p1',
+ p2: 'severity-p2',
+ healthy: 'severity-low',
+ degraded: 'severity-med',
+ down: 'severity-critical',
+ operational: 'severity-low',
+ incident: 'severity-high',
+ }
+ return map[v] ?? ''
+}
+
+function renderTableHtml(t: unknown, where: string, ctx: DashRender, title?: string): string {
+ const table = dashRecord(t, where, 'a table object {headers, rows}')
+ const headers = table.headers
+ if (!Array.isArray(headers) || headers.length === 0) {
+ throw new Error(`${where}.headers must be a non-empty array of column names.`)
+ }
+ const colTypes = isDashRecord(table.columnTypes) ? table.columnTypes : {}
+ const headerNames = headers.map(headerText)
+ const headerHtml = headerNames.map(h => `<th>${softBreaks(escapeHtml(h))}</th>`).join('')
+ const rows = fitRowsToHeaders(
+ normalizeTableRows(table.rows, headers, where, ctx.warnings),
+ headers.length,
+ where,
+ ctx
+ )
+ let structured = 0
+ const bodyHtml = rows
+ .map(row => {
+ const cells = row
+ .map((cell, c) => {
+ const colType = colTypes[c] ?? colTypes[headerNames[c]]
+ if (cell !== null && typeof cell === 'object') structured++
+ const text = tableCellText(cell)
+ const cls = BADGE_COLUMN_TYPES.has(String(colType)) ? dashSeverityClass(text) : ''
+ return cls
+ ? `<td><span class="severity-badge ${cls}">${escapeHtml(text)}</span></td>`
+ : `<td>${softBreaks(renderInlineMd(text))}</td>`
+ })
+ .join('')
+ return `<tr>${cells}</tr>`
+ })
+ .join('\n')
+
+ if (structured > 0) {
+ ctx.warnings.push(
+ `${where}: ${structured} cell(s) held an object or a list and are shown as text; ` +
+ 'send one value per cell.'
+ )
+ }
+ return titledSection(
+ title ?? (dashText(table.title) || undefined),
+ `
+<div class="data-table-wrap">
+ <table class="data-table${headers.length > WIDE_TABLE_COLUMNS ? ' data-table--wide' : ''}">
+ <thead><tr>${headerHtml}</tr></thead>
+ <tbody>${bodyHtml}</tbody>
+ </table>
+</div>`.trimEnd()
+ )
+}
+
+/**
+ * A table cell as text. Numbers print as written, without the float noise of
+ * 0.1 + 0.2 and without grouping, since a table column may hold years or IDs.
+ */
+function tableCellText(cell: unknown): string {
+ if (typeof cell === 'number') {
+ return Number.isInteger(cell) ? String(cell) : String(Number(cell.toPrecision(12)))
+ }
+ if (Array.isArray(cell)) return cell.map(tableCellText).join(', ')
+ if (cell !== null && typeof cell === 'object') return JSON.stringify(cell)
+ return dashText(cell)
+}
+
+/** Above this many columns a printed table breaks words anywhere so every column fits the page. */
+const WIDE_TABLE_COLUMNS = 8
+
+const SOFT_BREAK_AFTER = new Set(['&#x2F;', '.', '-', '_', '?', '&amp;', '=', ',', ':'])
+
+/**
+ * `html` with a line-break opportunity inside each long unbroken run of text,
+ * after punctuation or every 10 characters, so a URL or an ID wraps instead of
+ * widening its column. Words of ordinary length keep their width.
+ */
+function softBreaks(html: string): string {
+ return html.replace(/(<[^>]*>)|((?:&[#\w]+;|[^\s<&])+)/gu, (match, tag: string | undefined) => {
+ if (tag) return match
+ const units = match.match(/&[#\w]+;|[^]/gu) ?? []
+ if (units.length < 16) return match
+ let out = ''
+ let run = 0
+ units.forEach((unit, i) => {
+ out += unit
+ run++
+ if (i < units.length - 1 && (SOFT_BREAK_AFTER.has(unit) || run >= 10)) {
+ out += '<wbr>'
+ run = 0
+ }
+ })
+ return out
+ })
+}
+
+/** Each row cut or padded to one cell per header, reporting cells that held a value and were cut. */
+function fitRowsToHeaders(
+ rows: unknown[][],
+ width: number,
+ where: string,
+ ctx: DashRender
+): unknown[][] {
+ let padded = 0
+ const cut: string[] = []
+ const fitted = rows.map((row, r) => {
+ if (row.length < width) {
+ padded++
+ return [...row, ...Array<string>(width - row.length).fill('')]
+ }
+ if (row.slice(width).some(cell => dashText(cell).trim() !== '')) {
+ cut.push(
+ `${where}.rows[${r}] has ${row.length} cells for ${width} headers; the extra ` +
+ `${row.length - width} ${row.length - width === 1 ? 'was' : 'were'} left out.`
+ )
+ }
+ return row.slice(0, width)
+ })
+ if (cut.length > 0) {
+ const more = cut.length > 1 ? ` ${cut.length - 1} more row(s) had extra cells too.` : ''
+ ctx.warnings.push(`${cut[0]}${more} Add headers for them or drop them.`)
+ }
+ if (padded > 0) {
+ ctx.warnings.push(
+ `${where}: ${padded} row(s) have fewer cells than the ${width} headers and end in empty cells.`
+ )
+ }
+ return fitted
+}
+
+export const SECTION_TYPES = ['narrative', 'bullets', 'callout', 'code'] as const
+export const CALLOUT_TONES = ['info', 'success', 'warning', 'danger'] as const
+
+function renderSectionHtml(s: unknown, where: string): string {
+ const section = dashRecord(s, where, 'a section object {type, content}')
+ if (section.type !== undefined && !SECTION_TYPES.includes(section.type as never)) {
+ throw new Error(`${where}.type must be one of: ${SECTION_TYPES.join(', ')}.`)
+ }
+ const type = oneOf(section.type, SECTION_TYPES, 'narrative')
+ const content = dashTextList(section.content, `${where}.content`)
+ const titleText = dashText(section.title)
+ const title = titleText ? `<h2 class="section__title">${escapeHtml(titleText)}</h2>` : ''
+ let body: string
+ if (type === 'narrative') {
+ body = `<div class="narrative">${content.map(p => `<p>${renderInlineMd(p)}</p>`).join('\n')}</div>`
+ } else if (type === 'bullets') {
+ body = `<ul class="bullets">${content.map(b => `<li>${renderInlineMd(b)}</li>`).join('')}</ul>`
+ } else if (type === 'callout') {
+ const tone = oneOf(section.tone, CALLOUT_TONES, 'info')
+ body = `<div class="callout" data-tone="${tone}">${renderInlineMd(content.join('\n'))}</div>`
+ } else {
+ const language = dashText(section.language)
+ const lang = language ? `<div class="code-block__lang">${escapeHtml(language)}</div>` : ''
+ body = `<div class="code-block">${lang}<pre><code>${escapeHtml(content.join('\n'))}</code></pre></div>`
+ }
+ return `<section class="section">${title}${body}</section>`
+}
+
+const SERVICE_STATUSES = ['healthy', 'degraded', 'down', 'maintenance'] as const
+
+/** Status words models use, by the card color they mean. */
+/** The entry `words` has for `text`, ignoring case; never one inherited from Object. */
+function ownWord<T>(words: Partial<Record<string, T>>, text: string): T | undefined {
+ const key = text.toLowerCase()
+ return Object.hasOwn(words, key) ? words[key] : undefined
+}
+
+const SERVICE_STATUS_WORDS: Partial<Record<string, (typeof SERVICE_STATUSES)[number]>> = {
+ healthy: 'healthy',
+ ok: 'healthy',
+ up: 'healthy',
+ operational: 'healthy',
+ online: 'healthy',
+ green: 'healthy',
+ degraded: 'degraded',
+ warning: 'degraded',
+ partial: 'degraded',
+ yellow: 'degraded',
+ down: 'down',
+ outage: 'down',
+ offline: 'down',
+ failed: 'down',
+ red: 'down',
+ maintenance: 'maintenance',
+}
+
+function renderServiceHealthGrid(
+ services: unknown,
+ where: string,
+ ctx: DashRender,
+ title?: string
+): string {
+ const list = dashList(services, where, 'service objects {name, status}')
+ if (list.length === 0) return ''
+ const cards = dashItems(
+ ctx,
+ list,
+ where,
+ (item, at) => {
+ const s = dashRecord(item, at, 'a service object {name, status}')
+ const name = dashText(s.name)
+ if (!name) throw new Error(`${at}.name is missing; pass the service name.`)
+ const statusText = dashText(s.status).trim() || 'unknown'
+ const status = ownWord(SERVICE_STATUS_WORDS, statusText) ?? 'unknown'
+ if (status === 'unknown' && statusText.toLowerCase() !== 'unknown') {
+ ctx.warnings.push(
+ `${at}.status ${JSON.stringify(statusText)} is not healthy, degraded, down or ` +
+ 'maintenance, so the card is grey.'
+ )
+ }
+ const { text, direction } = dashDelta(s.delta, s.deltaDirection)
+ const sentiment = direction === 'up' ? 'good' : direction === 'down' ? 'bad' : 'neutral'
+ const delta = deltaHtml(text, direction, sentiment)
+ const metric = dashFigure(s.metric)
+ return `
+<div class="health-card" data-status="${status}">
+ <div class="health-card__head">
+ <span class="health-card__dot"></span>
+ <h3 class="health-card__name">${escapeHtml(name)}</h3>
+ </div>
+ <p class="health-card__status">${escapeHtml(statusText.toUpperCase())}</p>
+ ${metric ? `<p class="health-card__metric">${escapeHtml(metric)}</p>` : ''}
+ ${delta}
+</div>`.trim()
+ },
+ cardNotice
+ )
+ return titledSection(title, `<section class="health-grid">${cards}</section>`)
+}
+
+const INCIDENT_SEVERITIES = ['critical', 'high', 'med', 'low', 'info'] as const
+
+/** Severity words models use, by the color they take; p0-p2 match the table badges. */
+const SEVERITY_WORDS: Partial<Record<string, (typeof INCIDENT_SEVERITIES)[number]>> = {
+ critical: 'critical',
+ p0: 'critical',
+ high: 'high',
+ major: 'high',
+ p1: 'high',
+ med: 'med',
+ medium: 'med',
+ moderate: 'med',
+ low: 'low',
+ minor: 'low',
+ p2: 'low',
+ info: 'info',
+}
+
+function renderIncidentsTimeline(
+ items: unknown,
+ where: string,
+ ctx: DashRender,
+ title?: string
+): string {
+ const list = dashList(items, where, 'incident objects {time, title}')
+ if (list.length === 0) return ''
+ const html = dashItems(
+ ctx,
+ list,
+ where,
+ (item, at) => {
+ const it = dashRecord(item, at, 'an incident object {time, title}')
+ const time = dashText(it.time)
+ const heading = dashText(it.title)
+ if (!time && !heading) {
+ throw new Error(
+ `${at} needs a time and a title, e.g. {"time": "10:42", "title": "API errors"}.`
+ )
+ }
+ const given = dashText(it.severity).trim()
+ const sev = ownWord(SEVERITY_WORDS, given) ?? 'info'
+ if (given && !ownWord(SEVERITY_WORDS, given)) {
+ ctx.warnings.push(
+ `${at}.severity ${JSON.stringify(given)} is not critical, high, medium, low or info, ` +
+ 'so it is shown in the info color.'
+ )
+ }
+ const resolvedAt = dashText(it.resolvedAt)
+ const resolved = resolvedAt
+ ? `<span class="timeline-item__resolved">resolved ${escapeHtml(resolvedAt)}</span>`
+ : `<span class="timeline-item__open">open</span>`
+ const description = dashText(it.description)
+ const desc = description
+ ? `<p class="timeline-item__desc">${renderInlineMd(description)}</p>`
+ : ''
+ return `
+<li class="timeline-item" data-severity="${sev}">
+ <div class="timeline-item__time">${escapeHtml(time)}</div>
+ <div class="timeline-item__body">
+ <div class="timeline-item__head">
+ <span class="severity-badge severity-${sev}">${escapeHtml((given || sev).toUpperCase())}</span>
+ <h4 class="timeline-item__title">${escapeHtml(heading)}</h4>
+ ${resolved}
+ </div>
+ ${desc}
+ </div>
+</li>`.trim()
+ },
+ message =>
+ `<li class="timeline-item"><div class="timeline-item__time"></div>${cardNotice(message)}</li>`
+ )
+ return titledSection(title, `<ol class="timeline">${html}</ol>`)
+}
+
+/** meta.date as shown; a number of 10+ digits is a Unix timestamp (seconds or ms), a shorter one a year. */
+function footerDate(value: unknown): string {
+ const long = { year: 'numeric', month: 'long', day: 'numeric' } as const
+ if (typeof value === 'number' && Number.isInteger(value) && Math.abs(value) >= 1e9) {
+ const ms = Math.abs(value) < 1e11 ? value * 1000 : value
+ return new Date(ms).toLocaleDateString('en-US', { ...long, timeZone: 'UTC' })
+ }
+ return dashText(value) || new Date().toLocaleDateString('en-US', long)
+}
+
+function renderDashboardFooter(meta: unknown, branding: DashboardBranding): string {
+ const m: Record<string, unknown> = isDashRecord(meta) ? meta : {}
+ const companyName = dashText(branding.companyName)
+ const left = companyName
+ ? `<span class="dash-footer__brand">${escapeHtml(companyName)}</span>`
+ : ''
+ const right = [
+ dashText(branding.footerText),
+ dashText(m.author),
+ dashText(m.runId),
+ footerDate(m.date),
+ ]
+ .filter(part => part.trim() !== '')
+ .map(escapeHtml)
+ .join(' · ')
+ return `<footer class="dash-footer">${left}<span>${right}</span></footer>`
+}
+
+interface DashWrapperOptions {
+ title: string
+ cssSource?: string
+ chartJsSource?: string
+ chartInit?: string
+ body: string
+}
+
+function htmlWrapper(o: DashWrapperOptions): string {
+ const styleBlock = o.cssSource ? `<style>${o.cssSource}</style>` : ''
+ const scripts = o.chartInit
+ ? `<script>${o.chartJsSource ?? ''}</script>\n<script>${o.chartInit}</script>`
+ : ''
+ return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(o.title)}</title>
+${styleBlock}
+</head>
+<body>
+<main class="dashboard">
+${o.body}
+</main>
+${scripts}
+</body>
+</html>`
+}
+
+// ─── Chart.js bundle loader (cached) ────────────────────────────────
+
+let cachedChartJsBundle: string | undefined
+
+/**
+ * The Chart.js UMD bundle. chart.js exports only ".", "./auto" and
+ * "./helpers", so resolving "chart.js/dist/chart.umd.js" throws
+ * ERR_PACKAGE_PATH_NOT_EXPORTED; the entry point resolves, and the bundle sits
+ * beside it in dist/.
+ */
+export function loadChartJsBundle(): string {
+ if (cachedChartJsBundle) return cachedChartJsBundle
+ const bundle = path.join(path.dirname(require.resolve('chart.js')), 'chart.umd.js')
+ cachedChartJsBundle = fs.readFileSync(bundle, 'utf-8')
+ return cachedChartJsBundle
+}
+
+// ─── Templates ──────────────────────────────────────────────────────
+
+type DashboardTemplateName =
+ | 'executive-brief'
+ | 'operations-pulse'
+ | 'financial-review'
+ | 'technical-report'
+ | 'custom'
+
+type DashData = Record<string, unknown>
+
+// The fields are named rather than spread: a spread reads every key, which
+// would hide the ones nothing draws from the "Ignored arguments" note.
+function heroOf(data: DashData, eyebrowFallback?: unknown): string {
+ return renderHero({
+ title: data.title,
+ headline: data.headline,
+ status: data.status,
+ statusLabel: data.statusLabel,
+ eyebrow: data.eyebrow ?? eyebrowFallback,
+ })
+}
+
+function tablesOf(data: DashData, ctx: DashRender): string {
+ return dashPart(ctx, 'data.tables', false, () =>
+ dashList(data.tables, 'data.tables', 'table objects {headers, rows}')
+ .map((t, i) => {
+ const where = `data.tables[${i}]`
+ return dashPart(ctx, where, true, () => renderTableHtml(t, where, ctx))
+ })
+ .join('\n')
+ )
+}
+
+function sectionsOf(data: DashData, ctx: DashRender): string {
+ return dashPart(ctx, 'data.sections', false, () =>
+ dashList(data.sections, 'data.sections', 'section objects {type, content}')
+ .map((s, i) => {
+ const where = `data.sections[${i}]`
+ return dashPart(ctx, where, true, () => renderSectionHtml(s, where))
+ })
+ .join('\n')
+ )
+}
+
+function kpisOf(data: DashData, ctx: DashRender): string {
+ return dashPart(ctx, 'data.kpis', false, () => renderKpis(data.kpis, 'data.kpis', ctx))
+}
+
+function chartsOf(data: DashData, ctx: DashRender, title: string | undefined): string {
+ return dashPart(ctx, 'data.charts', false, () =>
+ renderChartCards(data.charts, 'data.charts', ctx, title)
+ )
+}
+
+const DASHBOARD_TEMPLATES: Record<
+ DashboardTemplateName,
+ (data: DashData, ctx: DashRender) => string[]
+> = {
+ 'executive-brief': (data, ctx) => [
+ heroOf(data),
+ kpisOf(data, ctx),
+ chartsOf(data, ctx, 'Visual Trends'),
+ tablesOf(data, ctx),
+ sectionsOf(data, ctx),
+ ],
+ 'operations-pulse': (data, ctx) => [
+ heroOf(data),
+ dashPart(ctx, 'data.services', false, () =>
+ renderServiceHealthGrid(data.services, 'data.services', ctx, 'Service Health')
+ ),
+ kpisOf(data, ctx),
+ dashPart(ctx, 'data.incidents', false, () =>
+ renderIncidentsTimeline(data.incidents, 'data.incidents', ctx, 'Incident Timeline')
+ ),
+ chartsOf(data, ctx, 'Performance Trends'),
+ tablesOf(data, ctx),
+ sectionsOf(data, ctx),
+ ],
+ 'financial-review': (data, ctx) => {
+ const hasHero = data.heroChart !== undefined && data.heroChart !== null
+ return [
+ heroOf(data, data.period),
+ kpisOf(data, ctx),
+ hasHero
+ ? dashPart(
+ ctx,
+ 'data.heroChart',
+ false,
+ () =>
+ `<section class="chart-stack">${ctx.charts.card(data.heroChart, 'data.heroChart', { tall: true })}</section>`
+ )
+ : '',
+ chartsOf(data, ctx, hasHero ? 'Breakdowns' : 'Visual Trends'),
+ tablesOf(data, ctx),
+ sectionsOf(data, ctx),
+ ]
+ },
+ 'technical-report': (data, ctx) => [
+ heroOf(data),
+ kpisOf(data, ctx),
+ sectionsOf(data, ctx),
+ tablesOf(data, ctx),
+ chartsOf(data, ctx, 'Charts'),
+ ],
+ custom: (data, ctx) => {
+ const blocks = dashList(data.blocks, 'data.blocks', 'block objects')
+ if (blocks.length === 0) {
+ throw new Error(
+ "template 'custom' needs data.blocks: a non-empty array of blocks such as " +
+ '{"type": "kpis", "items": [{"label": "Revenue", "value": "$1.2M"}]}.'
+ )
+ }
+ return blocks.map((b, idx) => renderBlock(b, `data.blocks[${idx}]`, ctx))
+ },
+}
+
+// ─── Custom template (composable blocks) ────────────────────────────
+
+export const BLOCK_TYPES = [
+ 'hero',
+ 'kpis',
+ 'chart',
+ 'charts-grid',
+ 'table',
+ 'narrative',
+ 'bullets',
+ 'code',
+ 'callout',
+ 'incidents',
+ 'service-health',
+ 'divider',
+ 'spacer',
+] as const
+
+/** Blocks that are content of their own; charts and card groups count their entries. */
+const COUNTED_BLOCKS = new Set(['table', 'narrative', 'bullets', 'code', 'callout'])
+
+function isEmptyList(value: unknown): boolean {
+ return value === undefined || value === null || (Array.isArray(value) && value.length === 0)
+}
+
+/** The list field of each list block, and the other name models give it. */
+const BLOCK_LISTS: Record<string, { field: 'items' | 'services'; alias: string; noun: string }> = {
+ kpis: { field: 'items', alias: 'kpis', noun: 'cards' },
+ 'charts-grid': { field: 'items', alias: 'charts', noun: 'charts' },
+ incidents: { field: 'items', alias: 'incidents', noun: 'incidents' },
+ 'service-health': { field: 'services', alias: 'items', noun: 'services' },
+}
+
+/** Whether `block` gives its list under the other name only. */
+function listUnderAlias(block: Record<string, unknown>): boolean {
+ const list = BLOCK_LISTS[String(block.type)]
+ return !!list && isEmptyList(block[list.field]) && !isEmptyList(block[list.alias])
+}
+
+/**
+ * The entries of a list block, from its field or from the other name models
+ * give it. A block with no entries throws, so it is reported rather than left
+ * off the page.
+ */
+function blockList(
+ block: Record<string, unknown>,
+ where: string,
+ ctx: DashRender
+): { value: unknown; at: string } {
+ const { field, alias, noun } = BLOCK_LISTS[String(block.type)]
+ if (listUnderAlias(block)) {
+ ctx.warnings.push(`${where}: the list was read from ${alias}; name it ${field}.`)
+ return { value: block[alias], at: `${where}.${alias}` }
+ }
+ if (isEmptyList(block[field])) {
+ throw new Error(
+ `${where}.${field} is missing or empty; a '${String(block.type)}' block lists its ${noun} in ${field}.`
+ )
+ }
+ return { value: block[field], at: `${where}.${field}` }
+}
+
+function renderBlock(b: unknown, where: string, ctx: DashRender): string {
+ const type = isDashRecord(b) ? b.type : undefined
+ return dashPart(ctx, where, COUNTED_BLOCKS.has(String(type)), () => {
+ const block = dashRecord(b, where, 'a block object with a type')
+ const title = dashText(block.title) || undefined
+ switch (block.type) {
+ case 'hero':
+ return renderHero(block)
+ case 'kpis': {
+ const list = blockList(block, where, ctx)
+ return renderKpis(list.value, list.at, ctx, title)
+ }
+ case 'chart':
+ if (!isDashRecord(block.spec)) {
+ throw new Error(
+ `${where} is a 'chart' block and needs spec: {type, labels, datasets}; ` +
+ `received ${describeDashValue(block.spec)}.`
+ )
+ }
+ return `<section class="chart-grid">${ctx.charts.card(block.spec, `${where}.spec`, { title })}</section>`
+ case 'charts-grid': {
+ const list = blockList(block, where, ctx)
+ return renderChartCards(list.value, list.at, ctx, title)
+ }
+ case 'table':
+ return renderTableHtml(block.spec, `${where}.spec`, ctx, title)
+ case 'narrative':
+ case 'code':
+ case 'callout':
+ return renderSectionHtml(
+ {
+ type: block.type,
+ content: block.content,
+ language: block.language,
+ tone: block.tone,
+ title,
+ },
+ where
+ )
+ case 'bullets':
+ return renderSectionHtml(
+ { type: 'bullets', title, content: block.items ?? block.content },
+ block.items === undefined ? where : `${where}.items`
+ )
+ case 'incidents': {
+ const list = blockList(block, where, ctx)
+ return renderIncidentsTimeline(list.value, list.at, ctx, title)
+ }
+ case 'service-health': {
+ const list = blockList(block, where, ctx)
+ return renderServiceHealthGrid(list.value, list.at, ctx, title)
+ }
+ case 'divider':
+ return '<hr class="dashboard-divider"/>'
+ case 'spacer':
+ return `<div class="dashboard-spacer dashboard-spacer--${oneOf(block.size, ['sm', 'md', 'lg'] as const, 'md')}"></div>`
+ default:
+ throw new Error(
+ `${where}.type ${block.type === undefined ? 'is missing' : `"${dashText(block.type)}" is not a block type`}; ` +
+ `use one of: ${BLOCK_TYPES.join(', ')}.`
+ )
+ }
+ })
+}
+
+// ─── Public entry point ─────────────────────────────────────────────
+
+interface DashboardRenderOptions {
+ template: DashboardTemplateName
+ data: DashData
+ theme: ThemeName
+ /** Kept whatever the viewer's color scheme; when absent the page follows it. */
+ defaultThemeMode?: 'light' | 'dark'
+ branding: DashboardBranding
+ inlineChartJs: boolean
+}
+
+function renderDashboard(opts: DashboardRenderOptions): { html: string; ctx: DashRender } {
+ const theme = DASHBOARD_THEMES[opts.theme] ?? DASHBOARD_THEMES.default
+ const warnings: string[] = []
+ const failures: string[] = []
+ const ctx: DashRender = {
+ charts: new DashboardCharts(opts.inlineChartJs, { warnings, failures }),
+ warnings,
+ sparklines: 0,
+ drawSparklines: opts.inlineChartJs,
+ skippedSparklines: 0,
+ rendered: 0,
+ failures,
+ }
+ const parts = (DASHBOARD_TEMPLATES[opts.template] ?? DASHBOARD_TEMPLATES['executive-brief'])(
+ opts.data,
+ ctx
+ )
+ const body = [...parts, renderDashboardFooter(opts.data.meta, opts.branding)].join('\n')
+ const needsCharts = ctx.charts.specs.length > 0 || ctx.sparklines > 0
+ const html = htmlWrapper({
+ title: dashText(opts.data.title),
+ cssSource: buildDashboardCss(theme, opts.defaultThemeMode),
+ chartJsSource: needsCharts ? loadChartJsBundle() : undefined,
+ chartInit: needsCharts ? dashboardScript(safeJsonForScript(ctx.charts.specs)) : undefined,
+ body,
+ })
+ return { html, ctx }
+}
+
+/** Fields each template reads beyond the shared ones, to flag data another template would need. */
+const TEMPLATE_ONLY_FIELDS: Record<string, DashboardTemplateName[]> = {
+ services: ['operations-pulse'],
+ incidents: ['operations-pulse'],
+ heroChart: ['financial-review'],
+ period: ['financial-review'],
+ blocks: ['custom'],
+}
+const FIXED_TEMPLATE_FIELDS = [
+ 'eyebrow',
+ 'headline',
+ 'status',
+ 'statusLabel',
+ 'kpis',
+ 'charts',
+ 'tables',
+ 'sections',
+]
+
+/** Data the chosen template does not show, which the model would otherwise believe is on the page. */
+function ignoredDashboardFields(template: DashboardTemplateName, data: DashData): string[] {
+ const ignored = Object.entries(TEMPLATE_ONLY_FIELDS)
+ .filter(([field, templates]) => data[field] !== undefined && !templates.includes(template))
+ .map(([field, templates]) => `data.${field} is only shown by template '${templates[0]}'`)
+ if (template === 'custom') {
+ for (const field of FIXED_TEMPLATE_FIELDS) {
+ if (data[field] !== undefined) {
+ ignored.push(`data.${field} is not read by template 'custom' (put it in a block)`)
+ }
+ }
+ }
+ return ignored.map(line => `${line}; it was left out.`)
+}
+
+// ─── generate_dashboard tool definition ─────────────────────────────
+
+export async function runGenerateDashboard(
+ args: Record<string, unknown>,
+ outputDir: string
+): Promise<InternalToolResult> {
+ try {
+ const filename = outputFilename(args.filename, 'html', 'dashboard')
+ const data = args.data
+ if (!isDashRecord(data) || !dashText(data.title).trim()) {
+ return {
+ success: false,
+ error:
+ 'data.title is required: pass data as an object with the dashboard heading, ' +
+ 'e.g. {"title": "Weekly review", "kpis": [...]}.',
+ }
+ }
+ const template = oneOf(args.template, DASHBOARD_TEMPLATE_NAMES, 'executive-brief')
+ const inlineChartJs = args.inlineChartJs !== false
+ const { html, ctx } = renderDashboard({
+ template,
+ data,
+ theme: oneOf(args.theme, ['default', 'corporate', 'warm', 'alert'] as const, 'default'),
+ defaultThemeMode:
+ args.defaultThemeMode === 'light' || args.defaultThemeMode === 'dark'
+ ? args.defaultThemeMode
+ : undefined,
+ inlineChartJs,
+ branding: isDashRecord(args.branding) ? args.branding : {},
+ })
+
+ const produced = ctx.rendered + ctx.charts.drawn
+ if (produced === 0 && ctx.failures.length > 0) {
+ return {
+ success: false,
+ error: `Nothing on the dashboard could be shown, so no file was written. ${ctx.failures.join(' ')}`,
+ }
+ }
+ const warnings = [
+ ...ctx.failures.map(f => `${f} A notice shows in its place.`),
+ ...ignoredDashboardFields(template, data),
+ ...ctx.warnings,
+ ]
+ if (produced === 0) {
+ warnings.push(
+ 'The dashboard only shows its title: pass kpis, charts, tables or sections ' +
+ "(blocks for template 'custom')."
+ )
+ }
+ if (!inlineChartJs && (ctx.charts.drawn > 0 || ctx.skippedSparklines > 0)) {
+ warnings.push(
+ 'inlineChartJs is false, so charts are shown as tables of their values and ' +
+ 'sparklines are left out.'
+ )
+ }
+
+ ensureDir(outputDir)
+ const target = claimOutputFile(outputDir, filename)
+ enforceQuota(outputDir, Buffer.byteLength(html, 'utf-8'), replacedBytes(target))
+ fs.writeFileSync(target.filePath, html, 'utf-8')
+
+ return artifactResult(target, 'html', { warnings })
+ } catch (err) {
+ return { success: false, error: err instanceof Error ? err.message : String(err) }
+ }
+}
+
+export const DASHBOARD_TEMPLATE_NAMES = [
+ 'executive-brief',
+ 'operations-pulse',
+ 'financial-review',
+ 'technical-report',
+ 'custom',
+] as const
diff --git a/mcp-host/src/workflow/documentChrome.ts b/mcp-host/src/workflow/documentChrome.ts
new file mode 100644
index 000000000..5cbbe9850
--- /dev/null
+++ b/mcp-host/src/workflow/documentChrome.ts
@@ -0,0 +1,103 @@
+/** Branding, footer lines and the empty-document note shared by the PDF and DOCX generators. */
+import { htmlToPlainLines, htmlToPlainText } from './inlineMarkup'
+import type { UnitMeasure } from './pdfTables'
+import { LINE_FILL } from './pdfText'
+
+/**
+ * Branding as it prints: HTML in the company name and footer read as text,
+ * the footer keeping its lines.
+ */
+export function printedBranding(raw: unknown): {
+ logoPath?: string
+ companyName?: string
+ footerText?: string
+} {
+ const branding = (raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {}) as Record<
+ string,
+ unknown
+ >
+ const text = (value: unknown) =>
+ value === undefined || value === null ? undefined : String(value)
+ const companyName = text(branding.companyName)
+ const footerText = text(branding.footerText)
+ // Named rather than spread, so a key nothing prints is reported as ignored.
+ return {
+ ...(branding.logoPath !== undefined ? { logoPath: branding.logoPath as string } : {}),
+ ...(companyName !== undefined ? { companyName: htmlToPlainText(companyName) } : {}),
+ ...(footerText !== undefined ? { footerText: htmlToPlainLines(footerText) } : {}),
+ }
+}
+
+/** Note for a PDF or DOCX written with nothing in it. */
+export const EMPTY_DOCUMENT_NOTE =
+ 'The document is empty: body has no text, and no title, table or image was given. ' +
+ 'Pass the text to write as body.'
+
+/** Footer lines that fit once the bottom margin has grown to hold them. */
+export const PDF_MAX_FOOTER_LINES = 6
+
+export const PDF_FOOTER_SIZE = 9
+
+/** More characters than a header or footer line ever holds at the running size. */
+export const RUNNING_LINE_CHARS = 400
+
+/** The longest start of `chars` that fits `fits`, at least one character. */
+export function longestFitting(chars: string[], fits: (text: string) => boolean): number {
+ let lo = 1
+ let hi = chars.length
+ while (lo < hi) {
+ const mid = Math.ceil((lo + hi) / 2)
+ if (fits(chars.slice(0, mid).join(''))) lo = mid
+ else hi = mid - 1
+ }
+ return lo
+}
+
+/**
+ * The footer text as the lines it will take, cut to what the bottom margin
+ * can hold, with a note when anything is cut.
+ */
+export function footerLines(
+ text: string,
+ width: number,
+ measure: UnitMeasure,
+ warnings: string[]
+): string[] {
+ // Lines break where the typesetter breaks them, or the footer outgrows its margin.
+ const fits = (s: string) => measure(s, false) * PDF_FOOTER_SIZE <= width * LINE_FILL
+ // Far more characters than a footer line holds, so a huge word is never measured whole.
+ const tooWide = (s: string) => s.length > RUNNING_LINE_CHARS || !fits(s)
+ const lines: string[] = []
+ // Counting stops one line past the most the footer holds.
+ const full = () => lines.length > PDF_MAX_FOOTER_LINES
+ for (const source of text.split('\n')) {
+ let line = ''
+ for (const word of source.split(/(\s+)/)) {
+ if (full()) break
+ if (line.trim() && tooWide(line + word)) {
+ lines.push(line.trimEnd())
+ line = word.trimStart()
+ } else {
+ line += word
+ }
+ // A word wider than the line, such as a long URL, takes as many lines as it fills.
+ while (!full() && tooWide(line)) {
+ const head = Array.from(line.slice(0, RUNNING_LINE_CHARS))
+ if (head.length <= 1) break
+ const piece = head.slice(0, longestFitting(head, fits)).join('')
+ lines.push(piece)
+ line = line.slice(piece.length)
+ }
+ }
+ if (full()) break
+ lines.push(line.trimEnd())
+ }
+ if (!full()) return lines
+ warnings.push(
+ `branding.footerText takes more than ${PDF_MAX_FOOTER_LINES} lines, the most that fit in the ` +
+ 'footer, so the rest was cut. Keep it to a line or two.'
+ )
+ const kept = lines.slice(0, PDF_MAX_FOOTER_LINES)
+ kept[kept.length - 1] = `${kept[kept.length - 1]}...`
+ return kept
+}
diff --git a/mcp-host/src/workflow/docxGenerator.ts b/mcp-host/src/workflow/docxGenerator.ts
new file mode 100644
index 000000000..deacd2dd0
--- /dev/null
+++ b/mcp-host/src/workflow/docxGenerator.ts
@@ -0,0 +1,315 @@
+/** The DOCX generator (clerum__generate_docx): markdown body, tables and images built with docx. */
+import {
+ AlignmentType,
+ Document as DocxDocument,
+ Footer as DocxFooter,
+ Header as DocxHeader,
+ Table as DocxTable,
+ HeadingLevel,
+ Packer,
+ PageNumber,
+ PageOrientation,
+ Paragraph,
+ TabStopType,
+ TextRun,
+} from 'docx'
+import * as fs from 'fs'
+import { config } from '../config'
+import {
+ artifactResult,
+ claimOutputFile,
+ enforceQuota,
+ ensureDir,
+ outputFilename,
+ replacedBytes,
+} from './artifactOutput'
+import { EMPTY_DOCUMENT_NOTE, footerLines, printedBranding } from './documentChrome'
+import { type DocxImagePlacement, docxImageParagraph } from './docxImages'
+import { textRuns } from './docxInline'
+import { bodyHasText, bodyToDocxChildren } from './docxMarkdown'
+import {
+ DOCX_COMPLEX_FONT,
+ DOCX_LATIN_FONT,
+ documentEastAsianScript,
+ docxDirection,
+ eastAsianScript,
+} from './docxScript'
+import {
+ DOCX_CONTENT_WIDTH_TWIPS,
+ DOCX_LANDSCAPE_CONTENT_WIDTH_TWIPS,
+ DOCX_PALETTES,
+ DocxListNumbering,
+ docxHex,
+} from './docxStyle'
+import { buildDocxTable, docxSections } from './docxTable'
+import { htmlToPlainText } from './inlineMarkup'
+import { normalizeTableRows } from './tableRows'
+import type { InternalToolResult } from './types'
+
+/**
+ * Widest a DOCX image is drawn, in pixels at 96 dpi; the page leaves about 601
+ * between its margins.
+ */
+const DOCX_MAX_IMAGE_WIDTH = 560
+const DOCX_MAX_IMAGE_HEIGHT = 380
+
+/** Largest logo drawn above the title, in pixels. */
+const DOCX_LOGO_BOX = { width: 160, height: 60 }
+
+/** Footer lines kept, as in the PDF. */
+const DOCX_MAX_FOOTER_LINES = 6
+
+export const DOCX_IMAGE_FILE_DESCRIPTION =
+ "File name in the output folder, as returned by clerum__generate_chart (e.g. 'sales.png'). " +
+ 'PNG, JPEG, GIF, WebP or SVG.'
+
+interface DocxBranding {
+ companyName?: string
+ logoPath?: string
+ footerText?: string
+}
+
+interface DocxImageArg {
+ width?: number
+ height?: number
+ alignment?: string
+}
+
+interface DocxTableArg {
+ headers?: unknown
+ rows?: unknown
+ layout?: unknown
+}
+
+export async function runGenerateDocx(
+ args: Record<string, unknown>,
+ outputDir: string
+): Promise<InternalToolResult> {
+ try {
+ const filename = outputFilename(args.filename, 'docx', 'output')
+ const title = args.title ? htmlToPlainText(String(args.title)) : undefined
+ const headline = args.headline ? htmlToPlainText(String(args.headline)) : undefined
+ const body = String(args.body ?? '')
+ const palette = DOCX_PALETTES[String(args.palette ?? 'default')] ?? DOCX_PALETTES.default
+ const branding: DocxBranding = printedBranding(args.branding)
+ const images: unknown[] = Array.isArray(args.images) ? args.images : []
+ const tables: unknown[] = Array.isArray(args.tables) ? args.tables : []
+ const warnings: string[] = []
+ const numbering = new DocxListNumbering()
+ const imageBox = { width: DOCX_MAX_IMAGE_WIDTH, height: DOCX_MAX_IMAGE_HEIGHT }
+ let embedded = 0
+ let imageLeftOut = false
+ const embed = (
+ ref: unknown,
+ label: string,
+ box: { width: number; height: number },
+ placement: DocxImagePlacement
+ ): Paragraph | undefined => {
+ const paragraph = docxImageParagraph(ref, outputDir, box, placement, warnings, label)
+ if (paragraph) embedded++
+ else imageLeftOut = true
+ return paragraph
+ }
+
+ const children: (Paragraph | DocxTable)[] = []
+
+ if (branding.logoPath) {
+ const logo = embed(branding.logoPath, 'branding.logoPath', DOCX_LOGO_BOX, {
+ spacing: { after: 160 },
+ })
+ if (logo) children.push(logo)
+ }
+ if (title) {
+ children.push(
+ new Paragraph({
+ ...docxDirection(title),
+ heading: HeadingLevel.TITLE,
+ spacing: { after: 120 },
+ children: textRuns(
+ title,
+ { bold: true, color: docxHex(palette.primary), size: 48 },
+ eastAsianScript(title)
+ ),
+ })
+ )
+ }
+ if (headline) {
+ children.push(
+ new Paragraph({
+ ...docxDirection(headline),
+ spacing: { after: 240 },
+ children: textRuns(
+ headline,
+ { italics: true, color: docxHex(palette.muted), size: 26 },
+ eastAsianScript(headline)
+ ),
+ })
+ )
+ }
+
+ children.push(
+ ...bodyToDocxChildren(body, {
+ palette,
+ numbering,
+ warnings,
+ image: (file, alt) =>
+ embed(file, 'body', imageBox, {
+ altText: alt,
+ spacing: { before: 120, after: 120 },
+ }),
+ })
+ )
+
+ let tablesWritten = 0
+ const tableTexts: unknown[] = []
+ tables.forEach((table, i) => {
+ const spec = (table && typeof table === 'object' ? table : {}) as DocxTableArg
+ const headers = Array.isArray(spec.headers) ? spec.headers : []
+ if (headers.length === 0) {
+ warnings.push(
+ `tables[${i}] has no headers and was left out; give it a headers array of column names.`
+ )
+ return
+ }
+ const rows = normalizeTableRows(spec.rows, headers, `tables[${i}]`, warnings)
+ tableTexts.push(...headers)
+ for (const row of rows) tableTexts.push(...row)
+ const layout = spec.layout === 'minimal' || spec.layout === 'grid' ? spec.layout : 'striped'
+ children.push(buildDocxTable(headers, rows, palette, layout, warnings, `tables[${i}]`))
+ children.push(new Paragraph({ children: [new TextRun({ text: '' })] }))
+ tablesWritten++
+ })
+
+ images.forEach((img, i) => {
+ const spec = (img && typeof img === 'object' ? img : {}) as DocxImageArg
+ const paragraph = embed(img, `images[${i}]`, imageBox, {
+ width: spec.width,
+ height: spec.height,
+ alignment: spec.alignment,
+ spacing: { before: 160, after: 160 },
+ })
+ if (paragraph) children.push(paragraph)
+ })
+
+ if (embedded === 0 && !title && !headline && tablesWritten === 0 && !bodyHasText(body)) {
+ if (warnings.length > 0) {
+ const hint = imageLeftOut
+ ? ' Pass images as file names in the output folder, such as those clerum__generate_chart returns.'
+ : ''
+ return {
+ success: false,
+ error: `Nothing could be written to ${filename}. ${[...new Set(warnings)].join(' ')}${hint}`,
+ }
+ }
+ warnings.push(EMPTY_DOCUMENT_NOTE)
+ }
+
+ // The page number follows the first footer line; the docx lib writes it as
+ // a field Word fills in on open. The other lines are run from a leading
+ // newline and lose its empty run, so each starts on a line of its own.
+ const footerMuted = { color: docxHex(palette.muted), size: 18 }
+ const footerLines = (branding.footerText ?? '').replace(/\r\n?/g, '\n').split('\n')
+ if (footerLines.length > DOCX_MAX_FOOTER_LINES) {
+ warnings.push(
+ `branding.footerText takes ${footerLines.length} lines, but only ` +
+ `${DOCX_MAX_FOOTER_LINES} fit in the footer, so the rest was cut. Keep it to a line or two.`
+ )
+ footerLines.length = DOCX_MAX_FOOTER_LINES
+ footerLines[DOCX_MAX_FOOTER_LINES - 1] += '...'
+ }
+ const [firstFooterLine, ...moreFooterLines] = footerLines
+ const headerMuted = { color: docxHex(palette.muted), size: 18 }
+ const companyName = branding.companyName ?? ''
+ // The page number and the title sit at the right margin, on a right tab
+ // stop at the width of the section's page.
+ const running = (width: number) => {
+ const tabStops = [{ type: TabStopType.RIGHT, position: width }]
+ const footer = new DocxFooter({
+ children: [
+ new Paragraph({
+ alignment: AlignmentType.LEFT,
+ tabStops,
+ children: [
+ ...textRuns(firstFooterLine, footerMuted, eastAsianScript(firstFooterLine)),
+ new TextRun({ text: '\t', ...footerMuted }),
+ new TextRun({ children: ['Page ', PageNumber.CURRENT], ...footerMuted }),
+ new TextRun({ children: [' / ', PageNumber.TOTAL_PAGES], ...footerMuted }),
+ ...(moreFooterLines.length > 0
+ ? textRuns(
+ `\n${moreFooterLines.join('\n')}`,
+ footerMuted,
+ eastAsianScript(moreFooterLines.join(' '))
+ ).slice(1)
+ : []),
+ ],
+ }),
+ ],
+ })
+ const header = new DocxHeader({
+ children: [
+ new Paragraph({
+ alignment: AlignmentType.LEFT,
+ tabStops,
+ children: [
+ ...textRuns(companyName, headerMuted, eastAsianScript(companyName)),
+ new TextRun({ text: '\t', ...headerMuted }),
+ ...textRuns(title ?? '', headerMuted, eastAsianScript(title ?? '')),
+ ],
+ }),
+ ],
+ })
+ return { header, footer }
+ }
+ const portrait = running(DOCX_CONTENT_WIDTH_TWIPS)
+ const landscape = running(DOCX_LANDSCAPE_CONTENT_WIDTH_TWIPS)
+
+ // Runs of Han characters alone name no East Asian face and take this one.
+ const eastAsia = documentEastAsianScript(
+ [title, headline, body, branding.companyName, branding.footerText, ...tableTexts]
+ .filter((text): text is string => typeof text === 'string')
+ .join('\n')
+ )
+ const doc = new DocxDocument({
+ creator: branding.companyName ?? '',
+ title: title ?? 'Report',
+ description: headline,
+ styles: {
+ default: {
+ document: {
+ run: {
+ font: {
+ ascii: DOCX_LATIN_FONT,
+ hAnsi: DOCX_LATIN_FONT,
+ cs: DOCX_COMPLEX_FONT,
+ ...(eastAsia ? { eastAsia: eastAsia.font } : {}),
+ },
+ ...(eastAsia ? { language: { eastAsia: eastAsia.lang } } : {}),
+ size: 22,
+ color: docxHex(palette.text),
+ },
+ paragraph: { spacing: { line: 320, after: 80 } },
+ },
+ },
+ },
+ numbering: { config: numbering.config() },
+ sections: docxSections(children).map(section => ({
+ properties: section.landscape
+ ? { page: { size: { orientation: PageOrientation.LANDSCAPE } } }
+ : {},
+ headers: { default: (section.landscape ? landscape : portrait).header },
+ footers: { default: (section.landscape ? landscape : portrait).footer },
+ children: section.children,
+ })),
+ })
+
+ const buffer = await Packer.toBuffer(doc)
+ ensureDir(outputDir)
+ const target = claimOutputFile(outputDir, filename)
+ enforceQuota(outputDir, buffer.byteLength, replacedBytes(target))
+ fs.writeFileSync(target.filePath, buffer)
+
+ return artifactResult(target, 'docx', { warnings: [...new Set(warnings)] })
+ } catch (err) {
+ return { success: false, error: err instanceof Error ? err.message : String(err) }
+ }
+}
diff --git a/mcp-host/src/workflow/internalTools.ts b/mcp-host/src/workflow/internalTools.ts
index 5759749cb..85f4cde36 100644
--- a/mcp-host/src/workflow/internalTools.ts
+++ b/mcp-host/src/workflow/internalTools.ts
@@ -11,139 +11,55 @@
* chart.js + @napi-rs/canvas (PNG charts), built-in string write
* for markdown and the dashboard HTML wrapper.
*/
-import { type SKRSContext2D, createCanvas } from '@napi-rs/canvas'
-import {
- Chart,
- type ChartConfiguration,
- type ChartType,
- type Plugin,
- type Scale,
- registerables,
-} from 'chart.js'
-import {
- AlignmentType,
- Document as DocxDocument,
- Footer as DocxFooter,
- Header as DocxHeader,
- Table as DocxTable,
- HeadingLevel,
- Packer,
- PageNumber,
- PageOrientation,
- Paragraph,
- TabStopType,
- TextRun,
-} from 'docx'
-import ExcelJS from 'exceljs'
import * as fs from 'fs'
import * as path from 'path'
-import type { Content, ContentText, Node, TDocumentDefinitions } from 'pdfmake/interfaces'
import { config } from '../config'
import { WorkflowListTool, WorkflowStatusTool } from '../core/tools/workflowReadTools'
import { WorkflowTriggerTool } from '../core/tools/workflowTriggerTool'
-import { artifactResult, claimOutputFile, outputFilename, replacedBytes } from './artifactOutput'
-import { ChartDataError, coerceNumber, normalizeChartData } from './chartData'
-import type { NormalizedDataset, NormalizedPoint } from './chartData'
-import {
- type ValueFormat,
- type ValueLabelOptions,
- backgroundPlugin,
- emptyStatePlugin,
- formatValue,
- gaugeCenterPlugin,
- sliceColors,
- valueLabelsPlugin,
-} from './chartPlugins'
-import { CONTEXT_FILES_TOOLS, loadContextFilesMounts } from './contextFiles'
-import { DASHBOARD_CHART_TYPES, DashboardCharts } from './dashboardCharts'
-import { escapeHtml, oneOf } from './dashboardHtml'
-import { dashboardScript } from './dashboardScript'
-import {
- DASHBOARD_THEMES,
- type DashboardTheme,
- type DashboardThemeColors,
- type ThemeName,
-} from './dashboardThemes'
-import { type DocxImagePlacement, docxImageParagraph } from './docxImages'
-import { textRuns } from './docxInline'
-import { bodyHasText, bodyToDocxChildren } from './docxMarkdown'
-import {
- DOCX_COMPLEX_FONT,
- DOCX_LATIN_FONT,
- documentEastAsianScript,
- docxDirection,
- eastAsianScript,
-} from './docxScript'
-import {
- DOCX_CONTENT_WIDTH_TWIPS,
- DOCX_LANDSCAPE_CONTENT_WIDTH_TWIPS,
- DOCX_PALETTES,
- DocxListNumbering,
- docxHex,
-} from './docxStyle'
-import { buildDocxTable, docxSections } from './docxTable'
-import {
- PNG_BASE_PPM,
- fitImageBox,
- fitImageSize,
- imageDataUrl,
- loadEmbeddableImage,
- predecodeImages,
-} from './embeddedImages'
import {
- CHART_FONT_STACK,
- PDF_FONT_FAMILY,
- PDF_MONO_FAMILY,
- ensureFontsReady,
- pdfGlyphSource,
- sanitizeForFont,
-} from './fonts'
+ artifactResult,
+ claimOutputFile,
+ enforceQuota,
+ ensureDir,
+ outputFilename,
+ replacedBytes,
+} from './artifactOutput'
import {
- closesFence,
- htmlToPlainLines,
- htmlToPlainText,
- inlineSpans,
- openingFence,
- quoteParagraphs,
- withoutClosingHashes,
-} from './inlineMarkup'
+ DEFAULT_CHART_HEIGHT,
+ DEFAULT_CHART_WIDTH,
+ MAX_CHART_DIMENSION,
+ MIN_CHART_DIMENSION,
+ runGenerateChart,
+} from './chartGenerator'
+import { CONTEXT_FILES_TOOLS, loadContextFilesMounts } from './contextFiles'
+import { DASHBOARD_CHART_TYPES } from './dashboardCharts'
import {
- BODY_FONT_SIZE,
- MIN_BOTTOM_MARGIN,
- PORTRAIT,
- type UnitMeasure,
- layoutPdfTable,
-} from './pdfTables'
-import { LINE_FILL, PdfTypesetter } from './pdfText'
+ BLOCK_TYPES,
+ CALLOUT_TONES,
+ DASHBOARD_TEMPLATE_NAMES,
+ HERO_STATUSES,
+ SECTION_TYPES,
+ runGenerateDashboard,
+} from './dashboardRender'
+import { PDF_MAX_FOOTER_LINES } from './documentChrome'
+import { DOCX_IMAGE_FILE_DESCRIPTION, runGenerateDocx } from './docxGenerator'
+import { predecodeImages } from './embeddedImages'
+import { IMAGE_FILE_DESCRIPTION, runGeneratePdf } from './pdfGenerator'
import { NATIVE_CHART_TYPES } from './pptxCharts'
import { PPTX_ASPECT_RATIOS, PPTX_PALETTES, buildPptxDeck } from './pptxDeck'
import { SLIDE_LAYOUTS, STATUSES } from './pptxInput'
import { PPTX_TEMPLATES, SEVERITIES } from './pptxTemplates'
import { watchUnknownArguments, withoutUnsetNulls } from './schemaArguments'
-import { headerText, normalizeTableRows } from './tableRows'
import { cleanToolArgs } from './toolText'
import type { InternalToolDefinition, InternalToolResult } from './types'
import { buildXlsxWorkbook } from './xlsxWorkbook'
+export { enforceQuota, getDirectorySize } from './artifactOutput'
export { fitImageBox, imageDisplaySize, imageIntrinsicSize } from './embeddedImages'
-
-const PdfPrinter = require('pdfmake')
-
-// 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'
-}
+export { CHART_THEMES } from './chartThemes'
+export type { ChartTheme } from './chartThemes'
+export { escapeHtmlAttr, safeJsonForScript } from './dashboardHtml'
+export { loadChartJsBundle } from './dashboardRender'
// Accessor to the current Host CRD, injected by main (avoids a circular import).
// Re-read on every getOutputDir() call because `currentHost` is hydrated async
@@ -166,34 +82,6 @@ export function setOutputDirHostAccessor(accessor: WorkspaceHostAccessor): void
// path traversal when reading user-named files, and formula injection
// in spreadsheet cells.
-/**
- * JSON.stringify with HTML-sensitive characters escaped, safe to embed
- * inside a `<script>` block. Prevents `</script>...<script>alert(1)...`
- * breakouts via attacker-controlled string content.
- */
-export function safeJsonForScript(v: unknown): string {
- return JSON.stringify(v)
- .replace(/</g, '\\u003c')
- .replace(/>/g, '\\u003e')
- .replace(/&/g, '\\u0026')
- .replace(/\u2028/g, '\\u2028')
- .replace(/\u2029/g, '\\u2029')
-}
-
-/**
- * Escape a value for use inside an HTML attribute (single OR double
- * quoted). Defends against attribute-breakout XSS like
- * `data-foo='${val}'` where `val` contains `'`.
- */
-export function escapeHtmlAttr(s: unknown): string {
- return String(s ?? '')
- .replace(/&/g, '&amp;')
- .replace(/"/g, '&quot;')
- .replace(/'/g, '&#39;')
- .replace(/</g, '&lt;')
- .replace(/>/g, '&gt;')
-}
-
/**
* Resolve `p` against `outputDir` and ensure the result stays inside
* `outputDir`. Throws on traversal attempts (`../etc/passwd`, absolute
@@ -229,561 +117,6 @@ export function safeCell(v: unknown): unknown {
// ─── Helpers ─────────────────────────────────────────────────────────
-function ensureDir(dir: string): void {
- if (!fs.existsSync(dir)) {
- fs.mkdirSync(dir, { recursive: true })
- }
-}
-
-// A dashboard with charts inlines the Chart.js UMD bundle (~210 KB) so the
-// HTML works offline: about 250 of them fit in the default quota.
-const DEFAULT_QUOTA_MB = 50
-
-/**
- * Recursively sum the size of all regular files under `dir`.
- * Returns 0 if the directory does not exist.
- */
-export function getDirectorySize(dir: string): number {
- if (!fs.existsSync(dir)) return 0
- let total = 0
- const entries = fs.readdirSync(dir, { withFileTypes: true })
- for (const entry of entries) {
- const full = path.join(dir, entry.name)
- if (entry.isDirectory()) {
- total += getDirectorySize(full)
- } else if (entry.isFile()) {
- try {
- total += fs.statSync(full).size
- } catch {
- // file may have been removed between readdir and stat — ignore
- }
- }
- }
- return total
-}
-
-/**
- * Enforce the per-recipe output quota before a file is written.
- *
- * Reads the ceiling from `CLERUM_WORKFLOW_OUTPUT_QUOTA_MB` (default: 50 MB).
- * Throws if the current directory usage + `incomingBytes` would exceed the cap.
- * `replacingBytes` is the size of a file the write overwrites, which stops
- * counting once it is replaced.
- *
- * Known limitation (race condition): When the LLM issues multiple tool calls
- * concurrently (e.g., generate_pdf + generate_xlsx in the same turn), both
- * calls read the directory size before either has written its file. Both see
- * the same "current" size and both pass the quota check, even though the
- * combined output would exceed the 50 MB cap. This is a best-effort soft
- * quota; the 1Gi PVC hard cap enforced by kubelet is the primary defense.
- */
-export function enforceQuota(outputDir: string, incomingBytes: number, replacingBytes = 0): void {
- const raw = process.env.CLERUM_WORKFLOW_OUTPUT_QUOTA_MB
- const parsed = raw ? parseInt(raw, 10) : NaN
- const quotaMB = Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_QUOTA_MB
- const quotaBytes = quotaMB * 1024 * 1024
-
- const current = getDirectorySize(outputDir) - replacingBytes
- const projected = current + incomingBytes
- if (projected > quotaBytes) {
- const mb = (bytes: number) => (bytes / (1024 * 1024)).toFixed(1)
- throw new Error(
- `Output quota exceeded: the output folder holds ${mb(current)} MB and this file needs ` +
- `${mb(incomingBytes)} MB, over the ${quotaMB} MB limit. Make the file smaller, or ask ` +
- 'the user to remove earlier generated files or an operator to raise ' +
- 'CLERUM_WORKFLOW_OUTPUT_QUOTA_MB.'
- )
- }
-}
-
-// ─── generate_chart ──────────────────────────────────────────────────
-
-export interface ChartTheme {
- backgroundColor: string
- textColor: string
- /** Secondary text, such as a gauge's maximum: at least 4.5:1 on the background. */
- mutedTextColor: string
- gridColor: string
- palette: string[]
- /** Semantic colors used by waterfall (positive/negative deltas) and gauge. */
- positive: string
- negative: string
-}
-
-export const CHART_THEMES: Record<string, ChartTheme> = {
- light: {
- backgroundColor: '#ffffff',
- textColor: '#0f172a',
- mutedTextColor: '#64748b',
- gridColor: '#e2e8f0',
- palette: ['#0f172a', '#22c55e', '#f59e0b', '#ef4444', '#3b82f6', '#a855f7', '#06b6d4'],
- positive: '#16a34a',
- negative: '#dc2626',
- },
- dark: {
- backgroundColor: '#0f172a',
- textColor: '#e2e8f0',
- mutedTextColor: '#94a3b8',
- gridColor: '#334155',
- palette: ['#22c55e', '#3b82f6', '#a855f7', '#f59e0b', '#ef4444', '#06b6d4', '#ec4899'],
- positive: '#22c55e',
- negative: '#f87171',
- },
- corporate: {
- backgroundColor: '#ffffff',
- textColor: '#1e293b',
- mutedTextColor: '#64748b',
- gridColor: '#cbd5e1',
- palette: ['#1e40af', '#0891b2', '#0d9488', '#059669', '#65a30d', '#ca8a04', '#dc2626'],
- positive: '#059669',
- negative: '#b91c1c',
- },
- warm: {
- backgroundColor: '#f7f7f5',
- textColor: '#2f2823',
- mutedTextColor: '#716961',
- gridColor: '#d6d2cc',
- palette: ['#b45309', '#2f2823', '#0d9488', '#1e40af', '#9f1239', '#65a30d', '#7c3aed'],
- positive: '#65a30d',
- negative: '#9f1239',
- },
- 'warm-dark': {
- backgroundColor: '#0e0f10',
- textColor: '#f2f2ef',
- mutedTextColor: '#9b958f',
- gridColor: '#2a2c2f',
- palette: ['#ca6e1e', '#f2f2ef', '#34d399', '#60a5fa', '#fb7185', '#a3e635', '#c4b5fd'],
- positive: '#a3e635',
- negative: '#fb7185',
- },
-}
-
-/** Types whose series overlap, so their fill has to let the one below show. */
-const TRANSLUCENT_FILL_TYPES = new Set(['line', 'area', 'radar'])
-
-/** Widest a single bar may be drawn, in nominal pixels. */
-const MAX_BAR_THICKNESS = 120
-
-const DEFAULT_CHART_WIDTH = 800
-const DEFAULT_CHART_HEIGHT = 400
-const MAX_CHART_DIMENSION = 4000
-const MIN_CHART_DIMENSION = 100
-/** 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
-])
-
-interface ChartDataset {
- label?: string
- /**
- * Numbers for category charts, {x,y[,r]} for scatter/bubble, and [from,to]
- * tuples once a waterfall has been expanded into floating bars.
- */
- data: Array<number | null> | NormalizedPoint[] | number[][]
- backgroundColor?: string | string[]
- borderColor?: string | string[]
- fill?: boolean
-}
-
-/**
- * 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
-}
-
-/**
- * Default radius of a series' points: `full` up to `crowd` points, and smaller
- * past that so a dense series keeps the ink of `crowd` points instead of
- * merging into one blot. Never under 1.5 px, so a lone point still shows.
- */
-function pointRadius(full: number, crowd: number, points: number): number {
- return points <= crowd ? full : Math.max(1.5, full * Math.sqrt(crowd / points))
-}
-
-/**
- * Apply theme colors to datasets that don't specify their own. Each dataset gets
- * a different color from the palette by index. For pie/doughnut/polarArea where
- * each slice is a separate color, every slice gets its own color: a caller's
- * short list is completed from the theme, and slices past the palette get
- * shades of it.
- *
- * Palettes have 7 colors; with more datasets the palette wraps via
- * `idx % palette.length`, so series i and i+7 share a color. Callers who need
- * more distinct series pass `borderColor` / `backgroundColor` per dataset.
- */
-function applyThemePalette(
- datasets: ChartDataset[],
- theme: ChartTheme,
- chartType: string,
- warnings: string[]
-): ChartDataset[] {
- const sliceTypes = new Set(['pie', 'doughnut', 'polarArea'])
- const isSliceType = sliceTypes.has(chartType)
-
- return datasets.map((ds, idx) => {
- const out: ChartDataset = { ...ds }
- if (isSliceType) {
- if (typeof out.backgroundColor !== 'string') {
- const requested = out.backgroundColor
- const { colors, padded, repeated } = sliceColors(
- ds.data.length,
- requested,
- theme.palette,
- theme.backgroundColor
- )
- out.backgroundColor = colors
- const where = `data.datasets[${idx}]`
- if (padded) {
- warnings.push(
- `${where}.backgroundColor had ${requested!.length} color(s) for ${ds.data.length} ` +
- 'slices; the rest were taken from the theme. Send one color per slice.'
- )
- }
- if (repeated) {
- warnings.push(
- `${where} has ${ds.data.length} slices, more than there are distinct colors, so ` +
- 'some colors repeat. Group the smallest slices into "Other".'
- )
- }
- }
- } else {
- const color = theme.palette[idx % theme.palette.length]
- if (!out.borderColor) out.borderColor = color
- if (!out.backgroundColor) {
- // Translucent wherever series are drawn over one another — a solid
- // radar fill hides every series behind the first.
- out.backgroundColor = TRANSLUCENT_FILL_TYPES.has(chartType) ? `${color}33` : color
- }
- if (chartType === 'area' && out.fill === undefined) {
- out.fill = true
- }
- const point = out as unknown as Record<string, unknown>
- const points = Array.isArray(ds.data) ? ds.data.length : 0
- if (chartType === 'scatter') {
- if (point.pointRadius === undefined) point.pointRadius = pointRadius(6, 100, points)
- } else if (chartType === 'line' || chartType === 'area' || chartType === 'stackedArea') {
- // A value with a gap on both sides gets no segment, so its point is
- // its only mark.
- if (point.pointRadius === undefined) point.pointRadius = pointRadius(4, 60, points)
- if (point.pointBackgroundColor === undefined) point.pointBackgroundColor = color
- }
- }
- return out
- })
-}
-
-interface ResolvedChartType {
- chartType: ChartType
- // Loosely typed because Chart.js options that are valid only for specific
- // chart kinds (rotation/circumference/cutout for doughnut, indexAxis for
- // bar, etc.) don't satisfy the general ChartConfiguration['options'] union.
- // The cast happens once at config-merge time.
- optionsOverrides: Record<string, unknown> & {
- scales?: {
- x?: Record<string, unknown>
- y?: Record<string, unknown>
- y1?: Record<string, unknown>
- }
- plugins?: { legend?: { display?: boolean } }
- indexAxis?: 'x' | 'y'
- }
- /** When set, the caller should replace the labels array with this value. */
- labels?: string[]
- /** Gauge only: the reading as sent and the dial's ceiling, for the centre readout. */
- gaugeValue?: number
- gaugeMax?: number
- /** What the type changed about the data, for the caller. */
- notes: string[]
-}
-
-/**
- * Resolve our user-facing chart-type string to the underlying Chart.js
- * type AND compute per-type option overrides + dataset mutations.
- *
- * For composed types (gauge / waterfall / funnel / mixedBarLine / stacked*)
- * this function MUTATES `datasets` (and sometimes `labels`) in-place so
- * the caller can pass the result straight into the Chart.js config.
- */
-function resolveChartType(
- raw: string,
- datasets: ChartDataset[],
- labels: string[] | undefined,
- theme: ChartTheme,
- args: Record<string, unknown>
-): ResolvedChartType {
- const o: ResolvedChartType = { chartType: 'bar', optionsOverrides: {}, notes: [] }
- switch (raw) {
- case 'horizontalBar':
- o.chartType = 'bar'
- o.optionsOverrides.indexAxis = 'y'
- return o
- case 'area':
- o.chartType = 'line'
- // applyThemePalette already set fill=true for area datasets.
- return o
- case 'stackedBar':
- o.chartType = 'bar'
- o.optionsOverrides.scales = {
- x: { stacked: true },
- y: { stacked: true },
- }
- return o
- case 'stackedArea':
- o.chartType = 'line'
- o.optionsOverrides.scales = { y: { stacked: true } }
- datasets.forEach((d, i) => {
- if (d.fill === undefined) d.fill = (i === 0 ? 'origin' : '-1') as unknown as boolean
- })
- return o
- case 'mixedBarLine': {
- o.chartType = 'bar'
- // First dataset stays as bar (default for mixed); subsequent
- // datasets render as line overlays via Chart.js per-dataset `type`.
- const dual = args.dualAxis === true
- datasets.forEach((d, i) => {
- if (i > 0) {
- ;(d as any).type = 'line'
- ;(d as any).fill = false
- if (dual) (d as unknown as Record<string, unknown>).yAxisID = 'y1'
- }
- })
- if (dual) {
- o.optionsOverrides.scales = {
- y1: { position: 'right', grid: { drawOnChartArea: false } },
- }
- }
- return o
- }
- case 'bubble':
- o.chartType = 'bubble'
- return o
- case 'gauge': {
- o.chartType = 'doughnut'
- // Single-value 0..max. Take datasets[0].data[0] as the value;
- // build a 2-segment doughnut [value, max-value] and rotate it
- // 180° so the cut shows as a half-circle dial at the bottom.
- const ds = datasets[0]
- if (!ds) return o
- const values = (ds.data as unknown[]).filter((v): v is number => typeof v === 'number')
- const reading = values[0] ?? 0
- const max = Math.max(0, Number(args.gaugeMax) || 100)
- // Only the arc is bounded by the dial; the readout prints the reading.
- const arc = Math.min(Math.max(reading, 0), max)
- if (reading > max) {
- o.notes.push(
- `the gauge value ${reading} exceeds gaugeMax ${max}, so the dial is shown full; ` +
- 'the readout prints the value. Raise gaugeMax to show it on the scale.'
- )
- } else if (reading < 0) {
- o.notes.push(`the gauge value ${reading} is below 0, so the dial is shown empty.`)
- }
- if (values.length > 1) {
- o.notes.push(
- `the gauge shows one value, so ${values.length - 1} more in data.datasets[0].data ` +
- `${values.length > 2 ? 'were' : 'was'} left out.`
- )
- }
- const fill = theme.palette[0]
- const remainder = theme.gridColor
- ds.data = [arc, max - arc]
- ds.backgroundColor = [fill, remainder]
- ds.borderColor = [fill, remainder]
- // Drop any extra datasets — gauge is single-value.
- datasets.length = 1
- o.gaugeValue = reading
- o.gaugeMax = max
- o.labels = ['Value', 'Remainder']
- o.optionsOverrides = {
- rotation: -90,
- circumference: 180,
- cutout: '70%',
- // The bottom padding leaves room under the dial's flat edge for the
- // "/ max" line the readout prints below it.
- radius: '88%',
- layout: { padding: { top: 12, right: 16, bottom: 90, left: 16 } },
- plugins: { legend: { display: false } },
- }
- return o
- }
- case 'waterfall': {
- o.chartType = 'bar'
- const ds = datasets[0]
- if (!ds || !Array.isArray(ds.data)) return o
- const deltas = ds.data as number[]
- const floats: number[][] = []
- const colors: string[] = []
- let cumulative = 0
- for (const delta of deltas) {
- const start = cumulative
- cumulative += Number(delta) || 0
- floats.push([start, cumulative])
- colors.push((Number(delta) || 0) >= 0 ? theme.positive : theme.negative)
- }
- // Final cumulative-total bar in primary color.
- floats.push([0, cumulative])
- colors.push(theme.palette[0])
- ds.data = floats as any
- ds.backgroundColor = colors
- ds.borderColor = colors
- // Append "Total" to labels (or synthesize labels if absent).
- const newLabels = labels ? [...labels] : deltas.map((_, i) => `Step ${i + 1}`)
- newLabels.push('Total')
- o.labels = newLabels
- // Drop extra datasets — waterfall is single-series.
- datasets.length = 1
- o.optionsOverrides = { plugins: { legend: { display: false } } }
- return o
- }
- case 'funnel': {
- o.chartType = 'bar'
- const ds = datasets[0]
- if (!ds || !Array.isArray(ds.data)) return o
- // Sort descending while keeping label/data alignment.
- const lbls = labels ?? (ds.data as number[]).map((_, i) => `Stage ${i + 1}`)
- const paired = (ds.data as number[]).map((v, i) => ({
- v: Number(v) || 0,
- l: lbls[i] ?? '',
- i,
- }))
- paired.sort((a, b) => b.v - a.v)
- ds.data = paired.map(p => p.v)
- o.labels = paired.map(p => p.l)
- // Per-stage colors follow their stage through the sort.
- const follow = (colors: string | string[] | undefined) =>
- Array.isArray(colors) ? paired.map(p => colors[p.i % colors.length]) : colors
- ds.backgroundColor = follow(ds.backgroundColor)
- ds.borderColor = follow(ds.borderColor)
- // Drop extra datasets — funnel is single-series.
- datasets.length = 1
- o.optionsOverrides = {
- indexAxis: 'y',
- plugins: { legend: { display: false } },
- }
- return o
- }
- default:
- o.chartType = raw as ChartType
- return o
- }
-}
-
-// ─── Portable schema fragments ───────────────────────────────────────
-//
-// A tool schema does two jobs. The workflow path (stepRouter) compiles it with
-// AJV and REJECTS arguments that do not match before execute() runs, so it must
-// accept everything the runtime handles. And it reaches every provider
-// verbatim, so it must survive each SDK's translation. Unions are therefore
-// written as scalar type lists or `anyOf` branches — @google/genai turns both
-// into its own schema — and never as `oneOf`, which it passes through
-// untranslated for the Gemini API to reject. Every array declares `items`.
-
/**
* The types of a table or sheet cell: text, a number, true/false, or null for
* an empty cell. Each runtime stringifies or formats what arrives.
@@ -970,419 +303,11 @@ const generateChart: InternalToolDefinition = {
},
required: ['filename', 'type', 'data'],
},
- async execute(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 themeName = String(args.theme ?? 'light')
- const theme = CHART_THEMES[themeName] ?? CHART_THEMES.light
-
- 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 themedDatasets = applyThemePalette(datasets, theme, chartTypeRaw, warnings)
- const resolved = resolveChartType(chartTypeRaw, themedDatasets, labels, theme, args)
- 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 }
- if (labelValues) plugins.push(valueLabelsPlugin({ ...valueOptions, unlabelled }))
- if (chartTypeRaw === 'gauge') {
- plugins.push(
- gaugeCenterPlugin({
- value: resolved.gaugeValue ?? 0,
- max: resolved.gaugeMax ?? 100,
- textColor: theme.textColor,
- mutedColor: theme.mutedTextColor,
- format: valueOptions,
- })
- )
- }
- if (isVisuallyEmpty(themedDatasets)) {
- 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
- // 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.'
- )
- }
- // 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))
- fs.writeFileSync(target.filePath, 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 })
- } 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()
- }
+ execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
+ return runGenerateChart(args, outputDir)
},
}
-/** 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 every plotted number is absent or zero, so nothing would be drawn. */
-function isVisuallyEmpty(datasets: ChartDataset[]): boolean {
- 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 {
- if (value === undefined || value === null) return fallback
- const n = typeof value === 'number' ? value : Number(value)
- if (!Number.isFinite(n) || n <= 0) {
- warnings.push(`${field} ${String(value)} is not a positive number; used ${fallback}.`)
- return fallback
- }
- 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 ───────────────────────────────────────────────
-
/** The file text, or an error saying what content must be; never a stringified array or object. */
function markdownContent(value: unknown): string | { error: string } {
if (value === undefined || value === null) {
@@ -1439,1016 +364,10 @@ const generateMarkdown: InternalToolDefinition = {
// ─── generate_pdf ────────────────────────────────────────────────────
-interface PdfPalette {
- primary: string
- text: string
- muted: string
- border: string
- accent: string
- statusGreen: string
- statusYellow: string
- statusRed: string
- alternateRowFill: string
- surface: string
-}
-
-const PDF_PALETTES: Record<string, PdfPalette> = {
- default: {
- primary: '#0f172a',
- text: '#0f172a',
- muted: '#475569',
- border: '#cbd5e1',
- accent: '#3b82f6',
- statusGreen: '#16a34a',
- statusYellow: '#ca8a04',
- statusRed: '#dc2626',
- alternateRowFill: '#f8fafc',
- surface: '#f1f5f9',
- },
- corporate: {
- primary: '#1e3a8a',
- text: '#1e293b',
- muted: '#475569',
- border: '#cbd5e1',
- accent: '#0891b2',
- statusGreen: '#059669',
- statusYellow: '#ca8a04',
- statusRed: '#b91c1c',
- alternateRowFill: '#f1f5f9',
- surface: '#e0f2fe',
- },
- warm: {
- primary: '#b45309',
- text: '#2f2823',
- muted: '#66584c',
- border: '#d6d2cc',
- accent: '#b45309',
- statusGreen: '#15803d',
- statusYellow: '#b45309',
- statusRed: '#9f1239',
- alternateRowFill: '#fefdfb',
- surface: '#f7f7f5',
- },
- alert: {
- primary: '#9f1239',
- text: '#1f2937',
- muted: '#4b5563',
- border: '#fecaca',
- accent: '#dc2626',
- statusGreen: '#15803d',
- statusYellow: '#ca8a04',
- statusRed: '#9f1239',
- alternateRowFill: '#fef2f2',
- surface: '#fee2e2',
- },
-}
-
-/**
- * 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
-}
-
-/** A4 width (595pt) less the 40pt side margins the documents use. */
-const PDF_CONTENT_WIDTH = PORTRAIT.width
-
-/**
- * Widest a DOCX image is drawn, in pixels at 96 dpi; the page leaves about 601
- * between its margins.
- */
-const DOCX_MAX_IMAGE_WIDTH = 560
-const DOCX_MAX_IMAGE_HEIGHT = 380
-
/** Drawn size for a spreadsheet image, in pixels. */
const XLSX_MAX_IMAGE_WIDTH = 640
const XLSX_MAX_IMAGE_HEIGHT = 400
-/** Keeps a tall image from taking a whole page on its own. */
-const PDF_MAX_IMAGE_HEIGHT = 330
-
-/** Vertical margin around an embedded image, above and below. */
-const PDF_IMAGE_MARGIN = 10
-
-/** The cover logo's box: its usual width, and a height a tall logo cannot exceed. */
-const PDF_LOGO_BOX = { width: 120, height: 80 }
-
-/**
- * Id prefix of each table's first header cell. pdfmake corrects the page
- * number it records for a block moved to the next page only on nodes with an
- * id, and the heading check reads it to see where a table really starts.
- */
-const TABLE_HEADER_ID = 'pdf-table-'
-
-/**
- * Style of the running header and footer. pdfmake lists their nodes among a
- * page's content when deciding page breaks, and this is how they are told apart.
- */
-const RUNNING_STYLE = 'running'
-
-/** Top page margin; the running header is drawn inside it. */
-const PDF_TOP_MARGIN = 60
-
-/** Footer lines that fit once the bottom margin has grown to hold them. */
-const PDF_MAX_FOOTER_LINES = 6
-const PDF_FOOTER_SIZE = 9
-
-const PDF_LINE_HEIGHT = 1.3
-
-interface PdfBranding {
- logoPath?: string
- companyName?: string
- footerText?: string
-}
-
-interface PdfImageRef {
- path: string
- width?: number
- height?: number
- alignment?: 'left' | 'center' | 'right'
-}
-
-interface PdfTableSpec {
- headers: unknown[]
- rows: unknown
- widths?: unknown
- layout?: 'striped' | 'minimal' | 'grid'
-}
-
-/** What the body parser needs from the call it serves. */
-interface PdfBodyEnv {
- warnings: string[]
- /** Width of text at 1pt in the body face, for sizing table columns. */
- measure: UnitMeasure
- /** An image block for a `![alt](file)` line, or undefined when it could not be loaded. */
- image(src: string): Content | undefined
- /** Tables that need landscape pages. */
- landscape: Set<Content>
- /** Tables parsed from the body so far, for naming them in warnings. */
- tableCount: number
- /** Tables built so far, body and explicit, for giving each header a unique id. */
- tablesBuilt: number
- /** Bottom page margin, which grows with the footer. */
- bottomMargin: number
-}
-
-/**
- * Branding as it prints: HTML in the company name and footer read as text,
- * the footer keeping its lines.
- */
-function printedBranding(raw: unknown): {
- logoPath?: string
- companyName?: string
- footerText?: string
-} {
- const branding = (raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {}) as Record<
- string,
- unknown
- >
- const text = (value: unknown) =>
- value === undefined || value === null ? undefined : String(value)
- const companyName = text(branding.companyName)
- const footerText = text(branding.footerText)
- // Named rather than spread, so a key nothing prints is reported as ignored.
- return {
- ...(branding.logoPath !== undefined ? { logoPath: branding.logoPath as string } : {}),
- ...(companyName !== undefined ? { companyName: htmlToPlainText(companyName) } : {}),
- ...(footerText !== undefined ? { footerText: htmlToPlainLines(footerText) } : {}),
- }
-}
-
-/** An image reference written in the body: `![alt](src)`. */
-interface MarkdownImage {
- alt: string
- src: string
-}
-
-/**
- * Inline markup of one line as pdfmake runs: **bold**, *italic*, ~~strike~~,
- * `code`, links, the HTML tags models write, and character entities. Image
- * references are taken out of the text and handed to `onImage`.
- */
-function parseInlineMarkdown(line: string, onImage: (image: MarkdownImage) => void): ContentText {
- const runs: ContentText[] = []
- for (const span of inlineSpans(line)) {
- if (span.image !== undefined) {
- onImage({ alt: span.text, src: span.image })
- continue
- }
- runs.push({
- text: span.text,
- ...(span.bold ? { bold: true } : {}),
- ...(span.italics ? { italics: true } : {}),
- ...(span.code ? { font: PDF_MONO_FAMILY } : {}),
- ...(span.link !== undefined
- ? { link: span.link, color: '#1d4ed8', decoration: 'underline' as const }
- : span.strike
- ? { decoration: 'lineThrough' as const }
- : {}),
- })
- }
- return { text: runs }
-}
-
-/** Characters, and styled runs, one pdfmake paragraph holds before the next piece starts. */
-const PARAGRAPH_PIECE_CHARS = 20_000
-const PARAGRAPH_PIECE_RUNS = 1_000
-
-/**
- * `paragraph` in pieces of up to PARAGRAPH_PIECE_CHARS characters and
- * PARAGRAPH_PIECE_RUNS runs, each cut after a space where there is one.
- * pdfmake lays a paragraph out in time that grows with the square of its words
- * and runs, so one 200 KB line of alternating emphasis held the event loop for
- * half a minute; pieces set one under another read on as the same paragraph,
- * with a line ending at each cut. No paragraph a person writes reaches either
- * limit.
- */
-function inPieces(paragraph: ContentText): ContentText[] {
- if (
- !Array.isArray(paragraph.text) ||
- (paragraph.text.length <= PARAGRAPH_PIECE_RUNS &&
- plainText(paragraph).length <= PARAGRAPH_PIECE_CHARS)
- ) {
- return [paragraph]
- }
- const pieces: ContentText[][] = [[]]
- let size = 0
- for (const run of paragraph.text as ContentText[]) {
- if (pieces[pieces.length - 1].length >= PARAGRAPH_PIECE_RUNS) {
- pieces.push([])
- size = 0
- }
- let text = String(run.text ?? '')
- while (size + text.length > PARAGRAPH_PIECE_CHARS) {
- const room = PARAGRAPH_PIECE_CHARS - size
- let cut = text.lastIndexOf(' ', room - 1) + 1
- if (cut <= 0 && size > 0) {
- pieces.push([])
- size = 0
- continue
- }
- if (cut <= 0) {
- // No space to cut after: cut inside the word, never inside a surrogate pair.
- cut = room
- const code = text.charCodeAt(cut - 1)
- if (code >= 0xd800 && code <= 0xdbff) cut--
- }
- pieces[pieces.length - 1].push({ ...run, text: text.slice(0, cut) })
- pieces.push([])
- size = 0
- text = text.slice(cut)
- }
- if (text) {
- pieces[pieces.length - 1].push({ ...run, text })
- size += text.length
- }
- }
- return pieces.filter(piece => piece.length > 0).map(piece => ({ text: piece }))
-}
-
-/** `parsed` as it is, or as a stack of its pieces when it is that long. */
-function asPieces(parsed: ContentText): ContentText | { stack: ContentText[] } {
- const pieces = inPieces(parsed)
- return pieces.length === 1 ? pieces[0] : { stack: pieces }
-}
-
-/** The text a parsed line prints, for measuring it. */
-function plainText(parsed: ContentText): string {
- const text = parsed.text
- if (!Array.isArray(text)) return String(text ?? '')
- return text
- .map(t => (typeof t === 'string' ? t : String((t as { text?: unknown }).text ?? '')))
- .join('')
-}
-
-/** A GFM delimiter row. One column needs its outer pipes, or it is only a rule. */
-function isTableSeparator(line: string): boolean {
- return (
- /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?\s*$/.test(line) ||
- /^\s*\|\s*:?-+:?\s*\|\s*$/.test(line)
- )
-}
-
-/** Cells of a pipe-table row. `\|` is a literal pipe inside a cell. */
-function splitTableRow(line: string): string[] {
- let trimmed = line.trim()
- if (trimmed.startsWith('|')) trimmed = trimmed.slice(1)
- if (trimmed.endsWith('|') && !trimmed.endsWith('\\|')) trimmed = trimmed.slice(0, -1)
- return trimmed.split(/(?<!\\)\|/).map(c => c.trim().replace(/\\\|/g, '|'))
-}
-
-/**
- * Whether a GFM table starts at line `i`. GFM makes the outer pipes optional
- * and some models leave them out, so a header without them counts when it has
- * as many cells as the separator under it.
- */
-function isPipeTableStart(lines: string[], i: number): boolean {
- const line = lines[i]
- const next = lines[i + 1]
- if (next === undefined || !line.includes('|') || !isTableSeparator(next)) return false
- return (
- line.trimStart().startsWith('|') || splitTableRow(line).length === splitTableRow(next).length
- )
-}
-
-type ColumnAlignment = 'left' | 'center' | 'right'
-
-interface PdfTableRequest {
- headers: string[]
- rows: string[][]
- layout?: 'striped' | 'minimal' | 'grid'
- widths?: unknown
- alignments?: ColumnAlignment[]
- /** How warnings name the table, such as "tables[0]". */
- label: string
- /** How warnings name one of its rows, such as "tables[0].rows[2]". */
- rowLabel(index: number): string
-}
-
-function buildTableNode(
- request: PdfTableRequest,
- palette: PdfPalette,
- env: PdfBodyEnv,
- onImage: (image: MarkdownImage) => void
-): Content {
- const { headers, alignments } = request
- const layout = request.layout ?? 'striped'
- // pdfmake needs every row to have one cell per column: short rows are
- // padded, and cells past the last header are cut and reported.
- const long = request.rows.flatMap((row, i) => (row.length > headers.length ? [i] : []))
- if (long.length > 0) {
- const first = request.rows[long[0]].length
- env.warnings.push(
- `${request.rowLabel(long[0])} has ${first} cells for ${headers.length} headers` +
- (long.length > 1 ? ` (and ${long.length - 1} more row(s) have too many)` : '') +
- ', so the cells past the last header were left out; add a header for every column.'
- )
- }
- const cells = request.rows.map(row =>
- normalizeRowLength(row, headers.length).map(cell => parseInlineMarkdown(cell ?? '', onImage))
- )
- const headerCells = headers.map(h => parseInlineMarkdown(h, onImage))
- const fit = layoutPdfTable(
- {
- headers: headerCells.map(plainText),
- rows: cells.map(row => row.map(plainText)),
- requested: request.widths,
- cellPadding: 8,
- ruleWidth: layout === 'grid' ? 0.5 : 0,
- allowLandscape: true,
- label: request.label,
- bottomMargin: env.bottomMargin,
- },
- env.measure,
- env.warnings
- )
- const align = (col: number) =>
- alignments?.[col] && alignments[col] !== 'left' ? { alignment: alignments[col] } : {}
- const node = {
- table: {
- headerRows: 1,
- // Without this a table starting near the foot of a page leaves its
- // header stranded there with every row on the next one.
- ...(fit.keepWithHeaderRows ? { keepWithHeaderRows: 1 } : {}),
- dontBreakRows: fit.dontBreakRows,
- widths: fit.widths,
- body: [
- headerCells.map((h, col) => ({
- ...asPieces(h),
- ...(col === 0 ? { id: `${TABLE_HEADER_ID}${++env.tablesBuilt}` } : {}),
- bold: true,
- color: '#ffffff',
- fillColor: palette.primary,
- ...align(col),
- })),
- // pdfmake accepts a `text` array of inline runs as a cell — use that
- // so **bold** / *italic* / `code` inside cells render correctly.
- ...cells.map(row => row.map((cell, col) => ({ ...asPieces(cell), ...align(col) }))),
- ],
- },
- layout: pdfTableLayout(layout, palette),
- margin: [0, 4, 0, 8],
- ...(fit.fontSize !== BODY_FONT_SIZE ? { fontSize: fit.fontSize } : {}),
- } as Content
- if (fit.landscape) env.landscape.add(node)
- return node
-}
-
-/**
- * Pad/truncate a row to a fixed number of columns. Used by table builders
- * to make ragged input deterministic.
- */
-function normalizeRowLength<T>(row: T[], width: number): (T | '')[] {
- if (row.length === width) return row
- if (row.length > width) return row.slice(0, width)
- return [...row, ...Array<''>(width - row.length).fill('')]
-}
-
-function pdfTableLayout(name: 'striped' | 'minimal' | 'grid', palette: PdfPalette) {
- if (name === 'minimal') {
- return {
- hLineWidth: (i: number, node: { table: { body: unknown[] } }) =>
- i === 0 || i === 1 || i === node.table.body.length ? 0.7 : 0,
- vLineWidth: () => 0,
- hLineColor: () => palette.border,
- }
- }
- if (name === 'grid') {
- return {
- hLineWidth: () => 0.5,
- vLineWidth: () => 0.5,
- hLineColor: () => palette.border,
- vLineColor: () => palette.border,
- }
- }
- return {
- hLineWidth: (i: number, node: { table: { body: unknown[] } }) =>
- i === 0 || i === 1 || i === node.table.body.length ? 0.7 : 0,
- vLineWidth: () => 0,
- hLineColor: () => palette.border,
- fillColor: (rowIndex: number) =>
- rowIndex === 0 ? null : rowIndex % 2 === 0 ? palette.alternateRowFill : null,
- }
-}
-
-/** Read the alignments a GFM separator row declares (`:---`, `---:`, `:---:`). */
-function parseColumnAlignments(separator: string): ColumnAlignment[] {
- return splitTableRow(separator).map(cell => {
- const c = cell.trim()
- const left = c.startsWith(':')
- const right = c.endsWith(':')
- if (left && right) return 'center'
- if (right) return 'right'
- return 'left'
- })
-}
-
-/** Indent width of a list line, used to decide its nesting depth. */
-function indentOf(line: string): number {
- const m = /^[ \t]*/.exec(line)
- if (!m) return 0
- // A tab counts as one level, matching how models write nested lists.
- return m[0].replace(/\t/g, ' ').length
-}
-
-const BULLET_RE = /^[-*+]\s+/
-const ORDERED_RE = /^\d+[.)]\s+/
-
-function isListLine(line: string): boolean {
- const t = line.trimStart()
- return BULLET_RE.test(t) || ORDERED_RE.test(t)
-}
-
-function stripListMarker(line: string): string {
- const t = line.trimStart()
- return t.replace(BULLET_RE, '').replace(ORDERED_RE, '')
-}
-
-/**
- * Build one list level, consuming the lines that belong to it. A line indented
- * further than the level's own indent starts a nested list attached to the item
- * above it, which is what preserves the hierarchy the author wrote.
- */
-function buildList(
- lines: string[],
- start: number,
- indent: number,
- onImage: (image: MarkdownImage) => void
-): { node: Content; next: number } {
- const ordered = ORDERED_RE.test(lines[start].trimStart())
- const items: Content[] = []
- let i = start
-
- while (i < lines.length) {
- if (lines[i].trim() === '') {
- // Blank lines between items keep the list going: models separate
- // numbered steps that way and expect the numbers to continue.
- let j = i
- while (j < lines.length && lines[j].trim() === '') j++
- const continues =
- j < lines.length &&
- isListLine(lines[j]) &&
- (indentOf(lines[j]) > indent ||
- (indentOf(lines[j]) === indent && ORDERED_RE.test(lines[j].trimStart()) === ordered))
- if (!continues) break
- i = j
- continue
- }
- if (!isListLine(lines[i]) || indentOf(lines[i]) < indent) break
- const own = indentOf(lines[i])
- if (own > indent) {
- // Deeper than this level: attach to the previous item as a sub-list.
- const sub = buildList(lines, i, own, onImage)
- const previous = items.pop()
- items.push(previous ? ([previous, sub.node] as unknown as Content) : sub.node)
- i = sub.next
- continue
- }
- const isOrdered = ORDERED_RE.test(lines[i].trimStart())
- // Switching between bullets and numbers at the same indent starts a different list.
- if (isOrdered !== ordered) break
- items.push(asPieces(parseInlineMarkdown(stripListMarker(lines[i]), onImage)))
- i++
- }
-
- // A list that picks up after a code block or a paragraph keeps its numbers.
- const first = ordered ? parseInt(lines[start].trimStart(), 10) : 1
- const node = (
- ordered
- ? { ol: items, ...(first !== 1 ? { start: first } : {}), margin: [0, 4, 0, 6] }
- : { ul: items, margin: [0, 4, 0, 6] }
- ) as Content
- return { node, next: i }
-}
-
-/**
- * Convert a markdown body into pdfmake content nodes: a single-pass line
- * scanner for headings, fenced code, rules, GFM tables, quotes, lists, image
- * lines and paragraphs.
- */
-function bodyToContent(body: string, palette: PdfPalette, env: PdfBodyEnv): Content[] {
- const out: Content[] = []
- const lines = body.split('\n')
- // A paragraph's images are placed after it; anywhere else they are left out
- // with a note rather than printing their path.
- const stray = (image: MarkdownImage) =>
- env.warnings.push(
- `The image '${image.src}' inside a table, list, heading or quote was left out; put ` +
- `![alt](${image.src}) on a line of its own to embed it.`
- )
- let i = 0
- while (i < lines.length) {
- const line = lines[i]
- const trimmed = line.trimStart()
-
- // Fenced code block. Everything up to the closing fence is verbatim, so a
- // shell snippet or a config sample keeps its spacing instead of being
- // reflowed into paragraphs.
- const fence = openingFence(trimmed)
- if (fence) {
- const { marker, language } = fence
- const code: string[] = []
- i++
- while (i < lines.length && !closesFence(lines[i], marker)) {
- code.push(lines[i])
- i++
- }
- i++ // closing fence
- out.push(buildCodeBlock(code.join('\n'), language, palette))
- continue
- }
-
- // Heading levels. The deeper ones share h3's style rather than falling
- // through as literal hashes. headlineLevel marks them for the page-break
- // check that keeps a heading off the foot of a page.
- const heading = /^(#{1,6})\s+(.*)$/.exec(trimmed)
- if (heading) {
- const level = heading[1].length
- const style = level === 1 ? 'h1' : level === 2 ? 'h2' : 'h3'
- const top = level === 1 ? 16 : level === 2 ? 12 : 8
- out.push({
- ...asPieces(parseInlineMarkdown(withoutClosingHashes(heading[2]), stray)),
- style,
- headlineLevel: 1,
- margin: [0, top, 0, level === 1 ? 6 : 4],
- } as Content)
- i++
- continue
- }
-
- // Horizontal rule in any of the three markdown spellings.
- if (/^(-{3,}|\*{3,}|_{3,})$/.test(trimmed.replace(/\s+/g, ''))) {
- out.push({
- canvas: [
- {
- type: 'line',
- x1: 0,
- y1: 0,
- x2: PDF_CONTENT_WIDTH,
- y2: 0,
- lineWidth: 0.5,
- lineColor: palette.border,
- },
- ],
- margin: [0, 8, 0, 8],
- })
- i++
- continue
- }
-
- // GFM pipe table: header line, then separator, then the rows up to the
- // first line without a pipe.
- if (isPipeTableStart(lines, i)) {
- const headers = splitTableRow(line)
- const alignments = parseColumnAlignments(lines[i + 1])
- const rows: string[][] = []
- i += 2
- while (i < lines.length && lines[i].trim() !== '' && lines[i].includes('|')) {
- rows.push(splitTableRow(lines[i]))
- i++
- }
- const label = `The body's table ${++env.tableCount}`
- out.push(
- buildTableNode(
- { headers, rows, alignments, label, rowLabel: index => `${label}, row ${index + 1}` },
- palette,
- env,
- stray
- )
- )
- continue
- }
-
- // Blockquote: consecutive `>` lines become one ruled, indented block.
- if (/^>\s?/.test(trimmed)) {
- const quoted: string[] = []
- while (i < lines.length && /^>\s?/.test(lines[i].trimStart())) {
- quoted.push(lines[i].trimStart().replace(/^>\s?/, ''))
- i++
- }
- out.push(buildBlockquote(quoteParagraphs(quoted), palette, stray))
- continue
- }
-
- // Bullet or numbered list, including anything nested under it.
- if (isListLine(line)) {
- const built = buildList(lines, i, indentOf(line), stray)
- out.push(built.node)
- i = built.next
- continue
- }
-
- // Blank line: small vertical breathing room.
- if (trimmed === '') {
- out.push({ text: '', margin: [0, 2, 0, 2] })
- i++
- continue
- }
-
- // Default: paragraph with inline markdown, then any images it references.
- const images: MarkdownImage[] = []
- const paragraph = parseInlineMarkdown(line, image => images.push(image))
- if (plainText(paragraph).trim() !== '') {
- const pieces = inPieces(paragraph)
- pieces.forEach((piece, p) =>
- out.push({ ...piece, margin: [0, 0, 0, p === pieces.length - 1 ? 4 : 0] })
- )
- }
- for (const image of images) {
- const block = env.image(image.src)
- if (block) out.push(block)
- }
- i++
- }
- return out
-}
-
-/** Monospaced block on a tinted ground, with the language noted when given. */
-function buildCodeBlock(code: string, language: string, palette: PdfPalette): Content {
- const stack: Content[] = []
- if (language) {
- stack.push({
- text: language,
- fontSize: 8,
- color: palette.muted,
- margin: [0, 0, 0, 2],
- })
- }
- stack.push({
- text: code,
- font: PDF_MONO_FAMILY,
- fontSize: 9,
- color: palette.text,
- preserveLeadingSpaces: true,
- lineHeight: 1.25,
- } as Content)
- return {
- table: {
- // A numeric width lets pdfmake break a line with no spaces (base64,
- // minified JSON) inside the block; a '*' column is never narrower than
- // its longest word.
- widths: [PDF_CONTENT_WIDTH - 2],
- body: [[{ stack, margin: [8, 6, 8, 6] }]],
- },
- layout: {
- hLineWidth: () => 0,
- vLineWidth: (i: number) => (i === 0 ? 2 : 0),
- vLineColor: () => palette.border,
- paddingLeft: () => 0,
- paddingRight: () => 0,
- paddingTop: () => 0,
- paddingBottom: () => 0,
- fillColor: () => palette.surface,
- },
- margin: [0, 6, 0, 8],
- } as Content
-}
-
-/** Quoted passage, set off by a rule down its left edge. */
-function buildBlockquote(
- paragraphs: string[],
- palette: PdfPalette,
- onImage: (image: MarkdownImage) => void
-): Content {
- return {
- table: {
- widths: [PDF_CONTENT_WIDTH - 2.5],
- body: [
- [
- {
- stack: paragraphs.flatMap((text, n) => {
- const pieces = inPieces(parseInlineMarkdown(text, onImage))
- return pieces.map((piece, p) => ({
- ...piece,
- margin: [0, 0, 0, p === pieces.length - 1 && n < paragraphs.length - 1 ? 4 : 0],
- }))
- }),
- italics: true,
- color: palette.muted,
- margin: [10, 4, 6, 4],
- },
- ],
- ],
- },
- layout: {
- hLineWidth: () => 0,
- vLineWidth: (i: number) => (i === 0 ? 2.5 : 0),
- vLineColor: () => palette.primary,
- paddingLeft: () => 0,
- paddingRight: () => 0,
- paddingTop: () => 0,
- paddingBottom: () => 0,
- },
- margin: [0, 6, 0, 8],
- } as Content
-}
-
-function statusColorFromPalette(palette: PdfPalette, status?: string): string | undefined {
- if (!status) return undefined
- const s = status.toLowerCase()
- if (s === 'green' || s === 'ok' || s === 'pass') return palette.statusGreen
- if (s === 'yellow' || s === 'warn' || s === 'warning') return palette.statusYellow
- if (s === 'red' || s === 'critical' || s === 'fail') return palette.statusRed
- // Unknown status keyword — fall back to muted accent so the band still
- // renders (matching the documented "status indicator color" behavior)
- // instead of silently dropping the cover-page band.
- return palette.muted
-}
-
-const IMAGE_ALIGNMENTS = new Set(['left', 'center', 'right'])
-
-/** Where images come from, for the schema: the name clerum__generate_chart reports. */
-const IMAGE_FILE_DESCRIPTION =
- "File name of a PNG or JPEG (GIF, WebP and SVG are converted) in the output folder, as returned by clerum__generate_chart, e.g. 'sales.png'."
-
-/**
- * pdfmake 0.2 calls this with the nodes that follow on the same page as its
- * second argument (the bundled typings describe 0.3's query object instead).
- * A heading with nothing after it on its page but more content on the next
- * page is moved there, so it is never left alone at the foot of a page.
- */
-function keepHeadingWithNext(node: Node, followingOnPage: Node[]): boolean {
- if (
- node.headlineLevel !== 1 ||
- node.pageNumbers.length !== 1 ||
- node.pageNumbers[0] >= node.pages ||
- // Already at the top of its page: moving it would only leave a blank page.
- node.startPosition.top <= PDF_TOP_MARGIN + 20
- ) {
- return false
- }
- const following = followingOnPage.filter(next => next.style !== RUNNING_STYLE)
- const content = following.find(next => next.headlineLevel !== 1)
- if (!content) return true
- // A table whose header row did not fit is carried to the next page whole,
- // yet its cells are still listed on this one; only the header id says so.
- const headerId = tableHeaderId(content)
- if (headerId === undefined) return false
- const header = following.find(next => next.id === headerId)
- return header?.startPosition.pageNumber !== node.pageNumbers[0]
-}
-
-/**
- * pdfmake hands a pageBreakBefore callback the nodes after each node on its
- * page, which it collects by scanning the rest of the document for every node,
- * and each break the callback asks for lays the whole document out again. Past
- * these sizes the check costs more than a heading left at the foot of a page.
- */
-const KEEP_WITH_NEXT_MAX_NODES = 1500
-const KEEP_WITH_NEXT_MAX_MOVES = 10
-
-/** How many nodes pdfmake lays out for `content`, counted up to `limit`. */
-function countNodes(content: unknown, limit: number): number {
- let count = 0
- const visit = (node: unknown): void => {
- if (count > limit || node === null || typeof node !== 'object') return
- if (Array.isArray(node)) {
- for (const item of node) visit(item)
- return
- }
- count++
- const n = node as Record<string, unknown>
- for (const key of ['stack', 'ul', 'ol', 'columns']) visit(n[key])
- const table = n.table as { body?: unknown } | undefined
- if (table) visit(table.body)
- }
- visit(content)
- return count
-}
-
-/** keepHeadingWithNext for `content`, or undefined when the document is too large for it. */
-function headingKeeper(
- content: Content[]
-): ((node: Node, following: Node[]) => boolean) | undefined {
- if (countNodes(content, KEEP_WITH_NEXT_MAX_NODES) > KEEP_WITH_NEXT_MAX_NODES) return undefined
- let moves = 0
- return (node: Node, following: Node[]) => {
- if (moves >= KEEP_WITH_NEXT_MAX_MOVES || !keepHeadingWithNext(node, following)) return false
- moves++
- return true
- }
-}
-
-/** The id buildTableNode gave a table's header; a right-to-left table has it last. */
-function tableHeaderId(node: Node): string | undefined {
- const header = (node as { table?: { body?: Array<Array<{ id?: unknown }>> } }).table?.body?.[0]
- const id = Array.isArray(header)
- ? header.find(cell => typeof cell?.id === 'string')?.id
- : undefined
- return typeof id === 'string' && id.startsWith(TABLE_HEADER_ID) ? id : undefined
-}
-
-/** Note for a PDF or DOCX written with nothing in it. */
-const EMPTY_DOCUMENT_NOTE =
- 'The document is empty: body has no text, and no title, table or image was given. ' +
- 'Pass the text to write as body.'
-
-/** The spacer bodyToContent leaves for a blank line. */
-function isBlankLine(node: Content): boolean {
- return typeof node === 'object' && node !== null && 'text' in node && node.text === ''
-}
-
-/**
- * Put each landscape table on landscape pages and return to portrait after
- * it. A heading directly above such a table moves with it. Returns the
- * orientation the document starts in.
- */
-function applyPageOrientation(
- content: Content[],
- landscape: Set<Content>
-): 'portrait' | 'landscape' {
- const previous = (i: number) => {
- let k = i - 1
- while (k >= 0 && isBlankLine(content[k])) k--
- return k
- }
- let initial: 'portrait' | 'landscape' = 'portrait'
- let current: 'portrait' | 'landscape' = 'portrait'
- for (let i = 0; i < content.length; i++) {
- if (isBlankLine(content[i])) continue
- const wanted = landscape.has(content[i]) ? 'landscape' : 'portrait'
- if (wanted === current) continue
- current = wanted
- let target = i
- const above = content[previous(i)] as { headlineLevel?: number } | undefined
- if (wanted === 'landscape' && above?.headlineLevel === 1) target = previous(i)
- // A break before the first node, or after the one that already ends the
- // cover page, would leave a blank page; those carry the orientation instead.
- const before = previous(target)
- if (before < 0) {
- initial = wanted
- } else if ((content[before] as { pageBreak?: string }).pageBreak === 'after') {
- Object.assign(content[before] as object, { pageOrientation: wanted })
- } else {
- Object.assign(content[target] as object, { pageBreak: 'before', pageOrientation: wanted })
- }
- }
- return initial
-}
-
-/** More characters than a header or footer line ever holds at the running size. */
-const RUNNING_LINE_CHARS = 400
-
-/** The longest start of `chars` that fits `fits`, at least one character. */
-function longestFitting(chars: string[], fits: (text: string) => boolean): number {
- let lo = 1
- let hi = chars.length
- while (lo < hi) {
- const mid = Math.ceil((lo + hi) / 2)
- if (fits(chars.slice(0, mid).join(''))) lo = mid
- else hi = mid - 1
- }
- return lo
-}
-
-/**
- * The footer text as the lines it will take, cut to what the bottom margin
- * can hold, with a note when anything is cut.
- */
-function footerLines(
- text: string,
- width: number,
- measure: UnitMeasure,
- warnings: string[]
-): string[] {
- // Lines break where the typesetter breaks them, or the footer outgrows its margin.
- const fits = (s: string) => measure(s, false) * PDF_FOOTER_SIZE <= width * LINE_FILL
- // Far more characters than a footer line holds, so a huge word is never measured whole.
- const tooWide = (s: string) => s.length > RUNNING_LINE_CHARS || !fits(s)
- const lines: string[] = []
- // Counting stops one line past the most the footer holds.
- const full = () => lines.length > PDF_MAX_FOOTER_LINES
- for (const source of text.split('\n')) {
- let line = ''
- for (const word of source.split(/(\s+)/)) {
- if (full()) break
- if (line.trim() && tooWide(line + word)) {
- lines.push(line.trimEnd())
- line = word.trimStart()
- } else {
- line += word
- }
- // A word wider than the line, such as a long URL, takes as many lines as it fills.
- while (!full() && tooWide(line)) {
- const head = Array.from(line.slice(0, RUNNING_LINE_CHARS))
- if (head.length <= 1) break
- const piece = head.slice(0, longestFitting(head, fits)).join('')
- lines.push(piece)
- line = line.slice(piece.length)
- }
- }
- if (full()) break
- lines.push(line.trimEnd())
- }
- if (!full()) return lines
- warnings.push(
- `branding.footerText takes more than ${PDF_MAX_FOOTER_LINES} lines, the most that fit in the ` +
- 'footer, so the rest was cut. Keep it to a line or two.'
- )
- const kept = lines.slice(0, PDF_MAX_FOOTER_LINES)
- kept[kept.length - 1] = `${kept[kept.length - 1]}...`
- return kept
-}
-
-/**
- * `text` cut at a word, with an ellipsis, to one line of the running header,
- * where pdfmake drops whatever does not fit without a mark.
- */
-function runningLine(text: string, width: number, measure: UnitMeasure): string {
- const fits = (s: string) => measure(s, false) * PDF_FOOTER_SIZE <= width * LINE_FILL
- if (text.length <= RUNNING_LINE_CHARS && fits(text)) return text
- // Far more than a line holds, so a huge title is never measured whole.
- const chars = Array.from(text.slice(0, RUNNING_LINE_CHARS))
- let kept = chars
- .slice(
- 0,
- longestFitting(chars, s => fits(`${s.trimEnd()}…`))
- )
- .join('')
- const space = kept.lastIndexOf(' ')
- if (space > kept.length * 0.6) kept = kept.slice(0, space)
- return `${kept.trimEnd()}…`
-}
-
const generatePdf: InternalToolDefinition = {
name: 'clerum__generate_pdf',
description:
@@ -2575,384 +494,13 @@ const generatePdf: InternalToolDefinition = {
},
required: ['filename', 'body'],
},
- async execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
- try {
- const filename = outputFilename(args.filename, 'pdf', 'output')
- const warnings: string[] = []
- const glyphs = pdfGlyphSource()
- // Titles take no formatting, so HTML in them is read as text.
- const title = args.title ? htmlToPlainText(String(args.title)) || undefined : undefined
- const body = String(args.body ?? '')
- const paletteName = String(args.palette ?? 'default')
- const palette = PDF_PALETTES[paletteName] ?? PDF_PALETTES.default
- const branding: PdfBranding = printedBranding(args.branding)
- const imageRefs = Array.isArray(args.images) ? args.images : []
- const tables = (Array.isArray(args.tables) ? args.tables : []) as PdfTableSpec[]
- const coverPage = Boolean(args.coverPage)
- const headline = args.headline
- ? htmlToPlainText(String(args.headline)) || undefined
- : undefined
- const statusBand = statusColorFromPalette(palette, args.statusColor as string | undefined)
-
- // A path outside the output folder still fails the call, but says what to pass instead.
- const loadImage = (ref: unknown, label: string) => {
- try {
- return loadEmbeddableImage(ref, outputDir, warnings, label)
- } catch (err) {
- const reason = err instanceof Error ? err.message : String(err)
- throw new Error(
- `${label}: ${reason}. Images are read from the output folder; pass the file name ` +
- "clerum__generate_chart returned, such as 'sales.png'."
- )
- }
- }
-
- // The footer sets the bottom margin, and with it the room images and tables have.
- const pageNumberWidth = 40
- // Measured at 100pt and scaled down: at 1pt the canvas rounds widths to hundredths.
- const measure: UnitMeasure = (text, bold) =>
- glyphs.measure(text, PDF_FONT_FAMILY, 100, bold) / 100
- const footer = branding.footerText
- ? footerLines(branding.footerText, PDF_CONTENT_WIDTH - pageNumberWidth, measure, warnings)
- : []
- const bottomMargin = Math.max(MIN_BOTTOM_MARGIN, 34 + footer.length * PDF_FOOTER_SIZE * 1.3)
- const contentHeight = PORTRAIT.height - (bottomMargin - MIN_BOTTOM_MARGIN)
-
- let imagesRequested = 0
- let imagesPlaced = 0
- const placeImage = (
- ref: unknown,
- label: string,
- sizing: { width?: unknown; height?: unknown; alignment?: unknown } = {}
- ): Content | undefined => {
- imagesRequested++
- const src = typeof ref === 'string' ? ref : undefined
- if (src && /^(https?:|data:)/i.test(src)) {
- warnings.push(
- `${label} is a web address or inline data, which is not downloaded; save the image to the ` +
- 'output folder first (clerum__generate_chart does) and pass its file name.'
- )
- return undefined
- }
- const image = loadImage(ref, label)
- if (!image) return undefined
- const requested = {
- ...(typeof sizing.width === 'number' ? { width: sizing.width } : {}),
- ...(typeof sizing.height === 'number' ? { height: sizing.height } : {}),
- }
- const sized = requested.width !== undefined || requested.height !== undefined
- const box = fitImageSize(
- image,
- {
- width: PDF_CONTENT_WIDTH,
- // An image given a size may take the page, less its own margins.
- height: sized ? contentHeight - 2 * PDF_IMAGE_MARGIN : PDF_MAX_IMAGE_HEIGHT,
- },
- requested
- )
- imagesPlaced++
- return {
- image: imageDataUrl(image),
- width: box.width,
- height: box.height,
- alignment: IMAGE_ALIGNMENTS.has(String(sizing.alignment)) ? sizing.alignment : 'center',
- margin: [0, PDF_IMAGE_MARGIN, 0, PDF_IMAGE_MARGIN],
- } as Content
- }
-
- const env: PdfBodyEnv = {
- warnings,
- measure,
- image: src => placeImage(src, `The body image '${src}'`),
- landscape: new Set(),
- tableCount: 0,
- tablesBuilt: 0,
- bottomMargin,
- }
-
- const content: Content[] = []
-
- // Cover page.
- if (coverPage) {
- const coverTitle = title ?? headline ?? filename.replace(/\.pdf$/, '')
- if (!title) {
- warnings.push(
- `coverPage was set without a title, so the cover shows '${coverTitle}'; pass title to choose it.`
- )
- }
- if (statusBand) {
- content.push({
- canvas: [
- {
- type: 'rect',
- x: 0,
- y: 0,
- w: PDF_CONTENT_WIDTH,
- h: 6,
- color: statusBand,
- },
- ],
- margin: [0, 0, 0, 24],
- })
- }
- if (branding.logoPath) {
- const logo = loadImage(branding.logoPath, 'branding.logoPath')
- if (logo) {
- const box = fitImageSize(logo, PDF_LOGO_BOX, { width: PDF_LOGO_BOX.width })
- content.push({
- image: imageDataUrl(logo),
- width: box.width,
- height: box.height,
- margin: [0, 0, 0, 12],
- })
- }
- }
- content.push({
- text: coverTitle,
- style: 'cover',
- color: palette.primary,
- margin: [0, 80, 0, 12],
- })
- if (headline && title) {
- content.push({
- text: headline,
- style: 'lead',
- color: palette.muted,
- margin: [0, 0, 0, 20],
- })
- }
- content.push({
- text: new Date().toLocaleDateString('en-US', {
- year: 'numeric',
- month: 'long',
- day: 'numeric',
- }),
- color: palette.muted,
- fontSize: 11,
- margin: [0, 0, 0, 0],
- pageBreak: 'after',
- })
- } else {
- if (title) {
- content.push({
- text: title,
- style: 'docTitle',
- color: palette.primary,
- margin: [0, 0, 0, 12],
- })
- }
- const coverOnly = [
- headline ? 'headline' : '',
- args.statusColor ? 'statusColor' : '',
- branding.logoPath ? 'branding.logoPath' : '',
- ].filter(Boolean)
- if (coverOnly.length > 0) {
- const many = coverOnly.length > 1
- warnings.push(
- `${coverOnly.join(', ')} ${many ? 'are' : 'is'} only drawn on the cover page, so ` +
- `${many ? 'they were' : 'it was'} left out; pass coverPage: true to show ${many ? 'them' : 'it'}.`
- )
- }
- }
-
- // Body.
- content.push(...bodyToContent(body, palette, env))
-
- // Tables (after body).
- tables.forEach((t, index) => {
- const label = `tables[${index}]`
- if (!t || !Array.isArray(t.headers) || t.headers.length === 0) {
- warnings.push(`${label} has no headers and was left out; pass headers: ['Column', ...].`)
- return
- }
- const rows = normalizeTableRows(t.rows, t.headers, label, warnings).map(row =>
- row.map(cell => (cell === null || cell === undefined ? '' : String(cell)))
- )
- content.push(
- buildTableNode(
- {
- headers: t.headers.map(headerText),
- rows,
- layout: t.layout,
- widths: t.widths,
- label,
- rowLabel: row => `${label}.rows[${row}]`,
- },
- palette,
- env,
- image =>
- warnings.push(
- `${label} names the image '${image.src}' in a cell, which a table cannot hold; pass it in images instead.`
- )
- )
- )
- })
-
- // Images (charts, logos) at the end of the body.
- imageRefs.forEach((ref, index) => {
- const sizing = ref && typeof ref === 'object' ? (ref as PdfImageRef) : {}
- const block = placeImage(ref, `images[${index}]`, sizing)
- if (block) content.push(block)
- })
-
- if (imagesRequested > 0 && imagesPlaced === 0 && content.every(isBlankLine)) {
- return {
- success: false,
- error: `No PDF was written: none of the images could be embedded. ${warnings.join(' ')}`,
- }
- }
- if (content.every(isBlankLine)) warnings.push(EMPTY_DOCUMENT_NOTE)
-
- const pageOrientation = applyPageOrientation(content, env.landscape)
-
- const styles: Record<string, Record<string, unknown>> = {
- cover: { fontSize: 36, bold: true },
- lead: { fontSize: 16, italics: true },
- docTitle: { fontSize: 22, bold: true },
- h1: { fontSize: 18, bold: true, color: palette.primary },
- h2: { fontSize: 14, bold: true, color: palette.primary },
- h3: { fontSize: 12, bold: true, color: palette.muted },
- [RUNNING_STYLE]: { fontSize: PDF_FOOTER_SIZE, color: palette.muted },
- }
- const typesetter = new PdfTypesetter(glyphs, styles)
- const base = {
- width: PDF_CONTENT_WIDTH,
- font: PDF_FONT_FAMILY,
- fontSize: BODY_FONT_SIZE,
- bold: false,
- lineHeight: PDF_LINE_HEIGHT,
- }
- typesetter.typeset(content, base)
-
- // The running header and footer are laid out on every page, so their text
- // is typeset once here and copied into each page's nodes.
- const running = (text: string | undefined, width: number): ContentText => {
- const node: ContentText = { text: text ?? '', style: RUNNING_STYLE }
- typesetter.typeset(node, { ...base, width })
- return node
- }
- // The title is printed whole on the first page; the running header takes one line of it.
- const half = PDF_CONTENT_WIDTH / 2
- const company = branding.companyName && runningLine(branding.companyName, half, measure)
- if (company && company !== branding.companyName) {
- warnings.push(
- 'branding.companyName is longer than the page header and was shortened there.'
- )
- }
- const companyNode = running(company || undefined, half)
- const headerTitleNode = running(title && runningLine(title, half, measure), half)
- const footerNode = running(footer.join('\n'), PDF_CONTENT_WIDTH - pageNumberWidth)
- typesetter.settleShaping()
- const copy = (node: ContentText): ContentText => JSON.parse(JSON.stringify(node))
-
- const docDef: TDocumentDefinitions = {
- info: {
- title: title ?? 'Report',
- ...(branding.companyName ? { creator: branding.companyName } : {}),
- },
- pageSize: 'A4',
- pageOrientation,
- pageMargins: [40, PDF_TOP_MARGIN, 40, bottomMargin],
- defaultStyle: {
- font: PDF_FONT_FAMILY,
- fontSize: BODY_FONT_SIZE,
- color: palette.text,
- lineHeight: PDF_LINE_HEIGHT,
- },
- styles,
- pageBreakBefore: headingKeeper(
- content
- ) as unknown as TDocumentDefinitions['pageBreakBefore'],
- header: (currentPage: number) =>
- currentPage === 1 && coverPage
- ? null
- : {
- columns: [copy(companyNode), { ...copy(headerTitleNode), alignment: 'right' }],
- style: RUNNING_STYLE,
- margin: [40, 24, 40, 0],
- },
- footer: (currentPage: number, pageCount: number) => ({
- columns: [
- copy(footerNode),
- {
- text: `${currentPage} / ${pageCount}`,
- style: RUNNING_STYLE,
- alignment: 'right',
- width: pageNumberWidth,
- },
- ],
- style: RUNNING_STYLE,
- margin: [40, 0, 40, 24],
- }),
- content,
- }
-
- // Han characters take the glyph forms of the document's language.
- const language = documentEastAsianScript(
- [
- title,
- body,
- branding.companyName,
- branding.footerText,
- ...tables.map(t => JSON.stringify([t.headers, t.rows])),
- ]
- .filter(text => text !== undefined && text !== null)
- .map(String)
- .join('\n')
- )?.lang.slice(0, 2)
- const printer = new PdfPrinter(glyphs.descriptors(typesetter.families, language))
- const pdfDoc = printer.createPdfKitDocument(docDef)
-
- const pdfBuffer: Buffer = await new Promise((resolve, reject) => {
- const chunks: Buffer[] = []
- pdfDoc.on('data', (c: Buffer) => chunks.push(c))
- pdfDoc.on('end', () => resolve(Buffer.concat(chunks)))
- pdfDoc.on('error', reject)
- pdfDoc.end()
- })
-
- ensureDir(outputDir)
- const target = claimOutputFile(outputDir, filename)
- enforceQuota(outputDir, pdfBuffer.byteLength, replacedBytes(target))
- fs.writeFileSync(target.filePath, pdfBuffer)
-
- return artifactResult(target, 'pdf', { warnings: [...warnings, ...typesetter.warnings()] })
- } catch (err) {
- return { success: false, error: err instanceof Error ? err.message : String(err) }
- }
+ execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
+ return runGeneratePdf(args, outputDir)
},
}
// ─── generate_docx ───────────────────────────────────────────────────
-/** Largest logo drawn above the title, in pixels. */
-const DOCX_LOGO_BOX = { width: 160, height: 60 }
-
-/** Footer lines kept, as in the PDF. */
-const DOCX_MAX_FOOTER_LINES = 6
-
-const DOCX_IMAGE_FILE_DESCRIPTION =
- "File name in the output folder, as returned by clerum__generate_chart (e.g. 'sales.png'). " +
- 'PNG, JPEG, GIF, WebP or SVG.'
-
-interface DocxBranding {
- companyName?: string
- logoPath?: string
- footerText?: string
-}
-
-interface DocxImageArg {
- width?: number
- height?: number
- alignment?: string
-}
-
-interface DocxTableArg {
- headers?: unknown
- rows?: unknown
- layout?: unknown
-}
-
const generateDocx: InternalToolDefinition = {
name: 'clerum__generate_docx',
description:
@@ -3060,2180 +608,256 @@ const generateDocx: InternalToolDefinition = {
},
required: ['filename', 'body'],
},
- async execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
- try {
- const filename = outputFilename(args.filename, 'docx', 'output')
- const title = args.title ? htmlToPlainText(String(args.title)) : undefined
- const headline = args.headline ? htmlToPlainText(String(args.headline)) : undefined
- const body = String(args.body ?? '')
- const palette = DOCX_PALETTES[String(args.palette ?? 'default')] ?? DOCX_PALETTES.default
- const branding: DocxBranding = printedBranding(args.branding)
- const images: unknown[] = Array.isArray(args.images) ? args.images : []
- const tables: unknown[] = Array.isArray(args.tables) ? args.tables : []
- const warnings: string[] = []
- const numbering = new DocxListNumbering()
- const imageBox = { width: DOCX_MAX_IMAGE_WIDTH, height: DOCX_MAX_IMAGE_HEIGHT }
- let embedded = 0
- let imageLeftOut = false
- const embed = (
- ref: unknown,
- label: string,
- box: { width: number; height: number },
- placement: DocxImagePlacement
- ): Paragraph | undefined => {
- const paragraph = docxImageParagraph(ref, outputDir, box, placement, warnings, label)
- if (paragraph) embedded++
- else imageLeftOut = true
- return paragraph
- }
-
- const children: (Paragraph | DocxTable)[] = []
-
- if (branding.logoPath) {
- const logo = embed(branding.logoPath, 'branding.logoPath', DOCX_LOGO_BOX, {
- spacing: { after: 160 },
- })
- if (logo) children.push(logo)
- }
- if (title) {
- children.push(
- new Paragraph({
- ...docxDirection(title),
- heading: HeadingLevel.TITLE,
- spacing: { after: 120 },
- children: textRuns(
- title,
- { bold: true, color: docxHex(palette.primary), size: 48 },
- eastAsianScript(title)
- ),
- })
- )
- }
- if (headline) {
- children.push(
- new Paragraph({
- ...docxDirection(headline),
- spacing: { after: 240 },
- children: textRuns(
- headline,
- { italics: true, color: docxHex(palette.muted), size: 26 },
- eastAsianScript(headline)
- ),
- })
- )
- }
-
- children.push(
- ...bodyToDocxChildren(body, {
- palette,
- numbering,
- warnings,
- image: (file, alt) =>
- embed(file, 'body', imageBox, {
- altText: alt,
- spacing: { before: 120, after: 120 },
- }),
- })
- )
-
- let tablesWritten = 0
- const tableTexts: unknown[] = []
- tables.forEach((table, i) => {
- const spec = (table && typeof table === 'object' ? table : {}) as DocxTableArg
- const headers = Array.isArray(spec.headers) ? spec.headers : []
- if (headers.length === 0) {
- warnings.push(
- `tables[${i}] has no headers and was left out; give it a headers array of column names.`
- )
- return
- }
- const rows = normalizeTableRows(spec.rows, headers, `tables[${i}]`, warnings)
- tableTexts.push(...headers)
- for (const row of rows) tableTexts.push(...row)
- const layout = spec.layout === 'minimal' || spec.layout === 'grid' ? spec.layout : 'striped'
- children.push(buildDocxTable(headers, rows, palette, layout, warnings, `tables[${i}]`))
- children.push(new Paragraph({ children: [new TextRun({ text: '' })] }))
- tablesWritten++
- })
-
- images.forEach((img, i) => {
- const spec = (img && typeof img === 'object' ? img : {}) as DocxImageArg
- const paragraph = embed(img, `images[${i}]`, imageBox, {
- width: spec.width,
- height: spec.height,
- alignment: spec.alignment,
- spacing: { before: 160, after: 160 },
- })
- if (paragraph) children.push(paragraph)
- })
-
- if (embedded === 0 && !title && !headline && tablesWritten === 0 && !bodyHasText(body)) {
- if (warnings.length > 0) {
- const hint = imageLeftOut
- ? ' Pass images as file names in the output folder, such as those clerum__generate_chart returns.'
- : ''
- return {
- success: false,
- error: `Nothing could be written to ${filename}. ${[...new Set(warnings)].join(' ')}${hint}`,
- }
- }
- warnings.push(EMPTY_DOCUMENT_NOTE)
- }
-
- // The page number follows the first footer line; the docx lib writes it as
- // a field Word fills in on open. The other lines are run from a leading
- // newline and lose its empty run, so each starts on a line of its own.
- const footerMuted = { color: docxHex(palette.muted), size: 18 }
- const footerLines = (branding.footerText ?? '').replace(/\r\n?/g, '\n').split('\n')
- if (footerLines.length > DOCX_MAX_FOOTER_LINES) {
- warnings.push(
- `branding.footerText takes ${footerLines.length} lines, but only ` +
- `${DOCX_MAX_FOOTER_LINES} fit in the footer, so the rest was cut. Keep it to a line or two.`
- )
- footerLines.length = DOCX_MAX_FOOTER_LINES
- footerLines[DOCX_MAX_FOOTER_LINES - 1] += '...'
- }
- const [firstFooterLine, ...moreFooterLines] = footerLines
- const headerMuted = { color: docxHex(palette.muted), size: 18 }
- const companyName = branding.companyName ?? ''
- // The page number and the title sit at the right margin, on a right tab
- // stop at the width of the section's page.
- const running = (width: number) => {
- const tabStops = [{ type: TabStopType.RIGHT, position: width }]
- const footer = new DocxFooter({
- children: [
- new Paragraph({
- alignment: AlignmentType.LEFT,
- tabStops,
- children: [
- ...textRuns(firstFooterLine, footerMuted, eastAsianScript(firstFooterLine)),
- new TextRun({ text: '\t', ...footerMuted }),
- new TextRun({ children: ['Page ', PageNumber.CURRENT], ...footerMuted }),
- new TextRun({ children: [' / ', PageNumber.TOTAL_PAGES], ...footerMuted }),
- ...(moreFooterLines.length > 0
- ? textRuns(
- `\n${moreFooterLines.join('\n')}`,
- footerMuted,
- eastAsianScript(moreFooterLines.join(' '))
- ).slice(1)
- : []),
- ],
- }),
- ],
- })
- const header = new DocxHeader({
- children: [
- new Paragraph({
- alignment: AlignmentType.LEFT,
- tabStops,
- children: [
- ...textRuns(companyName, headerMuted, eastAsianScript(companyName)),
- new TextRun({ text: '\t', ...headerMuted }),
- ...textRuns(title ?? '', headerMuted, eastAsianScript(title ?? '')),
- ],
- }),
- ],
- })
- return { header, footer }
- }
- const portrait = running(DOCX_CONTENT_WIDTH_TWIPS)
- const landscape = running(DOCX_LANDSCAPE_CONTENT_WIDTH_TWIPS)
-
- // Runs of Han characters alone name no East Asian face and take this one.
- const eastAsia = documentEastAsianScript(
- [title, headline, body, branding.companyName, branding.footerText, ...tableTexts]
- .filter((text): text is string => typeof text === 'string')
- .join('\n')
- )
- const doc = new DocxDocument({
- creator: branding.companyName ?? '',
- title: title ?? 'Report',
- description: headline,
- styles: {
- default: {
- document: {
- run: {
- font: {
- ascii: DOCX_LATIN_FONT,
- hAnsi: DOCX_LATIN_FONT,
- cs: DOCX_COMPLEX_FONT,
- ...(eastAsia ? { eastAsia: eastAsia.font } : {}),
- },
- ...(eastAsia ? { language: { eastAsia: eastAsia.lang } } : {}),
- size: 22,
- color: docxHex(palette.text),
- },
- paragraph: { spacing: { line: 320, after: 80 } },
- },
- },
- },
- numbering: { config: numbering.config() },
- sections: docxSections(children).map(section => ({
- properties: section.landscape
- ? { page: { size: { orientation: PageOrientation.LANDSCAPE } } }
- : {},
- headers: { default: (section.landscape ? landscape : portrait).header },
- footers: { default: (section.landscape ? landscape : portrait).footer },
- children: section.children,
- })),
- })
-
- const buffer = await Packer.toBuffer(doc)
- ensureDir(outputDir)
- const target = claimOutputFile(outputDir, filename)
- enforceQuota(outputDir, buffer.byteLength, replacedBytes(target))
- fs.writeFileSync(target.filePath, buffer)
-
- return artifactResult(target, 'docx', { warnings: [...new Set(warnings)] })
- } catch (err) {
- return { success: false, error: err instanceof Error ? err.message : String(err) }
- }
+ execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
+ return runGenerateDocx(args, outputDir)
},
}
// ─── generate_xlsx ───────────────────────────────────────────────────
-const XLSX_CELL_SCHEMA = {
- type: ['string', 'number', 'boolean', 'null'],
- description:
- 'A number, text, true/false, or null for empty. Text like "1,234.50", "$1,200", "45%" ' +
- 'or an ISO date or datetime ("2026-09-22") is stored as a number or date; leading-zero codes and ' +
- 'numbers over 15 digits stay text.',
-}
-
-const XLSX_IMAGE_PATH_DESCRIPTION =
- "File name in the output folder, as returned by clerum__generate_chart (e.g. 'sales.png')."
-
-const XLSX_COLOR = 'hex such as "#1e3a8a" or a basic color name such as "green"'
-
-const generateXlsx: InternalToolDefinition = {
- name: 'clerum__generate_xlsx',
- description:
- 'Generate a styled Excel (.xlsx) workbook: per sheet, rows plus an optional title row, ' +
- 'column formats, conditional formatting and images such as charts. Formulas are not ' +
- 'supported: text starting with "=" stays text.',
- parameters: {
- type: 'object',
- properties: {
- filename: {
- type: 'string',
- description: "Output filename (e.g. 'data.xlsx'); .xlsx added if missing.",
- },
- palette: {
- type: 'string',
- enum: ['default', 'corporate', 'warm', 'alert'],
- description: "Color palette. Default 'default'.",
- },
- branding: {
- type: 'object',
- description: 'Workbook-level branding.',
- properties: {
- companyName: { type: 'string', description: 'Author/company in workbook properties.' },
- logoPath: {
- type: 'string',
- description:
- 'Logo at the top of the first sheet; an image file name as in sheets[].images.',
- },
- },
- },
- sheets: {
- type: 'array',
- description: 'Worksheets, in tab order.',
- items: {
- type: 'object',
- required: ['name', 'rows'],
- properties: {
- name: {
- type: 'string',
- description: 'Tab name: up to 31 characters, none of \\ / ? * : [ ].',
- },
- headers: {
- type: 'array',
- description: 'Header row, when it is not the first row of rows.',
- items: { type: ['string', 'number'], description: 'Column header.' },
- },
- rows: {
- type: 'array',
- description:
- 'Rows of cells; the first is the header row unless headers is given. [] for an images-only sheet.',
- items: {
- anyOf: [
- {
- type: 'array',
- description: 'One row, left to right.',
- items: XLSX_CELL_SCHEMA,
- },
- RECORD_ROW_SCHEMA,
- ],
- },
- },
- titleRow: {
- type: 'object',
- description: 'Merged title row above the header.',
- properties: {
- text: { type: 'string', description: 'Title text.' },
- fillColor: { type: 'string', description: `Background: ${XLSX_COLOR}.` },
- fontColor: { type: 'string', description: `Text color: ${XLSX_COLOR}.` },
- },
- required: ['text'],
- },
- columnFormats: {
- type: 'object',
- description:
- "Format per column, keyed by header text, letter ('B') or 0-based index: " +
- 'currencyUsd, currencyUsdInt, currency:EUR (any ISO code), percent (0.45 = 45%), ' +
- 'percentPoints (45 = 45%), integer, decimal, plain (no separators: years, IDs), ' +
- "date, datetime, text (as sent), or an Excel code like '#,##0.0'. Others are inferred.",
- },
- conditionalFormatting: {
- type: 'array',
- description: "Style a column's cells that match a rule.",
- items: {
- type: 'object',
- required: ['column', 'rules'],
- properties: {
- column: {
- type: ['string', 'number'],
- description: "Header text, letter ('B') or 0-based index.",
- },
- rules: {
- type: 'array',
- description:
- "Tested in order; the first match styles the cell. '45%' compares as 45, '$1,200' as 1200.",
- items: {
- type: 'object',
- properties: {
- equals: {
- type: ['string', 'number', 'boolean'],
- description: 'Cell equals this (text ignores case and outer spaces).',
- },
- notEquals: {
- type: ['string', 'number', 'boolean'],
- description: 'Cell differs from this, compared as for equals.',
- },
- greaterThan: {
- type: 'number',
- description: 'Cell is a number above this.',
- },
- lessThan: {
- type: 'number',
- description: 'Cell is a number below this.',
- },
- between: {
- type: 'array',
- items: { type: 'number' },
- minItems: 2,
- maxItems: 2,
- description: 'Inclusive [min, max].',
- },
- contains: {
- type: 'string',
- description: 'Cell text contains this, ignoring case.',
- },
- regex: {
- type: 'string',
- maxLength: 256,
- description:
- 'Regex tested on the cell text. Invalid patterns and nested unbounded quantifiers are skipped with a warning.',
- },
- fillColor: {
- type: 'string',
- description: `Background: ${XLSX_COLOR}.`,
- },
- fontColor: {
- type: 'string',
- description: `Text color: ${XLSX_COLOR}.`,
- },
- bold: {
- type: 'boolean',
- description: 'Bold the text.',
- },
- },
- },
- },
- },
- },
- },
- freezeHeader: {
- type: 'boolean',
- description: 'Freeze the header row. Default true.',
- },
- autoFilter: {
- type: 'boolean',
- description: 'Filter buttons on the header. Default true.',
- },
- images: {
- type: 'array',
- description:
- 'Images such as charts; without anchor or range they stack below the data.',
- items: {
- anyOf: [
- { type: 'string', description: XLSX_IMAGE_PATH_DESCRIPTION },
- {
- type: 'object',
- required: ['path'],
- properties: {
- path: { type: 'string', description: 'Same as the string form.' },
- anchor: { type: 'string', description: "Top-left cell, e.g. 'F2'." },
- range: { type: 'string', description: "Cells to fill, e.g. 'F2:M20'." },
- width: {
- type: 'number',
- description: 'Width in px; proportions are kept. Omit for automatic.',
- },
- height: { type: 'number', description: 'Height in px; as for width.' },
- },
- },
- ],
- description: 'An image file name, or {path, anchor | range, width, height}.',
- },
- },
- },
- },
- },
- },
- required: ['filename', 'sheets'],
- },
- async execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
- try {
- const filename = outputFilename(args.filename, 'xlsx', 'output')
- const warnings: string[] = []
- const built = await buildXlsxWorkbook(
- args,
- outputDir,
- { width: XLSX_MAX_IMAGE_WIDTH, height: XLSX_MAX_IMAGE_HEIGHT },
- warnings
- )
- if (!built.ok) return { success: false, error: built.error }
- // The workbook is already in memory, so a quota breach leaves no partial file.
- ensureDir(outputDir)
- const target = claimOutputFile(outputDir, filename)
- enforceQuota(outputDir, built.buffer.byteLength, replacedBytes(target))
- fs.writeFileSync(target.filePath, built.buffer)
- return artifactResult(target, 'xlsx', {
- summary: `File generated: ${target.filename} (xlsx): ${built.summary}.`,
- warnings,
- })
- } catch (err) {
- return { success: false, error: err instanceof Error ? err.message : String(err) }
- }
- },
-}
-
-// ════════════════════════════════════════════════════════════════════
-// ─── DASHBOARD GENERATION (clerum__generate_dashboard) ──────────────
-// ════════════════════════════════════════════════════════════════════
-//
-// Self-contained HTML dashboard renderer. Produces a single .html file
-// with inlined CSS, plus the Chart.js bundle when the page has charts;
-// works offline and prints cleanly.
-//
-// Templates (4 fixed presets):
-// - executive-brief general-purpose daily/weekly executive report
-// - operations-pulse engineering / SRE / oncall view
-// - financial-review finance with hero chart + dense tables
-// - technical-report long-form engineering writeup with code blocks
-//
-// Themes: default | corporate | warm | alert (light + dark variants)
-
-// ─── CSS builder ────────────────────────────────────────────────────
-
-function dashboardColorVars(c: DashboardThemeColors): string {
- return `
- --bg: ${c.bg};
- --surface: ${c.surface};
- --surface-muted: ${c.surfaceMuted};
- --text: ${c.text};
- --text-muted: ${c.textMuted};
- --text-soft: ${c.textSoft};
- --border: ${c.border};
- --primary: ${c.primary};
- --primary-hover: ${c.primaryHover};
- --accent: ${c.accent};
- --success: ${c.success};
- --warning: ${c.warning};
- --danger: ${c.danger};
- --success-bg: ${c.successBg};
- --warning-bg: ${c.warningBg};
- --danger-bg: ${c.dangerBg};
- --neutral-bg: ${c.neutralBg};
- ${c.chart.map((color, i) => `--chart-${i + 1}: ${color};`).join('\n ')}`.trim()
-}
-
-/**
- * The page's styles. With no `mode` the page follows the viewer's color
- * scheme; a mode given is kept whatever the viewer's scheme. Print is light.
- */
-function buildDashboardCss(theme: DashboardTheme, mode?: 'light' | 'dark'): string {
- const lightVars = dashboardColorVars(theme.light)
- const darkVars = dashboardColorVars(theme.dark)
- const baseVars = mode === 'dark' ? darkVars : lightVars
- const oppositeVars = mode === 'dark' ? lightVars : darkVars
- const oppositeKey = mode === 'dark' ? 'light' : 'dark'
- const viewerScheme =
- mode === undefined
- ? `
-@media (prefers-color-scheme: dark) {
- :root:not([data-theme]) {
- ${darkVars}
- }
-}
-`
- : ''
-
- return `
-*, *::before, *::after { box-sizing: border-box; }
-html, body { margin: 0; padding: 0; }
-
-:root {
- ${baseVars}
- --font: ${theme.fontFamily};
- --radius-sm: 6px;
- --radius: 10px;
- --radius-lg: 14px;
- --shadow: 0 1px 2px rgba(0,0,0,0.05), 0 4px 12px rgba(0,0,0,0.04);
- --shadow-lg: 0 8px 24px rgba(0,0,0,0.08), 0 2px 6px rgba(0,0,0,0.04);
-}
-
-[data-theme="${oppositeKey}"] {
- ${oppositeVars}
-}
-${viewerScheme}
-body {
- font-family: var(--font);
- font-size: 15px;
- line-height: 1.55;
- color: var(--text);
- background: var(--bg);
- -webkit-font-smoothing: antialiased;
- -moz-osx-font-smoothing: grayscale;
-}
-
-a { color: var(--accent); text-decoration: none; }
-a:hover { text-decoration: underline; }
-code {
- font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
- font-size: 0.9em;
- background: var(--surface-muted);
- padding: 0.1em 0.3em;
- border-radius: 4px;
- color: var(--text);
-}
-strong, b { color: var(--text); font-weight: 600; }
-em, i { font-style: italic; }
-
-/* ─── Layout ──────────────────────────────────────────────────────── */
-
-.dashboard {
- max-width: 1180px;
- margin: 0 auto;
- padding: 32px 24px 64px;
-}
-
-.hero {
- display: flex;
- flex-direction: column;
- gap: 12px;
- padding: 32px;
- margin-bottom: 28px;
- background: var(--surface);
- border-radius: var(--radius-lg);
- border: 1px solid var(--border);
- box-shadow: var(--shadow);
- position: relative;
- overflow: hidden;
-}
-.hero::before {
- content: '';
- position: absolute;
- inset: 0 0 auto 0;
- height: 6px;
- background: var(--primary);
-}
-.hero[data-status="green"]::before { background: var(--success); }
-.hero[data-status="yellow"]::before { background: var(--warning); }
-.hero[data-status="red"]::before { background: var(--danger); }
-
-.hero__eyebrow {
- font-size: 12px;
- font-weight: 600;
- letter-spacing: 0.08em;
- text-transform: uppercase;
- color: var(--text-soft);
-}
-.hero__title, .hero__headline, .kpi-card__label, .kpi-card__value, .kpi-card__delta,
-.chart-card__title, .health-card__name, .health-card__metric, .timeline-item__title {
- overflow-wrap: anywhere;
-}
-.kpi-card, .chart-card, .health-card, .timeline-item__body { min-width: 0; }
-.hero__title {
- font-size: 32px;
- font-weight: 700;
- letter-spacing: -0.02em;
- color: var(--text);
- margin: 0;
-}
-.hero__headline {
- font-size: 18px;
- color: var(--text-muted);
- margin: 0;
- line-height: 1.4;
-}
-
-.status-badge {
- display: inline-flex;
- align-items: center;
- gap: 8px;
- padding: 6px 14px;
- border-radius: 999px;
- font-size: 12px;
- font-weight: 600;
- letter-spacing: 0.05em;
- text-transform: uppercase;
- align-self: flex-start;
-}
-.status-badge[data-status="green"] { background: var(--success-bg); color: var(--success); }
-.status-badge[data-status="yellow"] { background: var(--warning-bg); color: var(--warning); }
-.status-badge[data-status="red"] { background: var(--danger-bg); color: var(--danger); }
-.status-badge[data-status="neutral"] { background: var(--neutral-bg); color: var(--text-muted); }
-.status-badge::before {
- content: '';
- width: 8px; height: 8px;
- border-radius: 50%;
- background: currentColor;
-}
-
-/* ─── Section ─────────────────────────────────────────────────────── */
-
-.section {
- margin-bottom: 28px;
-}
-.section > :last-child { margin-bottom: 0; }
-.section__title {
- display: flex;
- align-items: baseline;
- justify-content: space-between;
- gap: 16px;
- margin: 0 0 12px;
- font-size: 18px;
- font-weight: 600;
- color: var(--text);
-}
-.section__subtitle {
- font-size: 13px;
- color: var(--text-soft);
- font-weight: 400;
-}
-
-/* ─── KPI grid ────────────────────────────────────────────────────── */
-
-.kpi-grid {
- display: grid;
- grid-template-columns: repeat(auto-fit, minmax(min(220px, 100%), 1fr));
- gap: 16px;
- margin-bottom: 28px;
-}
-
-.kpi-card {
- background: var(--surface);
- border: 1px solid var(--border);
- border-radius: var(--radius);
- padding: 20px;
- box-shadow: var(--shadow);
- display: flex;
- flex-direction: column;
- gap: 8px;
- transition: transform 0.12s ease;
-}
-.kpi-card:hover { transform: translateY(-2px); }
-
-.kpi-card__label {
- font-size: 12px;
- font-weight: 600;
- letter-spacing: 0.06em;
- text-transform: uppercase;
- color: var(--text-soft);
- margin: 0;
-}
-.kpi-card__value {
- font-size: 28px;
- font-weight: 700;
- letter-spacing: -0.02em;
- color: var(--text);
- margin: 0;
- line-height: 1.1;
-}
-.kpi-card__delta {
- display: inline-flex;
- align-items: center;
- gap: 4px;
- font-size: 13px;
- font-weight: 600;
- margin: 0;
-}
-.kpi-card__delta[data-sentiment="good"] { color: var(--success); }
-.kpi-card__delta[data-sentiment="bad"] { color: var(--danger); }
-.kpi-card__delta[data-sentiment="neutral"] { color: var(--text-muted); }
-.kpi-card__delta::before {
- font-size: 11px;
-}
-.kpi-card__delta[data-direction="up"]::before { content: '▲'; }
-.kpi-card__delta[data-direction="down"]::before { content: '▼'; }
-.kpi-card__delta[data-direction="neutral"]::before { content: '·'; }
-
-.kpi-card__sparkline-wrap {
- position: relative;
- margin-top: 8px;
- height: 36px;
- max-height: 36px;
- width: 100%;
- overflow: hidden;
- contain: size layout;
-}
-.kpi-card__sparkline {
- position: absolute !important;
- inset: 0 !important;
- width: 100% !important;
- height: 100% !important;
- max-width: 100% !important;
- max-height: 100% !important;
-}
-
-/* ─── Chart cards ─────────────────────────────────────────────────── */
-
-.chart-grid {
- display: grid;
- grid-template-columns: repeat(auto-fit, minmax(min(360px, 100%), 1fr));
- gap: 16px;
- margin-bottom: 28px;
-}
-
-.chart-card {
- background: var(--surface);
- border: 1px solid var(--border);
- border-radius: var(--radius);
- padding: 20px;
- box-shadow: var(--shadow);
-}
-.chart-card__table {
- overflow-x: auto;
-}
-.chart-card__table .data-table {
- font-size: 13px;
-}
-.chart-card__note {
- margin: 0;
- padding: 24px 12px;
- text-align: center;
- color: var(--text-muted);
- font-size: 13px;
- line-height: 1.5;
-}
-
-.chart-card__caption {
- margin: 8px 0 0;
- text-align: center;
- color: var(--text-muted);
- font-size: 13px;
- font-weight: 600;
- overflow-wrap: anywhere;
-}
-
-.chart-card__title {
- font-size: 14px;
- font-weight: 600;
- color: var(--text);
- margin: 0 0 12px;
-}
-.chart-card__container {
- position: relative;
- height: 280px;
- max-height: 280px;
- width: 100%;
- overflow: hidden;
- contain: size layout;
-}
-.chart-card__container > canvas {
- position: absolute !important;
- inset: 0 !important;
- width: 100% !important;
- height: 100% !important;
- max-width: 100% !important;
- max-height: 100% !important;
-}
-
-/* ─── Data tables ─────────────────────────────────────────────────── */
-
-.data-table-wrap {
- background: var(--surface);
- border: 1px solid var(--border);
- border-radius: var(--radius);
- overflow-x: auto;
- box-shadow: var(--shadow);
- margin-bottom: 28px;
-}
-
-.data-table {
- width: 100%;
- border-collapse: collapse;
- font-size: 14px;
-}
-.data-table thead th {
- background: var(--primary);
- color: white;
- font-weight: 600;
- text-align: left;
- padding: 12px 16px;
- letter-spacing: 0.02em;
-}
-.data-table tbody td {
- padding: 12px 16px;
- border-top: 1px solid var(--border);
- color: var(--text);
- vertical-align: top;
-}
-.data-table tbody tr:nth-child(even) td {
- background: var(--surface-muted);
-}
-.severity-badge {
- display: inline-block;
- padding: 2px 8px;
- border-radius: 999px;
- font-size: 11px;
- font-weight: 700;
- letter-spacing: 0.04em;
- text-transform: uppercase;
-}
-.severity-critical, .severity-p0 { background: var(--danger-bg); color: var(--danger); }
-.severity-high, .severity-p1 { background: var(--warning-bg); color: var(--warning); }
-.severity-med { background: var(--neutral-bg); color: var(--text-muted); }
-.severity-low, .severity-p2 { background: var(--success-bg); color: var(--success); }
-.severity-info { background: var(--neutral-bg); color: var(--text-soft); }
-
-/* ─── Callouts / risks / narrative ───────────────────────────────── */
-
-.callout {
- background: var(--surface);
- border: 1px solid var(--border);
- border-left: 4px solid var(--accent);
- border-radius: var(--radius);
- padding: 16px 20px;
- margin: 0 0 16px;
-}
-.callout[data-tone="warning"] { border-left-color: var(--warning); }
-.callout[data-tone="danger"] { border-left-color: var(--danger); }
-.callout[data-tone="success"] { border-left-color: var(--success); }
-.kpi-grid > .callout, .health-grid > .callout { margin: 0; }
-.timeline-item > .callout { margin: 0 0 0 12px; }
-
-.bullets {
- margin: 0;
- padding: 0 0 0 20px;
- color: var(--text);
-}
-.bullets li {
- margin-bottom: 8px;
- line-height: 1.55;
-}
-.bullets li::marker {
- color: var(--accent);
-}
-
-.narrative {
- background: var(--surface);
- border: 1px solid var(--border);
- border-radius: var(--radius);
- padding: 20px 24px;
- font-size: 15px;
- line-height: 1.65;
- color: var(--text);
- box-shadow: var(--shadow);
-}
-.narrative p { margin: 0 0 12px; }
-.narrative p:last-child { margin-bottom: 0; }
-
-/* ─── Service health grid (operations-pulse) ─────────────────────── */
-
-.health-grid {
- display: grid;
- grid-template-columns: repeat(auto-fit, minmax(min(200px, 100%), 1fr));
- gap: 12px;
- margin-bottom: 28px;
-}
-
-.health-card {
- background: var(--surface);
- border: 1px solid var(--border);
- border-left: 4px solid var(--text-muted);
- border-radius: var(--radius);
- padding: 14px 16px;
- box-shadow: var(--shadow);
-}
-.health-card[data-status="healthy"] { border-left-color: var(--success); }
-.health-card[data-status="degraded"] { border-left-color: var(--warning); }
-.health-card[data-status="down"] { border-left-color: var(--danger); }
-.health-card[data-status="maintenance"] { border-left-color: var(--text-muted); }
-
-.health-card__head {
- display: flex;
- align-items: center;
- gap: 8px;
- margin-bottom: 6px;
-}
-.health-card__dot {
- width: 8px; height: 8px;
- border-radius: 50%;
- background: var(--text-muted);
-}
-.health-card[data-status="healthy"] .health-card__dot { background: var(--success); }
-.health-card[data-status="degraded"] .health-card__dot { background: var(--warning); }
-.health-card[data-status="down"] .health-card__dot { background: var(--danger); }
-.health-card[data-status="maintenance"] .health-card__dot { background: var(--text-soft); }
-
-.health-card__name {
- font-size: 14px;
- font-weight: 600;
- color: var(--text);
- margin: 0;
-}
-.health-card__status {
- font-size: 11px;
- font-weight: 700;
- letter-spacing: 0.06em;
- color: var(--text-muted);
- margin: 0 0 6px;
-}
-.health-card__metric {
- font-size: 14px;
- font-weight: 500;
- color: var(--text);
- margin: 0;
- font-variant-numeric: tabular-nums;
-}
-
-/* ─── Incidents timeline (operations-pulse) ───────────────────────── */
-
-.timeline {
- list-style: none;
- margin: 0 0 28px;
- padding: 0;
- position: relative;
-}
-.timeline::before {
- content: '';
- position: absolute;
- left: 88px;
- top: 8px;
- bottom: 8px;
- width: 2px;
- background: var(--border);
-}
-
-.timeline-item {
- display: grid;
- grid-template-columns: 80px 1fr;
- gap: 16px;
- padding: 12px 0;
- position: relative;
-}
-.timeline-item__time {
- font-size: 12px;
- color: var(--text-muted);
- font-variant-numeric: tabular-nums;
- text-align: right;
- padding-top: 4px;
-}
-.timeline-item::before {
- content: '';
- position: absolute;
- left: 84px;
- top: 18px;
- width: 10px; height: 10px;
- border-radius: 50%;
- background: var(--text-muted);
- border: 2px solid var(--surface);
- z-index: 1;
-}
-.timeline-item[data-severity="critical"]::before { background: var(--danger); }
-.timeline-item[data-severity="high"]::before { background: var(--warning); }
-.timeline-item[data-severity="med"]::before { background: var(--accent); }
-.timeline-item[data-severity="low"]::before { background: var(--success); }
-.timeline-item[data-severity="info"]::before { background: var(--text-soft); }
-
-.timeline-item__body {
- background: var(--surface);
- border: 1px solid var(--border);
- border-radius: var(--radius);
- padding: 12px 16px;
- box-shadow: var(--shadow);
- margin-left: 12px;
-}
-.timeline-item__head {
- display: flex;
- align-items: center;
- gap: 10px;
- flex-wrap: wrap;
- margin-bottom: 4px;
-}
-.timeline-item__title {
- font-size: 14px;
- font-weight: 600;
- color: var(--text);
- margin: 0;
- flex: 1;
-}
-.timeline-item__open,
-.timeline-item__resolved {
- font-size: 11px;
- font-weight: 600;
- letter-spacing: 0.04em;
- text-transform: uppercase;
- padding: 2px 8px;
- border-radius: 999px;
-}
-.timeline-item__open { background: var(--warning-bg); color: var(--warning); }
-.timeline-item__resolved { background: var(--success-bg); color: var(--success); }
-.timeline-item__desc {
- margin: 4px 0 0;
- font-size: 13px;
- color: var(--text-muted);
-}
-
-/* ─── Code block (technical-report) ───────────────────────────────── */
-
-.code-block {
- background: var(--surface-muted);
- border: 1px solid var(--border);
- border-radius: var(--radius);
- margin: 0 0 16px;
- overflow: hidden;
-}
-.code-block__lang {
- font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
- font-size: 11px;
- font-weight: 600;
- color: var(--text-muted);
- background: var(--surface);
- padding: 6px 14px;
- border-bottom: 1px solid var(--border);
- text-transform: uppercase;
- letter-spacing: 0.06em;
-}
-.code-block pre {
- margin: 0;
- padding: 14px 16px;
- overflow-x: auto;
- font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
- font-size: 13px;
- line-height: 1.55;
- color: var(--text);
- background: transparent;
-}
-.code-block pre code {
- background: transparent;
- padding: 0;
- font-size: inherit;
- border-radius: 0;
-}
-
-/* ─── Wide / stacked chart layout (financial-review hero chart) ──── */
-
-.chart-stack {
- display: grid;
- grid-template-columns: 1fr;
- gap: 16px;
- margin-bottom: 28px;
-}
-.chart-card--wide {
- /* spans full available width even inside a grid row */
-}
-.chart-card__container--tall {
- height: 360px;
- max-height: 360px;
-}
-
-/* ─── KPI accent overrides ────────────────────────────────────────── */
-
-.kpi-card[data-accent="success"] { border-top: 3px solid var(--success); }
-.kpi-card[data-accent="warning"] { border-top: 3px solid var(--warning); }
-.kpi-card[data-accent="danger"] { border-top: 3px solid var(--danger); }
-.kpi-card[data-accent="neutral"] { border-top: 3px solid var(--text-soft); }
-
-/* ─── Divider / spacer (custom template) ──────────────────────────── */
-
-.dashboard-divider {
- border: none;
- border-top: 1px solid var(--border);
- margin: 28px 0;
-}
-.dashboard-spacer { display: block; }
-.dashboard-spacer--sm { height: 12px; }
-.dashboard-spacer--md { height: 28px; }
-.dashboard-spacer--lg { height: 56px; }
-
-/* ─── Footer ──────────────────────────────────────────────────────── */
-
-.dash-footer {
- display: flex;
- justify-content: space-between;
- align-items: center;
- padding: 24px 0 0;
- border-top: 1px solid var(--border);
- margin-top: 40px;
- font-size: 12px;
- color: var(--text-soft);
-}
-.dash-footer__brand {
- font-weight: 600;
- color: var(--text-muted);
-}
-
-/* ─── Print ───────────────────────────────────────────────────────── */
-
-@media print {
- :root, :root:not([data-theme]), [data-theme] {
- ${lightVars}
- }
- body { background: white; }
- .dashboard { max-width: 100%; padding: 0; }
- .kpi-card, .chart-card, .data-table-wrap, .narrative, .callout {
- box-shadow: none;
- break-inside: avoid;
- }
- .hero { box-shadow: none; }
- .section__title { break-after: avoid; }
- .data-table-wrap { overflow: visible; }
- .data-table { font-size: 11px; }
- .data-table thead th, .data-table tbody td { padding: 6px 8px; }
- .data-table--wide { font-size: 9px; }
- .data-table--wide thead th, .data-table--wide tbody td { padding: 4px; overflow-wrap: anywhere; }
-}
-
-/* ─── Responsive ──────────────────────────────────────────────────── */
-
-@media (max-width: 640px) {
- .dashboard { padding: 16px 12px 40px; }
- .hero { padding: 24px; }
- .hero__title { font-size: 24px; }
- .hero__headline { font-size: 16px; }
- .kpi-card__value { font-size: 22px; }
- .chart-card__container { height: 220px; }
-}
-`.trim()
-}
-
-// ─── Render helpers (shared across templates) ──────────────────────
-//
-// The schema cannot say which fields each template or block type needs, so
-// every helper reads its input defensively. A part that cannot be read throws
-// an error naming the field; the caller replaces that part with a notice and
-// reports it, and the rest still renders.
-
-interface DashboardBranding {
- companyName?: string
- footerText?: string
-}
-
-/** State gathered while one dashboard renders. */
-interface DashRender {
- charts: DashboardCharts
- warnings: string[]
- sparklines: number
- drawSparklines: boolean
- skippedSparklines: number
- /** Parts that rendered, to tell a partial page from an empty one. */
- rendered: number
- /** Why each part that could not be shown failed. */
- failures: string[]
-}
-
-function renderInlineMd(s: string): string {
- return escapeHtml(s)
- .replace(/\*\*([\s\S]+?)\*\*(?!\*)/g, '<strong>$1</strong>')
- .replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, '<em>$1</em>')
- .replace(/`([^`]+)`/g, '<code>$1</code>')
-}
-
-function isDashRecord(value: unknown): value is Record<string, unknown> {
- return value !== null && typeof value === 'object' && !Array.isArray(value)
-}
-
-function describeDashValue(value: unknown): string {
- if (value === undefined) return 'nothing'
- if (value === null) return 'null'
- if (Array.isArray(value)) return 'an array'
- if (typeof value === 'string') return `a string (${JSON.stringify(value.slice(0, 40))})`
- return typeof value === 'object' ? 'an object' : `a ${typeof value} (${String(value)})`
-}
-
-function dashRecord(value: unknown, where: string, shape: string): Record<string, unknown> {
- if (!isDashRecord(value)) {
- throw new Error(`${where} must be ${shape}; received ${describeDashValue(value)}.`)
- }
- return value
-}
-
-function dashList(value: unknown, where: string, shape: string): unknown[] {
- if (value === undefined || value === null) return []
- if (!Array.isArray(value)) {
- throw new Error(`${where} must be an array of ${shape}; received ${describeDashValue(value)}.`)
- }
- return value
-}
-
-/** Text of a scalar; anything else reads as empty. */
-function dashText(value: unknown): string {
- return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
- ? String(value)
- : ''
-}
-
-/** One paragraph or a list of them, rejecting what would print as "[object Object]". */
-function dashTextList(value: unknown, where: string): string[] {
- const items = Array.isArray(value) ? value : [value]
- const out = items.map((item, i) => {
- if (typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean') {
- return String(item)
- }
- const at = Array.isArray(value) ? `${where}[${i}]` : where
- throw new Error(`${at} must be text; received ${describeDashValue(item)}.`)
- })
- if (out.every(t => t.trim() === '')) throw new Error(`${where} is empty; pass the text to show.`)
- return out
-}
-
-/** `body` under its heading, in one section so a printed page never ends on the heading. */
-function titledSection(title: string | undefined, body: string): string {
- return title
- ? `<section class="section"><h2 class="section__title">${escapeHtml(title)}</h2>${body}</section>`
- : body
-}
-
-/** A number as a reader expects it: grouped, without floating-point noise. */
-function formatDashNumber(n: number): string {
- if (Number.isInteger(n)) return n.toLocaleString('en-US')
- return Math.abs(n) >= 1
- ? n.toLocaleString('en-US', { maximumFractionDigits: 2 })
- : n.toLocaleString('en-US', { maximumSignificantDigits: 4 })
-}
-
-/** A figure: numbers are formatted, text is shown as written. */
-function dashFigure(value: unknown): string {
- return typeof value === 'number' ? formatDashNumber(value) : dashText(value)
-}
-
-type DeltaDirection = 'up' | 'down' | 'neutral'
-
-/** A delta's text and arrow; a numeric delta is signed and, unless told otherwise, points its own way. */
-function dashDelta(
- delta: unknown,
- direction: unknown
-): { text: string; direction: DeltaDirection } {
- const directions = ['up', 'down', 'neutral'] as const
- if (typeof delta !== 'number') {
- return { text: dashText(delta), direction: oneOf(direction, directions, 'neutral') }
- }
- const own = delta > 0 ? 'up' : delta < 0 ? 'down' : 'neutral'
- return {
- text: `${delta > 0 ? '+' : ''}${formatDashNumber(delta)}`,
- direction: oneOf(direction, directions, own),
- }
-}
-
-function deltaHtml(text: string, direction: DeltaDirection, sentiment: string): string {
- if (!text) return ''
- return `<p class="kpi-card__delta" data-direction="${direction}" data-sentiment="${sentiment}">${escapeHtml(text)}</p>`
-}
-
-function failureCallout(heading: string, message: string): string {
- return `<section class="section"><h2 class="section__title">${escapeHtml(heading)}</h2><div class="callout" data-tone="danger">${escapeHtml(message)}</div></section>`
-}
-
-function recordFailure(ctx: DashRender, where: string, e: unknown): string {
- const message = e instanceof Error ? e.message : String(e)
- ctx.failures.push(message.includes(where) ? message : `${where}: ${message}`)
- return message
-}
-
-/**
- * Render one part of the page. A part that throws is replaced by a notice and
- * reported, so one malformed entry never takes the dashboard down. `counts`
- * is false for parts that are not content of their own (the hero, a divider)
- * and for parts that count their own entries (charts, card groups).
- */
-function dashPart(ctx: DashRender, where: string, counts: boolean, render: () => string): string {
- try {
- const html = render()
- if (counts && html) ctx.rendered++
- return html
- } catch (e) {
- const message = recordFailure(ctx, where, e)
- return failureCallout(`${where} could not be shown`, message)
- }
-}
-
-/**
- * Render each entry of a card group on its own: a bad entry becomes a notice
- * in its place and the other cards stay. The group counts as content when at
- * least one entry rendered.
- */
-function dashItems(
- ctx: DashRender,
- list: unknown[],
- where: string,
- render: (item: unknown, at: string) => string,
- notice: (message: string) => string
-): string {
- let shown = 0
- const html = list
- .map((item, i) => {
- const at = `${where}[${i}]`
- try {
- const out = render(item, at)
- shown++
- return out
- } catch (e) {
- return notice(recordFailure(ctx, at, e))
- }
- })
- .join('\n')
- if (shown > 0) ctx.rendered++
- return html
-}
-
-const cardNotice = (message: string) =>
- `<div class="callout" data-tone="danger">${escapeHtml(message)}</div>`
-
-const HERO_STATUSES = ['green', 'yellow', 'red', 'neutral'] as const
-
-function renderHero(o: Record<string, unknown>): string {
- const eyebrowText = dashText(o.eyebrow)
- const eyebrow = eyebrowText ? `<div class="hero__eyebrow">${escapeHtml(eyebrowText)}</div>` : ''
- const status = oneOf(dashText(o.status).trim().toLowerCase(), HERO_STATUSES, 'neutral')
- const statusLabel = dashText(o.statusLabel) || status.toUpperCase()
- const statusBadge =
- o.status !== undefined || dashText(o.statusLabel)
- ? `<span class="status-badge" data-status="${status}">${escapeHtml(statusLabel)}</span>`
- : ''
- const headlineText = dashText(o.headline)
- const headline = headlineText
- ? `<p class="hero__headline">${renderInlineMd(headlineText)}</p>`
- : ''
- return `
-<header class="hero" data-status="${status}">
- ${eyebrow}
- <h1 class="hero__title">${escapeHtml(dashText(o.title))}</h1>
- ${headline}
- ${statusBadge}
-</header>`.trim()
-}
-
-function renderSparkline(value: unknown, where: string, ctx: DashRender): string {
- if (value === undefined || value === null) return ''
- if (!Array.isArray(value)) {
- ctx.warnings.push(`${where} must be an array of numbers; the trend was left out.`)
- return ''
- }
- const points = value.map(v => (v === null ? null : coerceNumber(v)))
- const values = points.filter((v): v is number | null => v !== undefined)
- if (values.filter(v => v !== null).length < 2) {
- ctx.warnings.push(`${where} needs at least two numbers to draw a trend; it was left out.`)
- return ''
- }
- if (!ctx.drawSparklines) {
- ctx.skippedSparklines++
- return ''
- }
- if (values.length < points.length) {
- ctx.warnings.push(`${where}: entries that were not numbers were left out of the trend.`)
- }
- return `<div class="kpi-card__sparkline-wrap"><canvas class="kpi-card__sparkline" id="sparkline-${ctx.sparklines++}" data-spark="${escapeHtmlAttr(
- JSON.stringify(values)
- )}"></canvas></div>`
-}
-
-const YEAR_LABEL = /\b(year|years|yr|fy|a[nñ]o|anio)\b/i
-
-function renderKpis(items: unknown, where: string, ctx: DashRender, title?: string): string {
- const kpis = dashList(items, where, 'KPI objects {label, value}')
- if (kpis.length === 0) return ''
- const cards = dashItems(
- ctx,
- kpis,
- where,
- (item, at) => {
- const kpi = dashRecord(item, at, 'a KPI object {label, value}')
- // A year is not grouped: 2026, not 2,026. Only a figure that could be one
- // is taken for it; revenue per year is still grouped.
- const year =
- typeof kpi.value === 'number' &&
- Number.isInteger(kpi.value) &&
- kpi.value >= 1000 &&
- kpi.value <= 9999 &&
- YEAR_LABEL.test(dashText(kpi.label))
- const value = year ? String(kpi.value) : dashFigure(kpi.value)
- if (!value) {
- throw new Error(`${at}.value is missing; pass the figure to show, e.g. "$1.2M" or 48.`)
- }
- const { text, direction } = dashDelta(kpi.delta, kpi.deltaDirection)
- const sentiment = oneOf(
- kpi.deltaSentiment,
- ['good', 'bad', 'neutral'] as const,
- direction === 'up' ? 'good' : direction === 'down' ? 'bad' : 'neutral'
- )
- const delta = deltaHtml(text, direction, sentiment)
- const accent =
- kpi.accent === undefined
- ? ''
- : ` data-accent="${oneOf(kpi.accent, ['success', 'warning', 'danger', 'neutral'] as const, 'neutral')}"`
- return `
-<div class="kpi-card"${accent}>
- <p class="kpi-card__label">${escapeHtml(dashText(kpi.label))}</p>
- <p class="kpi-card__value">${escapeHtml(value)}</p>
- ${delta}
- ${renderSparkline(kpi.sparkline, `${at}.sparkline`, ctx)}
-</div>`.trim()
- },
- cardNotice
- )
- return titledSection(title, `<section class="kpi-grid">${cards}</section>`)
-}
-
-function renderChartCards(charts: unknown, where: string, ctx: DashRender, title?: string): string {
- const list = dashList(charts, where, 'chart objects {type, labels, datasets}')
- if (list.length === 0) return ''
- const cards = list.map((chart, i) => ctx.charts.card(chart, `${where}[${i}]`)).join('\n')
- return titledSection(title, `<section class="chart-grid">${cards}</section>`)
-}
-
-const BADGE_COLUMN_TYPES = new Set(['severity', 'priority', 'status'])
-
-function dashSeverityClass(value: unknown): string {
- const v = String(value ?? '')
- .trim()
- .toLowerCase()
- const map: Record<string, string> = {
- critical: 'severity-critical',
- high: 'severity-high',
- med: 'severity-med',
- medium: 'severity-med',
- low: 'severity-low',
- info: 'severity-info',
- p0: 'severity-p0',
- p1: 'severity-p1',
- p2: 'severity-p2',
- healthy: 'severity-low',
- degraded: 'severity-med',
- down: 'severity-critical',
- operational: 'severity-low',
- incident: 'severity-high',
- }
- return map[v] ?? ''
-}
-
-function renderTableHtml(t: unknown, where: string, ctx: DashRender, title?: string): string {
- const table = dashRecord(t, where, 'a table object {headers, rows}')
- const headers = table.headers
- if (!Array.isArray(headers) || headers.length === 0) {
- throw new Error(`${where}.headers must be a non-empty array of column names.`)
- }
- const colTypes = isDashRecord(table.columnTypes) ? table.columnTypes : {}
- const headerNames = headers.map(headerText)
- const headerHtml = headerNames.map(h => `<th>${softBreaks(escapeHtml(h))}</th>`).join('')
- const rows = fitRowsToHeaders(
- normalizeTableRows(table.rows, headers, where, ctx.warnings),
- headers.length,
- where,
- ctx
- )
- let structured = 0
- const bodyHtml = rows
- .map(row => {
- const cells = row
- .map((cell, c) => {
- const colType = colTypes[c] ?? colTypes[headerNames[c]]
- if (cell !== null && typeof cell === 'object') structured++
- const text = tableCellText(cell)
- const cls = BADGE_COLUMN_TYPES.has(String(colType)) ? dashSeverityClass(text) : ''
- return cls
- ? `<td><span class="severity-badge ${cls}">${escapeHtml(text)}</span></td>`
- : `<td>${softBreaks(renderInlineMd(text))}</td>`
- })
- .join('')
- return `<tr>${cells}</tr>`
- })
- .join('\n')
-
- if (structured > 0) {
- ctx.warnings.push(
- `${where}: ${structured} cell(s) held an object or a list and are shown as text; ` +
- 'send one value per cell.'
- )
- }
- return titledSection(
- title ?? (dashText(table.title) || undefined),
- `
-<div class="data-table-wrap">
- <table class="data-table${headers.length > WIDE_TABLE_COLUMNS ? ' data-table--wide' : ''}">
- <thead><tr>${headerHtml}</tr></thead>
- <tbody>${bodyHtml}</tbody>
- </table>
-</div>`.trimEnd()
- )
-}
-
-/**
- * A table cell as text. Numbers print as written, without the float noise of
- * 0.1 + 0.2 and without grouping, since a table column may hold years or IDs.
- */
-function tableCellText(cell: unknown): string {
- if (typeof cell === 'number') {
- return Number.isInteger(cell) ? String(cell) : String(Number(cell.toPrecision(12)))
- }
- if (Array.isArray(cell)) return cell.map(tableCellText).join(', ')
- if (cell !== null && typeof cell === 'object') return JSON.stringify(cell)
- return dashText(cell)
-}
-
-/** Above this many columns a printed table breaks words anywhere so every column fits the page. */
-const WIDE_TABLE_COLUMNS = 8
-
-const SOFT_BREAK_AFTER = new Set(['&#x2F;', '.', '-', '_', '?', '&amp;', '=', ',', ':'])
-
-/**
- * `html` with a line-break opportunity inside each long unbroken run of text,
- * after punctuation or every 10 characters, so a URL or an ID wraps instead of
- * widening its column. Words of ordinary length keep their width.
- */
-function softBreaks(html: string): string {
- return html.replace(/(<[^>]*>)|((?:&[#\w]+;|[^\s<&])+)/gu, (match, tag: string | undefined) => {
- if (tag) return match
- const units = match.match(/&[#\w]+;|[^]/gu) ?? []
- if (units.length < 16) return match
- let out = ''
- let run = 0
- units.forEach((unit, i) => {
- out += unit
- run++
- if (i < units.length - 1 && (SOFT_BREAK_AFTER.has(unit) || run >= 10)) {
- out += '<wbr>'
- run = 0
- }
- })
- return out
- })
-}
-
-/** Each row cut or padded to one cell per header, reporting cells that held a value and were cut. */
-function fitRowsToHeaders(
- rows: unknown[][],
- width: number,
- where: string,
- ctx: DashRender
-): unknown[][] {
- let padded = 0
- const cut: string[] = []
- const fitted = rows.map((row, r) => {
- if (row.length < width) {
- padded++
- return [...row, ...Array<string>(width - row.length).fill('')]
- }
- if (row.slice(width).some(cell => dashText(cell).trim() !== '')) {
- cut.push(
- `${where}.rows[${r}] has ${row.length} cells for ${width} headers; the extra ` +
- `${row.length - width} ${row.length - width === 1 ? 'was' : 'were'} left out.`
- )
- }
- return row.slice(0, width)
- })
- if (cut.length > 0) {
- const more = cut.length > 1 ? ` ${cut.length - 1} more row(s) had extra cells too.` : ''
- ctx.warnings.push(`${cut[0]}${more} Add headers for them or drop them.`)
- }
- if (padded > 0) {
- ctx.warnings.push(
- `${where}: ${padded} row(s) have fewer cells than the ${width} headers and end in empty cells.`
- )
- }
- return fitted
-}
-
-const SECTION_TYPES = ['narrative', 'bullets', 'callout', 'code'] as const
-const CALLOUT_TONES = ['info', 'success', 'warning', 'danger'] as const
-
-function renderSectionHtml(s: unknown, where: string): string {
- const section = dashRecord(s, where, 'a section object {type, content}')
- if (section.type !== undefined && !SECTION_TYPES.includes(section.type as never)) {
- throw new Error(`${where}.type must be one of: ${SECTION_TYPES.join(', ')}.`)
- }
- const type = oneOf(section.type, SECTION_TYPES, 'narrative')
- const content = dashTextList(section.content, `${where}.content`)
- const titleText = dashText(section.title)
- const title = titleText ? `<h2 class="section__title">${escapeHtml(titleText)}</h2>` : ''
- let body: string
- if (type === 'narrative') {
- body = `<div class="narrative">${content.map(p => `<p>${renderInlineMd(p)}</p>`).join('\n')}</div>`
- } else if (type === 'bullets') {
- body = `<ul class="bullets">${content.map(b => `<li>${renderInlineMd(b)}</li>`).join('')}</ul>`
- } else if (type === 'callout') {
- const tone = oneOf(section.tone, CALLOUT_TONES, 'info')
- body = `<div class="callout" data-tone="${tone}">${renderInlineMd(content.join('\n'))}</div>`
- } else {
- const language = dashText(section.language)
- const lang = language ? `<div class="code-block__lang">${escapeHtml(language)}</div>` : ''
- body = `<div class="code-block">${lang}<pre><code>${escapeHtml(content.join('\n'))}</code></pre></div>`
- }
- return `<section class="section">${title}${body}</section>`
-}
-
-const SERVICE_STATUSES = ['healthy', 'degraded', 'down', 'maintenance'] as const
-
-/** Status words models use, by the card color they mean. */
-/** The entry `words` has for `text`, ignoring case; never one inherited from Object. */
-function ownWord<T>(words: Partial<Record<string, T>>, text: string): T | undefined {
- const key = text.toLowerCase()
- return Object.hasOwn(words, key) ? words[key] : undefined
-}
-
-const SERVICE_STATUS_WORDS: Partial<Record<string, (typeof SERVICE_STATUSES)[number]>> = {
- healthy: 'healthy',
- ok: 'healthy',
- up: 'healthy',
- operational: 'healthy',
- online: 'healthy',
- green: 'healthy',
- degraded: 'degraded',
- warning: 'degraded',
- partial: 'degraded',
- yellow: 'degraded',
- down: 'down',
- outage: 'down',
- offline: 'down',
- failed: 'down',
- red: 'down',
- maintenance: 'maintenance',
-}
-
-function renderServiceHealthGrid(
- services: unknown,
- where: string,
- ctx: DashRender,
- title?: string
-): string {
- const list = dashList(services, where, 'service objects {name, status}')
- if (list.length === 0) return ''
- const cards = dashItems(
- ctx,
- list,
- where,
- (item, at) => {
- const s = dashRecord(item, at, 'a service object {name, status}')
- const name = dashText(s.name)
- if (!name) throw new Error(`${at}.name is missing; pass the service name.`)
- const statusText = dashText(s.status).trim() || 'unknown'
- const status = ownWord(SERVICE_STATUS_WORDS, statusText) ?? 'unknown'
- if (status === 'unknown' && statusText.toLowerCase() !== 'unknown') {
- ctx.warnings.push(
- `${at}.status ${JSON.stringify(statusText)} is not healthy, degraded, down or ` +
- 'maintenance, so the card is grey.'
- )
- }
- const { text, direction } = dashDelta(s.delta, s.deltaDirection)
- const sentiment = direction === 'up' ? 'good' : direction === 'down' ? 'bad' : 'neutral'
- const delta = deltaHtml(text, direction, sentiment)
- const metric = dashFigure(s.metric)
- return `
-<div class="health-card" data-status="${status}">
- <div class="health-card__head">
- <span class="health-card__dot"></span>
- <h3 class="health-card__name">${escapeHtml(name)}</h3>
- </div>
- <p class="health-card__status">${escapeHtml(statusText.toUpperCase())}</p>
- ${metric ? `<p class="health-card__metric">${escapeHtml(metric)}</p>` : ''}
- ${delta}
-</div>`.trim()
- },
- cardNotice
- )
- return titledSection(title, `<section class="health-grid">${cards}</section>`)
-}
-
-const INCIDENT_SEVERITIES = ['critical', 'high', 'med', 'low', 'info'] as const
-
-/** Severity words models use, by the color they take; p0-p2 match the table badges. */
-const SEVERITY_WORDS: Partial<Record<string, (typeof INCIDENT_SEVERITIES)[number]>> = {
- critical: 'critical',
- p0: 'critical',
- high: 'high',
- major: 'high',
- p1: 'high',
- med: 'med',
- medium: 'med',
- moderate: 'med',
- low: 'low',
- minor: 'low',
- p2: 'low',
- info: 'info',
-}
-
-function renderIncidentsTimeline(
- items: unknown,
- where: string,
- ctx: DashRender,
- title?: string
-): string {
- const list = dashList(items, where, 'incident objects {time, title}')
- if (list.length === 0) return ''
- const html = dashItems(
- ctx,
- list,
- where,
- (item, at) => {
- const it = dashRecord(item, at, 'an incident object {time, title}')
- const time = dashText(it.time)
- const heading = dashText(it.title)
- if (!time && !heading) {
- throw new Error(
- `${at} needs a time and a title, e.g. {"time": "10:42", "title": "API errors"}.`
- )
- }
- const given = dashText(it.severity).trim()
- const sev = ownWord(SEVERITY_WORDS, given) ?? 'info'
- if (given && !ownWord(SEVERITY_WORDS, given)) {
- ctx.warnings.push(
- `${at}.severity ${JSON.stringify(given)} is not critical, high, medium, low or info, ` +
- 'so it is shown in the info color.'
- )
- }
- const resolvedAt = dashText(it.resolvedAt)
- const resolved = resolvedAt
- ? `<span class="timeline-item__resolved">resolved ${escapeHtml(resolvedAt)}</span>`
- : `<span class="timeline-item__open">open</span>`
- const description = dashText(it.description)
- const desc = description
- ? `<p class="timeline-item__desc">${renderInlineMd(description)}</p>`
- : ''
- return `
-<li class="timeline-item" data-severity="${sev}">
- <div class="timeline-item__time">${escapeHtml(time)}</div>
- <div class="timeline-item__body">
- <div class="timeline-item__head">
- <span class="severity-badge severity-${sev}">${escapeHtml((given || sev).toUpperCase())}</span>
- <h4 class="timeline-item__title">${escapeHtml(heading)}</h4>
- ${resolved}
- </div>
- ${desc}
- </div>
-</li>`.trim()
- },
- message =>
- `<li class="timeline-item"><div class="timeline-item__time"></div>${cardNotice(message)}</li>`
- )
- return titledSection(title, `<ol class="timeline">${html}</ol>`)
-}
-
-/** meta.date as shown; a number of 10+ digits is a Unix timestamp (seconds or ms), a shorter one a year. */
-function footerDate(value: unknown): string {
- const long = { year: 'numeric', month: 'long', day: 'numeric' } as const
- if (typeof value === 'number' && Number.isInteger(value) && Math.abs(value) >= 1e9) {
- const ms = Math.abs(value) < 1e11 ? value * 1000 : value
- return new Date(ms).toLocaleDateString('en-US', { ...long, timeZone: 'UTC' })
- }
- return dashText(value) || new Date().toLocaleDateString('en-US', long)
-}
-
-function renderDashboardFooter(meta: unknown, branding: DashboardBranding): string {
- const m: Record<string, unknown> = isDashRecord(meta) ? meta : {}
- const companyName = dashText(branding.companyName)
- const left = companyName
- ? `<span class="dash-footer__brand">${escapeHtml(companyName)}</span>`
- : ''
- const right = [
- dashText(branding.footerText),
- dashText(m.author),
- dashText(m.runId),
- footerDate(m.date),
- ]
- .filter(part => part.trim() !== '')
- .map(escapeHtml)
- .join(' · ')
- return `<footer class="dash-footer">${left}<span>${right}</span></footer>`
-}
-
-interface DashWrapperOptions {
- title: string
- cssSource?: string
- chartJsSource?: string
- chartInit?: string
- body: string
-}
-
-function htmlWrapper(o: DashWrapperOptions): string {
- const styleBlock = o.cssSource ? `<style>${o.cssSource}</style>` : ''
- const scripts = o.chartInit
- ? `<script>${o.chartJsSource ?? ''}</script>\n<script>${o.chartInit}</script>`
- : ''
- return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtml(o.title)}</title>
-${styleBlock}
-</head>
-<body>
-<main class="dashboard">
-${o.body}
-</main>
-${scripts}
-</body>
-</html>`
-}
-
-// ─── Chart.js bundle loader (cached) ────────────────────────────────
-
-let cachedChartJsBundle: string | undefined
-
-/**
- * The Chart.js UMD bundle. chart.js exports only ".", "./auto" and
- * "./helpers", so resolving "chart.js/dist/chart.umd.js" throws
- * ERR_PACKAGE_PATH_NOT_EXPORTED; the entry point resolves, and the bundle sits
- * beside it in dist/.
- */
-export function loadChartJsBundle(): string {
- if (cachedChartJsBundle) return cachedChartJsBundle
- const bundle = path.join(path.dirname(require.resolve('chart.js')), 'chart.umd.js')
- cachedChartJsBundle = fs.readFileSync(bundle, 'utf-8')
- return cachedChartJsBundle
-}
-
-// ─── Templates ──────────────────────────────────────────────────────
-
-type DashboardTemplateName =
- | 'executive-brief'
- | 'operations-pulse'
- | 'financial-review'
- | 'technical-report'
- | 'custom'
-
-type DashData = Record<string, unknown>
-
-// The fields are named rather than spread: a spread reads every key, which
-// would hide the ones nothing draws from the "Ignored arguments" note.
-function heroOf(data: DashData, eyebrowFallback?: unknown): string {
- return renderHero({
- title: data.title,
- headline: data.headline,
- status: data.status,
- statusLabel: data.statusLabel,
- eyebrow: data.eyebrow ?? eyebrowFallback,
- })
-}
-
-function tablesOf(data: DashData, ctx: DashRender): string {
- return dashPart(ctx, 'data.tables', false, () =>
- dashList(data.tables, 'data.tables', 'table objects {headers, rows}')
- .map((t, i) => {
- const where = `data.tables[${i}]`
- return dashPart(ctx, where, true, () => renderTableHtml(t, where, ctx))
- })
- .join('\n')
- )
-}
-
-function sectionsOf(data: DashData, ctx: DashRender): string {
- return dashPart(ctx, 'data.sections', false, () =>
- dashList(data.sections, 'data.sections', 'section objects {type, content}')
- .map((s, i) => {
- const where = `data.sections[${i}]`
- return dashPart(ctx, where, true, () => renderSectionHtml(s, where))
- })
- .join('\n')
- )
-}
-
-function kpisOf(data: DashData, ctx: DashRender): string {
- return dashPart(ctx, 'data.kpis', false, () => renderKpis(data.kpis, 'data.kpis', ctx))
-}
-
-function chartsOf(data: DashData, ctx: DashRender, title: string | undefined): string {
- return dashPart(ctx, 'data.charts', false, () =>
- renderChartCards(data.charts, 'data.charts', ctx, title)
- )
-}
-
-const DASHBOARD_TEMPLATES: Record<
- DashboardTemplateName,
- (data: DashData, ctx: DashRender) => string[]
-> = {
- 'executive-brief': (data, ctx) => [
- heroOf(data),
- kpisOf(data, ctx),
- chartsOf(data, ctx, 'Visual Trends'),
- tablesOf(data, ctx),
- sectionsOf(data, ctx),
- ],
- 'operations-pulse': (data, ctx) => [
- heroOf(data),
- dashPart(ctx, 'data.services', false, () =>
- renderServiceHealthGrid(data.services, 'data.services', ctx, 'Service Health')
- ),
- kpisOf(data, ctx),
- dashPart(ctx, 'data.incidents', false, () =>
- renderIncidentsTimeline(data.incidents, 'data.incidents', ctx, 'Incident Timeline')
- ),
- chartsOf(data, ctx, 'Performance Trends'),
- tablesOf(data, ctx),
- sectionsOf(data, ctx),
- ],
- 'financial-review': (data, ctx) => {
- const hasHero = data.heroChart !== undefined && data.heroChart !== null
- return [
- heroOf(data, data.period),
- kpisOf(data, ctx),
- hasHero
- ? dashPart(
- ctx,
- 'data.heroChart',
- false,
- () =>
- `<section class="chart-stack">${ctx.charts.card(data.heroChart, 'data.heroChart', { tall: true })}</section>`
- )
- : '',
- chartsOf(data, ctx, hasHero ? 'Breakdowns' : 'Visual Trends'),
- tablesOf(data, ctx),
- sectionsOf(data, ctx),
- ]
- },
- 'technical-report': (data, ctx) => [
- heroOf(data),
- kpisOf(data, ctx),
- sectionsOf(data, ctx),
- tablesOf(data, ctx),
- chartsOf(data, ctx, 'Charts'),
- ],
- custom: (data, ctx) => {
- const blocks = dashList(data.blocks, 'data.blocks', 'block objects')
- if (blocks.length === 0) {
- throw new Error(
- "template 'custom' needs data.blocks: a non-empty array of blocks such as " +
- '{"type": "kpis", "items": [{"label": "Revenue", "value": "$1.2M"}]}.'
- )
- }
- return blocks.map((b, idx) => renderBlock(b, `data.blocks[${idx}]`, ctx))
- },
-}
-
-// ─── Custom template (composable blocks) ────────────────────────────
-
-const BLOCK_TYPES = [
- 'hero',
- 'kpis',
- 'chart',
- 'charts-grid',
- 'table',
- 'narrative',
- 'bullets',
- 'code',
- 'callout',
- 'incidents',
- 'service-health',
- 'divider',
- 'spacer',
-] as const
-
-/** Blocks that are content of their own; charts and card groups count their entries. */
-const COUNTED_BLOCKS = new Set(['table', 'narrative', 'bullets', 'code', 'callout'])
-
-function isEmptyList(value: unknown): boolean {
- return value === undefined || value === null || (Array.isArray(value) && value.length === 0)
-}
-
-/** The list field of each list block, and the other name models give it. */
-const BLOCK_LISTS: Record<string, { field: 'items' | 'services'; alias: string; noun: string }> = {
- kpis: { field: 'items', alias: 'kpis', noun: 'cards' },
- 'charts-grid': { field: 'items', alias: 'charts', noun: 'charts' },
- incidents: { field: 'items', alias: 'incidents', noun: 'incidents' },
- 'service-health': { field: 'services', alias: 'items', noun: 'services' },
-}
-
-/** Whether `block` gives its list under the other name only. */
-function listUnderAlias(block: Record<string, unknown>): boolean {
- const list = BLOCK_LISTS[String(block.type)]
- return !!list && isEmptyList(block[list.field]) && !isEmptyList(block[list.alias])
-}
-
-/**
- * The entries of a list block, from its field or from the other name models
- * give it. A block with no entries throws, so it is reported rather than left
- * off the page.
- */
-function blockList(
- block: Record<string, unknown>,
- where: string,
- ctx: DashRender
-): { value: unknown; at: string } {
- const { field, alias, noun } = BLOCK_LISTS[String(block.type)]
- if (listUnderAlias(block)) {
- ctx.warnings.push(`${where}: the list was read from ${alias}; name it ${field}.`)
- return { value: block[alias], at: `${where}.${alias}` }
- }
- if (isEmptyList(block[field])) {
- throw new Error(
- `${where}.${field} is missing or empty; a '${String(block.type)}' block lists its ${noun} in ${field}.`
- )
- }
- return { value: block[field], at: `${where}.${field}` }
-}
-
-function renderBlock(b: unknown, where: string, ctx: DashRender): string {
- const type = isDashRecord(b) ? b.type : undefined
- return dashPart(ctx, where, COUNTED_BLOCKS.has(String(type)), () => {
- const block = dashRecord(b, where, 'a block object with a type')
- const title = dashText(block.title) || undefined
- switch (block.type) {
- case 'hero':
- return renderHero(block)
- case 'kpis': {
- const list = blockList(block, where, ctx)
- return renderKpis(list.value, list.at, ctx, title)
- }
- case 'chart':
- if (!isDashRecord(block.spec)) {
- throw new Error(
- `${where} is a 'chart' block and needs spec: {type, labels, datasets}; ` +
- `received ${describeDashValue(block.spec)}.`
- )
- }
- return `<section class="chart-grid">${ctx.charts.card(block.spec, `${where}.spec`, { title })}</section>`
- case 'charts-grid': {
- const list = blockList(block, where, ctx)
- return renderChartCards(list.value, list.at, ctx, title)
- }
- case 'table':
- return renderTableHtml(block.spec, `${where}.spec`, ctx, title)
- case 'narrative':
- case 'code':
- case 'callout':
- return renderSectionHtml(
- {
- type: block.type,
- content: block.content,
- language: block.language,
- tone: block.tone,
- title,
- },
- where
- )
- case 'bullets':
- return renderSectionHtml(
- { type: 'bullets', title, content: block.items ?? block.content },
- block.items === undefined ? where : `${where}.items`
- )
- case 'incidents': {
- const list = blockList(block, where, ctx)
- return renderIncidentsTimeline(list.value, list.at, ctx, title)
- }
- case 'service-health': {
- const list = blockList(block, where, ctx)
- return renderServiceHealthGrid(list.value, list.at, ctx, title)
- }
- case 'divider':
- return '<hr class="dashboard-divider"/>'
- case 'spacer':
- return `<div class="dashboard-spacer dashboard-spacer--${oneOf(block.size, ['sm', 'md', 'lg'] as const, 'md')}"></div>`
- default:
- throw new Error(
- `${where}.type ${block.type === undefined ? 'is missing' : `"${dashText(block.type)}" is not a block type`}; ` +
- `use one of: ${BLOCK_TYPES.join(', ')}.`
- )
- }
- })
-}
-
-// ─── Public entry point ─────────────────────────────────────────────
-
-interface DashboardRenderOptions {
- template: DashboardTemplateName
- data: DashData
- theme: ThemeName
- /** Kept whatever the viewer's color scheme; when absent the page follows it. */
- defaultThemeMode?: 'light' | 'dark'
- branding: DashboardBranding
- inlineChartJs: boolean
+const XLSX_CELL_SCHEMA = {
+ type: ['string', 'number', 'boolean', 'null'],
+ description:
+ 'A number, text, true/false, or null for empty. Text like "1,234.50", "$1,200", "45%" ' +
+ 'or an ISO date or datetime ("2026-09-22") is stored as a number or date; leading-zero codes and ' +
+ 'numbers over 15 digits stay text.',
}
-function renderDashboard(opts: DashboardRenderOptions): { html: string; ctx: DashRender } {
- const theme = DASHBOARD_THEMES[opts.theme] ?? DASHBOARD_THEMES.default
- const warnings: string[] = []
- const failures: string[] = []
- const ctx: DashRender = {
- charts: new DashboardCharts(opts.inlineChartJs, { warnings, failures }),
- warnings,
- sparklines: 0,
- drawSparklines: opts.inlineChartJs,
- skippedSparklines: 0,
- rendered: 0,
- failures,
- }
- const parts = (DASHBOARD_TEMPLATES[opts.template] ?? DASHBOARD_TEMPLATES['executive-brief'])(
- opts.data,
- ctx
- )
- const body = [...parts, renderDashboardFooter(opts.data.meta, opts.branding)].join('\n')
- const needsCharts = ctx.charts.specs.length > 0 || ctx.sparklines > 0
- const html = htmlWrapper({
- title: dashText(opts.data.title),
- cssSource: buildDashboardCss(theme, opts.defaultThemeMode),
- chartJsSource: needsCharts ? loadChartJsBundle() : undefined,
- chartInit: needsCharts ? dashboardScript(safeJsonForScript(ctx.charts.specs)) : undefined,
- body,
- })
- return { html, ctx }
-}
+const XLSX_IMAGE_PATH_DESCRIPTION =
+ "File name in the output folder, as returned by clerum__generate_chart (e.g. 'sales.png')."
-/** Fields each template reads beyond the shared ones, to flag data another template would need. */
-const TEMPLATE_ONLY_FIELDS: Record<string, DashboardTemplateName[]> = {
- services: ['operations-pulse'],
- incidents: ['operations-pulse'],
- heroChart: ['financial-review'],
- period: ['financial-review'],
- blocks: ['custom'],
-}
-const FIXED_TEMPLATE_FIELDS = [
- 'eyebrow',
- 'headline',
- 'status',
- 'statusLabel',
- 'kpis',
- 'charts',
- 'tables',
- 'sections',
-]
+const XLSX_COLOR = 'hex such as "#1e3a8a" or a basic color name such as "green"'
-/** Data the chosen template does not show, which the model would otherwise believe is on the page. */
-function ignoredDashboardFields(template: DashboardTemplateName, data: DashData): string[] {
- const ignored = Object.entries(TEMPLATE_ONLY_FIELDS)
- .filter(([field, templates]) => data[field] !== undefined && !templates.includes(template))
- .map(([field, templates]) => `data.${field} is only shown by template '${templates[0]}'`)
- if (template === 'custom') {
- for (const field of FIXED_TEMPLATE_FIELDS) {
- if (data[field] !== undefined) {
- ignored.push(`data.${field} is not read by template 'custom' (put it in a block)`)
- }
+const generateXlsx: InternalToolDefinition = {
+ name: 'clerum__generate_xlsx',
+ description:
+ 'Generate a styled Excel (.xlsx) workbook: per sheet, rows plus an optional title row, ' +
+ 'column formats, conditional formatting and images such as charts. Formulas are not ' +
+ 'supported: text starting with "=" stays text.',
+ parameters: {
+ type: 'object',
+ properties: {
+ filename: {
+ type: 'string',
+ description: "Output filename (e.g. 'data.xlsx'); .xlsx added if missing.",
+ },
+ palette: {
+ type: 'string',
+ enum: ['default', 'corporate', 'warm', 'alert'],
+ description: "Color palette. Default 'default'.",
+ },
+ branding: {
+ type: 'object',
+ description: 'Workbook-level branding.',
+ properties: {
+ companyName: { type: 'string', description: 'Author/company in workbook properties.' },
+ logoPath: {
+ type: 'string',
+ description:
+ 'Logo at the top of the first sheet; an image file name as in sheets[].images.',
+ },
+ },
+ },
+ sheets: {
+ type: 'array',
+ description: 'Worksheets, in tab order.',
+ items: {
+ type: 'object',
+ required: ['name', 'rows'],
+ properties: {
+ name: {
+ type: 'string',
+ description: 'Tab name: up to 31 characters, none of \\ / ? * : [ ].',
+ },
+ headers: {
+ type: 'array',
+ description: 'Header row, when it is not the first row of rows.',
+ items: { type: ['string', 'number'], description: 'Column header.' },
+ },
+ rows: {
+ type: 'array',
+ description:
+ 'Rows of cells; the first is the header row unless headers is given. [] for an images-only sheet.',
+ items: {
+ anyOf: [
+ {
+ type: 'array',
+ description: 'One row, left to right.',
+ items: XLSX_CELL_SCHEMA,
+ },
+ RECORD_ROW_SCHEMA,
+ ],
+ },
+ },
+ titleRow: {
+ type: 'object',
+ description: 'Merged title row above the header.',
+ properties: {
+ text: { type: 'string', description: 'Title text.' },
+ fillColor: { type: 'string', description: `Background: ${XLSX_COLOR}.` },
+ fontColor: { type: 'string', description: `Text color: ${XLSX_COLOR}.` },
+ },
+ required: ['text'],
+ },
+ columnFormats: {
+ type: 'object',
+ description:
+ "Format per column, keyed by header text, letter ('B') or 0-based index: " +
+ 'currencyUsd, currencyUsdInt, currency:EUR (any ISO code), percent (0.45 = 45%), ' +
+ 'percentPoints (45 = 45%), integer, decimal, plain (no separators: years, IDs), ' +
+ "date, datetime, text (as sent), or an Excel code like '#,##0.0'. Others are inferred.",
+ },
+ conditionalFormatting: {
+ type: 'array',
+ description: "Style a column's cells that match a rule.",
+ items: {
+ type: 'object',
+ required: ['column', 'rules'],
+ properties: {
+ column: {
+ type: ['string', 'number'],
+ description: "Header text, letter ('B') or 0-based index.",
+ },
+ rules: {
+ type: 'array',
+ description:
+ "Tested in order; the first match styles the cell. '45%' compares as 45, '$1,200' as 1200.",
+ items: {
+ type: 'object',
+ properties: {
+ equals: {
+ type: ['string', 'number', 'boolean'],
+ description: 'Cell equals this (text ignores case and outer spaces).',
+ },
+ notEquals: {
+ type: ['string', 'number', 'boolean'],
+ description: 'Cell differs from this, compared as for equals.',
+ },
+ greaterThan: {
+ type: 'number',
+ description: 'Cell is a number above this.',
+ },
+ lessThan: {
+ type: 'number',
+ description: 'Cell is a number below this.',
+ },
+ between: {
+ type: 'array',
+ items: { type: 'number' },
+ minItems: 2,
+ maxItems: 2,
+ description: 'Inclusive [min, max].',
+ },
+ contains: {
+ type: 'string',
+ description: 'Cell text contains this, ignoring case.',
+ },
+ regex: {
+ type: 'string',
+ maxLength: 256,
+ description:
+ 'Regex tested on the cell text. Invalid patterns and nested unbounded quantifiers are skipped with a warning.',
+ },
+ fillColor: {
+ type: 'string',
+ description: `Background: ${XLSX_COLOR}.`,
+ },
+ fontColor: {
+ type: 'string',
+ description: `Text color: ${XLSX_COLOR}.`,
+ },
+ bold: {
+ type: 'boolean',
+ description: 'Bold the text.',
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ freezeHeader: {
+ type: 'boolean',
+ description: 'Freeze the header row. Default true.',
+ },
+ autoFilter: {
+ type: 'boolean',
+ description: 'Filter buttons on the header. Default true.',
+ },
+ images: {
+ type: 'array',
+ description:
+ 'Images such as charts; without anchor or range they stack below the data.',
+ items: {
+ anyOf: [
+ { type: 'string', description: XLSX_IMAGE_PATH_DESCRIPTION },
+ {
+ type: 'object',
+ required: ['path'],
+ properties: {
+ path: { type: 'string', description: 'Same as the string form.' },
+ anchor: { type: 'string', description: "Top-left cell, e.g. 'F2'." },
+ range: { type: 'string', description: "Cells to fill, e.g. 'F2:M20'." },
+ width: {
+ type: 'number',
+ description: 'Width in px; proportions are kept. Omit for automatic.',
+ },
+ height: { type: 'number', description: 'Height in px; as for width.' },
+ },
+ },
+ ],
+ description: 'An image file name, or {path, anchor | range, width, height}.',
+ },
+ },
+ },
+ },
+ },
+ },
+ required: ['filename', 'sheets'],
+ },
+ async execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
+ try {
+ const filename = outputFilename(args.filename, 'xlsx', 'output')
+ const warnings: string[] = []
+ const built = await buildXlsxWorkbook(
+ args,
+ outputDir,
+ { width: XLSX_MAX_IMAGE_WIDTH, height: XLSX_MAX_IMAGE_HEIGHT },
+ warnings
+ )
+ if (!built.ok) return { success: false, error: built.error }
+ // The workbook is already in memory, so a quota breach leaves no partial file.
+ ensureDir(outputDir)
+ const target = claimOutputFile(outputDir, filename)
+ enforceQuota(outputDir, built.buffer.byteLength, replacedBytes(target))
+ fs.writeFileSync(target.filePath, built.buffer)
+ return artifactResult(target, 'xlsx', {
+ summary: `File generated: ${target.filename} (xlsx): ${built.summary}.`,
+ warnings,
+ })
+ } catch (err) {
+ return { success: false, error: err instanceof Error ? err.message : String(err) }
}
- }
- return ignored.map(line => `${line}; it was left out.`)
+ },
}
-// ─── generate_dashboard tool definition ─────────────────────────────
+// ════════════════════════════════════════════════════════════════════
+// ─── DASHBOARD GENERATION (clerum__generate_dashboard) ──────────────
+// ════════════════════════════════════════════════════════════════════
+//
+// Self-contained HTML dashboard renderer. Produces a single .html file
+// with inlined CSS, plus the Chart.js bundle when the page has charts;
+// works offline and prints cleanly.
+//
+// Templates (4 fixed presets):
+// - executive-brief general-purpose daily/weekly executive report
+// - operations-pulse engineering / SRE / oncall view
+// - financial-review finance with hero chart + dense tables
+// - technical-report long-form engineering writeup with code blocks
+//
+// Themes: default | corporate | warm | alert (light + dark variants)
-const DASHBOARD_TEMPLATE_NAMES = [
- 'executive-brief',
- 'operations-pulse',
- 'financial-review',
- 'technical-report',
- 'custom',
-] as const
+// ─── CSS builder ────────────────────────────────────────────────────
const DELTA_DIRECTION_SCHEMA = {
type: 'string',
@@ -5636,66 +1260,8 @@ const generateDashboardTool: InternalToolDefinition = {
},
required: ['filename', 'data'],
},
- async execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
- try {
- const filename = outputFilename(args.filename, 'html', 'dashboard')
- const data = args.data
- if (!isDashRecord(data) || !dashText(data.title).trim()) {
- return {
- success: false,
- error:
- 'data.title is required: pass data as an object with the dashboard heading, ' +
- 'e.g. {"title": "Weekly review", "kpis": [...]}.',
- }
- }
- const template = oneOf(args.template, DASHBOARD_TEMPLATE_NAMES, 'executive-brief')
- const inlineChartJs = args.inlineChartJs !== false
- const { html, ctx } = renderDashboard({
- template,
- data,
- theme: oneOf(args.theme, ['default', 'corporate', 'warm', 'alert'] as const, 'default'),
- defaultThemeMode:
- args.defaultThemeMode === 'light' || args.defaultThemeMode === 'dark'
- ? args.defaultThemeMode
- : undefined,
- inlineChartJs,
- branding: isDashRecord(args.branding) ? args.branding : {},
- })
-
- const produced = ctx.rendered + ctx.charts.drawn
- if (produced === 0 && ctx.failures.length > 0) {
- return {
- success: false,
- error: `Nothing on the dashboard could be shown, so no file was written. ${ctx.failures.join(' ')}`,
- }
- }
- const warnings = [
- ...ctx.failures.map(f => `${f} A notice shows in its place.`),
- ...ignoredDashboardFields(template, data),
- ...ctx.warnings,
- ]
- if (produced === 0) {
- warnings.push(
- 'The dashboard only shows its title: pass kpis, charts, tables or sections ' +
- "(blocks for template 'custom')."
- )
- }
- if (!inlineChartJs && (ctx.charts.drawn > 0 || ctx.skippedSparklines > 0)) {
- warnings.push(
- 'inlineChartJs is false, so charts are shown as tables of their values and ' +
- 'sparklines are left out.'
- )
- }
-
- ensureDir(outputDir)
- const target = claimOutputFile(outputDir, filename)
- enforceQuota(outputDir, Buffer.byteLength(html, 'utf-8'), replacedBytes(target))
- fs.writeFileSync(target.filePath, html, 'utf-8')
-
- return artifactResult(target, 'html', { warnings })
- } catch (err) {
- return { success: false, error: err instanceof Error ? err.message : String(err) }
- }
+ execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
+ return runGenerateDashboard(args, outputDir)
},
}
diff --git a/mcp-host/src/workflow/pdfGenerator.ts b/mcp-host/src/workflow/pdfGenerator.ts
new file mode 100644
index 000000000..d0de67cbf
--- /dev/null
+++ b/mcp-host/src/workflow/pdfGenerator.ts
@@ -0,0 +1,1242 @@
+/** The PDF generator (clerum__generate_pdf): markdown body, tables and images typeset with pdfmake. */
+import * as fs from 'fs'
+import * as path from 'path'
+import type { Content, ContentText, Node, TDocumentDefinitions } from 'pdfmake/interfaces'
+import {
+ artifactResult,
+ claimOutputFile,
+ enforceQuota,
+ ensureDir,
+ outputFilename,
+ replacedBytes,
+} from './artifactOutput'
+import {
+ EMPTY_DOCUMENT_NOTE,
+ PDF_FOOTER_SIZE,
+ RUNNING_LINE_CHARS,
+ footerLines,
+ longestFitting,
+ printedBranding,
+} from './documentChrome'
+import { documentEastAsianScript } from './docxScript'
+import { fitImageSize, imageDataUrl, loadEmbeddableImage } from './embeddedImages'
+import { PDF_FONT_FAMILY, PDF_MONO_FAMILY, pdfGlyphSource } from './fonts'
+import {
+ closesFence,
+ htmlToPlainText,
+ inlineSpans,
+ openingFence,
+ quoteParagraphs,
+ withoutClosingHashes,
+} from './inlineMarkup'
+import {
+ BODY_FONT_SIZE,
+ MIN_BOTTOM_MARGIN,
+ PORTRAIT,
+ type UnitMeasure,
+ layoutPdfTable,
+} from './pdfTables'
+import { LINE_FILL, PdfTypesetter } from './pdfText'
+import { headerText, normalizeTableRows } from './tableRows'
+import type { InternalToolResult } from './types'
+
+const PdfPrinter = require('pdfmake')
+
+interface PdfPalette {
+ primary: string
+ text: string
+ muted: string
+ border: string
+ accent: string
+ statusGreen: string
+ statusYellow: string
+ statusRed: string
+ alternateRowFill: string
+ surface: string
+}
+
+const PDF_PALETTES: Record<string, PdfPalette> = {
+ default: {
+ primary: '#0f172a',
+ text: '#0f172a',
+ muted: '#475569',
+ border: '#cbd5e1',
+ accent: '#3b82f6',
+ statusGreen: '#16a34a',
+ statusYellow: '#ca8a04',
+ statusRed: '#dc2626',
+ alternateRowFill: '#f8fafc',
+ surface: '#f1f5f9',
+ },
+ corporate: {
+ primary: '#1e3a8a',
+ text: '#1e293b',
+ muted: '#475569',
+ border: '#cbd5e1',
+ accent: '#0891b2',
+ statusGreen: '#059669',
+ statusYellow: '#ca8a04',
+ statusRed: '#b91c1c',
+ alternateRowFill: '#f1f5f9',
+ surface: '#e0f2fe',
+ },
+ warm: {
+ primary: '#b45309',
+ text: '#2f2823',
+ muted: '#66584c',
+ border: '#d6d2cc',
+ accent: '#b45309',
+ statusGreen: '#15803d',
+ statusYellow: '#b45309',
+ statusRed: '#9f1239',
+ alternateRowFill: '#fefdfb',
+ surface: '#f7f7f5',
+ },
+ alert: {
+ primary: '#9f1239',
+ text: '#1f2937',
+ muted: '#4b5563',
+ border: '#fecaca',
+ accent: '#dc2626',
+ statusGreen: '#15803d',
+ statusYellow: '#ca8a04',
+ statusRed: '#9f1239',
+ alternateRowFill: '#fef2f2',
+ surface: '#fee2e2',
+ },
+}
+
+/** A4 width (595pt) less the 40pt side margins the documents use. */
+const PDF_CONTENT_WIDTH = PORTRAIT.width
+
+/** Keeps a tall image from taking a whole page on its own. */
+const PDF_MAX_IMAGE_HEIGHT = 330
+
+/** Vertical margin around an embedded image, above and below. */
+const PDF_IMAGE_MARGIN = 10
+
+/** The cover logo's box: its usual width, and a height a tall logo cannot exceed. */
+const PDF_LOGO_BOX = { width: 120, height: 80 }
+
+/**
+ * Id prefix of each table's first header cell. pdfmake corrects the page
+ * number it records for a block moved to the next page only on nodes with an
+ * id, and the heading check reads it to see where a table really starts.
+ */
+const TABLE_HEADER_ID = 'pdf-table-'
+
+/**
+ * Style of the running header and footer. pdfmake lists their nodes among a
+ * page's content when deciding page breaks, and this is how they are told apart.
+ */
+const RUNNING_STYLE = 'running'
+
+/** Top page margin; the running header is drawn inside it. */
+const PDF_TOP_MARGIN = 60
+
+const PDF_LINE_HEIGHT = 1.3
+
+interface PdfBranding {
+ logoPath?: string
+ companyName?: string
+ footerText?: string
+}
+
+interface PdfImageRef {
+ path: string
+ width?: number
+ height?: number
+ alignment?: 'left' | 'center' | 'right'
+}
+
+interface PdfTableSpec {
+ headers: unknown[]
+ rows: unknown
+ widths?: unknown
+ layout?: 'striped' | 'minimal' | 'grid'
+}
+
+/** What the body parser needs from the call it serves. */
+interface PdfBodyEnv {
+ warnings: string[]
+ /** Width of text at 1pt in the body face, for sizing table columns. */
+ measure: UnitMeasure
+ /** An image block for a `![alt](file)` line, or undefined when it could not be loaded. */
+ image(src: string): Content | undefined
+ /** Tables that need landscape pages. */
+ landscape: Set<Content>
+ /** Tables parsed from the body so far, for naming them in warnings. */
+ tableCount: number
+ /** Tables built so far, body and explicit, for giving each header a unique id. */
+ tablesBuilt: number
+ /** Bottom page margin, which grows with the footer. */
+ bottomMargin: number
+}
+
+/** An image reference written in the body: `![alt](src)`. */
+interface MarkdownImage {
+ alt: string
+ src: string
+}
+
+/**
+ * Inline markup of one line as pdfmake runs: **bold**, *italic*, ~~strike~~,
+ * `code`, links, the HTML tags models write, and character entities. Image
+ * references are taken out of the text and handed to `onImage`.
+ */
+function parseInlineMarkdown(line: string, onImage: (image: MarkdownImage) => void): ContentText {
+ const runs: ContentText[] = []
+ for (const span of inlineSpans(line)) {
+ if (span.image !== undefined) {
+ onImage({ alt: span.text, src: span.image })
+ continue
+ }
+ runs.push({
+ text: span.text,
+ ...(span.bold ? { bold: true } : {}),
+ ...(span.italics ? { italics: true } : {}),
+ ...(span.code ? { font: PDF_MONO_FAMILY } : {}),
+ ...(span.link !== undefined
+ ? { link: span.link, color: '#1d4ed8', decoration: 'underline' as const }
+ : span.strike
+ ? { decoration: 'lineThrough' as const }
+ : {}),
+ })
+ }
+ return { text: runs }
+}
+
+/** Characters, and styled runs, one pdfmake paragraph holds before the next piece starts. */
+const PARAGRAPH_PIECE_CHARS = 20_000
+const PARAGRAPH_PIECE_RUNS = 1_000
+
+/**
+ * `paragraph` in pieces of up to PARAGRAPH_PIECE_CHARS characters and
+ * PARAGRAPH_PIECE_RUNS runs, each cut after a space where there is one.
+ * pdfmake lays a paragraph out in time that grows with the square of its words
+ * and runs, so one 200 KB line of alternating emphasis held the event loop for
+ * half a minute; pieces set one under another read on as the same paragraph,
+ * with a line ending at each cut. No paragraph a person writes reaches either
+ * limit.
+ */
+function inPieces(paragraph: ContentText): ContentText[] {
+ if (
+ !Array.isArray(paragraph.text) ||
+ (paragraph.text.length <= PARAGRAPH_PIECE_RUNS &&
+ plainText(paragraph).length <= PARAGRAPH_PIECE_CHARS)
+ ) {
+ return [paragraph]
+ }
+ const pieces: ContentText[][] = [[]]
+ let size = 0
+ for (const run of paragraph.text as ContentText[]) {
+ if (pieces[pieces.length - 1].length >= PARAGRAPH_PIECE_RUNS) {
+ pieces.push([])
+ size = 0
+ }
+ let text = String(run.text ?? '')
+ while (size + text.length > PARAGRAPH_PIECE_CHARS) {
+ const room = PARAGRAPH_PIECE_CHARS - size
+ let cut = text.lastIndexOf(' ', room - 1) + 1
+ if (cut <= 0 && size > 0) {
+ pieces.push([])
+ size = 0
+ continue
+ }
+ if (cut <= 0) {
+ // No space to cut after: cut inside the word, never inside a surrogate pair.
+ cut = room
+ const code = text.charCodeAt(cut - 1)
+ if (code >= 0xd800 && code <= 0xdbff) cut--
+ }
+ pieces[pieces.length - 1].push({ ...run, text: text.slice(0, cut) })
+ pieces.push([])
+ size = 0
+ text = text.slice(cut)
+ }
+ if (text) {
+ pieces[pieces.length - 1].push({ ...run, text })
+ size += text.length
+ }
+ }
+ return pieces.filter(piece => piece.length > 0).map(piece => ({ text: piece }))
+}
+
+/** `parsed` as it is, or as a stack of its pieces when it is that long. */
+function asPieces(parsed: ContentText): ContentText | { stack: ContentText[] } {
+ const pieces = inPieces(parsed)
+ return pieces.length === 1 ? pieces[0] : { stack: pieces }
+}
+
+/** The text a parsed line prints, for measuring it. */
+function plainText(parsed: ContentText): string {
+ const text = parsed.text
+ if (!Array.isArray(text)) return String(text ?? '')
+ return text
+ .map(t => (typeof t === 'string' ? t : String((t as { text?: unknown }).text ?? '')))
+ .join('')
+}
+
+/** A GFM delimiter row. One column needs its outer pipes, or it is only a rule. */
+function isTableSeparator(line: string): boolean {
+ return (
+ /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?\s*$/.test(line) ||
+ /^\s*\|\s*:?-+:?\s*\|\s*$/.test(line)
+ )
+}
+
+/** Cells of a pipe-table row. `\|` is a literal pipe inside a cell. */
+function splitTableRow(line: string): string[] {
+ let trimmed = line.trim()
+ if (trimmed.startsWith('|')) trimmed = trimmed.slice(1)
+ if (trimmed.endsWith('|') && !trimmed.endsWith('\\|')) trimmed = trimmed.slice(0, -1)
+ return trimmed.split(/(?<!\\)\|/).map(c => c.trim().replace(/\\\|/g, '|'))
+}
+
+/**
+ * Whether a GFM table starts at line `i`. GFM makes the outer pipes optional
+ * and some models leave them out, so a header without them counts when it has
+ * as many cells as the separator under it.
+ */
+function isPipeTableStart(lines: string[], i: number): boolean {
+ const line = lines[i]
+ const next = lines[i + 1]
+ if (next === undefined || !line.includes('|') || !isTableSeparator(next)) return false
+ return (
+ line.trimStart().startsWith('|') || splitTableRow(line).length === splitTableRow(next).length
+ )
+}
+
+type ColumnAlignment = 'left' | 'center' | 'right'
+
+interface PdfTableRequest {
+ headers: string[]
+ rows: string[][]
+ layout?: 'striped' | 'minimal' | 'grid'
+ widths?: unknown
+ alignments?: ColumnAlignment[]
+ /** How warnings name the table, such as "tables[0]". */
+ label: string
+ /** How warnings name one of its rows, such as "tables[0].rows[2]". */
+ rowLabel(index: number): string
+}
+
+function buildTableNode(
+ request: PdfTableRequest,
+ palette: PdfPalette,
+ env: PdfBodyEnv,
+ onImage: (image: MarkdownImage) => void
+): Content {
+ const { headers, alignments } = request
+ const layout = request.layout ?? 'striped'
+ // pdfmake needs every row to have one cell per column: short rows are
+ // padded, and cells past the last header are cut and reported.
+ const long = request.rows.flatMap((row, i) => (row.length > headers.length ? [i] : []))
+ if (long.length > 0) {
+ const first = request.rows[long[0]].length
+ env.warnings.push(
+ `${request.rowLabel(long[0])} has ${first} cells for ${headers.length} headers` +
+ (long.length > 1 ? ` (and ${long.length - 1} more row(s) have too many)` : '') +
+ ', so the cells past the last header were left out; add a header for every column.'
+ )
+ }
+ const cells = request.rows.map(row =>
+ normalizeRowLength(row, headers.length).map(cell => parseInlineMarkdown(cell ?? '', onImage))
+ )
+ const headerCells = headers.map(h => parseInlineMarkdown(h, onImage))
+ const fit = layoutPdfTable(
+ {
+ headers: headerCells.map(plainText),
+ rows: cells.map(row => row.map(plainText)),
+ requested: request.widths,
+ cellPadding: 8,
+ ruleWidth: layout === 'grid' ? 0.5 : 0,
+ allowLandscape: true,
+ label: request.label,
+ bottomMargin: env.bottomMargin,
+ },
+ env.measure,
+ env.warnings
+ )
+ const align = (col: number) =>
+ alignments?.[col] && alignments[col] !== 'left' ? { alignment: alignments[col] } : {}
+ const node = {
+ table: {
+ headerRows: 1,
+ // Without this a table starting near the foot of a page leaves its
+ // header stranded there with every row on the next one.
+ ...(fit.keepWithHeaderRows ? { keepWithHeaderRows: 1 } : {}),
+ dontBreakRows: fit.dontBreakRows,
+ widths: fit.widths,
+ body: [
+ headerCells.map((h, col) => ({
+ ...asPieces(h),
+ ...(col === 0 ? { id: `${TABLE_HEADER_ID}${++env.tablesBuilt}` } : {}),
+ bold: true,
+ color: '#ffffff',
+ fillColor: palette.primary,
+ ...align(col),
+ })),
+ // pdfmake accepts a `text` array of inline runs as a cell — use that
+ // so **bold** / *italic* / `code` inside cells render correctly.
+ ...cells.map(row => row.map((cell, col) => ({ ...asPieces(cell), ...align(col) }))),
+ ],
+ },
+ layout: pdfTableLayout(layout, palette),
+ margin: [0, 4, 0, 8],
+ ...(fit.fontSize !== BODY_FONT_SIZE ? { fontSize: fit.fontSize } : {}),
+ } as Content
+ if (fit.landscape) env.landscape.add(node)
+ return node
+}
+
+/**
+ * Pad/truncate a row to a fixed number of columns. Used by table builders
+ * to make ragged input deterministic.
+ */
+function normalizeRowLength<T>(row: T[], width: number): (T | '')[] {
+ if (row.length === width) return row
+ if (row.length > width) return row.slice(0, width)
+ return [...row, ...Array<''>(width - row.length).fill('')]
+}
+
+function pdfTableLayout(name: 'striped' | 'minimal' | 'grid', palette: PdfPalette) {
+ if (name === 'minimal') {
+ return {
+ hLineWidth: (i: number, node: { table: { body: unknown[] } }) =>
+ i === 0 || i === 1 || i === node.table.body.length ? 0.7 : 0,
+ vLineWidth: () => 0,
+ hLineColor: () => palette.border,
+ }
+ }
+ if (name === 'grid') {
+ return {
+ hLineWidth: () => 0.5,
+ vLineWidth: () => 0.5,
+ hLineColor: () => palette.border,
+ vLineColor: () => palette.border,
+ }
+ }
+ return {
+ hLineWidth: (i: number, node: { table: { body: unknown[] } }) =>
+ i === 0 || i === 1 || i === node.table.body.length ? 0.7 : 0,
+ vLineWidth: () => 0,
+ hLineColor: () => palette.border,
+ fillColor: (rowIndex: number) =>
+ rowIndex === 0 ? null : rowIndex % 2 === 0 ? palette.alternateRowFill : null,
+ }
+}
+
+/** Read the alignments a GFM separator row declares (`:---`, `---:`, `:---:`). */
+function parseColumnAlignments(separator: string): ColumnAlignment[] {
+ return splitTableRow(separator).map(cell => {
+ const c = cell.trim()
+ const left = c.startsWith(':')
+ const right = c.endsWith(':')
+ if (left && right) return 'center'
+ if (right) return 'right'
+ return 'left'
+ })
+}
+
+/** Indent width of a list line, used to decide its nesting depth. */
+function indentOf(line: string): number {
+ const m = /^[ \t]*/.exec(line)
+ if (!m) return 0
+ // A tab counts as one level, matching how models write nested lists.
+ return m[0].replace(/\t/g, ' ').length
+}
+
+const BULLET_RE = /^[-*+]\s+/
+const ORDERED_RE = /^\d+[.)]\s+/
+
+function isListLine(line: string): boolean {
+ const t = line.trimStart()
+ return BULLET_RE.test(t) || ORDERED_RE.test(t)
+}
+
+function stripListMarker(line: string): string {
+ const t = line.trimStart()
+ return t.replace(BULLET_RE, '').replace(ORDERED_RE, '')
+}
+
+/**
+ * Build one list level, consuming the lines that belong to it. A line indented
+ * further than the level's own indent starts a nested list attached to the item
+ * above it, which is what preserves the hierarchy the author wrote.
+ */
+function buildList(
+ lines: string[],
+ start: number,
+ indent: number,
+ onImage: (image: MarkdownImage) => void
+): { node: Content; next: number } {
+ const ordered = ORDERED_RE.test(lines[start].trimStart())
+ const items: Content[] = []
+ let i = start
+
+ while (i < lines.length) {
+ if (lines[i].trim() === '') {
+ // Blank lines between items keep the list going: models separate
+ // numbered steps that way and expect the numbers to continue.
+ let j = i
+ while (j < lines.length && lines[j].trim() === '') j++
+ const continues =
+ j < lines.length &&
+ isListLine(lines[j]) &&
+ (indentOf(lines[j]) > indent ||
+ (indentOf(lines[j]) === indent && ORDERED_RE.test(lines[j].trimStart()) === ordered))
+ if (!continues) break
+ i = j
+ continue
+ }
+ if (!isListLine(lines[i]) || indentOf(lines[i]) < indent) break
+ const own = indentOf(lines[i])
+ if (own > indent) {
+ // Deeper than this level: attach to the previous item as a sub-list.
+ const sub = buildList(lines, i, own, onImage)
+ const previous = items.pop()
+ items.push(previous ? ([previous, sub.node] as unknown as Content) : sub.node)
+ i = sub.next
+ continue
+ }
+ const isOrdered = ORDERED_RE.test(lines[i].trimStart())
+ // Switching between bullets and numbers at the same indent starts a different list.
+ if (isOrdered !== ordered) break
+ items.push(asPieces(parseInlineMarkdown(stripListMarker(lines[i]), onImage)))
+ i++
+ }
+
+ // A list that picks up after a code block or a paragraph keeps its numbers.
+ const first = ordered ? parseInt(lines[start].trimStart(), 10) : 1
+ const node = (
+ ordered
+ ? { ol: items, ...(first !== 1 ? { start: first } : {}), margin: [0, 4, 0, 6] }
+ : { ul: items, margin: [0, 4, 0, 6] }
+ ) as Content
+ return { node, next: i }
+}
+
+/**
+ * Convert a markdown body into pdfmake content nodes: a single-pass line
+ * scanner for headings, fenced code, rules, GFM tables, quotes, lists, image
+ * lines and paragraphs.
+ */
+function bodyToContent(body: string, palette: PdfPalette, env: PdfBodyEnv): Content[] {
+ const out: Content[] = []
+ const lines = body.split('\n')
+ // A paragraph's images are placed after it; anywhere else they are left out
+ // with a note rather than printing their path.
+ const stray = (image: MarkdownImage) =>
+ env.warnings.push(
+ `The image '${image.src}' inside a table, list, heading or quote was left out; put ` +
+ `![alt](${image.src}) on a line of its own to embed it.`
+ )
+ let i = 0
+ while (i < lines.length) {
+ const line = lines[i]
+ const trimmed = line.trimStart()
+
+ // Fenced code block. Everything up to the closing fence is verbatim, so a
+ // shell snippet or a config sample keeps its spacing instead of being
+ // reflowed into paragraphs.
+ const fence = openingFence(trimmed)
+ if (fence) {
+ const { marker, language } = fence
+ const code: string[] = []
+ i++
+ while (i < lines.length && !closesFence(lines[i], marker)) {
+ code.push(lines[i])
+ i++
+ }
+ i++ // closing fence
+ out.push(buildCodeBlock(code.join('\n'), language, palette))
+ continue
+ }
+
+ // Heading levels. The deeper ones share h3's style rather than falling
+ // through as literal hashes. headlineLevel marks them for the page-break
+ // check that keeps a heading off the foot of a page.
+ const heading = /^(#{1,6})\s+(.*)$/.exec(trimmed)
+ if (heading) {
+ const level = heading[1].length
+ const style = level === 1 ? 'h1' : level === 2 ? 'h2' : 'h3'
+ const top = level === 1 ? 16 : level === 2 ? 12 : 8
+ out.push({
+ ...asPieces(parseInlineMarkdown(withoutClosingHashes(heading[2]), stray)),
+ style,
+ headlineLevel: 1,
+ margin: [0, top, 0, level === 1 ? 6 : 4],
+ } as Content)
+ i++
+ continue
+ }
+
+ // Horizontal rule in any of the three markdown spellings.
+ if (/^(-{3,}|\*{3,}|_{3,})$/.test(trimmed.replace(/\s+/g, ''))) {
+ out.push({
+ canvas: [
+ {
+ type: 'line',
+ x1: 0,
+ y1: 0,
+ x2: PDF_CONTENT_WIDTH,
+ y2: 0,
+ lineWidth: 0.5,
+ lineColor: palette.border,
+ },
+ ],
+ margin: [0, 8, 0, 8],
+ })
+ i++
+ continue
+ }
+
+ // GFM pipe table: header line, then separator, then the rows up to the
+ // first line without a pipe.
+ if (isPipeTableStart(lines, i)) {
+ const headers = splitTableRow(line)
+ const alignments = parseColumnAlignments(lines[i + 1])
+ const rows: string[][] = []
+ i += 2
+ while (i < lines.length && lines[i].trim() !== '' && lines[i].includes('|')) {
+ rows.push(splitTableRow(lines[i]))
+ i++
+ }
+ const label = `The body's table ${++env.tableCount}`
+ out.push(
+ buildTableNode(
+ { headers, rows, alignments, label, rowLabel: index => `${label}, row ${index + 1}` },
+ palette,
+ env,
+ stray
+ )
+ )
+ continue
+ }
+
+ // Blockquote: consecutive `>` lines become one ruled, indented block.
+ if (/^>\s?/.test(trimmed)) {
+ const quoted: string[] = []
+ while (i < lines.length && /^>\s?/.test(lines[i].trimStart())) {
+ quoted.push(lines[i].trimStart().replace(/^>\s?/, ''))
+ i++
+ }
+ out.push(buildBlockquote(quoteParagraphs(quoted), palette, stray))
+ continue
+ }
+
+ // Bullet or numbered list, including anything nested under it.
+ if (isListLine(line)) {
+ const built = buildList(lines, i, indentOf(line), stray)
+ out.push(built.node)
+ i = built.next
+ continue
+ }
+
+ // Blank line: small vertical breathing room.
+ if (trimmed === '') {
+ out.push({ text: '', margin: [0, 2, 0, 2] })
+ i++
+ continue
+ }
+
+ // Default: paragraph with inline markdown, then any images it references.
+ const images: MarkdownImage[] = []
+ const paragraph = parseInlineMarkdown(line, image => images.push(image))
+ if (plainText(paragraph).trim() !== '') {
+ const pieces = inPieces(paragraph)
+ pieces.forEach((piece, p) =>
+ out.push({ ...piece, margin: [0, 0, 0, p === pieces.length - 1 ? 4 : 0] })
+ )
+ }
+ for (const image of images) {
+ const block = env.image(image.src)
+ if (block) out.push(block)
+ }
+ i++
+ }
+ return out
+}
+
+/** Monospaced block on a tinted ground, with the language noted when given. */
+function buildCodeBlock(code: string, language: string, palette: PdfPalette): Content {
+ const stack: Content[] = []
+ if (language) {
+ stack.push({
+ text: language,
+ fontSize: 8,
+ color: palette.muted,
+ margin: [0, 0, 0, 2],
+ })
+ }
+ stack.push({
+ text: code,
+ font: PDF_MONO_FAMILY,
+ fontSize: 9,
+ color: palette.text,
+ preserveLeadingSpaces: true,
+ lineHeight: 1.25,
+ } as Content)
+ return {
+ table: {
+ // A numeric width lets pdfmake break a line with no spaces (base64,
+ // minified JSON) inside the block; a '*' column is never narrower than
+ // its longest word.
+ widths: [PDF_CONTENT_WIDTH - 2],
+ body: [[{ stack, margin: [8, 6, 8, 6] }]],
+ },
+ layout: {
+ hLineWidth: () => 0,
+ vLineWidth: (i: number) => (i === 0 ? 2 : 0),
+ vLineColor: () => palette.border,
+ paddingLeft: () => 0,
+ paddingRight: () => 0,
+ paddingTop: () => 0,
+ paddingBottom: () => 0,
+ fillColor: () => palette.surface,
+ },
+ margin: [0, 6, 0, 8],
+ } as Content
+}
+
+/** Quoted passage, set off by a rule down its left edge. */
+function buildBlockquote(
+ paragraphs: string[],
+ palette: PdfPalette,
+ onImage: (image: MarkdownImage) => void
+): Content {
+ return {
+ table: {
+ widths: [PDF_CONTENT_WIDTH - 2.5],
+ body: [
+ [
+ {
+ stack: paragraphs.flatMap((text, n) => {
+ const pieces = inPieces(parseInlineMarkdown(text, onImage))
+ return pieces.map((piece, p) => ({
+ ...piece,
+ margin: [0, 0, 0, p === pieces.length - 1 && n < paragraphs.length - 1 ? 4 : 0],
+ }))
+ }),
+ italics: true,
+ color: palette.muted,
+ margin: [10, 4, 6, 4],
+ },
+ ],
+ ],
+ },
+ layout: {
+ hLineWidth: () => 0,
+ vLineWidth: (i: number) => (i === 0 ? 2.5 : 0),
+ vLineColor: () => palette.primary,
+ paddingLeft: () => 0,
+ paddingRight: () => 0,
+ paddingTop: () => 0,
+ paddingBottom: () => 0,
+ },
+ margin: [0, 6, 0, 8],
+ } as Content
+}
+
+function statusColorFromPalette(palette: PdfPalette, status?: string): string | undefined {
+ if (!status) return undefined
+ const s = status.toLowerCase()
+ if (s === 'green' || s === 'ok' || s === 'pass') return palette.statusGreen
+ if (s === 'yellow' || s === 'warn' || s === 'warning') return palette.statusYellow
+ if (s === 'red' || s === 'critical' || s === 'fail') return palette.statusRed
+ // Unknown status keyword — fall back to muted accent so the band still
+ // renders (matching the documented "status indicator color" behavior)
+ // instead of silently dropping the cover-page band.
+ return palette.muted
+}
+
+const IMAGE_ALIGNMENTS = new Set(['left', 'center', 'right'])
+
+/** Where images come from, for the schema: the name clerum__generate_chart reports. */
+export const IMAGE_FILE_DESCRIPTION =
+ "File name of a PNG or JPEG (GIF, WebP and SVG are converted) in the output folder, as returned by clerum__generate_chart, e.g. 'sales.png'."
+
+/**
+ * pdfmake 0.2 calls this with the nodes that follow on the same page as its
+ * second argument (the bundled typings describe 0.3's query object instead).
+ * A heading with nothing after it on its page but more content on the next
+ * page is moved there, so it is never left alone at the foot of a page.
+ */
+function keepHeadingWithNext(node: Node, followingOnPage: Node[]): boolean {
+ if (
+ node.headlineLevel !== 1 ||
+ node.pageNumbers.length !== 1 ||
+ node.pageNumbers[0] >= node.pages ||
+ // Already at the top of its page: moving it would only leave a blank page.
+ node.startPosition.top <= PDF_TOP_MARGIN + 20
+ ) {
+ return false
+ }
+ const following = followingOnPage.filter(next => next.style !== RUNNING_STYLE)
+ const content = following.find(next => next.headlineLevel !== 1)
+ if (!content) return true
+ // A table whose header row did not fit is carried to the next page whole,
+ // yet its cells are still listed on this one; only the header id says so.
+ const headerId = tableHeaderId(content)
+ if (headerId === undefined) return false
+ const header = following.find(next => next.id === headerId)
+ return header?.startPosition.pageNumber !== node.pageNumbers[0]
+}
+
+/**
+ * pdfmake hands a pageBreakBefore callback the nodes after each node on its
+ * page, which it collects by scanning the rest of the document for every node,
+ * and each break the callback asks for lays the whole document out again. Past
+ * these sizes the check costs more than a heading left at the foot of a page.
+ */
+const KEEP_WITH_NEXT_MAX_NODES = 1500
+const KEEP_WITH_NEXT_MAX_MOVES = 10
+
+/** How many nodes pdfmake lays out for `content`, counted up to `limit`. */
+function countNodes(content: unknown, limit: number): number {
+ let count = 0
+ const visit = (node: unknown): void => {
+ if (count > limit || node === null || typeof node !== 'object') return
+ if (Array.isArray(node)) {
+ for (const item of node) visit(item)
+ return
+ }
+ count++
+ const n = node as Record<string, unknown>
+ for (const key of ['stack', 'ul', 'ol', 'columns']) visit(n[key])
+ const table = n.table as { body?: unknown } | undefined
+ if (table) visit(table.body)
+ }
+ visit(content)
+ return count
+}
+
+/** keepHeadingWithNext for `content`, or undefined when the document is too large for it. */
+function headingKeeper(
+ content: Content[]
+): ((node: Node, following: Node[]) => boolean) | undefined {
+ if (countNodes(content, KEEP_WITH_NEXT_MAX_NODES) > KEEP_WITH_NEXT_MAX_NODES) return undefined
+ let moves = 0
+ return (node: Node, following: Node[]) => {
+ if (moves >= KEEP_WITH_NEXT_MAX_MOVES || !keepHeadingWithNext(node, following)) return false
+ moves++
+ return true
+ }
+}
+
+/** The id buildTableNode gave a table's header; a right-to-left table has it last. */
+function tableHeaderId(node: Node): string | undefined {
+ const header = (node as { table?: { body?: Array<Array<{ id?: unknown }>> } }).table?.body?.[0]
+ const id = Array.isArray(header)
+ ? header.find(cell => typeof cell?.id === 'string')?.id
+ : undefined
+ return typeof id === 'string' && id.startsWith(TABLE_HEADER_ID) ? id : undefined
+}
+
+/** The spacer bodyToContent leaves for a blank line. */
+function isBlankLine(node: Content): boolean {
+ return typeof node === 'object' && node !== null && 'text' in node && node.text === ''
+}
+
+/**
+ * Put each landscape table on landscape pages and return to portrait after
+ * it. A heading directly above such a table moves with it. Returns the
+ * orientation the document starts in.
+ */
+function applyPageOrientation(
+ content: Content[],
+ landscape: Set<Content>
+): 'portrait' | 'landscape' {
+ const previous = (i: number) => {
+ let k = i - 1
+ while (k >= 0 && isBlankLine(content[k])) k--
+ return k
+ }
+ let initial: 'portrait' | 'landscape' = 'portrait'
+ let current: 'portrait' | 'landscape' = 'portrait'
+ for (let i = 0; i < content.length; i++) {
+ if (isBlankLine(content[i])) continue
+ const wanted = landscape.has(content[i]) ? 'landscape' : 'portrait'
+ if (wanted === current) continue
+ current = wanted
+ let target = i
+ const above = content[previous(i)] as { headlineLevel?: number } | undefined
+ if (wanted === 'landscape' && above?.headlineLevel === 1) target = previous(i)
+ // A break before the first node, or after the one that already ends the
+ // cover page, would leave a blank page; those carry the orientation instead.
+ const before = previous(target)
+ if (before < 0) {
+ initial = wanted
+ } else if ((content[before] as { pageBreak?: string }).pageBreak === 'after') {
+ Object.assign(content[before] as object, { pageOrientation: wanted })
+ } else {
+ Object.assign(content[target] as object, { pageBreak: 'before', pageOrientation: wanted })
+ }
+ }
+ return initial
+}
+
+/**
+ * `text` cut at a word, with an ellipsis, to one line of the running header,
+ * where pdfmake drops whatever does not fit without a mark.
+ */
+function runningLine(text: string, width: number, measure: UnitMeasure): string {
+ const fits = (s: string) => measure(s, false) * PDF_FOOTER_SIZE <= width * LINE_FILL
+ if (text.length <= RUNNING_LINE_CHARS && fits(text)) return text
+ // Far more than a line holds, so a huge title is never measured whole.
+ const chars = Array.from(text.slice(0, RUNNING_LINE_CHARS))
+ let kept = chars
+ .slice(
+ 0,
+ longestFitting(chars, s => fits(`${s.trimEnd()}…`))
+ )
+ .join('')
+ const space = kept.lastIndexOf(' ')
+ if (space > kept.length * 0.6) kept = kept.slice(0, space)
+ return `${kept.trimEnd()}…`
+}
+
+export async function runGeneratePdf(
+ args: Record<string, unknown>,
+ outputDir: string
+): Promise<InternalToolResult> {
+ try {
+ const filename = outputFilename(args.filename, 'pdf', 'output')
+ const warnings: string[] = []
+ const glyphs = pdfGlyphSource()
+ // Titles take no formatting, so HTML in them is read as text.
+ const title = args.title ? htmlToPlainText(String(args.title)) || undefined : undefined
+ const body = String(args.body ?? '')
+ const paletteName = String(args.palette ?? 'default')
+ const palette = PDF_PALETTES[paletteName] ?? PDF_PALETTES.default
+ const branding: PdfBranding = printedBranding(args.branding)
+ const imageRefs = Array.isArray(args.images) ? args.images : []
+ const tables = (Array.isArray(args.tables) ? args.tables : []) as PdfTableSpec[]
+ const coverPage = Boolean(args.coverPage)
+ const headline = args.headline ? htmlToPlainText(String(args.headline)) || undefined : undefined
+ const statusBand = statusColorFromPalette(palette, args.statusColor as string | undefined)
+
+ // A path outside the output folder still fails the call, but says what to pass instead.
+ const loadImage = (ref: unknown, label: string) => {
+ try {
+ return loadEmbeddableImage(ref, outputDir, warnings, label)
+ } catch (err) {
+ const reason = err instanceof Error ? err.message : String(err)
+ throw new Error(
+ `${label}: ${reason}. Images are read from the output folder; pass the file name ` +
+ "clerum__generate_chart returned, such as 'sales.png'."
+ )
+ }
+ }
+
+ // The footer sets the bottom margin, and with it the room images and tables have.
+ const pageNumberWidth = 40
+ // Measured at 100pt and scaled down: at 1pt the canvas rounds widths to hundredths.
+ const measure: UnitMeasure = (text, bold) =>
+ glyphs.measure(text, PDF_FONT_FAMILY, 100, bold) / 100
+ const footer = branding.footerText
+ ? footerLines(branding.footerText, PDF_CONTENT_WIDTH - pageNumberWidth, measure, warnings)
+ : []
+ const bottomMargin = Math.max(MIN_BOTTOM_MARGIN, 34 + footer.length * PDF_FOOTER_SIZE * 1.3)
+ const contentHeight = PORTRAIT.height - (bottomMargin - MIN_BOTTOM_MARGIN)
+
+ let imagesRequested = 0
+ let imagesPlaced = 0
+ const placeImage = (
+ ref: unknown,
+ label: string,
+ sizing: { width?: unknown; height?: unknown; alignment?: unknown } = {}
+ ): Content | undefined => {
+ imagesRequested++
+ const src = typeof ref === 'string' ? ref : undefined
+ if (src && /^(https?:|data:)/i.test(src)) {
+ warnings.push(
+ `${label} is a web address or inline data, which is not downloaded; save the image to the ` +
+ 'output folder first (clerum__generate_chart does) and pass its file name.'
+ )
+ return undefined
+ }
+ const image = loadImage(ref, label)
+ if (!image) return undefined
+ const requested = {
+ ...(typeof sizing.width === 'number' ? { width: sizing.width } : {}),
+ ...(typeof sizing.height === 'number' ? { height: sizing.height } : {}),
+ }
+ const sized = requested.width !== undefined || requested.height !== undefined
+ const box = fitImageSize(
+ image,
+ {
+ width: PDF_CONTENT_WIDTH,
+ // An image given a size may take the page, less its own margins.
+ height: sized ? contentHeight - 2 * PDF_IMAGE_MARGIN : PDF_MAX_IMAGE_HEIGHT,
+ },
+ requested
+ )
+ imagesPlaced++
+ return {
+ image: imageDataUrl(image),
+ width: box.width,
+ height: box.height,
+ alignment: IMAGE_ALIGNMENTS.has(String(sizing.alignment)) ? sizing.alignment : 'center',
+ margin: [0, PDF_IMAGE_MARGIN, 0, PDF_IMAGE_MARGIN],
+ } as Content
+ }
+
+ const env: PdfBodyEnv = {
+ warnings,
+ measure,
+ image: src => placeImage(src, `The body image '${src}'`),
+ landscape: new Set(),
+ tableCount: 0,
+ tablesBuilt: 0,
+ bottomMargin,
+ }
+
+ const content: Content[] = []
+
+ // Cover page.
+ if (coverPage) {
+ const coverTitle = title ?? headline ?? filename.replace(/\.pdf$/, '')
+ if (!title) {
+ warnings.push(
+ `coverPage was set without a title, so the cover shows '${coverTitle}'; pass title to choose it.`
+ )
+ }
+ if (statusBand) {
+ content.push({
+ canvas: [
+ {
+ type: 'rect',
+ x: 0,
+ y: 0,
+ w: PDF_CONTENT_WIDTH,
+ h: 6,
+ color: statusBand,
+ },
+ ],
+ margin: [0, 0, 0, 24],
+ })
+ }
+ if (branding.logoPath) {
+ const logo = loadImage(branding.logoPath, 'branding.logoPath')
+ if (logo) {
+ const box = fitImageSize(logo, PDF_LOGO_BOX, { width: PDF_LOGO_BOX.width })
+ content.push({
+ image: imageDataUrl(logo),
+ width: box.width,
+ height: box.height,
+ margin: [0, 0, 0, 12],
+ })
+ }
+ }
+ content.push({
+ text: coverTitle,
+ style: 'cover',
+ color: palette.primary,
+ margin: [0, 80, 0, 12],
+ })
+ if (headline && title) {
+ content.push({
+ text: headline,
+ style: 'lead',
+ color: palette.muted,
+ margin: [0, 0, 0, 20],
+ })
+ }
+ content.push({
+ text: new Date().toLocaleDateString('en-US', {
+ year: 'numeric',
+ month: 'long',
+ day: 'numeric',
+ }),
+ color: palette.muted,
+ fontSize: 11,
+ margin: [0, 0, 0, 0],
+ pageBreak: 'after',
+ })
+ } else {
+ if (title) {
+ content.push({
+ text: title,
+ style: 'docTitle',
+ color: palette.primary,
+ margin: [0, 0, 0, 12],
+ })
+ }
+ const coverOnly = [
+ headline ? 'headline' : '',
+ args.statusColor ? 'statusColor' : '',
+ branding.logoPath ? 'branding.logoPath' : '',
+ ].filter(Boolean)
+ if (coverOnly.length > 0) {
+ const many = coverOnly.length > 1
+ warnings.push(
+ `${coverOnly.join(', ')} ${many ? 'are' : 'is'} only drawn on the cover page, so ` +
+ `${many ? 'they were' : 'it was'} left out; pass coverPage: true to show ${many ? 'them' : 'it'}.`
+ )
+ }
+ }
+
+ // Body.
+ content.push(...bodyToContent(body, palette, env))
+
+ // Tables (after body).
+ tables.forEach((t, index) => {
+ const label = `tables[${index}]`
+ if (!t || !Array.isArray(t.headers) || t.headers.length === 0) {
+ warnings.push(`${label} has no headers and was left out; pass headers: ['Column', ...].`)
+ return
+ }
+ const rows = normalizeTableRows(t.rows, t.headers, label, warnings).map(row =>
+ row.map(cell => (cell === null || cell === undefined ? '' : String(cell)))
+ )
+ content.push(
+ buildTableNode(
+ {
+ headers: t.headers.map(headerText),
+ rows,
+ layout: t.layout,
+ widths: t.widths,
+ label,
+ rowLabel: row => `${label}.rows[${row}]`,
+ },
+ palette,
+ env,
+ image =>
+ warnings.push(
+ `${label} names the image '${image.src}' in a cell, which a table cannot hold; pass it in images instead.`
+ )
+ )
+ )
+ })
+
+ // Images (charts, logos) at the end of the body.
+ imageRefs.forEach((ref, index) => {
+ const sizing = ref && typeof ref === 'object' ? (ref as PdfImageRef) : {}
+ const block = placeImage(ref, `images[${index}]`, sizing)
+ if (block) content.push(block)
+ })
+
+ if (imagesRequested > 0 && imagesPlaced === 0 && content.every(isBlankLine)) {
+ return {
+ success: false,
+ error: `No PDF was written: none of the images could be embedded. ${warnings.join(' ')}`,
+ }
+ }
+ if (content.every(isBlankLine)) warnings.push(EMPTY_DOCUMENT_NOTE)
+
+ const pageOrientation = applyPageOrientation(content, env.landscape)
+
+ const styles: Record<string, Record<string, unknown>> = {
+ cover: { fontSize: 36, bold: true },
+ lead: { fontSize: 16, italics: true },
+ docTitle: { fontSize: 22, bold: true },
+ h1: { fontSize: 18, bold: true, color: palette.primary },
+ h2: { fontSize: 14, bold: true, color: palette.primary },
+ h3: { fontSize: 12, bold: true, color: palette.muted },
+ [RUNNING_STYLE]: { fontSize: PDF_FOOTER_SIZE, color: palette.muted },
+ }
+ const typesetter = new PdfTypesetter(glyphs, styles)
+ const base = {
+ width: PDF_CONTENT_WIDTH,
+ font: PDF_FONT_FAMILY,
+ fontSize: BODY_FONT_SIZE,
+ bold: false,
+ lineHeight: PDF_LINE_HEIGHT,
+ }
+ typesetter.typeset(content, base)
+
+ // The running header and footer are laid out on every page, so their text
+ // is typeset once here and copied into each page's nodes.
+ const running = (text: string | undefined, width: number): ContentText => {
+ const node: ContentText = { text: text ?? '', style: RUNNING_STYLE }
+ typesetter.typeset(node, { ...base, width })
+ return node
+ }
+ // The title is printed whole on the first page; the running header takes one line of it.
+ const half = PDF_CONTENT_WIDTH / 2
+ const company = branding.companyName && runningLine(branding.companyName, half, measure)
+ if (company && company !== branding.companyName) {
+ warnings.push('branding.companyName is longer than the page header and was shortened there.')
+ }
+ const companyNode = running(company || undefined, half)
+ const headerTitleNode = running(title && runningLine(title, half, measure), half)
+ const footerNode = running(footer.join('\n'), PDF_CONTENT_WIDTH - pageNumberWidth)
+ typesetter.settleShaping()
+ const copy = (node: ContentText): ContentText => JSON.parse(JSON.stringify(node))
+
+ const docDef: TDocumentDefinitions = {
+ info: {
+ title: title ?? 'Report',
+ ...(branding.companyName ? { creator: branding.companyName } : {}),
+ },
+ pageSize: 'A4',
+ pageOrientation,
+ pageMargins: [40, PDF_TOP_MARGIN, 40, bottomMargin],
+ defaultStyle: {
+ font: PDF_FONT_FAMILY,
+ fontSize: BODY_FONT_SIZE,
+ color: palette.text,
+ lineHeight: PDF_LINE_HEIGHT,
+ },
+ styles,
+ pageBreakBefore: headingKeeper(content) as unknown as TDocumentDefinitions['pageBreakBefore'],
+ header: (currentPage: number) =>
+ currentPage === 1 && coverPage
+ ? null
+ : {
+ columns: [copy(companyNode), { ...copy(headerTitleNode), alignment: 'right' }],
+ style: RUNNING_STYLE,
+ margin: [40, 24, 40, 0],
+ },
+ footer: (currentPage: number, pageCount: number) => ({
+ columns: [
+ copy(footerNode),
+ {
+ text: `${currentPage} / ${pageCount}`,
+ style: RUNNING_STYLE,
+ alignment: 'right',
+ width: pageNumberWidth,
+ },
+ ],
+ style: RUNNING_STYLE,
+ margin: [40, 0, 40, 24],
+ }),
+ content,
+ }
+
+ // Han characters take the glyph forms of the document's language.
+ const language = documentEastAsianScript(
+ [
+ title,
+ body,
+ branding.companyName,
+ branding.footerText,
+ ...tables.map(t => JSON.stringify([t.headers, t.rows])),
+ ]
+ .filter(text => text !== undefined && text !== null)
+ .map(String)
+ .join('\n')
+ )?.lang.slice(0, 2)
+ const printer = new PdfPrinter(glyphs.descriptors(typesetter.families, language))
+ const pdfDoc = printer.createPdfKitDocument(docDef)
+
+ const pdfBuffer: Buffer = await new Promise((resolve, reject) => {
+ const chunks: Buffer[] = []
+ pdfDoc.on('data', (c: Buffer) => chunks.push(c))
+ pdfDoc.on('end', () => resolve(Buffer.concat(chunks)))
+ pdfDoc.on('error', reject)
+ pdfDoc.end()
+ })
+
+ ensureDir(outputDir)
+ const target = claimOutputFile(outputDir, filename)
+ enforceQuota(outputDir, pdfBuffer.byteLength, replacedBytes(target))
+ fs.writeFileSync(target.filePath, pdfBuffer)
+
+ return artifactResult(target, 'pdf', { warnings: [...warnings, ...typesetter.warnings()] })
+ } catch (err) {
+ return { success: false, error: err instanceof Error ? err.message : String(err) }
+ }
+}