@blueprint-chart/mcp 0.1.1 → 0.1.4

package/dist/lib/zodToJsonSchema.d.ts

@@ -1,8 +1,13 @@
 import type { ZodTypeAny } from 'zod';
 /**
- * Permissive stub: returns a generic object schema that allows any properties.
- * MCP tool handlers do the precise runtime validation via Zod. If MCP clients
- * begin requiring precise JSON Schema for `listTools`, replace this body with
- * the `zod-to-json-schema` package.
+ * Convert a Zod schema to a JSON Schema object suitable for MCP `tools/list`.
+ *
+ * MCP clients (notably claude.ai web) introspect this schema to know what
+ * parameters a tool accepts. A permissive stub left tools effectively
+ * un-invokable because the param shapes weren't discoverable.
+ *
+ * `zod-to-json-schema` produces a `$schema`-prefixed draft-07 document; we
+ * unwrap that to just the inline schema body so it slots cleanly into the
+ * MCP tool descriptor.
  */
-export declare function zodToJsonSchema(_schema: ZodTypeAny): Record<string, unknown>;
+export declare function zodToJsonSchema(schema: ZodTypeAny): Record<string, unknown>;

package/dist/lib/zodToJsonSchema.js

@@ -1,9 +1,17 @@
+import { zodToJsonSchema as toJsonSchema } from 'zod-to-json-schema';
 /**
- * Permissive stub: returns a generic object schema that allows any properties.
- * MCP tool handlers do the precise runtime validation via Zod. If MCP clients
- * begin requiring precise JSON Schema for `listTools`, replace this body with
- * the `zod-to-json-schema` package.
+ * Convert a Zod schema to a JSON Schema object suitable for MCP `tools/list`.
+ *
+ * MCP clients (notably claude.ai web) introspect this schema to know what
+ * parameters a tool accepts. A permissive stub left tools effectively
+ * un-invokable because the param shapes weren't discoverable.
+ *
+ * `zod-to-json-schema` produces a `$schema`-prefixed draft-07 document; we
+ * unwrap that to just the inline schema body so it slots cleanly into the
+ * MCP tool descriptor.
  */
