@blueprint-chart/mcp 0.1.1 → 0.1.3

package/dist/tools/inspect.d.ts

@@ -13,14 +13,21 @@ export interface SceneSummary {
     name?: string;
     hasTransition: boolean;
 }
+export interface DataSummary {
+    rowCount: number;
+    entryCount: number;
+    labels: string[];
+    seriesNames: string[];
+    multiSeries: boolean;
+}
 export interface InspectOutput {
     chartType: string;
     scenes: SceneSummary[];
+    data: DataSummary;
     hasAnnotations: boolean;
     hasColorizes: boolean;
     hasHighlights: boolean;
     hasAreaFills: boolean;
     seriesCount: number;
-    rowCount: number;
 }
 export declare function inspectDsl(input: InspectInput): ToolResult<InspectOutput>;

package/dist/tools/inspect.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { astToDefinition } from '@blueprint-chart/lib';
 import { parseDsl } from '../parse';
 import { toolOk } from '../errors';
+import { looksLikeQuotedLabel } from '../dsl/dataKey';
 export const InspectInputSchema = z.object({
     source: z.string(),
 });
@@ -13,25 +14,48 @@ function summarizeScenes(ast) {
     return scenes.map((scene, i) => ({
         index: i,
         name: scene.name ?? undefined,
-        // SceneNode has no explicit `transition` field; transforms power animated
-        // transitions in the lib, so non-empty transforms imply a transition.
         hasTransition: (scene.transforms?.length ?? 0) > 0,
     }));
 }
+function summarizeData(ast) {
+    const entries = ast.data?.entries ?? [];
+    const seriesEntry = entries.find(e => e.key === '_series');
+    const seriesNames = seriesEntry
+        ? String(seriesEntry.value).split(',').map(s => s.trim().replace(/^"|"$/g, ''))
+        : [];
+    const rowEntries = entries.filter(looksLikeQuotedLabel);
+    return {
+        rowCount: rowEntries.length,
+        entryCount: entries.length,
+        labels: rowEntries.map(e => e.key.replace(/^"|"$/g, '')),
+        seriesNames,
+        multiSeries: seriesNames.length > 0,
+    };
+}
+function countHighlights(ast) {
+    // Grammar: `highlight "X" { … }` parses as ColorizeNode with fromHighlight:true,
+    // `highlight "X"` (no braces) parses as HighlightNode. Count both.
+    const fromHighlightColorizes = (ast.colorizes ?? []).filter((c) => c.fromHighlight === true).length;
+    return (ast.highlights?.length ?? 0) + fromHighlightColorizes;
+}
+function countNonHighlightColorizes(ast) {
+    return (ast.colorizes ?? []).filter((c) => c.fromHighlight !== true).length;
+}
 export function inspectDsl(input) {
     const parsed = parseDsl(input.source);
     if (!parsed.ok) {
         return parsed;
     }
-    const def = astToDefinition(parsed.data.ast);
+    const ast = parsed.data.ast;
+    const def = astToDefinition(ast);
     return toolOk({
         chartType: def.chartType,
-        scenes: summarizeScenes(parsed.data.ast),
+        scenes: summarizeScenes(ast),
+        data: summarizeData(ast),
         hasAnnotations: (def.annotations?.length ?? 0) > 0,
-        hasColorizes: (def.colorizes?.length ?? 0) > 0,
-        hasHighlights: (def.highlights?.length ?? 0) > 0,
+        hasColorizes: countNonHighlightColorizes(ast) > 0,
+        hasHighlights: countHighlights(ast) > 0,
         hasAreaFills: (def.areaFills?.length ?? 0) > 0,
         seriesCount: def.data.series?.length ?? 0,
-        rowCount: def.data.labels?.length ?? 0,
     });
 }

package/dist/tools/inspect.test.js

