@unovis/mcp 1.7.0-mcp.0

package/dist/render/headless.js

@@ -0,0 +1,158 @@
+/** Headless chart rendering — the SSR primitive.
+ *
+ * Everything here is independent of the MCP layer: give it a callback that
+ * builds any Unovis chart and it returns standalone SVG. This is the boundary
+ * a future `@unovis/ssr` package would follow.
+ *
+ * Why the callback receives `unovis` instead of importing it: the library
+ * captures its environment at module load (emotion inserts stylesheets,
+ * text measurement grabs a canvas context), so it must be imported *after*
+ * the shims are installed. Handing the already-initialised namespace to the
+ * callback is what makes that safe.
+ */
+import { getRenderEnv, defineElementSize } from '../env/index.js';
+import { Mutex } from './mutex.js';
+import { finalizeSvg, CHART_PADDING } from '../svg/postprocess.js';
+const RENDER_TIMEOUT_MS = 5000;
+/** Async layouts (graph force/dagre/elk) may need dynamic imports + solver time */
+const ASYNC_RENDER_TIMEOUT_MS = 20000;
+/** A synchronous render settles within a couple of frames; this only bounds
+ * how long a broken one takes to report itself. Async renders are bounded by
+ * the deadline instead — counting rounds is meaningless there, because a
+ * microtask tick costs microseconds while a cold module import needs
+ * milliseconds of real time. */
+const MAX_FLUSH_ROUNDS = 10;
+/** Idle wait while an asynchronous layout is still pending */
+const ASYNC_POLL_MS = 5;
+/** Extra settle passes after an async layout reports completion */
+const ASYNC_GRACE_ROUNDS = 4;
+/** Renders share one jsdom document and one frame queue */
+const mutex = new Mutex();
+const nextMacrotask = () => new Promise(resolve => setImmediate(resolve));
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/**
+ * 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 async function renderToSvg(options, build) {
+    const env = await getRenderEnv();
+    return mutex.run(async () => {
+        const { document, lib, raf } = env;
+        const warnings = [];
+        const padding = options.padding ?? CHART_PADDING;
+        const width = Math.max(40, options.width - padding.left - padding.right);
+        const height = Math.max(40, options.height - padding.top - padding.bottom);
+        const theme = options.theme ?? 'light';
+        const host = document.createElement('div');
+        defineElementSize(host, width, height);
+        document.body.appendChild(host);
+        // Theme and palette reach the library through the getComputedStyle shim:
+        // the dark flag from the document root, palette overrides from the host's
+        // inline custom properties.
+        if (theme === 'dark')
+            document.documentElement.setAttribute('data-theme', 'dark');
+        options.colors?.forEach((color, i) => {
+            host.style.setProperty(`--vis-color${i}`, color);
+            host.style.setProperty(`--vis-dark-color${i}`, color);
+        });
+        let renderCompleted = false;
+        let componentCompleted = true;
+        let needsComponent = false;
+        let chart;
+        try {
+            chart = build({
+                container: host,
+                unovis: lib,
+                width,
+                height,
+                onRenderComplete: () => { renderCompleted = true; },
+                onComponentReady: () => { componentCompleted = true; },
+                requireComponentReady: () => {
+                    needsComponent = true;
+                    componentCompleted = false;
+                },
+            });
+            // Belt and braces for library builds without the clientWidth fallback
+            if (chart?.element)
+                defineElementSize(chart.element, width, height);
+            const deadline = Date.now() + (needsComponent ? ASYNC_RENDER_TIMEOUT_MS : RENDER_TIMEOUT_MS);
+            let rounds = 0;
+            for (;;) {
+                raf.flushAll();
+                await nextMacrotask(); // let 0ms timers (d3-timer) and layout promises progress
+                if (raf.size === 0 && renderCompleted && componentCompleted)
+                    break;
+                if (Date.now() > deadline)
+                    break;
+                if (!needsComponent && ++rounds >= MAX_FLUSH_ROUNDS)
+                    break;
+                // Waiting on a layout that resolves through module loading and solver
+                // work: yield real time rather than spinning on microtasks
+                if (needsComponent && raf.size === 0 && !componentCompleted)
+                    await sleep(ASYNC_POLL_MS);
+            }
+            raf.flushAll();
+            // Components with async layouts schedule follow-up frames *after*
+            // signalling completion — graph fit-view, label placement. Without a
+            // grace period the output depends on how loaded the machine is, which
+            // shows up as charts that differ run to run.
+            if (needsComponent) {
+                for (let grace = 0; grace < ASYNC_GRACE_ROUNDS; grace++) {
+                    await sleep(ASYNC_POLL_MS);
+                    raf.flushAll();
+                }
+            }
+            if (!renderCompleted || !componentCompleted) {
+                const details = raf.errors.length ? ` Render errors: ${raf.errors.map(e => String(e)).join('; ')}` : '';
+                const what = !renderCompleted
+                    ? 'onRenderComplete never fired — is it wired into the container config?'
+                    : 'component layout never completed';
+                throw new Error(`Chart rendering did not complete (${what}).${details}`);
+            }
+            for (const error of raf.errors)
+                warnings.push(`render frame error: ${String(error)}`);
+            const svgElement = (chart?.element?.localName === 'svg'
+                ? chart.element
+                : host.querySelector('svg'));
+            if (!svgElement)
+                throw new Error('Chart produced no SVG element');
+            const svg = finalizeSvg(svgElement, {
+                document,
+                frame: { ...options, theme },
+                varMaps: env.varMaps,
+                idPrefix: options.idPrefix,
+                keepClasses: options.keepClasses,
+                padding,
+            });
+            return {
+                svg,
+                width: options.width,
+                height: parseFloat(svgElement.getAttribute('height') ?? '') || options.height,
+                warnings,
+            };
+        }
+        finally {
+            try {
+                chart?.destroy?.();
+            }
+            catch { /* a failed render may leave a partially constructed chart */ }
+            host.remove();
+            if (theme === 'dark')
+                document.documentElement.removeAttribute('data-theme');
+            raf.clear();
+        }
+    });
+}
+//# sourceMappingURL=headless.js.map