-export function zodToJsonSchema(_schema) {
-    return { type: 'object', additionalProperties: true };
+export function zodToJsonSchema(schema) {
+    const full = toJsonSchema(schema, { target: 'jsonSchema7', $refStrategy: 'none' });
+    const { $schema: _$schema, ...rest } = full;
+    return rest;
 }

package/dist/links/buildUrls.d.ts

@@ -0,0 +1,14 @@
+export type DocUrlGroup = 'handbook' | 'guide' | 'charts' | 'reference/dsl' | 'reference/api';
+/**
+ * Editable "open & copy" deep-link: hydrates a fresh editor session.
+ * The `/copy` route reads `bpc64` from the query string and decodes it as
+ * URL-SAFE base64 (`decodeUrlSafeBase64`). `encodeURIComponent` mirrors the
+ * editor/docs code; it is a no-op on url-safe base64 (alphabet is `[A-Za-z0-9-_]`)
+ * but kept for fidelity. NOTE: distinct from `/render?bpc64=` below, which
+ * decodes STANDARD base64 via `atob` despite the identical param name.
+ */
+export declare function buildCopyUrl(source: string, editorBase: string): string;
+/** Read-only render deep-link, suitable as an iframe `src` (standard base64). */
+export declare function buildEmbedUrl(source: string, editorBase: string): string;
+/** Public docs page URL for a docs group + slug. */
+export declare function buildDocUrl(group: DocUrlGroup, slug: string, docsBase: string): string;

package/dist/links/buildUrls.js

@@ -0,0 +1,20 @@
+import { toUrlSafeB64, toStandardB64 } from './encode';
+/**
+ * Editable "open & copy" deep-link: hydrates a fresh editor session.
+ * The `/copy` route reads `bpc64` from the query string and decodes it as
+ * URL-SAFE base64 (`decodeUrlSafeBase64`). `encodeURIComponent` mirrors the
+ * editor/docs code; it is a no-op on url-safe base64 (alphabet is `[A-Za-z0-9-_]`)
+ * but kept for fidelity. NOTE: distinct from `/render?bpc64=` below, which
+ * decodes STANDARD base64 via `atob` despite the identical param name.
+ */
+export function buildCopyUrl(source, editorBase) {
+    return `${editorBase}/#/copy?bpc64=${encodeURIComponent(toUrlSafeB64(source))}`;
+}
+/** Read-only render deep-link, suitable as an iframe `src` (standard base64). */
+export function buildEmbedUrl(source, editorBase) {
+    return `${editorBase}/#/render?bpc64=${encodeURIComponent(toStandardB64(source))}`;
+}
+/** Public docs page URL for a docs group + slug. */
+export function buildDocUrl(group, slug, docsBase) {
+    return `${docsBase}/${group}/${slug}`;
+}

package/dist/links/buildUrls.test.d.ts

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

package/dist/links/buildUrls.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { buildCopyUrl, buildEmbedUrl, buildDocUrl } from './buildUrls';
+const EDITOR = 'https://blueprintchart.com';
+const DOCS = 'https://docs.blueprintchart.com';
+const SRC = 'chart bar-vertical {\n}\n';
+describe('buildCopyUrl', () => {
+    it('builds a /copy?bpc64= deep-link with url-safe base64', () => {
+        expect(buildCopyUrl(SRC, EDITOR)).toBe('https://blueprintchart.com/#/copy?bpc64=Y2hhcnQgYmFyLXZlcnRpY2FsIHsKfQo');
+    });
+    it('produces a url-safe payload (no +, /, or = to encode)', () => {
+        const url = buildCopyUrl(SRC, EDITOR);
+        const payload = url.split('bpc64=')[1];
+        expect(payload).not.toMatch(/[+/=]|%/);
+    });
+});
+describe('buildEmbedUrl', () => {
+    it('builds a hash /render link with URI-encoded standard base64', () => {
+        expect(buildEmbedUrl(SRC, EDITOR)).toBe('https://blueprintchart.com/#/render?bpc64=Y2hhcnQgYmFyLXZlcnRpY2FsIHsKfQo%3D');
+    });
+});
+describe('buildDocUrl', () => {
+    it('maps the charts group to the /charts docs path', () => {
+        expect(buildDocUrl('charts', 'bar-vertical', DOCS)).toBe('https://docs.blueprintchart.com/charts/bar-vertical');
+    });
+    it('maps reference/dsl to a nested path', () => {
+        expect(buildDocUrl('reference/dsl', 'properties', DOCS)).toBe('https://docs.blueprintchart.com/reference/dsl/properties');
+    });
+});

package/dist/links/editorConfig.d.ts

@@ -0,0 +1,4 @@
+/** Editor app base URL (e.g. https://blueprintchart.com), or undefined when unset. */
+export declare function getEditorBaseUrl(): string | undefined;
+/** Docs site base URL (e.g. https://docs.blueprintchart.com), or undefined when unset. */
+export declare function getDocsBaseUrl(): string | undefined;

package/dist/links/editorConfig.js

@@ -0,0 +1,15 @@
+function normalize(raw) {
+    const trimmed = raw?.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return trimmed.replace(/\/+$/, '');
+}
+/** Editor app base URL (e.g. https://blueprintchart.com), or undefined when unset. */
+export function getEditorBaseUrl() {
+    return normalize(process.env.BLUEPRINT_CHART_EDITOR_URL);
+}
+/** Docs site base URL (e.g. https://docs.blueprintchart.com), or undefined when unset. */
+export function getDocsBaseUrl() {
+    return normalize(process.env.BLUEPRINT_CHART_DOCS_URL);
+}

package/dist/links/editorConfig.test.d.ts

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

package/dist/links/editorConfig.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { getEditorBaseUrl, getDocsBaseUrl } from './editorConfig';
+afterEach(() => {
+    delete process.env.BLUEPRINT_CHART_EDITOR_URL;
+    delete process.env.BLUEPRINT_CHART_DOCS_URL;
+});
+describe('getEditorBaseUrl', () => {
+    it('returns undefined when unset', () => {
+        expect(getEditorBaseUrl()).toBeUndefined();
+    });
+    it('returns undefined when blank/whitespace', () => {
+        process.env.BLUEPRINT_CHART_EDITOR_URL = '   ';
+        expect(getEditorBaseUrl()).toBeUndefined();
+    });
+    it('strips trailing slashes and trims', () => {
+        process.env.BLUEPRINT_CHART_EDITOR_URL = '  https://blueprintchart.com//  ';
+        expect(getEditorBaseUrl()).toBe('https://blueprintchart.com');
+    });
+});
+describe('getDocsBaseUrl', () => {
+    it('returns undefined when unset', () => {
+        expect(getDocsBaseUrl()).toBeUndefined();
+    });
+    it('normalizes a set value', () => {
+        process.env.BLUEPRINT_CHART_DOCS_URL = 'https://docs.blueprintchart.com/';
+        expect(getDocsBaseUrl()).toBe('https://docs.blueprintchart.com');
+    });
+});

package/dist/links/encode.d.ts

@@ -0,0 +1,11 @@
+/**
+ * RFC 4648 §5 url-safe base64 with padding stripped — the encoding the editor's
+ * `/#/copy?bpc64=` route decodes (via `decodeUrlSafeBase64`). Mirrors
+ * `toUrlSafeB64` in the editor/docs.
+ */
+export declare function toUrlSafeB64(input: string): string;
+/**
+ * Standard (padded) base64 — the form the editor's `/#/render?bpc64=` route
+ * decodes via `atob`. Callers must `encodeURIComponent` it for the query string.
+ */
+export declare function toStandardB64(input: string): string;

package/dist/links/encode.js

@@ -0,0 +1,19 @@
+/**
+ * RFC 4648 §5 url-safe base64 with padding stripped — the encoding the editor's
+ * `/#/copy?bpc64=` route decodes (via `decodeUrlSafeBase64`). Mirrors
+ * `toUrlSafeB64` in the editor/docs.
+ */
+export function toUrlSafeB64(input) {
+    return Buffer.from(input, 'utf-8')
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+/**
+ * Standard (padded) base64 — the form the editor's `/#/render?bpc64=` route
+ * decodes via `atob`. Callers must `encodeURIComponent` it for the query string.
+ */
+export function toStandardB64(input) {
+    return Buffer.from(input, 'utf-8').toString('base64');
+}

package/dist/links/encode.test.d.ts

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

package/dist/links/encode.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { samples } from '@blueprint-chart/lib';
+import { toUrlSafeB64, toStandardB64 } from './encode';
+/** Decode a url-safe, unpadded base64 string back to UTF-8 (mirrors the editor's /copy decoder). */
+function decodeUrlSafe(raw) {
+    const padded = raw.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = padded.length % 4 === 0 ? '' : '='.repeat(4 - (padded.length % 4));
+    return Buffer.from(padded + pad, 'base64').toString('utf8');
+}
+describe('toUrlSafeB64', () => {
+    it('encodes ASCII with no padding and a url-safe alphabet', () => {
+        const out = toUrlSafeB64('chart bar-vertical {\n}\n');
+        expect(out).toBe('Y2hhcnQgYmFyLXZlcnRpY2FsIHsKfQo');
+        expect(out).not.toContain('=');
+        expect(out).not.toMatch(/[+/]/);
+    });
+    it('round-trips non-ASCII (en dash, euro) through UTF-8', () => {
+        const src = 'Price – €5';
+        expect(toUrlSafeB64(src)).toBe('UHJpY2Ug4oCTIOKCrDU');
+        expect(decodeUrlSafe(toUrlSafeB64(src))).toBe(src);
+    });
+});
+describe('toStandardB64', () => {
+    it('encodes with standard alphabet and padding (atob-compatible)', () => {
+        expect(toStandardB64('chart bar-vertical {\n}\n')).toBe('Y2hhcnQgYmFyLXZlcnRpY2FsIHsKfQo=');
+    });
+});
+describe('letter-frequency golden link', () => {
+    // The url-safe base64 of the letter-frequency sample, as hardcoded in the
+    // editor's LandingMcp.vue (`/#/copy?bpc64=<this>`). MCP output must match exactly.
+    const LANDING_B64 = 'Y2hhcnQgYmFyLXZlcnRpY2FsIHsKICB0aXRsZSA9ICJFIGlzIHRoZSBtb3N0IGZyZXF1ZW50IGxldHRlciBpbiBFbmdsaXNoIgogIGRlc2NyaXB0aW9uID0gIkhvdyBvZnRlbiBlYWNoIGxldHRlciBhcHBlYXJzIGluIHR5cGljYWwgRW5nbGlzaCB0ZXh0IgogIGJ5bGluZSA9ICJQaWVycmUgUm9tZXJhIgogIHNvdXJjZSA9ICJMZXdhbmQsIENyeXB0b2xvZ2ljYWwgTWF0aGVtYXRpY3MiCiAgc291cmNlVXJsID0gImh0dHBzOi8vZW4ud2lraXBlZGlhLm9yZy93aWtpL0xldHRlcl9mcmVxdWVuY3kiCiAgbm90ZSA9ICJCYXNlZCBvbiBhbmFseXNpcyBvZiA0MCwwMDAgd29yZHMgZnJvbSBFbmdsaXNoIHByb3NlIgogIGNvbG9yUGFsZXR0ZSA9ICJMb25kb24iCiAgc29ydCA9IGRlc2NlbmRpbmcKICB2YWx1ZUxhYmVscyA9IHRydWUKICB2ZXJ0aWNhbExhYmVsUG9zaXRpb24gPSBvZmYKICB2ZXJ0aWNhbEdyaWRTdHlsZSA9IG5vbmUKCiAgaGlnaGxpZ2h0ICJFIgoKICBkYXRhIHsKICAgICJFIiA9IDEyLjcwCiAgICAiVCIgPSA5LjA2CiAgICAiQSIgPSA4LjE3CiAgICAiTyIgPSA3LjUxCiAgICAiSSIgPSA2Ljk3CiAgICAiTiIgPSA2Ljc1CiAgICAiUyIgPSA2LjMzCiAgICAiSCIgPSA2LjA5CiAgICAiUiIgPSA1Ljk5CiAgICAiRCIgPSA0LjI1CiAgfQp9Cg';
+    it('matches the editor landing-page copy link byte-for-byte', () => {
+        const sample = samples.find(s => s.id === 'letter-frequency');
+        expect(sample).toBeDefined();
+        expect(toUrlSafeB64(sample.dsl)).toBe(LANDING_B64);
+    });
+});

package/dist/parse.js

@@ -1,5 +1,6 @@
 import { parse as libParse } from '@blueprint-chart/lib';
 import { ErrorCode, toolError, toolOk } from './errors';
+import { humanizeParseError } from './dsl/parseErrorHints';
 export function parseDsl(source) {
     if (typeof source !== 'string') {
         return toolError(ErrorCode.E_INPUT, [{ path: 'source', message: 'expected string' }]);
@@ -10,15 +11,22 @@ export function parseDsl(source) {
     }
     catch (err) {
         if (err instanceof Error) {
-            // lib's parser wraps SyntaxError with " at L:C" suffix in the message
             const match = err.message.match(/^(.*) at (\d+):(\d+)$/);
             if (match) {
-                const [, message, line, column] = match;
-                return toolError(ErrorCode.E_PARSE, [
-                    { line: Number(line), column: Number(column), message: message.trim() },
-                ]);
+                const [, rawMessage, line, column] = match;
+                const h = humanizeParseError(rawMessage.trim());
+                return toolError(ErrorCode.E_PARSE, [{
+                        line: Number(line),
+                        column: Number(column),
+                        message: h.message,
+                        ...(h.suggestion !== undefined && { suggestion: h.suggestion }),
+                    }]);
             }
-            return toolError(ErrorCode.E_PARSE, [{ message: err.message }]);
+            const h = humanizeParseError(err.message);
+            return toolError(ErrorCode.E_PARSE, [{
+                    message: h.message,
+                    ...(h.suggestion !== undefined && { suggestion: h.suggestion }),
+                }]);
         }
         return toolError(ErrorCode.E_INTERNAL, [{ message: String(err) }]);
     }

package/dist/parse.test.js

@@ -19,6 +19,14 @@ describe('parseDsl', () => {
             expect(typeof r.errors[0].message).toBe('string');
         }
     });
+    it('humanizes the parser message (YAML-colon case flows through parse.ts)', () => {
+        const r = parseDsl('chart: donut { data { "A" = 1 } }');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_PARSE');
+            expect(r.errors[0].message).toContain('chart <type> {');
+        }
+    });
     it('returns E_INPUT for non-string input', () => {
         const r = parseDsl(123);
         expect(r.ok).toBe(false);

package/dist/prompts/authorChart.js

@@ -1,30 +1,35 @@
 const BODY = `You are authoring a Blueprint Chart (\`.bpc\`) file for a user.
 
 Workflow:
-1. Read \`bpc://grammar\` for the DSL syntax.
-2. Read \`bpc://handbook/choosing\` and \`bpc://handbook/design-principles\` for dataviz judgment.
-3. If unsure about the chart type, call \`recommend_chart_type\` with the user's column types and row count.
-4. Read \`bpc://chart-types/<type>\` for the specific chart you'll use.
-5. Look at \`bpc://samples/<id>\` for a working example in the same family.
-6. Write the \`.bpc\` source.
-7. Call \`validate_dsl\` on your draft. If errors, read the line/column from the response and fix them.
-8. Call \`inspect_dsl\` to sanity-check the parsed structure.
-9. Call \`render\` with format="png" to get a visual. If the chart looks wrong, iterate on the \`.bpc\` and re-render.
-10. Return the final \`.bpc\` source AND the rendered chart to the user.
+1. Call \`list_chart_types\` to see what's renderable. (Or read \`bpc://handbook/choosing\` if your client supports resources.)
+2. If unsure which type to use, call \`recommend_chart_type({ columnTypes, rowCount, goal? })\`.
+3. Call \`describe_chart_type({ name: "<type>" })\` for properties, when-to-use, and a data-shape example.
+4. Call \`get_example({ chartType: "<type>" })\` (or \`{ name: "<sample-id>" }\`) to copy a canonical .bpc as a starting point.
+5. Write the \`.bpc\` source.
+6. Call \`validate_dsl\` — read \`errors[]\`: each entry has \`code\`, \`message\`, \`suggestion\`. Fix and retry.
+7. Call \`inspect_dsl\` to sanity-check structure: \`data.rowCount\` confirms rows parsed, \`hasHighlights\`/\`hasColorizes\` confirm overrides.
+8. Call \`render({ source, format: "png" })\` for a visual. If \`errors[]\` is non-empty, each entry has \`code\` and a usable \`suggestion\`.
+9. Return the final \`.bpc\` and rendered chart to the user.
+10. If the user wants to share or embed the chart, call \`export_chart({ source })\` and give them \`copyUrl\` (editable — anyone can open and copy it) or \`embedUrl\` (a read-only render URL for an iframe). Requires the server to have BLUEPRINT_CHART_EDITOR_URL configured; otherwise it returns \`E_CONFIG\`.
 
-Resources you can read:
-- \`bpc://grammar\` — DSL syntax reference (aggregate)
+Resources you can read (if your client supports MCP resources):
+- \`bpc://grammar\` — DSL syntax reference (use \`get_grammar\` as a tool equivalent)
 - \`bpc://handbook/{slug}\` — dataviz pedagogy (choosing, design-principles, color, typography, annotations, accessibility, ...)
 - \`bpc://guide/{slug}\` — Blueprint Chart guides (scenes, palettes, data-transforms, ...)
-- \`bpc://chart-types/{slug}\` — per-chart-type docs
-- \`bpc://samples/{id}\` — canonical \`.bpc\` examples
+- \`bpc://chart-types/{slug}\` — per-chart-type docs (use \`describe_chart_type\` as a tool equivalent)
+- \`bpc://samples/{id}\` — canonical \`.bpc\` examples (use \`get_example\` as a tool equivalent)
 - \`bpc://reference/dsl/{slug}\`, \`bpc://reference/api/{slug}\` — full reference
 
 Tools:
-- \`validate_dsl({source})\` — parse, return errors with line/column
-- \`inspect_dsl({source})\` — parsed summary (chart type, scenes, series, annotations)
-- \`recommend_chart_type({columnTypes, rowCount, goal?})\` — ranked suggestions
-- \`render({source, format, scene?, width?, height?})\` — SVG (default) or PNG
+- \`validate_dsl({source})\` — parse; returns \`{ valid, errors[], warnings[] }\` — each error has \`code\`, \`message\`, \`suggestion\`
+- \`inspect_dsl({source})\` — parsed summary: \`chartType\`, \`scenes\`, \`seriesCount\`, \`rowCount\`, \`hasHighlights\`, \`hasColorizes\`, etc.
+- \`recommend_chart_type({columnTypes, rowCount, goal?})\` — ranked chart-type suggestions
+- \`render({source, format, scene?, width?, height?})\` — SVG (default) or PNG; \`errors[]\` on failure (each has \`code\` + \`suggestion\`)
+- \`list_chart_types()\` — list all renderable chart types (tool equivalent of \`bpc://handbook/choosing\`)
+- \`describe_chart_type({name})\` — properties, when-to-use, data-shape for one chart type (tool equivalent of \`bpc://chart-types/{slug}\`)
+- \`get_example({chartType?, name?})\` — fetch a canonical \`.bpc\` sample (tool equivalent of \`bpc://samples/{id}\`)
+- \`get_grammar()\` — full DSL syntax reference (tool equivalent of \`bpc://grammar\`)
+- \`export_chart({source})\` — validate then return \`{ copyUrl, embedUrl, frame }\` shareable editor URLs (returns \`E_CONFIG\` if the server has no editor URL configured)
 
 Be patient with errors — the feedback loop is the point.`;
 export function authorChartPrompt() {

package/dist/prompts/authorChart.test.js

@@ -10,4 +10,10 @@ describe('authorChartPrompt', () => {
         expect(first.content.text).toMatch(/bpc:\/\/grammar/);
         expect(first.content.text).toMatch(/validate_dsl/);
     });
+    it('mentions export_chart and the export step', () => {
+        const prompt = authorChartPrompt();
+        const text = prompt.messages[0].content.text;
+        expect(text).toContain('export_chart');
+        expect(text).toMatch(/copyUrl/);
+    });
 });

package/dist/render/diagnose.d.ts

@@ -0,0 +1,19 @@
+export type RenderDiagnosticCode = 'E_PARSE' | 'E_UNKNOWN_CHART_TYPE' | 'E_NO_DATA' | 'E_NO_RESOLVED_SERIES' | 'E_UNKNOWN_SCENE_INDEX' | 'E_UNRESOLVED_COLORIZE' | 'E_UNRESOLVED_HIGHLIGHT';
+export interface RenderDiagnostic {
+    code: RenderDiagnosticCode;
+    path: string;
+    message: string;
+    context?: Record<string, unknown>;
+    suggestion?: string;
+}
+export interface DiagnoseOptions {
+    sceneIndex?: number;
+}
+type DiagnoseResult = {
+    ok: true;
+} | {
+    ok: false;
+    diagnostics: RenderDiagnostic[];
+};
+export declare function diagnoseRender(source: string, opts?: DiagnoseOptions): DiagnoseResult;
+export {};

package/dist/render/diagnose.js

@@ -0,0 +1,100 @@
+import { parse, astToDefinition, resolveScene, getChart } from '@blueprint-chart/lib';
+import { canonicalChartType, listCanonicalChartTypes } from '../dsl/chartTypes';
+import { nearestSuggestion } from '../dsl/suggest';
+function colorizeTargets(ast) {
+    return (ast.colorizes ?? []).map(c => c.target);
+}
+function highlightTargets(ast) {
+    return (ast.highlights ?? []).map(h => h.target);
+}
+export function diagnoseRender(source, opts = {}) {
+    let ast;
+    try {
+        ast = parse(source);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            diagnostics: [{
+                    code: 'E_PARSE',
+                    path: 'source',
+                    message: err instanceof Error ? err.message : String(err),
+                }],
+        };
+    }
+    const diagnostics = [];
+    // Unknown chart type — silent no-op in render-chart.ts:52-55
+    const canonical = canonicalChartType(ast.chartType);
+    if (!canonical || !getChart(canonical)) {
+        const known = listCanonicalChartTypes();
+        diagnostics.push({
+            code: 'E_UNKNOWN_CHART_TYPE',
+            path: 'chart',
+            message: `No renderer registered for chart type "${ast.chartType}".`,
+            context: { got: ast.chartType, known },
+            suggestion: nearestSuggestion(ast.chartType, known),
+        });
+        return { ok: false, diagnostics };
+    }
+    const definition = astToDefinition(ast);
+    // Empty data — silent return in render-chart.ts:25-31
+    if (definition.data.labels.length === 0) {
+        diagnostics.push({
+            code: 'E_NO_DATA',
+            path: 'data',
+            message: 'Chart has no parsed data rows. Add quoted-string labels with numeric values to the data block.',
+        });
+    }
+    // Scene index out of range
+    const sceneCount = (ast.scenes ?? []).length;
+    if (opts.sceneIndex !== undefined && opts.sceneIndex >= sceneCount) {
+        diagnostics.push({
+            code: 'E_UNKNOWN_SCENE_INDEX',
+            path: 'scene',
+            message: `Requested scene index ${opts.sceneIndex} but chart has ${sceneCount} scene(s).`,
+            context: { requested: opts.sceneIndex, availableSceneCount: sceneCount },
+        });
+    }
+    // Unresolved colorize/highlight targets
+    const labels = new Set(definition.data.labels);
+    const seriesNames = new Set();
+    for (const s of definition.data.series ?? []) {
+        if (s.name) {
+            seriesNames.add(s.name);
+        }
+    }
+    for (const target of colorizeTargets(ast)) {
+        if (!labels.has(target) && !seriesNames.has(target)) {
+            diagnostics.push({
+                code: 'E_UNRESOLVED_COLORIZE',
+                path: 'colorize',
+                message: `colorize "${target}" does not match any data label or series name.`,
+                context: { target, availableLabels: [...labels], availableSeries: [...seriesNames] },
+                suggestion: nearestSuggestion(target, [...labels, ...seriesNames]),
+            });
+        }
+    }
+    for (const target of highlightTargets(ast)) {
+        if (!labels.has(target) && !seriesNames.has(target)) {
+            diagnostics.push({
+                code: 'E_UNRESOLVED_HIGHLIGHT',
+                path: 'highlight',
+                message: `highlight "${target}" does not match any data label or series name.`,
+                context: { target, availableLabels: [...labels], availableSeries: [...seriesNames] },
+                suggestion: nearestSuggestion(target, [...labels, ...seriesNames]),
+            });
+        }
+    }
+    // Resolve scene (defensive — surfaces internal errors)
+    try {
+        resolveScene(definition, opts.sceneIndex);
+    }
+    catch (err) {
+        diagnostics.push({
+            code: 'E_NO_RESOLVED_SERIES',
+            path: 'scene',
+            message: `Failed to resolve scene state: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    return diagnostics.length === 0 ? { ok: true } : { ok: false, diagnostics };
+}

package/dist/render/diagnose.test.d.ts

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

package/dist/render/diagnose.test.js

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { samples } from '@blueprint-chart/lib';
+import { diagnoseRender } from './diagnose';
+describe('diagnoseRender', () => {
+    it('returns ok for every shipped sample', () => {
+        for (const s of samples) {
+            const r = diagnoseRender(s.dsl);
+            expect(r.ok, `sample ${s.id}: ${JSON.stringify(r)}`).toBe(true);
+        }
+    });
+    it('reports E_UNKNOWN_CHART_TYPE for chart bar', () => {
+        const r = diagnoseRender('chart bar { data { "E" = 1 } }');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            const issue = r.diagnostics.find(d => d.code === 'E_UNKNOWN_CHART_TYPE');
+            expect(issue).toBeDefined();
+            expect(issue.suggestion).toMatch(/^bar-/);
+        }
+    });
+    it('reports E_NO_DATA when data is empty', () => {
+        const r = diagnoseRender('chart bar-vertical {}');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.diagnostics.some(d => d.code === 'E_NO_DATA')).toBe(true);
+        }
+    });
+    it('reports E_UNKNOWN_SCENE_INDEX when sceneIndex is out of range', () => {
+        const r = diagnoseRender('chart bar-vertical { data { "E" = 1 } }', { sceneIndex: 5 });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            const issue = r.diagnostics.find(d => d.code === 'E_UNKNOWN_SCENE_INDEX');
+            expect(issue).toBeDefined();
+            expect(issue.context?.availableSceneCount).toBe(0);
+        }
+    });
+    it('reports E_UNRESOLVED_COLORIZE when colorize target is not a label', () => {
+        const r = diagnoseRender('chart bar-vertical { data { "E" = 1 } colorize "Z" { color = "red" } }');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            const issue = r.diagnostics.find(d => d.code === 'E_UNRESOLVED_COLORIZE');
+            expect(issue).toBeDefined();
+            expect(issue.context?.target).toBe('Z');
+            expect(issue.context?.availableLabels).toEqual(['E']);
+        }
+    });
+    it('reports E_PARSE on malformed source', () => {
+        const r = diagnoseRender('@@@ not valid');
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.diagnostics[0].code).toBe('E_PARSE');
+        }
+    });
+});

package/dist/render/frame.d.ts

@@ -0,0 +1,10 @@
+import type { ChartNode } from '@blueprint-chart/lib';
+export interface FrameMetadata {
+    title?: string;
+    description?: string;
+    byline?: string;
+    source?: string;
+    sourceUrl?: string;
+    note?: string;
+}
+export declare function extractFrameMetadata(ast: ChartNode): FrameMetadata;

package/dist/render/frame.js

@@ -0,0 +1,10 @@
+const FRAME_KEYS = ['title', 'description', 'byline', 'source', 'sourceUrl', 'note'];
+export function extractFrameMetadata(ast) {
+    const frame = {};
+    for (const prop of ast.properties ?? []) {
+        if (FRAME_KEYS.includes(prop.key)) {
+            frame[prop.key] = String(prop.value).replace(/^"|"$/g, '');
+        }
+    }
+    return frame;
+}

package/dist/render/frame.test.d.ts

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

package/dist/render/frame.test.js

@@ -0,0 +1,12 @@
+import { describe, it, expect } from 'vitest';
+import { parse } from '@blueprint-chart/lib';
+import { extractFrameMetadata } from './frame';
+describe('extractFrameMetadata', () => {
+    it('pulls frame keys off the chart AST and strips surrounding quotes', () => {
+        const ast = parse('chart bar-vertical {\n  title = "Hi"\n  source = "ICIJ"\n  data {\n    "A" = 1\n  }\n}\n');
+        const frame = extractFrameMetadata(ast);
+        expect(frame.title).toBe('Hi');
+        expect(frame.source).toBe('ICIJ');
+        expect(frame.byline).toBeUndefined();
+    });
+});

package/dist/render/jsdomEnv.d.ts

@@ -2,7 +2,8 @@ import { type DOMWindow } from 'jsdom';
 export interface JsdomEnv {
     window: DOMWindow;
     container: HTMLElement;
-    serialize: () => string;
+    serializeSvg: () => string;
+    serializeFrame: () => string | undefined;
     cleanup: () => void;
 }
 export interface JsdomEnvOptions {

package/dist/render/jsdomEnv.js

@@ -19,10 +19,23 @@ export function createJsdomEnv(opts) {
     return {
         window: dom.window,
         container,
-        serialize: () => {
+        serializeSvg: () => {
+            // When thumbnail=false the lib wraps the SVG in a div.bc-frame. The chart
+            // SVG lives inside div.bc-frame-body. Extract it precisely so we don't
+            // accidentally grab the small logo SVG in the footer.
+            const frameBody = container.querySelector('.bc-frame-body');
+            if (frameBody) {
+                const svg = frameBody.querySelector('svg');
+                return svg ? svg.outerHTML : '';
+            }
+            // Fallback for bare renders (no frame): grab the direct SVG.
             const svg = container.querySelector('svg');
             return svg ? svg.outerHTML : '';
         },
+        serializeFrame: () => {
+            const frame = container.querySelector('.bc-frame');
+            return frame ? frame.outerHTML : undefined;
+        },
         cleanup: () => dom.window.close(),
     };
 }