@unovis/mcp 1.7.0-mcp.0

package/dist/recipes/shared.js

@@ -0,0 +1,212 @@
+/** Shared schema fragments and helpers for chart recipes.
+ *
+ * Conventions:
+ *  - data is always an array of flat records
+ *  - accessors are field names (never code)
+ *  - every option has a description and a sane default
+ *  - enums over free-form strings, bounded numbers
+ */
+import { z } from 'zod';
+import { ChartInputError } from '../render/materialize.js';
+export { ChartInputError };
+// ── schema fragments ────────────────────────────────────────────────────────
+export const dataValue = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export const dataRecords = z.array(z.record(z.string(), dataValue)).min(1)
+    .describe('Chart data: an array of flat records, e.g. [{"month": "Jan", "sales": 120, "cost": 80}, ...]');
+export const fieldName = z.string().min(1);
+export const commonInput = {
+    width: z.number().int().min(100).max(4000).default(800).describe('Chart width in pixels'),
+    height: z.number().int().min(100).max(4000).default(480).describe('Chart height in pixels'),
+    theme: z.enum(['light', 'dark']).default('light').describe('Color theme of the chart'),
+    title: z.string().optional().describe('Chart title rendered above the chart'),
+    colors: z.array(z.string().regex(/^#[0-9a-fA-F]{3,8}$/, 'hex color, e.g. #4D8CFD')).max(12).optional()
+        .describe('Custom color palette (hex). Replaces the default palette in order'),
+    framework: z.enum(['ts', 'react', 'svelte', 'vue', 'angular', 'solid']).default('ts')
+        .describe('Target framework for outputType "code". ts emits the imperative @unovis/ts API'),
+    outputType: z.enum(['svg', 'png', 'html', 'interactive', 'config', 'code']).default('svg')
+        .describe('svg: SVG markup; png: a rendered PNG image; html: a self-contained interactive HTML file ' +
+        '(tooltips, crosshair, hover — saved to disk, path returned); interactive: an interactive chart ' +
+        'rendered inline by clients that support MCP UI widgets; config: the resolved Unovis chart spec as JSON'),
+    outputPath: z.string().optional()
+        .describe('Absolute file path with an extension matching outputType (.svg, .png or .html) — saves the chart to disk and returns the path instead of inline content'),
+    scale: z.number().min(1).max(4).default(2)
+        .describe('Pixel density multiplier for PNG output (2 = retina). Ignored for svg/config'),
+};
+export const xyInput = {
+    xAxisLabel: z.string().optional().describe('Label for the X axis'),
+    yAxisLabel: z.string().optional().describe('Label for the Y axis'),
+    showGridLines: z.boolean().default(true).describe('Show horizontal/vertical grid lines'),
+    legend: z.boolean().default(true).describe('Show a legend (multi-series charts only)'),
+};
+const hexColor = z.string().regex(/^#[0-9a-fA-F]{3,8}$/, 'hex color, e.g. #FF6B7E');
+/** Reference-line / shaded-band decorations available on XY charts */
+export const xyDecorations = {
+    referenceLines: z.array(z.object({
+        axis: z.enum(['x', 'y']).default('y').describe('y: horizontal line at a Y value; x: vertical line at an X value'),
+        value: z.number().describe('Position in data units'),
+        label: z.string().optional().describe('Small label next to the line'),
+        color: hexColor.optional(),
+        lineWidth: z.number().min(0.5).max(10).default(1.5),
+        style: z.enum(['dashed', 'solid', 'dotted']).default('dashed'),
+    })).max(8).optional().describe('Reference lines for thresholds/targets, e.g. an SLA or goal'),
+    referenceBands: z.array(z.object({
+        axis: z.enum(['x', 'y']).default('y'),
+        from: z.number().describe('Band start, in data units'),
+        to: z.number().describe('Band end, in data units'),
+        label: z.string().optional(),
+        color: hexColor.optional(),
+    })).max(8).optional().describe('Shaded ranges drawn behind the data, e.g. an acceptable range'),
+};
+/** Decoration components: bands render behind the data, lines on top */
+export function decorationComponents(input) {
+    const bands = (input.referenceBands ?? []).map(band => ({
+        type: 'Plotband',
+        config: {
+            axis: band.axis,
+            from: band.from,
+            to: band.to,
+            ...(band.color ? { color: band.color } : {}),
+            ...(band.label ? { labelText: band.label } : {}),
+        },
+    }));
+    const lines = (input.referenceLines ?? []).map(line => ({
+        type: 'Plotline',
+        config: {
+            axis: line.axis,
+            value: line.value,
+            lineWidth: line.lineWidth,
+            lineStyle: line.style,
+            ...(line.color ? { color: line.color } : {}),
+            ...(line.label ? { labelText: line.label } : {}),
+        },
+    }));
+    return { bands, lines };
+}
+export const field = (name, as) => ({ $field: name, as });
+export const toArray = (value) => (Array.isArray(value) ? value : [value]);
+/** Throw an actionable error when referenced fields are missing from the data */
+export function assertFieldsExist(data, fields) {
+    const first = data[0];
+    if (!first || typeof first !== 'object')
+        throw new ChartInputError('data must be an array of objects');
+    const available = Object.keys(first);
+    const missing = fields.filter((f) => !!f && !(f in first));
+    if (missing.length) {
+        throw new ChartInputError(`Field${missing.length > 1 ? 's' : ''} ${missing.map(f => `"${f}"`).join(', ')} not found in data. ` +
+            `Available fields: ${available.map(f => `"${f}"`).join(', ')}`);
+    }
+}
+/** True when every value of a field (in the first few records) is numeric */
+export function isNumericField(data, fieldName) {
+    const sample = data.slice(0, 20);
+    return sample.every(d => d[fieldName] === null || d[fieldName] === undefined || typeof d[fieldName] === 'number' ||
+        (typeof d[fieldName] === 'string' && d[fieldName] !== '' && !Number.isNaN(Number(d[fieldName]))));
+}
+/** Distinct values of a field, in first-seen order */
+export function distinctValues(data, fieldName) {
+    const seen = new Set();
+    for (const record of data) {
+        const value = record[fieldName];
+        if (value === null || value === undefined)
+            continue;
+        seen.add(value);
+    }
+    return Array.from(seen);
+}
+/** Numeric fields map directly; string categories map to their index with
+ * labeled ticks (Unovis XY scales are numeric). */
+export function categoricalX(data, fieldName, isTime) {
+    if (isTime)
+        return { x: field(fieldName, 'date') };
+    if (isNumericField(data, fieldName))
+        return { x: field(fieldName, 'number') };
+    const categories = distinctValues(data, fieldName).map(String);
+    return { x: { $index: true }, categories };
+}
+/** Axis spec for a categorical dimension: one labeled tick per category.
+ * Explicit integer tickValues — approximate d3 tick counts can emit
+ * fractional ticks that would round into duplicate category labels. */
+export function categoryAxis(base, categories) {
+    const maxTicks = 30;
+    const step = Math.ceil(categories.length / maxTicks);
+    const tickValues = categories.map((_, i) => i).filter(i => i % step === 0);
+    return {
+        ...base,
+        tickFormat: { $lookup: categories },
+        tickValues,
+    };
+}
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+/** Calendar-aligned tick values for date axes. Linear-scale ticks land at
+ * arbitrary times of day, which the date formatter would render as
+ * time-of-day labels ("08:53 AM" on a 3-month chart) — align ticks to
+ * month/day/hour/minute boundaries instead. */
+export function dateTickValues(min, max, target = 7) {
+    const span = max - min;
+    if (!Number.isFinite(span) || span <= 0)
+        return undefined;
+    const ticks = [];
+    if (span >= 60 * DAY) { // month starts
+        const stepMonths = Math.max(1, Math.ceil(span / (30 * DAY) / target));
+        const start = new Date(min);
+        let date = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), 1));
+        if (date.getTime() < min)
+            date = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 1));
+        while (date.getTime() <= max && ticks.length < 24) {
+            ticks.push(date.getTime());
+            date = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + stepMonths, 1));
+        }
+    }
+    else {
+        // day / hour / minute boundaries (uniform in UTC epoch time)
+        const unit = span >= 2 * DAY ? DAY : span >= 2 * HOUR ? HOUR : MINUTE;
+        const niceSteps = unit === DAY ? [1, 2, 7, 14] : unit === HOUR ? [1, 2, 3, 6, 12] : [1, 2, 5, 10, 15, 30];
+        const rawStep = span / unit / target;
+        const step = (niceSteps.find(s => s >= rawStep) ?? Math.ceil(rawStep)) * unit;
+        for (let t = Math.ceil(min / step) * step; t <= max && ticks.length < 24; t += step)
+            ticks.push(t);
+    }
+    return ticks.length >= 2 ? ticks : undefined;
+}
+/** Tick values for a time axis derived from the data extent of a date field */
+export function timeTickValuesFromData(data, fieldName) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const record of data) {
+        const raw = record[fieldName];
+        if (raw === null || raw === undefined || raw === '')
+            continue;
+        const time = typeof raw === 'number' ? raw : new Date(String(raw)).getTime();
+        if (Number.isNaN(time))
+            continue;
+        if (time < min)
+            min = time;
+        if (time > max)
+            max = time;
+    }
+    return dateTickValues(min, max);
+}
+export function seriesLegend(labels, enabled, colors) {
+    if (!enabled || labels.length < 2)
+        return undefined;
+    return labels.map((name, i) => ({ name, paletteIndex: i, color: colors?.[i % (colors.length || 1)] }));
+}
+/** Common ChartSpec fields from common tool inputs */
+export function baseSpec(input) {
+    return {
+        width: input.width,
+        height: input.height,
+        theme: input.theme,
+        title: input.title,
+        colors: input.colors,
+    };
+}
+export function xyAxes(input) {
+    return {
+        xAxis: { label: input.xAxisLabel, gridLine: input.showGridLines },
+        yAxis: { label: input.yAxisLabel, gridLine: input.showGridLines },
+    };
+}
+//# sourceMappingURL=shared.js.map

