@blueprint-chart/mcp 0.1.1 → 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 four deterministic tools: `validate_dsl`, `inspect_dsl`, `recommend_chart_type`, and `render`. 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
 
@@ -44,17 +44,29 @@ Add to `claude_desktop_config.json`:
 ## Use with Claude Code
 
 ```bash
-claude mcp add blueprint-chart -- npx -y @blueprint-chart/mcp
+claude mcp add blueprint-chart \
+  -e BLUEPRINT_CHART_EDITOR_URL=https://blueprintchart.com \
+  -e BLUEPRINT_CHART_DOCS_URL=https://docs.blueprintchart.com \
+  -- npx -y @blueprint-chart/mcp
 ```
 
 ## Tools
 
 | Tool | Purpose |
 | --- | --- |
-| `validate_dsl` | Parse `.bpc`; precise errors with line/column |
-| `inspect_dsl` | Parse and summarize: chart type, scenes, series, annotations |
-| `recommend_chart_type` | Rank chart types for a given column shape |
-| `render` | Render to SVG (default) or PNG |
+| `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), 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, 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 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
 
@@ -77,7 +89,7 @@ Once the MCP is connected, ask Claude to make a chart:
 
 > **You:** Make a horizontal bar chart of English letter frequencies — top 10, highlight E.
 >
-> **Claude:** *(reads `bpc://grammar`, `bpc://handbook/choosing`, `bpc://samples/letter-frequency`, writes the `.bpc`, calls `validate_dsl` to confirm it parses, calls `render` with `format: 'png'` and shows you the image and the source)*
+> **Claude:** *(calls `list_chart_types`, `get_example({ chartType: "bar-horizontal" })`, writes the `.bpc`, calls `validate_dsl` to confirm it parses, calls `render` with `format: 'png'` and shows you the image and the source)*
 >
 > Here's the chart:
 >
@@ -119,7 +131,7 @@ chart bar-vertical {
 
 Full grammar at `bpc://grammar`; 17 canonical samples at `bpc://samples/<id>` (`letter-frequency`, `co2-emissions`, `quarterly-revenue`, `browser-market`, `temperature-anomaly`, `population-stacked-bar`, ...).
 
-### `validate_dsl` — parse with precise errors
+### `validate_dsl` — parse with structured diagnostics
 
 Request:
 
@@ -130,15 +142,19 @@ Request:
 }
 ```
 
-Response (note the line + column):
+Response — `valid` is false; each entry in `errors[]` carries a `code`, human-readable `message`, and an actionable `suggestion`:
 
 ```json
 {
-  "ok": false,
-  "code": "E_PARSE",
+  "valid": false,
   "errors": [
-    { "line": 2, "column": 19, "message": "Expected \"\\\"\" but end of input found." }
-  ]
+    {
+      "code": "E_PARSE",
+      "message": "Expected \"\\\"\" but end of input found.",
+      "suggestion": "Close the string literal on line 2."
+    }
+  ],
+  "warnings": []
 }
 ```
 
@@ -195,7 +211,7 @@ Response:
 }
 ```
 
-### `render` — SVG (default) or PNG
+### `render` — SVG (default), PNG, or HTML
 
 Request:
 
