@blueprint-chart/mcp 0.1.3 → 0.1.4

package/README.md

@@ -17,7 +17,7 @@
 
 </div>
 
-The MCP exposes Blueprint Chart's dataviz handbook, DSL grammar reference, chart-type docs, and canonical samples as MCP resources, plus eight deterministic tools: `validate_dsl`, `inspect_dsl`, `recommend_chart_type`, `render`, `list_chart_types`, `describe_chart_type`, `get_example`, and `get_grammar`. Your LLM writes the `.bpc`; the MCP grounds it in real dataviz pedagogy and gives it a tight feedback loop.
+The MCP exposes Blueprint Chart's dataviz handbook, DSL grammar reference, chart-type docs, and canonical samples as MCP resources, plus eleven deterministic tools: `validate_dsl`, `inspect_dsl`, `recommend_chart_type`, `render`, `list_chart_types`, `describe_chart_type`, `get_example`, `get_grammar`, `export_chart`, `search_examples`, and `list_palettes`. Your LLM writes the `.bpc`; the MCP grounds it in real dataviz pedagogy and gives it a tight feedback loop.
 
 ## Install
 
@@ -57,13 +57,16 @@ claude mcp add blueprint-chart \
 | `validate_dsl` | Parse `.bpc`; returns `{ valid, errors[], warnings[] }` — each error has `code`, `message`, `suggestion` |
 | `inspect_dsl` | Parse and summarize: `chartType`, `scenes`, `seriesCount`, `rowCount`, `hasHighlights`, `hasColorizes`, etc. |
 | `recommend_chart_type` | Rank chart types for a given column shape and row count |
-| `render` | Render to SVG (default) or PNG; structured `errors[]` (each with `code` + `suggestion`) on failure |
+| `render` | Render to SVG (default), PNG, or HTML; always returns structured frame metadata, with structured `errors[]` (each with `code` + `suggestion`) on failure. Pass `save: <path>` to write the output to disk (requires `MCP_ALLOW_FS_WRITE=1`) |
 | `list_chart_types` | List all renderable chart types (tool equivalent of `bpc://handbook/choosing`) |
-| `describe_chart_type` | Properties, when-to-use, and data-shape for one chart type (tool equivalent of `bpc://chart-types/{slug}`) |
+| `describe_chart_type` | Properties, when-to-use, when-NOT-to-use, and data-shape for one chart type (tool equivalent of `bpc://chart-types/{slug}`) |
 | `get_example` | Fetch a canonical `.bpc` sample by chart type or sample name (tool equivalent of `bpc://samples/{id}`) |
+| `search_examples` | Find canonical examples by topic keywords and/or chart type (returns pointers; fetch full DSL with `get_example`) |
 | `get_grammar` | Full DSL syntax reference (tool equivalent of `bpc://grammar`) |
+| `list_palettes` | List named colour palettes with hex colours for `colorPalette` |
+| `export_chart` | Validate a `.bpc` and return shareable editor URLs — an editable `copyUrl` and a read-only `embedUrl` for iframes (requires `BLUEPRINT_CHART_EDITOR_URL`) |
 
-The four discovery tools (`list_chart_types`, `describe_chart_type`, `get_example`, `get_grammar`) let clients without MCP resource support access the same reference material that the `bpc://` URIs expose.
+The discovery tools (`list_chart_types`, `describe_chart_type`, `get_example`, `search_examples`, `get_grammar`, `list_palettes`) let clients without MCP resource support access the same reference material that the `bpc://` URIs expose.
 
 ## Resources
 