package/dist/recipes/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/recipes/shared.ts"],"names":[],"mappings":"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"}

package/dist/recipes/timeline.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { Recipe } from './types.js';
+/** Calendar-aligned axis tick values (UTC) for a time extent. Linear-scale
+ * ticks land on decimal-nice epoch values (mid-day times), which format as
+ * times of day and lose the date — so we pick month/day/hour boundaries
+ * instead. Returns undefined for degenerate extents. */
+export declare const timelineInputShape: {
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+    theme: z.ZodDefault<z.ZodEnum<["light", "dark"]>>;
+    title: z.ZodOptional<z.ZodString>;
+    colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    framework: z.ZodDefault<z.ZodEnum<["ts", "react", "svelte", "vue", "angular", "solid"]>>;
+    outputType: z.ZodDefault<z.ZodEnum<["svg", "png", "html", "interactive", "config", "code"]>>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    scale: z.ZodDefault<z.ZodNumber>;
+    data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, "many">;
+    row: z.ZodString;
+    start: z.ZodString;
+    end: z.ZodOptional<z.ZodString>;
+    duration: z.ZodOptional<z.ZodString>;
+    timeIsDate: z.ZodOptional<z.ZodBoolean>;
+    showRowLabels: z.ZodDefault<z.ZodBoolean>;
+    rowHeight: z.ZodDefault<z.ZodNumber>;
+    lineWidth: z.ZodOptional<z.ZodNumber>;
+    roundedEnds: z.ZodDefault<z.ZodBoolean>;
+    alternatingRowColors: z.ZodDefault<z.ZodBoolean>;
+    xAxisLabel: z.ZodOptional<z.ZodString>;
+    showGridLines: z.ZodDefault<z.ZodBoolean>;
+};
+export declare const timelineRecipe: Recipe<typeof timelineInputShape>;