@@ -219,7 +235,7 @@ Response:
 }
 ```
 
-If rasterization fails (rare), the response is `{ ok: false, code: "E_RENDER", … }` **and still includes** the SVG that was successfully produced — partial success is preserved.
+If rasterization fails (rare), `errors[]` is non-empty — each entry has a `code` (`"E_RENDER"`) and a `suggestion` — **and the response still includes** the SVG that was successfully produced, so partial success is preserved.
 
 ### Reading a resource
 

package/dist/cli.js

@@ -15,7 +15,7 @@ function parseList(value) {
 function parseConfig(argv) {
     const env = process.env;
     const port = Number(env.PORT) || 4321;
-    const host = env.MCP_HOST || '127.0.0.1';
+    const host = env.MCP_HOST || (env.PORT ? '0.0.0.0' : '127.0.0.1');
     const allowedOriginsList = parseList(env.MCP_ALLOWED_ORIGINS);
     const allowedOrigins = allowedOriginsList
         && allowedOriginsList.length === 1 && allowedOriginsList[0] === '*'
@@ -38,6 +38,7 @@ function parseConfig(argv) {
                 ? Number(env.MCP_RATE_LIMIT_PER_MINUTE)
                 : undefined,
             silent: parseBool(env.MCP_SILENT),
+            rootRedirectUrl: env.MCP_ROOT_REDIRECT_URL || undefined,
         },
     };
     for (let i = 0; i < argv.length; i++) {
@@ -76,6 +77,18 @@ Environment variables (HTTP mode):
   MCP_MAX_CONCURRENT_REQUESTS   Cap on concurrent POSTs (default 16).
   MCP_RATE_LIMIT_PER_MINUTE     Per-IP rate limit (default off; e.g. 60).
   MCP_SILENT=1                  Suppress JSON access logs to stderr.
+  MCP_ROOT_REDIRECT_URL         If set, redirect GET / to this URL.
+  MCP_PUBLIC_URL                Public base URL (no path, no trailing slash).
+                                When set, advertised in serverInfo.icons so
+                                MCP clients (claude.ai, etc.) can render the
+                                favicon. Example: https://mcp.example.com
+  BLUEPRINT_CHART_EDITOR_URL    Editor app base URL (no trailing slash), e.g.
+                                https://blueprintchart.com. Required for the
+                                export_chart tool to mint copy/embed links;
+                                unset disables export (returns E_CONFIG).
+  BLUEPRINT_CHART_DOCS_URL      Docs site base URL, e.g.
+                                https://docs.blueprintchart.com. When set,
+                                tools/resources include public docsUrl fields.
 `);
             process.exit(0);
         }