package/dist/render/headless.js.map

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

package/dist/render/materialize.d.ts

@@ -0,0 +1,35 @@
+/** Materialize a ChartSpec into live Unovis component/container configs.
+ *
+ * Converts JSON accessor descriptors into real functions. Field access is by
+ * property name only — user input is never evaluated as code.
+ */
+import type { UnovisLib } from '../env/index.js';
+import type { AccessorRef, ChartSpec } from './spec.js';
+type AnyFn = (...args: any[]) => any;
+export declare class ChartInputError extends Error {
+}
+export declare function materializeAccessor(ref: AccessorRef): AnyFn | unknown;
+/** Deep-walk a config value, replacing accessor descriptors with functions */
+export declare function materializeValue(value: unknown): unknown;
+export interface MaterializedChart {
+    containerType: 'xy' | 'single';
+    containerConfig: Record<string, unknown>;
+    data: unknown;
+}
+/** Components that finish rendering asynchronously (after layout calculation)
+ * and expose their own onRenderComplete hook the renderer must await */
+export declare const ASYNC_COMPONENTS: Set<string>;
+/** Options controlling how a spec becomes live Unovis configs.
+ * Static rendering uses `duration: 0` and fixed sizes for deterministic
+ * output; interactive rendering animates and lets the chart fill its host. */
+export interface MaterializeOptions {
+    /** Animation duration in ms. 0 (default) renders synchronously */
+    duration?: number;
+    /** Omit width/height so the container sizes from its DOM parent */
+    responsive?: boolean;
+    onRenderComplete?: () => void;
+    /** Called by components whose layout completes asynchronously (Graph) */
+    onComponentComplete?: () => void;
+}
+export declare function materializeChart(lib: UnovisLib, spec: ChartSpec, options?: MaterializeOptions): MaterializedChart;
+export {};

package/dist/render/materialize.js