package/dist/recipes/timeline.js

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import { commonInput, xyInput, dataRecords, fieldName, assertFieldsExist, baseSpec, dateTickValues, field, isNumericField, ChartInputError, } from './shared.js';
+/** Coerce a raw record value to a time position: numbers pass through,
+ * strings are parsed as dates (→ epoch milliseconds) */
+const toTime = (value) => {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string' && value !== '') {
+        const numeric = Number(value);
+        if (!Number.isNaN(numeric))
+            return numeric;
+        const time = new Date(value).getTime();
+        if (!Number.isNaN(time))
+            return time;
+    }
+    return NaN;
+};
+/** Calendar-aligned axis tick values (UTC) for a time extent. Linear-scale
+ * ticks land on decimal-nice epoch values (mid-day times), which format as
+ * times of day and lose the date — so we pick month/day/hour boundaries
+ * instead. Returns undefined for degenerate extents. */
+export const timelineInputShape = {
+    data: dataRecords,
+    row: fieldName.describe('Field with the row (lane) name. Records sharing a row value are drawn in one lane'),
+    start: fieldName.describe('Field with the item start: a number, or a date string (e.g. "2024-03-01")'),
+    end: fieldName.optional()
+        .describe('Field with the item end, same format as start. Provide either end or duration'),
+    duration: fieldName.optional()
+        .describe('Field with the item duration, in the same units as start (milliseconds when start is a date). Ignored when end is provided'),
+    timeIsDate: z.boolean().optional()
+        .describe('Treat start/end values as dates (time axis). Auto-detected from the start field when omitted'),
+    showRowLabels: z.boolean().default(true).describe('Show the row names on the left'),
+    rowHeight: z.number().min(10).max(100).default(22).describe('Row height in pixels'),
+    lineWidth: z.number().min(1).max(60).optional()
+        .describe('Thickness of the timeline bars in pixels. Defaults to a value derived from rowHeight'),
+    roundedEnds: z.boolean().default(false).describe('Draw the bars with rounded ends'),
+    alternatingRowColors: z.boolean().default(true).describe('Alternate the row background colors'),
+    xAxisLabel: xyInput.xAxisLabel,
+    showGridLines: xyInput.showGridLines,
+    ...commonInput,
+};
+export const timelineRecipe = {
+    name: 'generate_timeline_chart',
+    title: 'Timeline chart',
+    description: 'Generate a timeline (Gantt-style) chart of items with a start and an end (or duration), grouped into labeled rows. ' +
+        'Use for schedules, project plans, traces, or event durations. Provide either an end field or a duration field. ' +
+        'Example: data=[{"task":"Design","from":"2024-01-08","to":"2024-02-02"},...], row="task", start="from", end="to".',
+    inputShape: timelineInputShape,
+    toSpec: (input) => {
+        const data = input.data;
+        if (!input.end && !input.duration) {
+            throw new ChartInputError('Either "end" or "duration" must be provided');
+        }
+        assertFieldsExist(data, [input.row, input.start, input.end, input.duration]);
+        const isDate = input.timeIsDate ?? !isNumericField(data, input.start);
+        // Normalize into flat numeric positions: start (epoch ms for dates) and
+        // duration (end - start when an end field is given). A synthetic id keeps
+        // items distinct even when a row has two items starting at the same time.
+        const normalized = data.map((d, i) => {
+            const start = isDate ? toTime(d[input.start]) : Number(d[input.start]);
+            if (!Number.isFinite(start)) {
+                throw new ChartInputError(`Invalid "${input.start}" value in record ${i}: ${JSON.stringify(d[input.start])}`);
+            }
+            let duration;
+            if (input.end) {
+                const end = isDate ? toTime(d[input.end]) : Number(d[input.end]);
+                if (!Number.isFinite(end)) {
+                    throw new ChartInputError(`Invalid "${input.end}" value in record ${i}: ${JSON.stringify(d[input.end])}`);
+                }
+                duration = end - start;
+            }
+            else {
+                duration = Number(d[input.duration]);
+            }
+            if (!Number.isFinite(duration) || duration < 0) {
+                throw new ChartInputError(`Record ${i} has an invalid or negative duration: ${JSON.stringify(duration)}`);
+            }
+            return {
+                ...d,
+                _id: `item-${i}`,
+                _row: d[input.row] === null || d[input.row] === undefined ? 'Unknown' : String(d[input.row]),
+                _start: start,
+                _duration: duration,
+            };
+        });
+        // Calendar-aligned ticks for date axes: default linear ticks land on
+        // decimal-nice epoch values, which format as times of day.
+        let tickValues;
+        if (isDate) {
+            const min = Math.min(...normalized.map(d => d._start));
+            const max = Math.max(...normalized.map(d => d._start + d._duration));
+            tickValues = dateTickValues(min, max);
+        }
+        return {
+            container: 'xy',
+            ...baseSpec(input),
+            components: [{
+                    type: 'Timeline',
+                    config: {
+                        id: { $field: '_id' },
+                        x: field('_start', 'number'),
+                        lineRow: { $field: '_row' },
+                        lineDuration: field('_duration', 'number'),
+                        showRowLabels: input.showRowLabels,
+                        rowMaxLabelWidth: Math.max(120, Math.round(input.width * 0.2)),
+                        rowHeight: input.rowHeight,
+                        ...(input.lineWidth !== undefined ? { lineWidth: input.lineWidth } : {}),
+                        lineCap: input.roundedEnds,
+                        showEmptySegments: true,
+                        alternatingRowColors: input.alternatingRowColors,
+                    },
+                }],
+            xAxis: {
+                label: input.xAxisLabel,
+                gridLine: input.showGridLines,
+                tickFormat: isDate ? { $dateTickFormat: true } : { $numTickFormat: true },
+                ...(tickValues ? { tickValues } : {}),
+            },
+            data: normalized,
+        };
+    },
+};
+//# sourceMappingURL=timeline.js.map