@@ -208,7 +211,7 @@ Response:
 }
 ```
 
-### `render` — SVG (default) or PNG
+### `render` — SVG (default), PNG, or HTML
 
 Request:
 

package/dist/dsl/capabilityMatrix.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Per-(chartType × key) capability metadata. `key` is a chart property OR a
+ * directive name (`highlight`, `colorize`, `annotation`, `transform`, `scene`).
+ *
+ * Phase 1: this matrix is MCP-local, seeded from the authoring usability test
+ * (test-results/mcp-authoring-report.md). Phase 2 promotes it into
+ * @blueprint-chart/lib as renderer-verified metadata; the MCP then consumes
+ * lib's matrix and deletes this file.
+ *
+ * Design: DEFAULT every cell to { applicable: true, implemented: true }
+ * ("supported") and list ONLY non-default cells in OVERRIDES. This keeps
+ * warnings high-precision (no false positives on the 34 bundled samples) and
+ * means a new chart type needs zero matrix edits to avoid spurious warnings.
+ */
+export interface CapabilityCell {
+    applicable: boolean;
+    implemented: boolean;
+    note?: string;
+}
+export type CapabilityStatus = 'supported' | 'not-implemented' | 'inapplicable';
+export declare function statusOf(cell: CapabilityCell): CapabilityStatus;
+export declare function lookupCapability(chartType: string, key: string): CapabilityCell;

package/dist/dsl/capabilityMatrix.js

@@ -0,0 +1,37 @@
+const SUPPORTED = Object.freeze({ applicable: true, implemented: true });
+export function statusOf(cell) {
+    if (!cell.applicable) {
+        return 'inapplicable';
+    }
+    if (!cell.implemented) {
+        return 'not-implemented';
+    }
+    return 'supported';
+}
+const OVERRIDES = {
+    donut: {
+        sort: { applicable: false, implemented: false, note: 'Slice order on a donut follows data order; use a `transform sort` on the data instead.' },
+        sortMode: { applicable: false, implemented: false, note: 'sortMode applies to grouped/stacked charts, not donut.' },
+        valueLabels: { applicable: false, implemented: false, note: 'Donut shows slice labels; use `displayAsPercentage` / `tooltips` instead of valueLabels.' },
+    },
+    pie: {
+        sort: { applicable: false, implemented: false, note: 'Slice order on a pie follows data order; use a `transform sort` on the data instead.' },
+        sortMode: { applicable: false, implemented: false, note: 'sortMode applies to grouped/stacked charts, not pie.' },
+        valueLabels: { applicable: false, implemented: false, note: 'Pie shows slice labels; use `tooltips` / `displayAsPercentage` instead of valueLabels.' },
+    },
+    // Single-series line/area are one path with no per-series/per-category marks.
+    // `highlight` (dim others) and `colorize` (recolour a target) both need a
+    // target to act on, so they are inapplicable here — they work on the
+    // multi-series variants (line-multi / area-stacked), which default supported.
+    line: {
+        highlight: { applicable: false, implemented: false, note: 'highlight dims other series/categories; a single-series line has nothing to dim. Use an `annotation` to call out a point, or `line-multi` for multiple series.' },
+        colorize: { applicable: false, implemented: false, note: 'colorize recolours a named series/category; a single-series line has no target. Use `colorPalette` / `colors`, or `line-multi` for multiple series.' },
+    },
+    area: {
+        highlight: { applicable: false, implemented: false, note: 'highlight dims other series/categories; a single-series area has nothing to dim. Use an `annotation` to call out a point, or `area-stacked` for multiple series.' },
+        colorize: { applicable: false, implemented: false, note: 'colorize recolours a named series/category; a single-series area has no target. Use `colorPalette` / `colors`, or `area-stacked` for multiple series.' },
+    },
+};
+export function lookupCapability(chartType, key) {
+    return OVERRIDES[chartType]?.[key] ?? SUPPORTED;
+}

package/dist/dsl/capabilityMatrix.test.d.ts

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

package/dist/dsl/capabilityMatrix.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { samples } from '@blueprint-chart/lib';
+import { canonicalChartType } from './chartTypes';
+import { lookupCapability, statusOf } from './capabilityMatrix';
+describe('capabilityMatrix', () => {
+    it('defaults unknown cells to supported', () => {
+        expect(statusOf(lookupCapability('bar-vertical', 'title'))).toBe('supported');
+        expect(statusOf(lookupCapability('bar-vertical', 'some-unknown-key'))).toBe('supported');
+    });
+    it('marks sort on donut as inapplicable with a note', () => {
+        const cell = lookupCapability('donut', 'sort');
+        expect(statusOf(cell)).toBe('inapplicable');
+        expect(cell.note).toBeTruthy();
+    });
+    it('marks colorize supported on donut/pie (W1c shipped per-slice colorize)', () => {
+        expect(statusOf(lookupCapability('donut', 'colorize'))).toBe('supported');
+        expect(statusOf(lookupCapability('pie', 'colorize'))).toBe('supported');
+    });
+    it('marks colorize inapplicable on single-series line/area, supported on multi-series (W1c)', () => {
+        expect(statusOf(lookupCapability('line', 'colorize'))).toBe('inapplicable');
+        expect(lookupCapability('line', 'colorize').note).toBeTruthy();
+        expect(statusOf(lookupCapability('area', 'colorize'))).toBe('inapplicable');
+        expect(statusOf(lookupCapability('line-multi', 'colorize'))).toBe('supported');
+        expect(statusOf(lookupCapability('bar-multi', 'colorize'))).toBe('supported');
+    });
+    it('marks highlight inapplicable on single-series line/area, supported on multi-series (W1b)', () => {
+        expect(statusOf(lookupCapability('line', 'highlight'))).toBe('inapplicable');
+        expect(lookupCapability('line', 'highlight').note).toBeTruthy();
+        expect(statusOf(lookupCapability('area', 'highlight'))).toBe('inapplicable');
+        // multi-series variants got highlight dimming in W1b → default supported
+        expect(statusOf(lookupCapability('line-multi', 'highlight'))).toBe('supported');
+        expect(statusOf(lookupCapability('area-stacked', 'highlight'))).toBe('supported');
+        expect(statusOf(lookupCapability('donut', 'highlight'))).toBe('supported');
+    });
+    it('does not flag any bundled sample property as inapplicable', () => {
+        const offenders = [];
+        for (const s of samples) {
+            const type = canonicalChartType(s.chartType) ?? s.chartType;
+            // matches bare-word "key =" property assignments (the only form bundled samples use)
+            const keys = Array.from(s.dsl.matchAll(/^\s*([A-Za-z][A-Za-z0-9]*)\s*=/gm)).map(m => m[1]);
+            for (const key of keys) {
+                if (statusOf(lookupCapability(type, key)) === 'inapplicable') {
+                    offenders.push(`${s.id} (${type}): ${key}`);
+                }
+            }
+        }
+        expect(offenders).toEqual([]);
+    });
+});

package/dist/dsl/goalRanking.d.ts

@@ -0,0 +1,7 @@
+import type { ChartRecommendation } from '@blueprint-chart/lib';
+/**
+ * Re-rank lib's recommendations using the goal string. Returns a new array;
+ * never mutates the input. `rowCount` (when provided) enables a pie-before-donut
+ * tiebreak for very small slice counts.
+ */
+export declare function applyGoalReranking(recs: ChartRecommendation[], goal: string | undefined, rowCount?: number): ChartRecommendation[];

package/dist/dsl/goalRanking.js

@@ -0,0 +1,76 @@
+/**
+ * Goal keyword → chart types that goal favours, classified `strong` or `weak`.
+ *
+ * STRONG rules name a goal that implies a different chart *family* (part-to-whole,
+ * composition-over-time, range) and so may override lib's column-type "best".
+ * WEAK rules are narrative framings (trend, crossover, rank) that only break ties
+ * among non-best candidates — they must NOT demote lib's structurally-best pick.
+ * (Without this distinction the "overtakes" keyword wrongly boosted line-multi
+ * above the correct bar-multi for quarterly-revenue.)
+ *
+ * Used as a re-ranking layer ON TOP of lib's column-type/row-count ranking;
+ * lib's `recommendCharts` ignores the goal string entirely.
+ */
+const GOAL_RULES = [
+    { pattern: /\b(share|part[- ]to[- ]whole|proportion|percentage of (the )?total|breakdown|make up)\b/i, types: ['pie', 'donut', 'bar-stacked', 'column-stacked'], strong: true },
+    { pattern: /(?:\b(?:composition|mix|stacked).*(?:over time|by year|trend)|\b(?:over time|by year).*(?:composition|mix))\b/i, types: ['area-stacked', 'column-stacked'], strong: true },
+    { pattern: /\b(over time|trend|grew|rose|fell|climbed|change over|year[- ]over[- ]year)\b/i, types: ['line', 'line-multi', 'area'], strong: false },
+    { pattern: /\b(overtak\w*|overtook|crossover|surpass|cross over|catch[- ]up|diverg\w*)/i, types: ['line-multi', 'line'], strong: false },
+    { pattern: /\b(rank|ranked|more than|compared|top \d+|most|largest|biggest)\b/i, types: ['bar-vertical', 'bar-horizontal'], strong: false },
+    { pattern: /\b(range|high and low|high\/low|margin of error|confidence|interval|plus or minus)\b/i, types: ['bar-split'], strong: true },
+];
+/**
+ * Re-rank lib's recommendations using the goal string. Returns a new array;
+ * never mutates the input. `rowCount` (when provided) enables a pie-before-donut
+ * tiebreak for very small slice counts.
+ */
+export function applyGoalReranking(recs, goal, rowCount) {
+    if (!goal || goal.trim() === '') {
+        return recs;
+    }
+    const strongBoost = new Set();
+    const weakBoost = new Set();
+    for (const rule of GOAL_RULES) {
+        if (rule.pattern.test(goal)) {
+            const target = rule.strong ? strongBoost : weakBoost;
+            for (const t of rule.types) {
+                target.add(t);
+            }
+        }
+    }
+    // No-match contract: if nothing matched, return unchanged WITHOUT running the
+    // tier sort — otherwise tier 1 (lib "best") would float ahead of a lib-higher
+    // "good" even when the author gave no usable goal.
+    if (strongBoost.size === 0 && weakBoost.size === 0) {
+        return recs;
+    }
+    // Tier: strong-boosted (0) → lib "best" (1) → weak-boosted (2) → rest (3).
+    const tierOf = (rec) => {
+        if (strongBoost.has(rec.chartType)) {
+            return 0;
+        }
+        if (rec.fitness === 'best') {
+            return 1;
+        }
+        if (weakBoost.has(rec.chartType)) {
+            return 2;
+        }
+        return 3;
+    };
+    const sorted = recs
+        .map((rec, index) => ({ rec, index, tier: tierOf(rec) }))
+        // tier ascending; within a tier preserve lib's original order (stable)
+        .sort((a, b) => (a.tier === b.tier ? a.index - b.index : a.tier - b.tier))
+        .map(x => x.rec);
+    // Pie suits very small N; for ≤5 slices prefer pie over donut when both are
+    // present (and pie currently trails donut). Larger N keeps lib's donut order.
+    if (rowCount !== undefined && rowCount <= 5) {
+        const donutIdx = sorted.findIndex(r => r.chartType === 'donut');
+        const pieIdx = sorted.findIndex(r => r.chartType === 'pie');
+        if (donutIdx !== -1 && pieIdx !== -1 && pieIdx > donutIdx) {
+            const [pieRec] = sorted.splice(pieIdx, 1);
+            sorted.splice(donutIdx, 0, pieRec);
+        }
+    }
+    return sorted;
+}

package/dist/dsl/goalRanking.test.d.ts

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

package/dist/dsl/goalRanking.test.js

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+import { applyGoalReranking } from './goalRanking';
+const recs = [
+    { chartType: 'bar-vertical', label: 'Bar', fitness: 'best', reason: 'r' },
+    { chartType: 'donut', label: 'Donut', fitness: 'good', reason: 'r' },
+    { chartType: 'pie', label: 'Pie', fitness: 'alternative', reason: 'r' },
+    { chartType: 'area-stacked', label: 'Area stacked', fitness: 'alternative', reason: 'r' },
+];
+describe('applyGoalReranking', () => {
+    it('returns input unchanged when goal is undefined', () => {
+        expect(applyGoalReranking(recs, undefined)).toEqual(recs);
+    });
+    it('promotes part-to-whole types for a "share of total" goal', () => {
+        const out = applyGoalReranking(recs, 'show each region as a share of the total population');
+        expect(['pie', 'donut']).toContain(out[0].chartType);
+    });
+    it('promotes area-stacked for a "composition over time" goal', () => {
+        const out = applyGoalReranking(recs, 'composition of energy sources over time');
+        expect(out[0].chartType).toBe('area-stacked');
+    });
+    it('keeps original order when no keyword matches', () => {
+        const out = applyGoalReranking(recs, 'just some unrelated text');
+        expect(out.map(r => r.chartType)).toEqual(recs.map(r => r.chartType));
+    });
+    it('keeps lib "best" bar-multi ahead of a narrative-boosted line-multi (quarterly-revenue)', () => {
+        const r = [
+            { chartType: 'line-multi', label: 'Multi-Line', fitness: 'good', reason: 'r' },
+            { chartType: 'bar-multi', label: 'Grouped Bar', fitness: 'best', reason: 'r' },
+        ];
+        const out = applyGoalReranking(r, 'software overtakes hardware as the top revenue driver', 6);
+        expect(out[0].chartType).toBe('bar-multi');
+        expect(out[1].chartType).toBe('line-multi');
+    });
+    it('promotes pie ahead of donut for a part-to-whole goal at very small N (world-population)', () => {
+        const r = [
+            { chartType: 'donut', label: 'Donut', fitness: 'good', reason: 'r' },
+            { chartType: 'pie', label: 'Pie', fitness: 'alternative', reason: 'r' },
+            { chartType: 'bar-vertical', label: 'Bar', fitness: 'best', reason: 'r' },
+            { chartType: 'bar-horizontal', label: 'HBar', fitness: 'good', reason: 'r' },
+        ];
+        const out = applyGoalReranking(r, 'Asia is nearly 60% of the world population; share of total', 5);
+        expect(out[0].chartType).toBe('pie');
+        expect(out.map(x => x.chartType)).toEqual(['pie', 'donut', 'bar-vertical', 'bar-horizontal']);
+    });
+    it('leaves lib "best" bar-vertical #1 for a ranked-comparison goal (co2-emissions)', () => {
+        const r = [
+            { chartType: 'bar-vertical', label: 'Bar', fitness: 'best', reason: 'r' },
+            { chartType: 'bar-horizontal', label: 'HBar', fitness: 'good', reason: 'r' },
+            { chartType: 'donut', label: 'Donut', fitness: 'good', reason: 'r' },
+            { chartType: 'pie', label: 'Pie', fitness: 'alternative', reason: 'r' },
+        ];
+        const out = applyGoalReranking(r, 'China emits more than the US and India combined; ranked', 6);
+        expect(out.map(x => x.chartType)).toEqual(['bar-vertical', 'bar-horizontal', 'donut', 'pie']);
+    });
+    it('promotes bar-split to #1 for a range / high-low goal (election-polls)', () => {
+        const r = [
+            { chartType: 'bar-multi', label: 'Grouped Bar', fitness: 'best', reason: 'r' },
+            { chartType: 'bar-split', label: 'Split Bar', fitness: 'good', reason: 'r' },
+            { chartType: 'line-multi', label: 'Multi-Line', fitness: 'alternative', reason: 'r' },
+        ];
+        const out = applyGoalReranking(r, 'each party has a high and low estimate; a polling range', 6);
+        expect(out[0].chartType).toBe('bar-split');
+    });
+    it('does NOT apply the pie tiebreak for larger N', () => {
+        const r = [
+            { chartType: 'donut', label: 'Donut', fitness: 'good', reason: 'r' },
+            { chartType: 'pie', label: 'Pie', fitness: 'alternative', reason: 'r' },
+            { chartType: 'bar-vertical', label: 'Bar', fitness: 'best', reason: 'r' },
+        ];
+        const out = applyGoalReranking(r, 'share of total', 12);
+        const di = out.findIndex(x => x.chartType === 'donut');
+        const pi = out.findIndex(x => x.chartType === 'pie');
+        expect(di).toBeLessThan(pi);
+    });
+    it('returns input unchanged on no-match WITHOUT floating best ahead of a lib-higher good', () => {
+        const r = [
+            { chartType: 'line-multi', label: 'Multi-Line', fitness: 'good', reason: 'r' },
+            { chartType: 'bar-multi', label: 'Grouped Bar', fitness: 'best', reason: 'r' },
+        ];
+        const out = applyGoalReranking(r, 'just some unrelated text', 6);
+        expect(out.map(x => x.chartType)).toEqual(['line-multi', 'bar-multi']);
+    });
+});

package/dist/dsl/parseErrorHints.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Translates raw PEG parser messages from @blueprint-chart/lib into plain,
+ * actionable guidance. The raw token-class messages (e.g.
+ * `Expected "\t" or [^\t\n\r{}=] but "\n" found`) were the worst-rated error
+ * in the authoring usability test — newcomers averaged 6.3 attempts-to-valid,
+ * largely stuck on data syntax. Unknown messages pass through unchanged.
+ */
+export interface HumanizedError {
+    message: string;
+    suggestion?: string;
+}
+export declare function humanizeParseError(raw: string): HumanizedError;

package/dist/dsl/parseErrorHints.js

@@ -0,0 +1,32 @@
+const RULES = [
+    {
+        // The PEG message contains the literal two-char sequence backslash-t (e.g.
+        // `Expected "\t" or [^\t\n\r{}=] ...`); \\t in this literal matches that
+        // backslash-t, not an actual tab.
+        match: /Expected .*\\t.* but .* found/,
+        message: 'A data row must be written as `"Label" = value` (a quoted label, `=`, then the value). Multiple values per row are comma-separated.',
+        suggestion: 'Single series: `"Asia" = 59.4`. Multi-series: add `_series = "Gold","Silver"` then `"USA" = 40,44`.',
+    },
+    {
+        match: /Expected whitespace but ":" found/,
+        message: 'The chart declaration uses a block, not a colon. Write `chart <type> { … }`.',
+        suggestion: 'chart donut {\n  data { "A" = 1 }\n}',
+    },
+    {
+        match: /Expected (?:"chart"|end of input)[^"]*but "d" found/,
+        message: 'The `data { … }` block must be nested inside the chart block, not at the top level.',
+        suggestion: 'chart bar-vertical {\n  data { "A" = 1 }\n}',
+    },
+    {
+        match: /Expected "=" .* but ":" found/,
+        message: 'Properties use `=`, not `:`. Write `title = "…"`.',
+    },
+];
+export function humanizeParseError(raw) {
+    for (const rule of RULES) {
+        if (rule.match.test(raw)) {
+            return { message: rule.message, suggestion: rule.suggestion };
+        }
+    }
+    return { message: raw };
+}

package/dist/dsl/parseErrorHints.test.d.ts

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

package/dist/dsl/parseErrorHints.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { humanizeParseError } from './parseErrorHints';
+describe('humanizeParseError', () => {
+    // Real lib message (with trailing period): 'Expected "\t" or [^\t\n\r{}=] but "\n" found.'
+    it('explains the tab/delimiter error for data rows', () => {
+        const h = humanizeParseError('Expected "\\t" or [^\\t\\n\\r{}=] but "\\n" found.');
+        expect(h.message).toMatch(/data row/i);
+        expect(h.suggestion).toMatch(/_series|comma/i);
+    });
+    // Real lib message (with trailing period): 'Expected whitespace but ":" found.'
+    it('explains a YAML-style chart declaration', () => {
+        const h = humanizeParseError('Expected whitespace but ":" found.');
+        expect(h.message).toMatch(/chart <type> \{/i);
+    });
+    // Real lib message: 'Expected "chart" or optional whitespace but "d" found.'
+    // (data block written at the top level, not inside a chart block)
+    it('explains data at the top level', () => {
+        const h = humanizeParseError('Expected "chart" or optional whitespace but "d" found.');
+        expect(h.message).toMatch(/inside the chart block/i);
+    });
+    it('passes unknown messages through unchanged', () => {
+        const h = humanizeParseError('something totally different');
+        expect(h.message).toBe('something totally different');
+        expect(h.suggestion).toBeUndefined();
+    });
+});

package/dist/dsl/semanticWarnings.d.ts

@@ -0,0 +1,7 @@
+import type { ChartNode } from '@blueprint-chart/lib';
+import type { ValidationIssue } from './validate';
+/** Like ValidationIssue but with a widened string `code` for the new W_* advisory codes. */
+export type WarningIssue = Omit<ValidationIssue, 'code'> & {
+    code: string;
+};
+export declare function collectWarnings(ast: ChartNode): WarningIssue[];

package/dist/dsl/semanticWarnings.js

@@ -0,0 +1,66 @@
+import { canonicalChartType } from './chartTypes';
+import { lookupCapability, statusOf } from './capabilityMatrix';
+// Chart types that REQUIRE multiple series to be meaningful.
+const MULTI_SERIES_TYPES = new Set([
+    'bar-multi',
+    'bar-grouped',
+    'bar-stacked',
+    'bar-split',
+    'column-stacked',
+    'line-multi',
+    'area-stacked',
+]);
+function checkKey(type, key, path) {
+    const cell = lookupCapability(type, key);
+    const status = statusOf(cell);
+    if (status === 'inapplicable') {
+        return {
+            code: 'W_NO_EFFECT',
+            path,
+            message: `"${key}" has no effect on a ${type} chart.${cell.note ? ' ' + cell.note : ''}`,
+        };
+    }
+    if (status === 'not-implemented') {
+        return {
+            code: 'W_NOT_IMPLEMENTED',
+            path,
+            message: `"${key}" is not yet honored by the ${type} renderer.${cell.note ? ' ' + cell.note : ''}`,
+        };
+    }
+    return undefined;
+}
+export function collectWarnings(ast) {
+    const issues = [];
+    const type = canonicalChartType(ast.chartType) ?? ast.chartType;
+    for (const prop of ast.properties ?? []) {
+        const issue = checkKey(type, prop.key, `chart.${prop.key}`);
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    if ((ast.colorizes ?? []).some(c => c.fromHighlight !== true)) {
+        const issue = checkKey(type, 'colorize', 'chart.colorize');
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    if ((ast.highlights?.length ?? 0) > 0 || (ast.colorizes ?? []).some(c => c.fromHighlight === true)) {
+        const issue = checkKey(type, 'highlight', 'chart.highlight');
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    if (MULTI_SERIES_TYPES.has(type)) {
+        const entries = ast.data?.entries ?? [];
+        const hasSeriesHeader = entries.some(e => e.key === '_series');
+        const hasMultiValueRow = entries.some(e => (e.values?.length ?? 0) > 1);
+        if (!hasSeriesHeader && !hasMultiValueRow && entries.length > 0) {
+            issues.push({
+                code: 'W_MULTISERIES_SHAPE',
+                path: 'data',
+                message: `A ${type} chart needs multiple series, but the data parsed as single-value rows with no \`_series\` header. Add a \`_series = "A","B",…\` row and comma-separated values per row (e.g. \`"USA" = 40,44,42\`).`,
+            });
+        }
+    }
+    return issues;
+}