@@ -105,7 +118,7 @@ const config = parseConfig(process.argv.slice(2));
 if (config.http) {
     startHttp(config.httpOpts)
         .then((handle) => {
-        process.stderr.write(`MCP HTTP server listening at ${handle.url}/mcp\n`);
+        process.stderr.write(`MCP HTTP server listening at ${handle.url}\n`);
         installSignalHandlers(handle.close);
     })
         .catch((err) => {

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/chartTypes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Maps alias chart-type names to canonical names. Lib registers aliases
+ * (`horizontal-bar` → `bar-horizontal`, `vertical-bar` → `bar-vertical`) at
+ * the registry level so both render identically; we surface that mapping here
+ * so validation and discovery tools can normalize input.
+ *
+ * Static rather than derived from the registry because the registry doesn't
+ * track alias→canonical pairs — it just registers each alias as a duplicate
+ * entry. Source of truth: `packages/lib/src/charts/registry.ts:445-446` and
+ * `packages/lib/src/enums.ts:24-25`.
+ */
+export declare const CHART_TYPE_ALIASES: Record<string, string>;
+export declare function listCanonicalChartTypes(): string[];
+export declare function canonicalChartType(name: string): string | undefined;
+export declare function isKnownChartType(name: string): boolean;
+export declare function aliasesFor(canonical: string): string[];

package/dist/dsl/chartTypes.js

@@ -0,0 +1,37 @@
+import { listCharts } from '@blueprint-chart/lib';
+/**
+ * Maps alias chart-type names to canonical names. Lib registers aliases
+ * (`horizontal-bar` → `bar-horizontal`, `vertical-bar` → `bar-vertical`) at
+ * the registry level so both render identically; we surface that mapping here
+ * so validation and discovery tools can normalize input.
+ *
+ * Static rather than derived from the registry because the registry doesn't
+ * track alias→canonical pairs — it just registers each alias as a duplicate
+ * entry. Source of truth: `packages/lib/src/charts/registry.ts:445-446` and
+ * `packages/lib/src/enums.ts:24-25`.
+ */
+export const CHART_TYPE_ALIASES = {
+    'horizontal-bar': 'bar-horizontal',
+    'vertical-bar': 'bar-vertical',
+};
+const ALIAS_NAMES = new Set(Object.keys(CHART_TYPE_ALIASES));
+export function listCanonicalChartTypes() {
+    return listCharts().filter(name => !ALIAS_NAMES.has(name));
+}
+export function canonicalChartType(name) {
+    if (CHART_TYPE_ALIASES[name]) {
+        return CHART_TYPE_ALIASES[name];
+    }
+    if (listCharts().includes(name)) {
+        return name;
+    }
+    return undefined;
+}
+export function isKnownChartType(name) {
+    return canonicalChartType(name) !== undefined;
+}
+export function aliasesFor(canonical) {
+    return Object.entries(CHART_TYPE_ALIASES)
+        .filter(([, target]) => target === canonical)
+        .map(([alias]) => alias);
+}

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

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

package/dist/dsl/chartTypes.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { CHART_TYPE_ALIASES, aliasesFor, canonicalChartType, isKnownChartType, listCanonicalChartTypes, } from './chartTypes';
+describe('chartTypes', () => {
+    it('lists canonical chart types', () => {
+        const canon = listCanonicalChartTypes();
+        expect(canon).toContain('bar-vertical');
+        expect(canon).toContain('bar-horizontal');
+        expect(canon).not.toContain('horizontal-bar'); // alias excluded
+    });
+    it('maps aliases to canonical names', () => {
+        expect(CHART_TYPE_ALIASES['horizontal-bar']).toBe('bar-horizontal');
+        expect(CHART_TYPE_ALIASES['vertical-bar']).toBe('bar-vertical');
+    });
+    it('canonicalChartType returns canonical for alias or canonical', () => {
+        expect(canonicalChartType('horizontal-bar')).toBe('bar-horizontal');
+        expect(canonicalChartType('bar-horizontal')).toBe('bar-horizontal');
+    });
+    it('canonicalChartType returns undefined for unknown', () => {
+        expect(canonicalChartType('bar')).toBeUndefined();
+        expect(canonicalChartType('totally-fake')).toBeUndefined();
+    });
+    it('isKnownChartType accepts canonical and aliases', () => {
+        expect(isKnownChartType('bar-vertical')).toBe(true);
+        expect(isKnownChartType('horizontal-bar')).toBe(true);
+        expect(isKnownChartType('bar')).toBe(false);
+    });
+    it('aliasesFor returns the registered aliases for a canonical name', () => {
+        expect(aliasesFor('bar-horizontal')).toEqual(['horizontal-bar']);
+        expect(aliasesFor('bar-vertical')).toEqual(['vertical-bar']);
+        expect(aliasesFor('bar-stacked')).toEqual([]);
+    });
+});

package/dist/dsl/dataKey.d.ts

@@ -0,0 +1,25 @@
+import type { PropertyNode } from '@blueprint-chart/lib';
+/**
+ * Heuristic for "data key is unquoted identifier-shaped." The lib's PropertyNode
+ * tagged quoted-string keys via an isQuoted boolean in older grammar versions,
+ * but the installed lib (v0.1.19) does not consistently expose it. We fall back
+ * to a regex match against the Identifier production from grammar.peggy.
+ *
+ * The Identifier production is: [a-zA-Z_#][a-zA-Z0-9_#-]*
+ *
+ * However, since parsed PropertyNode has no isQuoted flag, we cannot distinguish
+ * `"China" = 5` from `China = 5` purely from the AST. We tighten the heuristic
+ * by only flagging keys that start with a lowercase letter — real data labels in
+ * shipped samples always start with an uppercase letter, a digit, or `_`. A
+ * camelCase-starting key (e.g. `unquotedKey`) is a strong signal that the user
+ * typed a property key as if it were a chart-level option.
+ */
+export declare function looksLikeUnquotedKey(entry: PropertyNode): boolean;
+/**
+ * Inverse of `looksLikeUnquotedKey`, with an additional exclusion of the
+ * `_series` pseudo-key (which is a multi-series header, not a row label).
+ *
+ * Quoted-label-shaped means: proper nouns, digit-leading, hyphen/underscore-
+ * leading — anything that does NOT start with a lowercase letter.
+ */
+export declare function looksLikeQuotedLabel(entry: PropertyNode): boolean;

package/dist/dsl/dataKey.js

@@ -0,0 +1,42 @@
+/**
+ * Heuristic for "data key is unquoted identifier-shaped." The lib's PropertyNode
+ * tagged quoted-string keys via an isQuoted boolean in older grammar versions,
+ * but the installed lib (v0.1.19) does not consistently expose it. We fall back
+ * to a regex match against the Identifier production from grammar.peggy.
+ *
+ * The Identifier production is: [a-zA-Z_#][a-zA-Z0-9_#-]*
+ *
+ * However, since parsed PropertyNode has no isQuoted flag, we cannot distinguish
+ * `"China" = 5` from `China = 5` purely from the AST. We tighten the heuristic
+ * by only flagging keys that start with a lowercase letter — real data labels in
+ * shipped samples always start with an uppercase letter, a digit, or `_`. A
+ * camelCase-starting key (e.g. `unquotedKey`) is a strong signal that the user
+ * typed a property key as if it were a chart-level option.
+ */
+export function looksLikeUnquotedKey(entry) {
+    const k = entry.key;
+    const tagged = entry.isQuoted;
+    if (typeof tagged === 'boolean') {
+        return !tagged;
+    }
+    // Only flag identifiers that start with a lowercase letter — proper-noun labels
+    // and abbreviations used as data row labels always start with uppercase or `_`.
+    return /^[a-z][A-Za-z0-9_#-]*$/.test(k);
+}
+/**
+ * Inverse of `looksLikeUnquotedKey`, with an additional exclusion of the
+ * `_series` pseudo-key (which is a multi-series header, not a row label).
+ *
+ * Quoted-label-shaped means: proper nouns, digit-leading, hyphen/underscore-
+ * leading — anything that does NOT start with a lowercase letter.
+ */
+export function looksLikeQuotedLabel(entry) {
+    if (entry.key === '_series') {
+        return false;
+    }
+    const tagged = entry.isQuoted;
+    if (typeof tagged === 'boolean') {
+        return tagged;
+    }
+    return !/^[a-z][A-Za-z0-9_#-]*$/.test(entry.key);
+}

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

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

package/dist/dsl/dataKey.test.js

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { looksLikeUnquotedKey, looksLikeQuotedLabel } from './dataKey';
+function node(key) {
+    return { key, value: 1 };
+}
+describe('dataKey helpers', () => {
+    it('looksLikeUnquotedKey flags camelCase identifiers', () => {
+        expect(looksLikeUnquotedKey(node('unquotedKey'))).toBe(true);
+        expect(looksLikeUnquotedKey(node('sort'))).toBe(true);
+    });
+    it('looksLikeUnquotedKey passes proper-noun labels through', () => {
+        expect(looksLikeUnquotedKey(node('China'))).toBe(false);
+        expect(looksLikeUnquotedKey(node('United States'))).toBe(false);
+        expect(looksLikeUnquotedKey(node('_series'))).toBe(false);
+    });
+    it('looksLikeQuotedLabel excludes _series pseudo-key', () => {
+        expect(looksLikeQuotedLabel(node('_series'))).toBe(false);
+    });
+    it('looksLikeQuotedLabel accepts proper-noun labels', () => {
+        expect(looksLikeQuotedLabel(node('China'))).toBe(true);
+        expect(looksLikeQuotedLabel(node('New York'))).toBe(true);
+    });
+    it('looksLikeQuotedLabel rejects camelCase keys', () => {
+        expect(looksLikeQuotedLabel(node('sort'))).toBe(false);
+        expect(looksLikeQuotedLabel(node('colorPalette'))).toBe(false);
+    });
+    it('respects tagged isQuoted field when present', () => {
+        const tagged = { key: 'someKey', value: 1, isQuoted: true };
+        expect(looksLikeUnquotedKey(tagged)).toBe(false);
+        expect(looksLikeQuotedLabel(tagged)).toBe(true);
+        const untagged = { key: 'SomeKey', value: 1, isQuoted: false };
+        expect(looksLikeUnquotedKey(untagged)).toBe(true);
+        expect(looksLikeQuotedLabel(untagged)).toBe(false);
+    });
+});

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']);
+    });
+});