@@ -2,26 +2,48 @@ import { describe, expect, it } from 'vitest';
 import { samples } from '@blueprint-chart/lib';
 import { inspectDsl } from './inspect';
 describe('inspect_dsl', () => {
-    it('returns chartType + scene summary for a sample', () => {
-        const sample = samples[0];
-        const r = inspectDsl({ source: sample.dsl });
-        expect(r.ok).toBe(true);
-        if (r.ok) {
-            expect(r.data.chartType).toBe(sample.chartType);
-            expect(Array.isArray(r.data.scenes)).toBe(true);
-            expect(r.data.seriesCount).toBeGreaterThanOrEqual(0);
-            expect(r.data.rowCount).toBeGreaterThanOrEqual(0);
-        }
-    });
-    it('returns at least one scene for every shipped sample', () => {
+    it('returns chartType + data summary for every sample', () => {
         for (const s of samples) {
             const r = inspectDsl({ source: s.dsl });
             expect(r.ok, `sample ${s.id}`).toBe(true);
             if (r.ok) {
-                expect(r.data.scenes.length).toBeGreaterThanOrEqual(1);
+                expect(r.data.chartType).toBe(s.chartType);
+                expect(r.data.data.rowCount).toBeGreaterThan(0);
+                expect(Array.isArray(r.data.data.labels)).toBe(true);
+                expect(r.data.data.labels.length).toBe(r.data.data.rowCount);
             }
         }
     });
+    it('rowCount counts parsed rows only, not arbitrary AST entries', () => {
+        // Unquoted-identifier keys are now an E_UNKNOWN_DATA_KEY situation; the
+        // inspector should still parse but rowCount reflects only quoted labels.
+        const r = inspectDsl({
+            source: 'chart bar-vertical { data { a = "foo"  b = "bar" "E" = 1 } }',
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.data.rowCount).toBe(1); // only "E" counts
+            expect(r.data.data.entryCount).toBe(3); // a, b, "E"
+        }
+    });
+    it('hasHighlights is true for braced highlight syntax', () => {
+        const r = inspectDsl({
+            source: 'chart bar-vertical { data { "E" = 1 }  highlight "E" { color = "red" } }',
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.hasHighlights).toBe(true);
+        }
+    });
+    it('hasHighlights is true for bare highlight syntax', () => {
+        const r = inspectDsl({
+            source: 'chart bar-vertical { data { "E" = 1 }  highlight "E" }',
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.hasHighlights).toBe(true);
+        }
+    });
     it('forwards parse errors', () => {
         const r = inspectDsl({ source: '@@@ not valid' });
         expect(r.ok).toBe(false);

package/dist/tools/listChartTypes.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const ListChartTypesInputSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+export type ListChartTypesInput = z.infer<typeof ListChartTypesInputSchema>;
+export interface ChartTypeListEntry {
+    name: string;
+    aliases: string[];
+    summary: string;
+    docsUrl?: string;
+}
+export interface ListChartTypesOutput {
+    chartTypes: ChartTypeListEntry[];
+}
+export declare function listChartTypes(): ToolResult<ListChartTypesOutput>;

package/dist/tools/listChartTypes.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { getDoc, listDocs } from '@blueprint-chart/docs';
+import { aliasesFor, listCanonicalChartTypes } from '../dsl/chartTypes';
+import { publicDocUrl } from '../resources/docsReader';
+import { toolOk } from '../errors';
+export const ListChartTypesInputSchema = z.object({}).strict();
+function summaryFor(name) {
+    // The chart-type docs follow a consistent template: an H1 followed by a
+    // blockquote subtitle. Example (`bar-horizontal.md`):
+    //   # Horizontal bar chart
+    //
+    //   > Single-series horizontal bar chart for long category labels and ranked bars.
+    // If the doc is missing or the template doesn't match, return ''.
+    const entries = listDocs('charts');
+    const entry = entries.find(e => e.slug === name);
+    if (!entry) {
+        return '';
+    }
+    try {
+        const { content } = getDoc('charts', name);
+        const match = content.match(/^>\s*(.+)$/m);
+        return match?.[1]?.trim() ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+export function listChartTypes() {
+    const chartTypes = listCanonicalChartTypes().map((name) => {
+        const entry = {
+            name,
+            aliases: aliasesFor(name),
+            summary: summaryFor(name),
+        };
+        const docsUrl = publicDocUrl('charts', name);
+        if (docsUrl) {
+            entry.docsUrl = docsUrl;
+        }
+        return entry;
+    });
+    return toolOk({ chartTypes });
+}

package/dist/tools/listChartTypes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/listChartTypes.test.js

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { listChartTypes } from './listChartTypes';
+describe('list_chart_types', () => {
+    afterEach(() => {
+        delete process.env.BLUEPRINT_CHART_DOCS_URL;
+    });
+    it('returns canonical chart types with aliases and a summary', () => {
+        const r = listChartTypes();
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            const types = r.data.chartTypes;
+            expect(types.length).toBeGreaterThan(5);
+            const horiz = types.find(t => t.name === 'bar-horizontal');
+            expect(horiz).toBeDefined();
+            expect(horiz.aliases).toContain('horizontal-bar');
+            expect(horiz.summary.length).toBeGreaterThan(0);
+        }
+    });
+    it('does not include alias names as canonical entries', () => {
+        const r = listChartTypes();
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.chartTypes.find(t => t.name === 'horizontal-bar')).toBeUndefined();
+        }
+    });
+    it('omits docsUrl when docs base is unset', () => {
+        const result = listChartTypes();
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.chartTypes[0]?.docsUrl).toBeUndefined();
+        }
+    });
+    it('includes docsUrl per entry when docs base is set', () => {
+        process.env.BLUEPRINT_CHART_DOCS_URL = 'https://docs.blueprintchart.com';
+        const result = listChartTypes();
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            const entry = result.data.chartTypes[0];
+            expect(entry?.docsUrl).toBe(`https://docs.blueprintchart.com/charts/${entry?.name}`);
+        }
+    });
+});

package/dist/tools/render.d.ts

@@ -1,35 +1,37 @@
 import { z } from 'zod';
+import { type FrameMetadata } from '../render/frame';
 import { type ToolResult } from '../errors';
 export declare const RenderInputSchema: z.ZodObject<{
     source: z.ZodString;
-    format: z.ZodDefault<z.ZodEnum<["svg", "png"]>>;
+    format: z.ZodDefault<z.ZodEnum<["svg", "png", "html"]>>;
     scene: z.ZodOptional<z.ZodNumber>;
     width: z.ZodDefault<z.ZodNumber>;
     height: z.ZodDefault<z.ZodNumber>;
+    /** Optional file path (absolute, or relative to MCP server CWD). When provided, the primary output (PNG bytes / SVG / HTML) is written to that path and the inline content is omitted from the response. Requires MCP_ALLOW_FS_WRITE=1. */
+    save: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     source: string;
     width: number;
     height: number;
-    format: "svg" | "png";
+    format: "html" | "svg" | "png";
     scene?: number | undefined;
+    save?: string | undefined;
 }, {
     source: string;
     width?: number | undefined;
     height?: number | undefined;
-    format?: "svg" | "png" | undefined;
     scene?: number | undefined;
+    format?: "html" | "svg" | "png" | undefined;
+    save?: string | undefined;
 }>;
 export type RenderInput = z.infer<typeof RenderInputSchema>;
 export interface RenderOutput {
-    svg: string;
+    svg?: string;
     png?: string;
-    mimeType: 'image/svg+xml' | 'image/png';
+    html?: string;
+    frame: FrameMetadata;
+    mimeType: 'image/svg+xml' | 'image/png' | 'text/html';
+    /** When `save` was used, the resolved absolute path the output was written to. Inline content fields (svg/png/html) are omitted. */
+    savedTo?: string;
 }
-/**
- * Composes `parseDsl`, `renderSceneState`, and `rasterizeToPng` into the
- * `render` MCP tool. Always returns SVG; when `format=png`, also includes a
- * base64-encoded PNG. If rasterisation fails we surface `E_RENDER` — the SVG
- * is discarded in that branch to keep the union shape (ToolResult is either
- * ok-with-data or err-with-errors, no partial-success carrier).
- */
 export declare function renderTool(input: unknown): Promise<ToolResult<RenderOutput>>;

package/dist/tools/render.js

@@ -1,63 +1,131 @@
 import { z } from 'zod';
-import { parseDsl } from '../parse';
+import { writeFile } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+import { extractFrameMetadata } from '../render/frame';
 import { renderSceneState } from '../render/renderSceneState';
 import { rasterizeToPng } from '../render/rasterize';
+import { validatePipeline } from '../render/validatePipeline';
 import { ErrorCode, toolError, toolOk } from '../errors';
 export const RenderInputSchema = z.object({
     source: z.string(),
-    format: z.enum(['svg', 'png']).default('svg'),
+    format: z.enum(['svg', 'png', 'html']).default('svg'),
     scene: z.number().int().nonnegative().optional(),
     width: z.number().int().positive().default(800),
     height: z.number().int().positive().default(500),
+    /** Optional file path (absolute, or relative to MCP server CWD). When provided, the primary output (PNG bytes / SVG / HTML) is written to that path and the inline content is omitted from the response. Requires MCP_ALLOW_FS_WRITE=1. */
+    save: z.string().optional(),
 });
-/**
- * `renderSceneState` returns the SVG fragment as produced by jsdom's
- * `outerHTML`, which omits the default SVG namespace. resvg's strict parser
- * rejects that as "the document does not have a root node". Inject the
- * namespace on the way to the rasterizer so the PNG path succeeds.
- */
+function isFsWriteEnabled() {
+    const v = process.env.MCP_ALLOW_FS_WRITE;
+    return v === '1' || v === 'true' || v === 'yes';
+}
+async function trySave(absPath, body) {
+    try {
+        await writeFile(absPath, body);
+        return { savedTo: absPath };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
 function ensureSvgNamespace(svg) {
     if (svg.includes('xmlns="http://www.w3.org/2000/svg"')) {
         return svg;
     }
     return svg.replace(/^<svg(?=\s|>)/, '<svg xmlns="http://www.w3.org/2000/svg"');
 }
-/**
- * Composes `parseDsl`, `renderSceneState`, and `rasterizeToPng` into the
- * `render` MCP tool. Always returns SVG; when `format=png`, also includes a
- * base64-encoded PNG. If rasterisation fails we surface `E_RENDER` — the SVG
- * is discarded in that branch to keep the union shape (ToolResult is either
- * ok-with-data or err-with-errors, no partial-success carrier).
- */
 export async function renderTool(input) {
     const parsed = RenderInputSchema.safeParse(input);
     if (!parsed.success) {
         return toolError(ErrorCode.E_INPUT, parsed.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
     }
-    const { source, format, scene, width, height } = parsed.data;
-    const parseResult = parseDsl(source);
-    if (!parseResult.ok) {
-        return parseResult;
+    const { source, format, scene, width, height, save } = parsed.data;
+    if (save !== undefined && !isFsWriteEnabled()) {
+        return toolError(ErrorCode.E_INPUT, [{
+                code: 'E_FS_WRITE_DISABLED',
+                path: 'save',
+                message: 'File saving is disabled. Set MCP_ALLOW_FS_WRITE=1 to enable. This is typically only safe in local stdio mode.',
+            }]);
     }
+    const validated = validatePipeline(source, { sceneIndex: scene });
+    if (!validated.ok) {
+        return validated.error;
+    }
+    const frame = extractFrameMetadata(validated.ast);
+    // Layer 3: actual render.
     let svg;
+    let html;
     try {
-        svg = renderSceneState(source, { sceneIndex: scene, width, height });
+        const result = renderSceneState(source, { sceneIndex: scene, width, height });
+        svg = result.svg;
+        html = result.html;
     }
     catch (err) {
-        return toolError(ErrorCode.E_RENDER, [
-            { path: 'render', message: err instanceof Error ? err.message : String(err) },
-        ]);
+        return toolError(ErrorCode.E_RENDER, [{
+                code: 'E_RENDER_UNKNOWN',
+                path: 'render',
+                message: err instanceof Error ? err.message : String(err),
+            }]);
     }
     if (format === 'svg') {
-        return toolOk({ svg, mimeType: 'image/svg+xml' });
+        if (save !== undefined) {
+            const absPath = resolvePath(save);
+            const result = await trySave(absPath, svg);
+            if ('error' in result) {
+                return toolError(ErrorCode.E_RENDER, [{
+                        code: 'E_SAVE_FAILED',
+                        path: 'save',
+                        message: result.error,
+                    }]);
+            }
+            return toolOk({ frame, mimeType: 'image/svg+xml', savedTo: result.savedTo });
+        }
+        return toolOk({ svg, frame, mimeType: 'image/svg+xml' });
+    }
+    if (format === 'html') {
+        if (!html) {
+            return toolError(ErrorCode.E_RENDER, [{
+                    code: 'E_FRAME_UNAVAILABLE',
+                    path: 'render',
+                    message: 'HTML frame was not produced by the renderer',
+                }]);
+        }
+        if (save !== undefined) {
+            const absPath = resolvePath(save);
+            const result = await trySave(absPath, html);
+            if ('error' in result) {
+                return toolError(ErrorCode.E_RENDER, [{
+                        code: 'E_SAVE_FAILED',
+                        path: 'save',
+                        message: result.error,
+                    }]);
+            }
+            return toolOk({ frame, mimeType: 'text/html', savedTo: result.savedTo });
+        }
+        return toolOk({ svg, html, frame, mimeType: 'text/html' });
     }
+    // format === 'png'
     try {
         const png = await rasterizeToPng(ensureSvgNamespace(svg), { width });
-        return toolOk({ svg, png: png.toString('base64'), mimeType: 'image/png' });
+        if (save !== undefined) {
+            const absPath = resolvePath(save);
+            const result = await trySave(absPath, png);
+            if ('error' in result) {
+                return toolError(ErrorCode.E_RENDER, [{
+                        code: 'E_SAVE_FAILED',
+                        path: 'save',
+                        message: result.error,
+                    }]);
+            }
+            return toolOk({ frame, mimeType: 'image/png', savedTo: result.savedTo });
+        }
+        return toolOk({ svg, png: png.toString('base64'), frame, mimeType: 'image/png' });
     }
     catch (err) {
-        return toolError(ErrorCode.E_RENDER, [
-            { path: 'rasterize', message: err instanceof Error ? err.message : String(err) },
-        ]);
+        return toolError(ErrorCode.E_RENDER, [{
+                code: 'E_RASTERIZE',
+                path: 'rasterize',
+                message: err instanceof Error ? err.message : String(err),
+            }]);
     }
 }

package/dist/tools/render.test.js

@@ -2,13 +2,15 @@ import { describe, expect, it } from 'vitest';
 import { samples } from '@blueprint-chart/lib';
 import { renderTool } from './render';
 describe('render', () => {
-    it('returns SVG by default', async () => {
+    it('returns pure SVG by default', async () => {
         const r = await renderTool({ source: samples[0].dsl });
         expect(r.ok).toBe(true);
         if (r.ok) {
             expect(r.data.mimeType).toBe('image/svg+xml');
             expect(r.data.svg).toMatch(/^<svg/);
             expect(r.data.png).toBeUndefined();
+            expect(r.data.html).toBeUndefined();
+            expect(r.data.frame).toBeDefined();
         }
     });
     it('returns both SVG and PNG when format=png', async () => {
@@ -19,6 +21,7 @@ describe('render', () => {
             expect(r.data.svg).toMatch(/^<svg/);
             expect(r.data.png).toBeTypeOf('string'); // base64
             expect(r.data.png.length).toBeGreaterThan(100);
+            expect(r.data.frame).toBeDefined();
         }
     });
     it('forwards parse errors', async () => {
@@ -37,3 +40,136 @@ describe('render', () => {
         }
     });
 });
+describe('render — frame defaults', () => {
+    it('format=svg returns pure SVG without HTML wrapper', async () => {
+        const { samples } = await import('@blueprint-chart/lib');
+        const sample = samples.find(s => s.id === 'letter-frequency');
+        const r = await renderTool({ source: sample.dsl, format: 'svg' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.svg).toMatch(/^<svg/);
+            expect(r.data.svg).not.toContain('<div class="bc-frame"');
+            expect(r.data.html).toBeUndefined();
+        }
+    });
+    it('format=svg on letter-frequency returns correct frame.title', async () => {
+        const { samples } = await import('@blueprint-chart/lib');
+        const sample = samples.find(s => s.id === 'letter-frequency');
+        const r = await renderTool({ source: sample.dsl, format: 'svg' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.frame.title).toBe('E is the most frequent letter in English');
+        }
+    });
+    it('format=html returns html containing bc-frame and svg', async () => {
+        const { samples } = await import('@blueprint-chart/lib');
+        const sample = samples.find(s => s.id === 'letter-frequency');
+        const r = await renderTool({ source: sample.dsl, format: 'html' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.mimeType).toBe('text/html');
+            expect(r.data.html).toContain('<div class="bc-frame"');
+            expect(r.data.html).toContain('<svg');
+            expect(r.data.svg).toMatch(/^<svg/);
+            expect(r.data.frame).toBeDefined();
+        }
+    });
+});
+describe('render — save option', () => {
+    it('errors when MCP_ALLOW_FS_WRITE is unset', async () => {
+        delete process.env.MCP_ALLOW_FS_WRITE;
+        const r = await renderTool({
+            source: 'chart bar-vertical { data { "E" = 1 } }',
+            format: 'png',
+            save: '/tmp/test.png',
+        });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.errors[0].code).toBe('E_FS_WRITE_DISABLED');
+        }
+    });
+    it('writes the PNG when MCP_ALLOW_FS_WRITE=1', async () => {
+        process.env.MCP_ALLOW_FS_WRITE = '1';
+        const { samples } = await import('@blueprint-chart/lib');
+        const sample = samples.find(s => s.id === 'letter-frequency');
+        const tmp = `/tmp/mcp-render-test-${Date.now()}.png`;
+        try {
+            const r = await renderTool({ source: sample.dsl, format: 'png', save: tmp });
+            expect(r.ok).toBe(true);
+            if (r.ok) {
+                expect(r.data.savedTo).toBe(tmp);
+                expect(r.data.png).toBeUndefined(); // inline payload omitted
+                const { statSync } = await import('node:fs');
+                expect(statSync(tmp).size).toBeGreaterThan(1000); // real PNG, not stub
+            }
+        }
+        finally {
+            const { unlinkSync, existsSync } = await import('node:fs');
+            if (existsSync(tmp)) {
+                unlinkSync(tmp);
+            }
+            delete process.env.MCP_ALLOW_FS_WRITE;
+        }
+    });
+    it('writes the SVG when format=svg and save provided', async () => {
+        process.env.MCP_ALLOW_FS_WRITE = '1';
+        const tmp = `/tmp/mcp-render-test-${Date.now()}.svg`;
+        try {
+            const r = await renderTool({
+                source: 'chart bar-vertical { title = "x"  data { "E" = 1 } }',
+                format: 'svg',
+                save: tmp,
+            });
+            expect(r.ok).toBe(true);
+            if (r.ok) {
+                expect(r.data.savedTo).toBe(tmp);
+                expect(r.data.svg).toBeUndefined();
+            }
+        }
+        finally {
+            const { unlinkSync, existsSync } = await import('node:fs');
+            if (existsSync(tmp)) {
+                unlinkSync(tmp);
+            }
+            delete process.env.MCP_ALLOW_FS_WRITE;
+        }
+    });
+});
+describe('render — structured diagnostics', () => {
+    it('returns E_SEMANTIC + E_UNKNOWN_CHART_TYPE for chart bar', async () => {
+        const r = await renderTool({ source: 'chart bar { data { "E" = 1 } }' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_SEMANTIC');
+            expect(r.errors[0].code).toBe('E_UNKNOWN_CHART_TYPE');
+            expect(r.errors[0].suggestion).toMatch(/^bar-/);
+        }
+    });
+    it('returns E_SEMANTIC + E_EMPTY_DATA when data is empty', async () => {
+        const r = await renderTool({ source: 'chart bar-vertical { title = "x" }' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_SEMANTIC');
+            expect(r.errors[0].code).toBe('E_EMPTY_DATA');
+        }
+    });
+    it('never returns the generic "produced no SVG output" message', async () => {
+        const r = await renderTool({ source: 'chart bar { data { "E" = 1 } }' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            for (const e of r.errors) {
+                expect(e.message).not.toContain('produced no SVG output');
+            }
+        }
+    });
+    it('renders every sample to SVG and provides frame metadata', async () => {
+        const { samples } = await import('@blueprint-chart/lib');
+        for (const s of samples) {
+            const r = await renderTool({ source: s.dsl, format: 'svg' });
+            expect(r.ok, `sample ${s.id}`).toBe(true);
+            if (r.ok) {
+                expect(r.data.frame, `sample ${s.id} frame`).toBeDefined();
+            }
+        }
+    });
+});

package/dist/tools/validate.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type ValidationIssue } from '../dsl/validate';
 import { type ToolResult } from '../errors';
 export declare const ValidateInputSchema: z.ZodObject<{
     source: z.ZodString;
@@ -8,6 +9,13 @@ export declare const ValidateInputSchema: z.ZodObject<{
     source: string;
 }>;
 export type ValidateInput = z.infer<typeof ValidateInputSchema>;
-export declare function validateDsl(input: ValidateInput): ToolResult<{
-    valid: true;
-}>;
+export interface ValidateOutput {
+    valid: boolean;
+    errors: ValidationIssue[];
+    /**
+     * Reserved for non-fatal advisories. Currently always empty; future versions
+     * may populate this without breaking existing clients.
+     */
+    warnings: ValidationIssue[];
+}
+export declare function validateDsl(input: ValidateInput): ToolResult<ValidateOutput>;

package/dist/tools/validate.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { parseDsl } from '../parse';
+import { validateAst } from '../dsl/validate';
 import { toolOk } from '../errors';
 export const ValidateInputSchema = z.object({
     source: z.string(),
@@ -9,5 +10,12 @@ export function validateDsl(input) {
     if (!parsed.ok) {
         return parsed;
     }
-    return toolOk({ valid: true });
+    const issues = validateAst(parsed.data.ast);
+    return toolOk({
+        valid: issues.length === 0,
+        errors: issues,
+        // `warnings` is reserved for non-fatal advisories. Currently always empty;
+        // future versions may populate this without breaking existing clients.
+        warnings: [],
+    });
 }