package/dist/recipes/timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.js","sourceRoot":"","sources":["../../src/recipes/timeline.ts"],"names":[],"mappings":"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"}

package/dist/recipes/treemap.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { Recipe } from './types.js';
+export declare const treemapInputShape: {
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+    theme: z.ZodDefault<z.ZodEnum<["light", "dark"]>>;
+    title: z.ZodOptional<z.ZodString>;
+    colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    framework: z.ZodDefault<z.ZodEnum<["ts", "react", "svelte", "vue", "angular", "solid"]>>;
+    outputType: z.ZodDefault<z.ZodEnum<["svg", "png", "html", "interactive", "config", "code"]>>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    scale: z.ZodDefault<z.ZodNumber>;
+    data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, "many">;
+    layers: z.ZodArray<z.ZodString, "many">;
+    value: z.ZodString;
+    labelInternalNodes: z.ZodOptional<z.ZodBoolean>;
+    tilePadding: z.ZodDefault<z.ZodNumber>;
+};
+export declare const treemapRecipe: Recipe<typeof treemapInputShape>;

package/dist/recipes/treemap.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { commonInput, dataRecords, fieldName, assertFieldsExist, baseSpec, field } from './shared.js';
+export const treemapInputShape = {
+    data: dataRecords,
+    layers: z.array(fieldName).min(1).max(4)
+        .describe('Fields defining the hierarchy, top-level groups first, e.g. ["sector", "company"]'),
+    value: fieldName.describe('Field with the numeric tile size'),
+    labelInternalNodes: z.boolean().optional()
+        .describe('Show labels on the group (non-leaf) tiles. Defaults to true when there is more than one layer'),
+    tilePadding: z.number().min(0).max(24).default(2).describe('Padding between tiles in pixels'),
+    ...commonInput,
+};
+export const treemapRecipe = {
+    name: 'generate_treemap',
+    title: 'Treemap',
+    description: 'Generate a treemap of nested rectangles sized by value. Use for part-of-whole comparisons, ' +
+        'optionally across hierarchy levels. Tiles are labeled "name: value". ' +
+        'Example: data=[{"sector":"Tech","company":"Apple","cap":2900},{"sector":"Energy","company":"Shell","cap":210}], layers=["sector","company"], value="cap".',
+    inputShape: treemapInputShape,
+    toSpec: (input) => {
+        const data = input.data;
+        assertFieldsExist(data, [...input.layers, input.value]);
+        const labelInternalNodes = input.labelInternalNodes ?? input.layers.length > 1;
+        return {
+            container: 'single',
+            ...baseSpec(input),
+            components: [{
+                    type: 'Treemap',
+                    config: {
+                        layers: input.layers.map(layer => field(layer)),
+                        value: field(input.value, 'number'),
+                        labelInternalNodes,
+                        tilePadding: input.tilePadding,
+                        // Group labels render inside the group tile — reserve headroom for them
+                        ...(labelInternalNodes ? { tilePaddingTop: 22 } : {}),
+                        tileShowHtmlTooltip: false,
+                    },
+                }],
+            data,
+        };
+    },
+};
+//# sourceMappingURL=treemap.js.map