@@ -0,0 +1,160 @@
+import { isAccessorRef } from './spec.js';
+export class ChartInputError extends Error {
+}
+const coerceNumber = (value) => {
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    const n = Number(value);
+    return Number.isNaN(n) ? undefined : n;
+};
+const coerceDate = (value) => {
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    if (typeof value === 'number')
+        return value;
+    const time = new Date(value).getTime();
+    return Number.isNaN(time) ? undefined : time;
+};
+/** Time tick formatter: picks granularity from the value */
+const formatDateTick = (value) => {
+    const time = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(time))
+        return String(value);
+    const date = new Date(time);
+    const opts = date.getUTCHours() === 0 && date.getUTCMinutes() === 0
+        ? (date.getUTCDate() === 1 ? { year: 'numeric', month: 'short' } : { month: 'short', day: 'numeric' })
+        : { hour: '2-digit', minute: '2-digit' };
+    return date.toLocaleString('en-US', { ...opts, timeZone: 'UTC' });
+};
+const formatNumTick = (value) => {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return String(value);
+    return n.toLocaleString('en-US', { maximumFractionDigits: 6 });
+};
+export function materializeAccessor(ref) {
+    if ('$field' in ref) {
+        const { $field: field, as } = ref;
+        if (as === 'number')
+            return (d) => coerceNumber(d?.[field]);
+        if (as === 'date')
+            return (d) => coerceDate(d?.[field]);
+        return (d) => d?.[field];
+    }
+    if ('$index' in ref)
+        return (_, i) => i;
+    if ('$const' in ref)
+        return () => ref.$const;
+    if ('$dateTickFormat' in ref)
+        return formatDateTick;
+    if ('$numTickFormat' in ref)
+        return formatNumTick;
+    if ('$lookup' in ref) {
+        const values = ref.$lookup;
+        return (d) => values[Math.round(Number(d)) % values.length] ?? String(d);
+    }
+    if ('$format' in ref) {
+        const { field, prefix = '', suffix = '' } = ref.$format;
+        return (d) => {
+            const value = d?.[field];
+            if (value === null || value === undefined)
+                return '';
+            return `${prefix}${formatNumTick(value)}${suffix}`;
+        };
+    }
+    if ('$mapField' in ref) {
+        const { field, mapping, fallback } = ref.$mapField;
+        return (d) => mapping[String(d?.[field])] ?? fallback;
+    }
+    return ref;
+}
+/** Deep-walk a config value, replacing accessor descriptors with functions */
+export function materializeValue(value) {
+    if (isAccessorRef(value))
+        return materializeAccessor(value);
+    if (Array.isArray(value))
+        return value.map(materializeValue);
+    if (typeof value === 'object' && value !== null) {
+        const out = {};
+        for (const [key, v] of Object.entries(value))
+            out[key] = materializeValue(v);
+        return out;
+    }
+    return value;
+}
+/** Component classes recipes are allowed to instantiate */
+const XY_COMPONENTS = new Set(['Line', 'Area', 'GroupedBar', 'StackedBar', 'Scatter', 'Timeline', 'Boxplot', 'XYLabels', 'Plotband', 'Plotline']);
+const SINGLE_COMPONENTS = new Set(['Donut', 'NestedDonut', 'RadialBar', 'Sankey', 'Heatmap', 'Treemap', 'ChordDiagram', 'Graph', 'TopoJSONMap']);
+/** Components that finish rendering asynchronously (after layout calculation)
+ * and expose their own onRenderComplete hook the renderer must await */
+export const ASYNC_COMPONENTS = new Set(['Graph']);
+function instantiateComponent(lib, spec, options) {
+    const allowed = XY_COMPONENTS.has(spec.type) || SINGLE_COMPONENTS.has(spec.type);
+    if (!allowed)
+        throw new ChartInputError(`Unsupported component type: ${spec.type}`);
+    const componentClass = lib[spec.type];
+    if (!componentClass)
+        throw new ChartInputError(`Component ${spec.type} is not available in this @unovis/ts build`);
+    const config = materializeValue(spec.config);
+    config.duration = options.duration ?? 0;
+    if (ASYNC_COMPONENTS.has(spec.type) && options.onComponentComplete)
+        config.onRenderComplete = options.onComponentComplete;
+    // { $mapProjection: 'AlbersUsa' } → MapProjection.AlbersUsa() — projections
+    // are factory functions and can't live in the JSON spec directly
+    const projection = config.projection;
+    if (projection?.$mapProjection) {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        const projections = lib.MapProjection;
+        const factory = projections?.[projection.$mapProjection];
+        if (!factory)
+            throw new ChartInputError(`Unknown map projection: ${projection.$mapProjection}`);
+        config.projection = factory();
+    }
+    // eslint-disable-next-line new-cap
+    return new componentClass(config);
+}
+export function materializeChart(lib, spec, options = {}) {
+    const base = materializeValue(spec.containerConfig ?? {});
+    const duration = options.duration ?? 0;
+    const size = options.responsive ? {} : { width: spec.width, height: spec.height };
+    if (spec.container === 'xy') {
+        const components = spec.components.map(c => {
+            if (!XY_COMPONENTS.has(c.type))
+                throw new ChartInputError(`${c.type} cannot be used in an XY container`);
+            return instantiateComponent(lib, c, options);
+        });
+        const axisConfig = (axis, type) => {
+            if (!axis)
+                return undefined;
+            return new lib.Axis({ ...materializeValue(axis), type, duration });
+        };
+        return {
+            containerType: 'xy',
+            containerConfig: {
+                ...base,
+                components,
+                xAxis: axisConfig(spec.xAxis, 'x'),
+                yAxis: axisConfig(spec.yAxis, 'y'),
+                ...size,
+                duration,
+                onRenderComplete: options.onRenderComplete,
+            },
+            data: spec.data,
+        };
+    }
+    if (spec.components.length !== 1)
+        throw new ChartInputError('single container requires exactly one component');
+    const component = instantiateComponent(lib, spec.components[0], options);
+    return {
+        containerType: 'single',
+        containerConfig: {
+            ...base,
+            component,
+            ...size,
+            duration,
+            onRenderComplete: options.onRenderComplete,
+        },
+        data: spec.data,
+    };
+}
+//# sourceMappingURL=materialize.js.map

