@blueprint-chart/mcp 0.1.1 → 0.1.3

package/dist/dsl/validate.test.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { parse, samples } from '@blueprint-chart/lib';
+import { validateAst } from './validate';
+function ast(src) {
+    return parse(src);
+}
+describe('validateAst', () => {
+    it('returns empty issues for a known chart type with data', () => {
+        const a = ast('chart bar-vertical { data { "E" = 1 } }');
+        expect(validateAst(a)).toEqual([]);
+    });
+    it('reports E_UNKNOWN_CHART_TYPE with suggestion', () => {
+        const a = ast('chart bar { data { "E" = 1 } }');
+        const issues = validateAst(a);
+        expect(issues.length).toBeGreaterThanOrEqual(1);
+        const chartIssue = issues.find(i => i.code === 'E_UNKNOWN_CHART_TYPE');
+        expect(chartIssue).toBeDefined();
+        expect(chartIssue.path).toBe('chart');
+        expect(chartIssue.suggestion).toMatch(/^bar-/);
+        expect(chartIssue.context?.got).toBe('bar');
+        expect(Array.isArray(chartIssue.context?.known)).toBe(true);
+    });
+    it('reports E_EMPTY_DATA when data block is missing', () => {
+        const a = ast('chart bar-vertical { title = "x" }');
+        const issues = validateAst(a);
+        expect(issues.some(i => i.code === 'E_EMPTY_DATA')).toBe(true);
+    });
+    it('reports E_EMPTY_DATA when data block has zero entries', () => {
+        const a = ast('chart bar-vertical { data {} }');
+        const issues = validateAst(a);
+        expect(issues.some(i => i.code === 'E_EMPTY_DATA')).toBe(true);
+    });
+    it('does not double-report when chart type is unknown but data is fine', () => {
+        const a = ast('chart bar { data { "E" = 1 } }');
+        const issues = validateAst(a);
+        expect(issues.find(i => i.code === 'E_EMPTY_DATA')).toBeUndefined();
+    });
+});
+describe('validateAst — properties and data keys', () => {
+    it('reports E_UNKNOWN_PROPERTY for an unknown chart-level key', () => {
+        const a = ast('chart bar-vertical { totallyMadeUp = 1  data { "E" = 1 } }');
+        const issues = validateAst(a);
+        const unk = issues.find(i => i.code === 'E_UNKNOWN_PROPERTY');
+        expect(unk).toBeDefined();
+        expect(unk.context?.got).toBe('totallyMadeUp');
+    });
+    it('does not report a known per-chart-type property as unknown', () => {
+        const a = ast('chart bar-vertical { barGap = 0.2  data { "E" = 1 } }');
+        expect(validateAst(a).filter(i => i.code === 'E_UNKNOWN_PROPERTY')).toEqual([]);
+    });
+    it('does not report a known universal property as unknown', () => {
+        const a = ast('chart bar-vertical { title = "x"  data { "E" = 1 } }');
+        expect(validateAst(a).filter(i => i.code === 'E_UNKNOWN_PROPERTY')).toEqual([]);
+    });
+    it('suggests a near-miss universal property', () => {
+        const a = ast('chart bar-vertical { titl = "x"  data { "E" = 1 } }');
+        const issues = validateAst(a);
+        const unk = issues.find(i => i.code === 'E_UNKNOWN_PROPERTY');
+        expect(unk?.suggestion).toBe('title');
+    });
+    it('reports E_UNKNOWN_DATA_KEY for unquoted-identifier data keys when chart expects labels', () => {
+        const a = ast('chart bar-vertical { data { unquotedKey = 1 } }');
+        const issues = validateAst(a);
+        expect(issues.some(i => i.code === 'E_UNKNOWN_DATA_KEY')).toBe(true);
+    });
+    it('roundtrips every shipped sample with no errors', () => {
+        for (const sample of samples) {
+            const a = ast(sample.dsl);
+            const issues = validateAst(a);
+            expect(issues, `sample ${sample.id}: ${JSON.stringify(issues)}`).toEqual([]);
+        }
+    });
+});

package/dist/errors.d.ts

@@ -3,15 +3,32 @@ export declare const ErrorCode: {
     readonly E_PARSE: "E_PARSE";
     readonly E_SEMANTIC: "E_SEMANTIC";
     readonly E_RENDER: "E_RENDER";
+    readonly E_CONFIG: "E_CONFIG";
     readonly E_INTERNAL: "E_INTERNAL";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 export interface ToolErrorEntry {
+    /**
+     * Item-level error code in `E_XXX` shape.
+     *
+     * Intentionally typed as `string` rather than the `ErrorCode` enum.
+     * Item-level codes are driven by the context that produced the error:
+     * - validation errors use `ValidationCode` values (e.g. `'E_UNKNOWN_PROPERTY'`)
+     * - render pre-flight uses `RenderDiagnosticCode` values (e.g. `'E_NO_DATA'`)
+     * - individual tools may define their own codes (e.g. `'E_UNKNOWN_SAMPLE'`)
+     *
+     * These codes differ from the top-level `ToolResult.code` field, which always
+     * uses the `ErrorCode` enum and categorises the failure class (parse, input,
+     * render, etc.). Item-level codes do not need to be enumerated here.
+     */
+    code?: string;
     path?: string;
     line?: number;
     column?: number;
     message: string;
     snippet?: string;
+    context?: Record<string, unknown>;
+    suggestion?: string;
 }
 export type ToolResult<T> = {
     ok: true;
@@ -22,7 +39,9 @@ export type ToolResult<T> = {
     errors: ToolErrorEntry[];
 };
 export declare function toolOk<T>(data: T): ToolResult<T>;
-export declare function toolError<T = never>(code: ErrorCode, errors: ToolErrorEntry[]): ToolResult<T>;
+export declare function toolError<T = never>(code: ErrorCode, errors: ToolErrorEntry[]): Extract<ToolResult<T>, {
+    ok: false;
+}>;
 export declare function isToolError<T>(r: ToolResult<T>): r is Extract<ToolResult<T>, {
     ok: false;
 }>;

package/dist/errors.js

@@ -3,6 +3,7 @@ export const ErrorCode = {
     E_PARSE: 'E_PARSE',
     E_SEMANTIC: 'E_SEMANTIC',
     E_RENDER: 'E_RENDER',
+    E_CONFIG: 'E_CONFIG',
     E_INTERNAL: 'E_INTERNAL',
 };
 export function toolOk(data) {

package/dist/errors.test.js

@@ -20,4 +20,25 @@ describe('errors', () => {
         const r = toolError(ErrorCode.E_INTERNAL, [{ message: 'x' }]);
         expect(isToolError(r)).toBe(true);
     });
+    it('includes E_CONFIG for missing server configuration', () => {
+        expect(ErrorCode.E_CONFIG).toBe('E_CONFIG');
+    });
+});
+describe('ToolErrorEntry structured fields', () => {
+    it('accepts code, context, and suggestion on a tool-error entry', () => {
+        const entry = {
+            code: 'E_UNKNOWN_CHART_TYPE',
+            path: 'chart',
+            message: 'Unknown chart type "bar"',
+            context: { got: 'bar', knownTypes: ['bar-vertical'] },
+            suggestion: 'bar-vertical',
+        };
+        const r = toolError(ErrorCode.E_SEMANTIC, [entry]);
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.errors[0].code).toBe('E_UNKNOWN_CHART_TYPE');
+            expect(r.errors[0].context).toEqual({ got: 'bar', knownTypes: ['bar-vertical'] });
+            expect(r.errors[0].suggestion).toBe('bar-vertical');
+        }
+    });
 });

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/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 {};