package/dist/dsl/semanticWarnings.test.d.ts

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

package/dist/dsl/semanticWarnings.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { parseDsl } from '../parse';
+import { collectWarnings } from './semanticWarnings';
+function warn(src) {
+    const r = parseDsl(src);
+    if (!r.ok) {
+        throw new Error('parse failed: ' + JSON.stringify(r.errors));
+    }
+    return collectWarnings(r.data.ast);
+}
+describe('collectWarnings', () => {
+    it('warns W_NO_EFFECT for sort on donut', () => {
+        const w = warn('chart donut {\n  sort = descending\n  data {\n    "A" = 1\n    "B" = 2\n  }\n}');
+        expect(w.some(i => i.code === 'W_NO_EFFECT' && i.path === 'chart.sort')).toBe(true);
+    });
+    it('does not warn for colorize on donut (now supported since W1c)', () => {
+        const w = warn('chart donut {\n  data { "A" = 1 }\n  colorize "A" { color = "#f00" }\n}');
+        expect(w.some(i => i.path.includes('colorize'))).toBe(false);
+    });
+    it('warns W_MULTISERIES_SHAPE when a multi-series type parsed zero series', () => {
+        const w = warn('chart bar-multi {\n  data {\n    "A" = 1\n    "B" = 2\n  }\n}');
+        expect(w.some(i => i.code === 'W_MULTISERIES_SHAPE')).toBe(true);
+    });
+    it('is silent for a well-formed multi-series chart', () => {
+        const w = warn('chart bar-multi {\n  data {\n    _series = "X","Y"\n    "A" = 1,2\n    "B" = 3,4\n  }\n}');
+        expect(w.filter(i => i.code === 'W_MULTISERIES_SHAPE')).toEqual([]);
+    });
+    it('is silent for a clean single-series bar chart', () => {
+        const w = warn('chart bar-vertical {\n  title = "t"\n  data { "A" = 1 }\n}');
+        expect(w).toEqual([]);
+    });
+});