package/dist/render/materialize.js.map

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

package/dist/render/mutex.d.ts

@@ -0,0 +1,9 @@
+/** Minimal promise-chain mutex.
+ *
+ * Renders share one jsdom document and one rAF queue, so they must not
+ * interleave. Failures don't poison the chain.
+ */
+export declare class Mutex {
+    private tail;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}

package/dist/render/mutex.js

@@ -0,0 +1,14 @@
+/** Minimal promise-chain mutex.
+ *
+ * Renders share one jsdom document and one rAF queue, so they must not
+ * interleave. Failures don't poison the chain.
+ */
+export class Mutex {
+    tail = Promise.resolve();
+    run(fn) {
+        const result = this.tail.then(fn, fn);
+        this.tail = result.catch(() => undefined);
+        return result;
+    }
+}
+//# sourceMappingURL=mutex.js.map

package/dist/render/mutex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../src/render/mutex.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,KAAK;IACR,IAAI,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAA;IAElD,GAAG,CAAK,EAAoB;QAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;QACrC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QACzC,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}

package/dist/render/rasterize.d.ts

@@ -0,0 +1,10 @@
+export interface RasterizeOptions {
+    /** CSS pixel width of the SVG (defaults to the width attribute) */
+    width?: number;
+    /** Pixel density multiplier (2 = retina). Default 2 */
+    scale?: number;
+    /** Background color; PNG has no page to inherit one from */
+    background?: string;
+}
+export declare function svgToPng(svg: string, options?: RasterizeOptions): Promise<Buffer>;
+export declare const themeBackground: (theme: "light" | "dark") => string;

package/dist/render/rasterize.js

@@ -0,0 +1,29 @@
+/** SVG → PNG rasterization via @resvg/resvg-js.
+ *
+ * The post-processed SVG is fully self-contained (styles inlined as
+ * attributes, no classes, no var(), no external refs) — exactly what resvg
+ * handles well. Text is shaped with the same provisioned Inter fonts used
+ * for measurement, so PNG output matches the measured layout.
+ *
+ * resvg ignores the CSS `background-color` style on the root (it's not an
+ * SVG rendering attribute), so the theme background is passed explicitly.
+ */
+import { ensureFontsDir } from '../env/fonts.js';
+export async function svgToPng(svg, options = {}) {
+    const resvgModule = await import('@resvg/resvg-js');
+    const scale = options.scale ?? 2;
+    const width = options.width ?? parseFloat(/width="([\d.]+)"/.exec(svg)?.[1] ?? '') ?? undefined;
+    const fontsDir = await ensureFontsDir();
+    const resvg = new resvgModule.Resvg(svg, {
+        fitTo: width ? { mode: 'width', value: Math.round(width * scale) } : { mode: 'original' },
+        background: options.background,
+        font: {
+            fontDirs: fontsDir ? [fontsDir] : [],
+            defaultFontFamily: 'Inter',
+            loadSystemFonts: true,
+        },
+    });
+    return Buffer.from(resvg.render().asPng());
+}
+export const themeBackground = (theme) => theme === 'dark' ? '#292b34' : '#ffffff';
+//# sourceMappingURL=rasterize.js.map