package/dist/recipes/treemap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treemap.js","sourceRoot":"","sources":["../../src/recipes/treemap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,iBAAiB,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAGrG,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;SACrC,QAAQ,CAAC,mFAAmF,CAAC;IAChG,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,kCAAkC,CAAC;IAC7D,kBAAkB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;SACvC,QAAQ,CAAC,+FAA+F,CAAC;IAC5G,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAC7F,GAAG,WAAW;CACf,CAAA;AAED,MAAM,CAAC,MAAM,aAAa,GAAqC;IAC7D,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,SAAS;IAChB,WAAW,EAAE,6FAA6F;QACxG,uEAAuE;QACvE,2JAA2J;IAC7J,UAAU,EAAE,iBAAiB;IAC7B,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;QAChB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAoB,CAAA;QACvC,iBAAiB,CAAC,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;QAEvD,MAAM,kBAAkB,GAAG,KAAK,CAAC,kBAAkB,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAA;QAE9E,OAAO;YACL,SAAS,EAAE,QAAQ;YACnB,GAAG,QAAQ,CAAC,KAAK,CAAC;YAClB,UAAU,EAAE,CAAC;oBACX,IAAI,EAAE,SAAS;oBACf,MAAM,EAAE;wBACN,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;wBAC/C,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC;wBACnC,kBAAkB;wBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;wBAC9B,wEAAwE;wBACxE,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACrD,mBAAmB,EAAE,KAAK;qBAC3B;iBACF,CAAC;YACF,IAAI;SACL,CAAA;IACH,CAAC;CACF,CAAA"}