package/dist/dsl/suggest.js

@@ -29,7 +29,26 @@ function distance(a, b) {
     return dp[m][n];
 }
 const DEFAULT_MAX_DISTANCE = 10;
+/**
+ * Hand-curated synonyms for property keys authors commonly guess wrong but that
+ * are too edit-distant for the Levenshtein scan to catch. `subtitle` is the
+ * canonical example: authors reach for it constantly, but the real key is
+ * `description` (distance 7), so the distance scan wrongly suggests `title`.
+ */
+const SYNONYMS = {
+    subtitle: 'description',
+    subhead: 'description',
+    subheading: 'description',
+    author: 'byline',
+    credit: 'byline',
+    caption: 'note',
+    footnote: 'note',
+};
 export function nearestSuggestion(input, candidates, maxDistance = DEFAULT_MAX_DISTANCE) {
+    const synonym = SYNONYMS[input];
+    if (synonym && candidates.includes(synonym)) {
+        return synonym;
+    }
     let best;
     for (const cand of candidates) {
         const d = distance(input, cand);

package/dist/dsl/suggest.test.js

@@ -17,4 +17,18 @@ describe('nearestSuggestion', () => {
     it('handles exact match', () => {
         expect(nearestSuggestion('line', ['line', 'pie'])).toBe('line');
     });
+    it('suggests description for the common subtitle mistake', () => {
+        const keys = ['title', 'description', 'byline', 'source', 'sourceUrl', 'note'];
+        expect(nearestSuggestion('subtitle', keys)).toBe('description');
+    });
+    it('still does edit-distance matching for other typos', () => {
+        const keys = ['title', 'description', 'colorPalette'];
+        expect(nearestSuggestion('titel', keys)).toBe('title');
+    });
+    it('falls back to edit-distance when the synonym target is absent from candidates', () => {
+        const keys = ['title', 'byline', 'note']; // no 'description'
+        // subtitle's synonym (description) isn't a candidate, so the scan runs;
+        // nearest by distance among these is 'title'
+        expect(nearestSuggestion('subtitle', keys)).toBe('title');
+    });
 });

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/server.js

@@ -12,6 +12,8 @@ import { describeChartType, DescribeChartTypeInputSchema } from './tools/describ
 import { getExample, GetExampleInputSchema } from './tools/getExample';
 import { getGrammar, GetGrammarInputSchema } from './tools/getGrammar';
 import { exportChart, ExportChartInputSchema } from './tools/exportChart';
+import { searchExamples, SearchExamplesInputSchema } from './tools/searchExamples';
+import { listPalettesTool, ListPalettesInputSchema } from './tools/listPalettes';
 import { listResources, readResource } from './resources/index';
 import { authorChartPrompt } from './prompts/authorChart';
 import { zodToJsonSchema } from './lib/zodToJsonSchema';
@@ -68,6 +70,16 @@ export const TOOLS = {
         inputSchema: GetExampleInputSchema,
         handler: args => getExample(args),
     },
+    search_examples: {
+        description: 'Find canonical .bpc examples by topic keywords and/or chart type. Returns ranked pointers { id, title, description, chartType } — call get_example with an id to fetch the full DSL.',
+        inputSchema: SearchExamplesInputSchema,
+        handler: args => searchExamples(args),
+    },
+    list_palettes: {
+        description: 'List every named colour palette with its label and hex colours, for use in `colorPalette = "<name>"`.',
+        inputSchema: ListPalettesInputSchema,
+        handler: () => listPalettesTool(),
+    },
     get_grammar: {
         description: 'Return the .bpc DSL grammar as markdown. Pass { section: "chart" | "data" | "properties" | "scenes" | "annotations" } for a focused subset, or no args for the full grammar.',
         inputSchema: GetGrammarInputSchema,

package/dist/server.test.js

@@ -12,7 +12,7 @@ async function connectInMemory() {
     return { client, server };
 }
 describe('TOOLS registry', () => {
-    it('contains the nine expected tool names', () => {
+    it('contains the eleven expected tool names', () => {
         expect(Object.keys(TOOLS).sort()).toEqual([
             'describe_chart_type',
             'export_chart',
@@ -20,14 +20,16 @@ describe('TOOLS registry', () => {
             'get_grammar',
             'inspect_dsl',
             'list_chart_types',
+            'list_palettes',
             'recommend_chart_type',
             'render',
+            'search_examples',
             'validate_dsl',
         ]);
     });
 });
 describe('server', () => {
-    it('lists 9 tools', async () => {
+    it('lists 11 tools', async () => {
         const { client } = await connectInMemory();
         const r = await client.listTools();
         const names = r.tools.map(t => t.name).sort();
@@ -38,8 +40,10 @@ describe('server', () => {
             'get_grammar',
             'inspect_dsl',
             'list_chart_types',
+            'list_palettes',
             'recommend_chart_type',
             'render',
+            'search_examples',
             'validate_dsl',
         ]);
     });

package/dist/tools/describeChartType.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { type ToolResult } from '../errors';
+import { type CapabilityStatus } from '../dsl/capabilityMatrix';
 export declare const DescribeChartTypeInputSchema: z.ZodObject<{
     chartType: z.ZodString;
 }, "strict", z.ZodTypeAny, {
@@ -15,6 +16,12 @@ export interface ChartTypeProperty {
     choices?: string[];
     default?: unknown;
 }
+export interface ChartTypeDirective {
+    name: string;
+    status: CapabilityStatus;
+    description: string;
+    note?: string;
+}
 export interface ChartTypeDataShape {
     kind: 'single-series' | 'multi-series' | 'unknown';
     example: string;
@@ -26,6 +33,7 @@ export interface DescribeChartTypeOutput {
     whenToUse: string[];
     whenNotToUse: string[];
     properties: ChartTypeProperty[];
+    directives: ChartTypeDirective[];
     dataShape: ChartTypeDataShape;
     exampleSlug?: string;
     docsUrl?: string;

package/dist/tools/describeChartType.js

@@ -6,6 +6,7 @@ import { nearestSuggestion } from '../dsl/suggest';
 import { UNIVERSAL_PROPERTIES, UNIVERSAL_PROPERTY_META } from '../dsl/universalProperties';
 import { ErrorCode, toolError, toolOk } from '../errors';
 import { publicDocUrl } from '../resources/docsReader';
+import { lookupCapability, statusOf } from '../dsl/capabilityMatrix';
 export const DescribeChartTypeInputSchema = z.object({
     chartType: z.string(),
 }).strict();
@@ -81,6 +82,27 @@ function inferDataShape(name, example) {
     }
     return { kind: 'unknown', example: 'data {\n  "Label" = 1.0\n}' };
 }
+const DIRECTIVE_DOCS = [
+    { name: 'highlight', description: 'Emphasise one category/series, e.g. `highlight "China"`.' },
+    { name: 'colorize', description: 'Override colour for a category/series, e.g. `colorize "China" { color = "#f00" }`.' },
+    { name: 'annotation', description: 'Attach a callout to a data point, e.g. `annotation "2009" { text = "…" }`.' },
+    { name: 'transform', description: 'Reshape data, e.g. `transform sort { column = "value" direction = descending }`.' },
+    { name: 'scene', description: 'Add a narrative step that overrides data/properties, e.g. `scene "Step 2" { … }`.' },
+];
+function buildDirectives(canonical) {
+    return DIRECTIVE_DOCS.map((d) => {
+        const cell = lookupCapability(canonical, d.name);
+        const directive = {
+            name: d.name,
+            status: statusOf(cell),
+            description: d.description,
+        };
+        if (cell.note) {
+            directive.note = cell.note;
+        }
+        return directive;
+    });
+}
 export function describeChartType(input) {
     const parsed = DescribeChartTypeInputSchema.safeParse(input);
     if (!parsed.success) {
@@ -99,6 +121,7 @@ export function describeChartType(input) {
     }
     const doc = extractDocSections(canonical);
     const properties = buildProperties(canonical);
+    const directives = buildDirectives(canonical);
     const sample = samples.find(s => s.chartType === canonical);
     const exampleText = doc.example || sample?.dsl || '';
     const output = {
@@ -108,6 +131,7 @@ export function describeChartType(input) {
         whenToUse: doc.whenToUse,
         whenNotToUse: doc.whenNotToUse,
         properties,
+        directives,
         dataShape: inferDataShape(canonical, exampleText),
         exampleSlug: sample?.id,
     };

package/dist/tools/describeChartType.test.js

@@ -56,3 +56,23 @@ describe('describe_chart_type', () => {
         }
     });
 });
+describe('describe_chart_type directives', () => {
+    it('lists highlight/colorize/annotation directives with status', () => {
+        const r = describeChartType({ chartType: 'bar-vertical' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            const names = r.data.directives.map(d => d.name);
+            expect(names).toEqual(expect.arrayContaining(['highlight', 'colorize', 'annotation']));
+            const highlight = r.data.directives.find(d => d.name === 'highlight');
+            expect(highlight?.status).toBe('supported');
+        }
+    });
+    it('marks colorize supported on donut (W1c shipped per-slice colorize)', () => {
+        const r = describeChartType({ chartType: 'donut' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            const colorize = r.data.directives.find(d => d.name === 'colorize');
+            expect(colorize?.status).toBe('supported');
+        }
+    });
+});

package/dist/tools/getGrammar.d.ts

@@ -4,9 +4,9 @@ declare const SectionSchema: z.ZodDefault<z.ZodEnum<["all", "chart", "properties
 export declare const GetGrammarInputSchema: z.ZodObject<{
     section: z.ZodOptional<z.ZodDefault<z.ZodEnum<["all", "chart", "properties", "scenes", "annotations"]>>>;
 }, "strict", z.ZodTypeAny, {
-    section?: "chart" | "all" | "properties" | "scenes" | "annotations" | undefined;
+    section?: "chart" | "properties" | "all" | "scenes" | "annotations" | undefined;
 }, {
-    section?: "chart" | "all" | "properties" | "scenes" | "annotations" | undefined;
+    section?: "chart" | "properties" | "all" | "scenes" | "annotations" | undefined;
 }>;
 export type GetGrammarInput = z.infer<typeof GetGrammarInputSchema>;
 export interface GetGrammarOutput {

package/dist/tools/getGrammar.js

@@ -6,7 +6,7 @@ export const GetGrammarInputSchema = z.object({
     section: SectionSchema.optional(),
 }).strict();
 const SECTION_TO_SLUG = {
-    chart: 'index',
+    chart: 'properties', // reference/dsl has no standalone chart-block doc; properties.md covers the block + properties
     properties: 'properties',
     scenes: 'scenes-and-transforms',
     annotations: 'annotations',

package/dist/tools/getGrammar.test.js

@@ -22,3 +22,14 @@ describe('get_grammar', () => {
         expect(r.ok).toBe(false);
     });
 });
+describe('get_grammar section resolution', () => {
+    it('returns non-empty text for every enum section', () => {
+        for (const section of ['all', 'chart', 'properties', 'scenes', 'annotations']) {
+            const r = getGrammar({ section });
+            expect(r.ok, `section ${section} should resolve`).toBe(true);
+            if (r.ok) {
+                expect(r.data.text.length).toBeGreaterThan(0);
+            }
+        }
+    });
+});

package/dist/tools/inspect.js

@@ -20,9 +20,10 @@ function summarizeScenes(ast) {
 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 seriesValues = seriesEntry
+        ? (seriesEntry.values ?? [seriesEntry.value])
         : [];
+    const seriesNames = seriesValues.map(v => String(v).trim().replace(/^"|"$/g, ''));
     const rowEntries = entries.filter(looksLikeQuotedLabel);
     return {
         rowCount: rowEntries.length,
@@ -33,13 +34,21 @@ function summarizeData(ast) {
     };
 }
 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;
+    // `highlight "X" { … }` parses as ColorizeNode with fromHighlight:true,
+    // `highlight "X"` (no braces) parses as HighlightNode. Count both, at the
+    // chart level AND inside every scene (scenes carry their own highlights).
+    // unknown[]: only .length is read, so element type is irrelevant here
+    const countIn = (node) => {
+        const fromHighlightColorizes = (node.colorizes ?? []).filter(c => c.fromHighlight === true).length;
+        return (node.highlights?.length ?? 0) + fromHighlightColorizes;
+    };
+    const sceneTotal = (ast.scenes ?? []).reduce((sum, s) => sum + countIn(s), 0);
+    return countIn(ast) + sceneTotal;
 }
 function countNonHighlightColorizes(ast) {
-    return (ast.colorizes ?? []).filter((c) => c.fromHighlight !== true).length;
+    const countIn = (cs) => (cs ?? []).filter(c => c.fromHighlight !== true).length;
+    const sceneTotal = (ast.scenes ?? []).reduce((sum, s) => sum + countIn(s.colorizes), 0);
+    return countIn(ast.colorizes) + sceneTotal;
 }
 export function inspectDsl(input) {
     const parsed = parseDsl(input.source);

package/dist/tools/inspect.test.js

@@ -49,3 +49,30 @@ describe('inspect_dsl', () => {
         expect(r.ok).toBe(false);
     });
 });
+describe('inspect_dsl fixes', () => {
+    it('lists ALL series names from the _series header', () => {
+        const src = 'chart bar-multi {\n  data {\n    _series = "Hardware","Software","Services"\n    "Q1" = 1,2,3\n  }\n}';
+        const r = inspectDsl({ source: src });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.data.seriesNames).toEqual(['Hardware', 'Software', 'Services']);
+            expect(r.data.data.multiSeries).toBe(true);
+        }
+    });
+    it('reports hasHighlights:true when a highlight lives inside a scene', () => {
+        const src = 'chart area-stacked {\n  data {\n    _series = "A","B"\n    "2000" = 1,2\n  }\n  scene "S1" {\n    highlight "A"\n  }\n}';
+        const r = inspectDsl({ source: src });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.hasHighlights).toBe(true);
+        }
+    });
+    it('reports hasColorizes:true when a colorize lives inside a scene', () => {
+        const src = 'chart area-stacked {\n  data {\n    _series = "A","B"\n    "2000" = 1,2\n  }\n  scene "S1" {\n    colorize "A" { color = "#f00" }\n  }\n}';
+        const r = inspectDsl({ source: src });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.hasColorizes).toBe(true);
+        }
+    });
+});

package/dist/tools/listPalettes.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const ListPalettesInputSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+export type ListPalettesInput = z.infer<typeof ListPalettesInputSchema>;
+export interface PaletteSummary {
+    name: string;
+    label: string;
+    colors: string[];
+}
+export interface ListPalettesOutput {
+    palettes: PaletteSummary[];
+}
+export declare function listPalettesTool(): ToolResult<ListPalettesOutput>;

package/dist/tools/listPalettes.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { listPalettes } from '@blueprint-chart/lib';
+import { toolOk } from '../errors';
+export const ListPalettesInputSchema = z.object({}).strict();
+export function listPalettesTool() {
+    const palettes = listPalettes().map(p => ({
+        name: p.name,
+        label: p.label,
+        colors: [...p.colors],
+    }));
+    return toolOk({ palettes });
+}

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

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

package/dist/tools/listPalettes.test.js

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { listPalettesTool } from './listPalettes';
+describe('list_palettes', () => {
+    it('returns named palettes with their colours', () => {
+        const r = listPalettesTool();
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.palettes.length).toBeGreaterThan(0);
+            const first = r.data.palettes[0];
+            expect(first).toHaveProperty('name');
+            expect(Array.isArray(first.colors)).toBe(true);
+            expect(first.colors.length).toBeGreaterThan(0);
+        }
+    });
+});

package/dist/tools/recommend.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { recommendCharts } from '@blueprint-chart/lib';
+import { applyGoalReranking } from '../dsl/goalRanking';
 import { ErrorCode, toolError, toolOk } from '../errors';
 const ColumnTypeSchema = z.enum(['string', 'number', 'date']);
 export const RecommendInputSchema = z.object({
@@ -12,6 +13,7 @@ export function recommendChartType(input) {
     if (!parsed.success) {
         return toolError(ErrorCode.E_INPUT, parsed.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
     }
-    const recommendations = recommendCharts(parsed.data.columnTypes, parsed.data.rowCount);
+    const base = recommendCharts(parsed.data.columnTypes, parsed.data.rowCount);
+    const recommendations = applyGoalReranking(base, parsed.data.goal, parsed.data.rowCount);
     return toolOk({ recommendations });
 }

package/dist/tools/recommend.test.js

@@ -30,4 +30,44 @@ describe('recommend_chart_type', () => {
             expect(r.code).toBe('E_INPUT');
         }
     });
+    it('reorders toward part-to-whole when a goal says "share of total"', () => {
+        const r = recommendChartType({ columnTypes: ['string', 'number'], rowCount: 5, goal: 'each region as a share of the total' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(['pie', 'donut', 'bar-stacked', 'column-stacked']).toContain(r.data.recommendations[0]?.chartType);
+        }
+    });
+    it('keeps lib-best bar-multi ahead of a narrative-boosted line-multi', () => {
+        const r = recommendChartType({
+            columnTypes: ['string', 'number', 'number', 'number'],
+            rowCount: 6,
+            goal: 'software overtakes hardware as the top revenue driver',
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            const types = r.data.recommendations.map(x => x.chartType);
+            const barMulti = types.indexOf('bar-multi');
+            const lineMulti = types.indexOf('line-multi');
+            expect(barMulti).toBeGreaterThanOrEqual(0);
+            expect(lineMulti).toBeGreaterThanOrEqual(0);
+            expect(barMulti).toBeLessThan(lineMulti);
+        }
+    });
+    it('threads rowCount so the pie tiebreak fires for a small-N part-to-whole goal', () => {
+        const r = recommendChartType({
+            columnTypes: ['string', 'number'],
+            rowCount: 5,
+            goal: 'Asia is nearly 60% of the world population; share of total across five regions',
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            const types = r.data.recommendations.map(x => x.chartType);
+            const pieIdx = types.indexOf('pie');
+            const donutIdx = types.indexOf('donut');
+            // both should be present and boosted to the front; pie before donut at N=5
+            expect(pieIdx).toBeGreaterThanOrEqual(0);
+            expect(donutIdx).toBeGreaterThanOrEqual(0);
+            expect(pieIdx).toBeLessThan(donutIdx);
+        }
+    });
 });

package/dist/tools/searchExamples.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { type ToolResult } from '../errors';
+export declare const SearchExamplesInputSchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    chartType: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    chartType?: string | undefined;
+    query?: string | undefined;
+    limit?: number | undefined;
+}, {
+    chartType?: string | undefined;
+    query?: string | undefined;
+    limit?: number | undefined;
+}>;
+export type SearchExamplesInput = z.infer<typeof SearchExamplesInputSchema>;
+export interface SearchExampleHit {
+    id: string;
+    title: string;
+    description: string;
+    chartType: string;
+    /** Raw count of query terms matched in title+description; used only for ordering. */
+    score: number;
+}
+export interface SearchExamplesOutput {
+    results: SearchExampleHit[];
+}
+export declare function searchExamples(input: unknown): ToolResult<SearchExamplesOutput>;

package/dist/tools/searchExamples.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { samples } from '@blueprint-chart/lib';
+import { canonicalChartType } from '../dsl/chartTypes';
+import { ErrorCode, toolError, toolOk } from '../errors';
+export const SearchExamplesInputSchema = z.object({
+    query: z.string().optional(),
+    chartType: z.string().optional(),
+    limit: z.number().int().positive().max(20).optional(),
+}).strict();
+function scoreSample(s, terms) {
+    if (terms.length === 0) {
+        return 1;
+    }
+    const hay = `${s.title} ${s.description}`.toLowerCase();
+    let score = 0;
+    for (const t of terms) {
+        if (hay.includes(t)) {
+            score += 1;
+        }
+    }
+    return score;
+}
+export function searchExamples(input) {
+    const parsed = SearchExamplesInputSchema.safeParse(input);
+    if (!parsed.success) {
+        return toolError(ErrorCode.E_INPUT, parsed.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
+    }
+    const { query, chartType, limit } = parsed.data;
+    if ((!query || query.trim() === '') && !chartType) {
+        return toolError(ErrorCode.E_INPUT, [{
+                path: 'query',
+                message: 'Provide a `query` (topic keywords) and/or a `chartType` to search examples.',
+            }]);
+    }
+    let canonical;
+    if (chartType) {
+        canonical = canonicalChartType(chartType);
+        if (!canonical) {
+            return toolError(ErrorCode.E_INPUT, [{
+                    code: 'E_UNKNOWN_CHART_TYPE',
+                    path: 'chartType',
+                    message: `Unknown chart type "${chartType}".`,
+                }]);
+        }
+    }
+    const terms = (query ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+    const results = samples
+        .filter(s => (canonical ? s.chartType === canonical : true))
+        .map(s => ({ id: s.id, title: s.title, description: s.description, chartType: s.chartType, score: scoreSample(s, terms) }))
+        .filter(h => h.score > 0)
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+        .slice(0, limit ?? 10);
+    return toolOk({ results });
+}

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

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

package/dist/tools/searchExamples.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { searchExamples } from './searchExamples';
+describe('search_examples', () => {
+    it('finds samples by topic keyword in title/description', () => {
+        const r = searchExamples({ query: 'population' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.results.length).toBeGreaterThan(0);
+            expect(r.data.results[0]).toHaveProperty('id');
+            expect(r.data.results[0]).toHaveProperty('chartType');
+            expect(r.data.results[0]).not.toHaveProperty('dsl');
+        }
+    });
+    it('filters by chartType', () => {
+        const r = searchExamples({ chartType: 'pie' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.results.every(x => x.chartType === 'pie')).toBe(true);
+        }
+    });
+    it('rejects when neither query nor chartType is given', () => {
+        const r = searchExamples({});
+        expect(r.ok).toBe(false);
+    });
+    it('rejects an unknown chartType', () => {
+        const r = searchExamples({ chartType: 'notachart' });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe('E_INPUT');
+        }
+    });
+});

package/dist/tools/validate.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { type ValidationIssue } from '../dsl/validate';
+import { type WarningIssue } from '../dsl/semanticWarnings';
 import { type ToolResult } from '../errors';
 export declare const ValidateInputSchema: z.ZodObject<{
     source: z.ZodString;
@@ -12,10 +13,7 @@ export type ValidateInput = z.infer<typeof ValidateInputSchema>;
 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[];
+    /** Non-fatal advisories (W_NO_EFFECT / W_NOT_IMPLEMENTED / W_MULTISERIES_SHAPE). `code` is a plain string until the warning catalogue stabilises; errors keep the strict ValidationCode union. */
+    warnings: WarningIssue[];
 }
 export declare function validateDsl(input: ValidateInput): ToolResult<ValidateOutput>;

package/dist/tools/validate.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { parseDsl } from '../parse';
 import { validateAst } from '../dsl/validate';
+import { collectWarnings } from '../dsl/semanticWarnings';
 import { toolOk } from '../errors';
 export const ValidateInputSchema = z.object({
     source: z.string(),
@@ -10,12 +11,13 @@ export function validateDsl(input) {
     if (!parsed.ok) {
         return parsed;
     }
-    const issues = validateAst(parsed.data.ast);
+    const errors = validateAst(parsed.data.ast);
+    // Warnings are non-fatal: they never change `valid`. Only emit them when the
+    // structure is sound, so authors fix hard errors before chasing advisories.
+    const warnings = errors.length === 0 ? collectWarnings(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: [],
+        valid: errors.length === 0,
+        errors,
+        warnings,
     });
 }

package/dist/tools/validate.test.js

@@ -30,3 +30,20 @@ describe('validate_dsl', () => {
         }
     });
 });
+describe('validate_dsl warnings', () => {
+    it('stays valid but surfaces a no-op warning for sort on donut', () => {
+        const r = validateDsl({ source: 'chart donut {\n  sort = descending\n  data { "A" = 1 }\n}' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.valid).toBe(true);
+            expect(r.data.warnings.some(w => w.code === 'W_NO_EFFECT')).toBe(true);
+        }
+    });
+    it('emits no warnings for a clean chart', () => {
+        const r = validateDsl({ source: 'chart bar-vertical {\n  data { "A" = 1 }\n}' });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.data.warnings).toEqual([]);
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-chart/mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Model Context Protocol server for authoring Blueprint Chart .bpc files with LLMs.",
   "license": "MIT",
   "author": "pirhoo",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@blueprint-chart/docs": "0.1.20",
-    "@blueprint-chart/lib": "0.1.19",
+    "@blueprint-chart/lib": "0.1.25",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@napi-rs/canvas": "^0.1.71",
     "@resvg/resvg-js": "^2.6.2",