package/dist/render/rasterize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rasterize.js","sourceRoot":"","sources":["../../src/render/rasterize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAWhD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAE,GAAW,EAAE,UAA4B,EAAE;IACzE,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAA;IAEnD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAA;IAChC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,SAAS,CAAA;IAC/F,MAAM,QAAQ,GAAG,MAAM,cAAc,EAAE,CAAA;IAEvC,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE;QACvC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE;QACzF,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,IAAI,EAAE;YACJ,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;YACpC,iBAAiB,EAAE,OAAO;YAC1B,eAAe,EAAE,IAAI;SACtB;KACF,CAAC,CAAA;IACF,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,CAAA;AAC5C,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAuB,EAAU,EAAE,CACjE,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA"}

package/dist/render/renderer.d.ts

@@ -0,0 +1,21 @@
+/** Spec-driven rendering: ChartSpec in, standalone SVG out.
+ *
+ * The headless mechanics (DOM, frame flushing, serialization) live in
+ * headless.ts; this module only knows how to turn a spec into components.
+ */
+import { ChartInputError } from './materialize.js';
+import type { RenderResult } from './headless.js';
+import type { ChartSpec, ComponentSpec } from './spec.js';
+export { ChartInputError };
+export interface RenderOptions {
+    /** Deterministic id prefix (snapshot tests) */
+    idPrefix?: string;
+    /** Keep emotion classes / skip style inlining (debug) */
+    keepClasses?: boolean;
+}
+export type { RenderResult } from './headless.js';
+/** Resolve `{ $unovisMap: name }` markers to lazily-imported TopoJSON data
+ * (the map bundles are large — only loaded when a map chart renders) and
+ * default `mapFeatureName` to the map's feature collection key. */
+export declare function resolveMapMarkers(components: ComponentSpec[]): Promise<ComponentSpec[]>;
+export declare function renderChart(spec: ChartSpec, options?: RenderOptions): Promise<RenderResult>;

package/dist/render/renderer.js

@@ -0,0 +1,66 @@
+/** Spec-driven rendering: ChartSpec in, standalone SVG out.
+ *
+ * The headless mechanics (DOM, frame flushing, serialization) live in
+ * headless.ts; this module only knows how to turn a spec into components.
+ */
+import { materializeChart, ChartInputError, ASYNC_COMPONENTS } from './materialize.js';
+import { renderToSvg } from './headless.js';
+export { ChartInputError };
+/** Unovis map names accepted in `{ $unovisMap: name }` config markers */
+const UNOVIS_MAPS = new Set([
+    'WorldMapTopoJSON', 'WorldMapSimplestTopoJSON', 'WorldMap110mAlphaTopoJSON',
+    'USATopoJSON', 'USCountiesTopoJSON', 'GermanyTopoJSON', 'UKTopoJSON',
+    'FranceTopoJSON', 'IndiaTopoJSON', 'ChinaTopoJSON',
+]);
+/** Resolve `{ $unovisMap: name }` markers to lazily-imported TopoJSON data
+ * (the map bundles are large — only loaded when a map chart renders) and
+ * default `mapFeatureName` to the map's feature collection key. */
+export async function resolveMapMarkers(components) {
+    return Promise.all(components.map(async (component) => {
+        const marker = component.config.topojson?.$unovisMap;
+        if (!marker)
+            return component;
+        if (!UNOVIS_MAPS.has(marker))
+            throw new ChartInputError(`Unknown Unovis map: ${marker}`);
+        // Explicit extension: @unovis/ts has no exports map, and ESM does not
+        // append .js to bare subpath imports (only the tsx loader tolerates it)
+        const maps = await import('@unovis/ts/maps.js');
+        const topojson = maps[marker];
+        if (!topojson)
+            throw new ChartInputError(`Map ${marker} is not available in this @unovis/ts build`);
+        return {
+            ...component,
+            config: {
+                ...component.config,
+                topojson,
+                mapFeatureName: component.config.mapFeatureName ?? Object.keys(topojson.objects)[0],
+            },
+        };
+    }));
+}
+export async function renderChart(spec, options = {}) {
+    const components = await resolveMapMarkers(spec.components);
+    const needsAsyncLayout = components.some(c => ASYNC_COMPONENTS.has(c.type));
+    return renderToSvg({
+        width: spec.width,
+        height: spec.height,
+        theme: spec.theme,
+        title: spec.title,
+        legend: spec.legend,
+        colors: spec.colors,
+        idPrefix: options.idPrefix,
+        keepClasses: options.keepClasses,
+    }, (ctx) => {
+        if (needsAsyncLayout)
+            ctx.requireComponentReady();
+        const materialized = materializeChart(ctx.unovis, { ...spec, components, width: ctx.width, height: ctx.height }, {
+            duration: 0,
+            onRenderComplete: ctx.onRenderComplete,
+            onComponentComplete: ctx.onComponentReady,
+        });
+        return materialized.containerType === 'xy'
+            ? new ctx.unovis.XYContainer(ctx.container, materialized.containerConfig, materialized.data)
+            : new ctx.unovis.SingleContainer(ctx.container, materialized.containerConfig, materialized.data);
+    });
+}
+//# sourceMappingURL=renderer.js.map