package/dist/recipes/types.d.ts

@@ -0,0 +1,16 @@
+import type { ZodRawShape, ZodObject, infer as ZodInfer } from 'zod';
+import type { ChartSpec } from '../render/spec.js';
+/** A recipe maps a simplified, LLM-friendly tool input onto a ChartSpec.
+ * `toSpec` must be pure and produce a JSON-serializable spec — it doubles
+ * as the `config` output mode and, later, as input for code generation. */
+export interface Recipe<Shape extends ZodRawShape = ZodRawShape> {
+    /** MCP tool name, e.g. 'generate_line_chart' */
+    name: string;
+    /** Human-readable title, e.g. 'Line chart' */
+    title: string;
+    /** LLM-facing tool description — say when to use it and show a data example */
+    description: string;
+    inputShape: Shape;
+    toSpec(input: ZodInfer<ZodObject<Shape>>): ChartSpec;
+}
+export type AnyRecipe = Recipe<any>;

package/dist/recipes/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/recipes/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/recipes/types.ts"],"names":[],"mappings":""}

package/dist/render/headless.d.ts

@@ -0,0 +1,62 @@
+import type { UnovisLib } from '../env/index.js';
+import type { SvgFrame } from '../svg/postprocess.js';
+export interface HeadlessRenderOptions extends SvgFrame {
+    /** Deterministic id prefix (snapshot tests); random per render otherwise */
+    idPrefix?: string;
+    /** Keep emotion classes and skip style inlining (debug) */
+    keepClasses?: boolean;
+    /** Frame drawn around the chart so content never touches the image edge.
+     * The chart renders at width/height minus this padding. */
+    padding?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+/** Handed to the build callback. */
+export interface BuildContext {
+    /** Sized host element to render the chart into */
+    container: HTMLElement;
+    /** The shim-initialised @unovis/ts namespace — use this, don't import it */
+    unovis: UnovisLib;
+    /** Inner chart size (options size minus padding) */
+    width: number;
+    height: number;
+    /** Pass as the container config's `onRenderComplete` */
+    onRenderComplete: () => void;
+    /** Pass as the `onRenderComplete` of components whose layout is async
+     * (Graph), after calling `requireComponentReady()` */
+    onComponentReady: () => void;
+    /** Declare that a component signals readiness separately, so the render
+     * waits for `onComponentReady` as well */
+    requireComponentReady: () => void;
+}
+export interface RenderResult {
+    svg: string;
+    width: number;
+    height: number;
+    warnings: string[];
+}
+/** A chart instance, as returned by any Unovis container */
+export interface RenderedChart {
+    element?: Element | null;
+    destroy?: () => void;
+}
+/**
+ * Render a chart to standalone SVG in Node.
+ *
+ * ```ts
+ * const { svg } = await renderToSvg({ width: 800, height: 400 }, (ctx) => {
+ *   const line = new ctx.unovis.Line({ x: d => d.x, y: d => d.y, duration: 0 })
+ *   return new ctx.unovis.XYContainer(ctx.container, {
+ *     components: [line],
+ *     width: ctx.width,
+ *     height: ctx.height,
+ *     duration: 0,
+ *     onRenderComplete: ctx.onRenderComplete,
+ *   }, data)
+ * })
+ * ```
+ */
+export declare function renderToSvg(options: HeadlessRenderOptions, build: (context: BuildContext) => RenderedChart): Promise<RenderResult>;