package/dist/render/renderer.js.map

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

package/dist/render/spec.d.ts

@@ -0,0 +1,95 @@
+/** ChartSpec — a JSON-serializable intermediate representation of a chart.
+ *
+ * Tool inputs are converted to a ChartSpec (recipes), which the renderer
+ * materializes into live Unovis containers/components. Keeping the IR
+ * serializable enables the `config` output mode and, later, framework code
+ * generation. Accessors are descriptors referencing data fields by name —
+ * user input is never evaluated as code.
+ */
+export type FieldType = 'number' | 'string' | 'date';
+/** Accessor descriptors (JSON-safe stand-ins for Unovis accessor functions) */
+export type AccessorRef = 
+/** d => coerce(d[field]) */
+{
+    $field: string;
+    as?: FieldType;
+}
+/** (d, i) => i */
+ | {
+    $index: true;
+}
+/** () => value */
+ | {
+    $const: unknown;
+}
+/** Multi-line time-aware tick formatter for date scales */
+ | {
+    $dateTickFormat: true;
+}
+/** Numeric tick formatter with thousands separators */
+ | {
+    $numTickFormat: true;
+}
+/** (d, i) => values[i % values.length] — e.g. ordinal index → category name */
+ | {
+    $lookup: (string | number)[];
+}
+/** d => prefix + formatNumber(d[field]) + suffix (empty string for missing values) */
+ | {
+    $format: {
+        field: string;
+        prefix?: string;
+        suffix?: string;
+    };
+}
+/** d => mapping[String(d[field])] ?? fallback — e.g. category → color */
+ | {
+    $mapField: {
+        field: string;
+        mapping: Record<string, string>;
+        fallback?: string;
+    };
+};
+export declare const isAccessorRef: (value: unknown) => value is AccessorRef;
+/** Component config values: JSON values with AccessorRefs anywhere inside */
+export type SpecConfigValue = unknown;
+export interface ComponentSpec {
+    /** Unovis class name, e.g. 'Line', 'StackedBar', 'Donut' */
+    type: string;
+    config: Record<string, SpecConfigValue>;
+}
+export interface AxisSpec {
+    label?: string;
+    gridLine?: boolean;
+    numTicks?: number;
+    tickFormat?: AccessorRef;
+    domainLine?: boolean;
+    tickTextAngle?: number;
+    [key: string]: SpecConfigValue;
+}
+export interface LegendItemSpec {
+    name: string;
+    /** Resolved during post-processing when omitted (default palette) */
+    color?: string;
+    /** Palette index used when color is not set */
+    paletteIndex?: number;
+}
+export interface ChartSpec {
+    container: 'xy' | 'single';
+    width: number;
+    height: number;
+    theme: 'light' | 'dark';
+    title?: string;
+    /** Extra container config (xy: xDomain, yDirection…; single: sizing…) */
+    containerConfig?: Record<string, SpecConfigValue>;
+    components: ComponentSpec[];
+    xAxis?: AxisSpec;
+    yAxis?: AxisSpec;
+    /** Custom palette — overrides --vis-colorN for the whole chart */
+    colors?: string[];
+    legend?: LegendItemSpec[];
+    data: unknown;
+}
+export interface RenderWarnings {
+    warnings: string[];
+}