@blueprint-chart/mcp 0.1.1 → 0.1.3

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 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.
 
 ## Install
 
@@ -44,17 +44,26 @@ 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) or PNG; structured `errors[]` (each with `code` + `suggestion`) on failure |
+| `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}`) |
+| `get_example` | Fetch a canonical `.bpc` sample by chart type or sample name (tool equivalent of `bpc://samples/{id}`) |
+| `get_grammar` | Full DSL syntax reference (tool equivalent of `bpc://grammar`) |
+
+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.
 
 ## Resources
 
@@ -77,7 +86,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 +128,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 +139,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": []
 }
 ```
 
@@ -219,7 +232,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/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/suggest.d.ts

@@ -0,0 +1 @@
+export declare function nearestSuggestion(input: string, candidates: readonly string[], maxDistance?: number): string | undefined;

package/dist/dsl/suggest.js

@@ -0,0 +1,47 @@
+function distance(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (a.length === 0) {
+        return b.length;
+    }
+    if (b.length === 0) {
+        return a.length;
+    }
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++) {
+        dp[i][0] = i;
+    }
+    for (let j = 0; j <= n; j++) {
+        dp[0][j] = j;
+    }
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const deletion = dp[i - 1][j] + 1;
+            const insertion = dp[i][j - 1] + 1;
+            const substitution = dp[i - 1][j - 1] + cost;
+            dp[i][j] = Math.min(deletion, insertion, substitution);
+        }
+    }
+    return dp[m][n];
+}
+const DEFAULT_MAX_DISTANCE = 10;
+export function nearestSuggestion(input, candidates, maxDistance = DEFAULT_MAX_DISTANCE) {
+    let best;
+    for (const cand of candidates) {
+        const d = distance(input, cand);
+        if (d > maxDistance) {
+            continue;
+        }
+        // Prefer candidates that start with the input (prefix match bonus)
+        const prefixBonus = cand.startsWith(input) ? -1000 : 0;
+        const score = d + prefixBonus;
+        if (!best || score < best.score || (score === best.score && cand < best.name)) {
+            best = { name: cand, dist: d, score };
+        }
+    }
+    return best?.name;
+}

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

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

package/dist/dsl/suggest.test.js

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { nearestSuggestion } from './suggest';
+describe('nearestSuggestion', () => {
+    it('returns the closest match within edit distance', () => {
+        expect(nearestSuggestion('bar', ['bar-vertical', 'bar-horizontal', 'line']))
+            .toBe('bar-vertical');
+    });
+    it('returns the alphabetically-first on tie', () => {
+        expect(nearestSuggestion('xx', ['ab', 'ba'])).toBe('ab');
+    });
+    it('returns undefined when no candidate is within max distance', () => {
+        expect(nearestSuggestion('zz', ['absolutely-unrelated'], 3)).toBeUndefined();
+    });
+    it('returns undefined when candidates is empty', () => {
+        expect(nearestSuggestion('any', [])).toBeUndefined();
+    });
+    it('handles exact match', () => {
+        expect(nearestSuggestion('line', ['line', 'pie'])).toBe('line');
+    });
+});

package/dist/dsl/universalProperties.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Metadata for a universal chart property (type, description, and optional
+ * choice list). Consumed by `describeChartType` to build the properties list.
+ */
+export interface UniversalPropertyMeta {
+    type: string;
+    description?: string;
+    choices?: string[];
+}
+/**
+ * Static metadata for universal properties that are consumed by astToDefinition
+ * directly rather than registered per chart type via getChartOptions. These
+ * appear in chart DSL across all chart types (e.g. sort, title, colors).
+ *
+ * This is the single source of truth for both the metadata and the membership
+ * of the universal-properties set. `UNIVERSAL_PROPERTIES` is derived from the
+ * keys of this object so the two cannot drift apart.
+ */
+export declare const UNIVERSAL_PROPERTY_META: Readonly<Record<string, UniversalPropertyMeta>>;
+/**
+ * Property keys recognized at the chart top level regardless of chart type.
+ *
+ * Derived from the keys of UNIVERSAL_PROPERTY_META to keep membership and
+ * metadata in lockstep. If a new universal property is added to the lib,
+ * add it to UNIVERSAL_PROPERTY_META above. The sample-roundtrip test (added
+ * in Task 6) catches drift: if a sample uses a key we don't know about, the
+ * validator will error on it and that test will fail.
+ */
+export declare const UNIVERSAL_PROPERTIES: ReadonlySet<string>;
+export declare function isUniversalProperty(key: string): boolean;

package/dist/dsl/universalProperties.js

@@ -0,0 +1,52 @@
+/**
+ * Static metadata for universal properties that are consumed by astToDefinition
+ * directly rather than registered per chart type via getChartOptions. These
+ * appear in chart DSL across all chart types (e.g. sort, title, colors).
+ *
+ * This is the single source of truth for both the metadata and the membership
+ * of the universal-properties set. `UNIVERSAL_PROPERTIES` is derived from the
+ * keys of this object so the two cannot drift apart.
+ */
+export const UNIVERSAL_PROPERTY_META = {
+    // Attribution metadata
+    title: { type: 'text', description: 'Chart title' },
+    description: { type: 'text', description: 'Chart description / subtitle' },
+    byline: { type: 'text', description: 'Byline / author credit' },
+    source: { type: 'text', description: 'Data source label' },
+    sourceUrl: { type: 'text', description: 'Data source URL' },
+    note: { type: 'text', description: 'Footer note' },
+    // Sort directives
+    sort: { type: 'select', description: 'Sort direction for categories', choices: ['ascending', 'descending', 'none'] },
+    sortMode: { type: 'select', description: 'Sort mode for grouped/stacked charts', choices: ['total', 'within-groups', 'none'] },
+    // Theme + palette (apply to every chart type)
+    theme: { type: 'text', description: 'Visual theme name' },
+    colorPalette: { type: 'text', description: 'Named color palette' },
+    colors: { type: 'colors', description: 'Custom color list' },
+    // Frame / layout
+    padding: { type: 'text', description: 'Frame padding (CSS shorthand)' },
+    background: { type: 'text', description: 'Background color' },
+    frameSizing: { type: 'select', description: 'Frame sizing mode', choices: ['auto', 'standard', 'aspect-ratio'] },
+    aspectRatio: { type: 'text', description: 'Aspect ratio (width / height)' },
+    // Value-label toggles (shared across bar/column variants but used universally
+    // in samples; per-type registry overrides when stricter)
+    valueLabels: { type: 'boolean', description: 'Show value labels on bars/segments' },
+    verticalLabelPosition: { type: 'select', description: 'Vertical axis label position', choices: ['auto', 'inside', 'outside', 'off'] },
+    horizontalLabelPosition: { type: 'select', description: 'Horizontal axis label position', choices: ['auto', 'inside', 'outside', 'off'] },
+    verticalGridStyle: { type: 'select', description: 'Vertical grid line style', choices: ['solid', 'dashed', 'dotted', 'none'] },
+    horizontalGridStyle: { type: 'select', description: 'Horizontal grid line style', choices: ['solid', 'dashed', 'dotted', 'none'] },
+    // TODO(lib): expose heightMode on area-stacked via getChartOptions
+    heightMode: { type: 'text', description: 'Height mode for stacked area charts' },
+};
+/**
+ * Property keys recognized at the chart top level regardless of chart type.
+ *
+ * Derived from the keys of UNIVERSAL_PROPERTY_META to keep membership and
+ * metadata in lockstep. If a new universal property is added to the lib,
+ * add it to UNIVERSAL_PROPERTY_META above. The sample-roundtrip test (added
+ * in Task 6) catches drift: if a sample uses a key we don't know about, the
+ * validator will error on it and that test will fail.
+ */
+export const UNIVERSAL_PROPERTIES = new Set(Object.keys(UNIVERSAL_PROPERTY_META));
+export function isUniversalProperty(key) {
+    return UNIVERSAL_PROPERTIES.has(key);
+}

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

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

package/dist/dsl/universalProperties.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { UNIVERSAL_PROPERTIES, UNIVERSAL_PROPERTY_META, isUniversalProperty } from './universalProperties';
+describe('universalProperties', () => {
+    it('includes attribution metadata', () => {
+        expect(UNIVERSAL_PROPERTIES.has('title')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('description')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('byline')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('source')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('sourceUrl')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('note')).toBe(true);
+    });
+    it('includes universal sort directives', () => {
+        expect(UNIVERSAL_PROPERTIES.has('sort')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('sortMode')).toBe(true);
+    });
+    it('isUniversalProperty matches', () => {
+        expect(isUniversalProperty('title')).toBe(true);
+        expect(isUniversalProperty('madeUpKey')).toBe(false);
+    });
+    it('UNIVERSAL_PROPERTY_META has schema entries matching the set', () => {
+        expect(UNIVERSAL_PROPERTY_META['title']?.type).toBe('text');
+        expect(UNIVERSAL_PROPERTY_META['sort']?.choices).toContain('ascending');
+        // Membership and metadata are in lockstep
+        expect(new Set(Object.keys(UNIVERSAL_PROPERTY_META))).toEqual(UNIVERSAL_PROPERTIES);
+    });
+});

package/dist/dsl/validate.d.ts

@@ -0,0 +1,10 @@
+import type { ChartNode } from '@blueprint-chart/lib';
+export type ValidationCode = 'E_UNKNOWN_CHART_TYPE' | 'E_UNKNOWN_PROPERTY' | 'E_INVALID_PROPERTY_VALUE' | 'E_DUPLICATE_BLOCK' | 'E_EMPTY_DATA' | 'E_UNKNOWN_DATA_KEY';
+export interface ValidationIssue {
+    code: ValidationCode;
+    path: string;
+    message: string;
+    suggestion?: string;
+    context?: Record<string, unknown>;
+}
+export declare function validateAst(ast: ChartNode): ValidationIssue[];

package/dist/dsl/validate.js

@@ -0,0 +1,68 @@
+import { getChartOptions } from '@blueprint-chart/lib';
+import { canonicalChartType, isKnownChartType, listCanonicalChartTypes } from './chartTypes';
+import { UNIVERSAL_PROPERTIES } from './universalProperties';
+import { nearestSuggestion } from './suggest';
+import { looksLikeUnquotedKey } from './dataKey';
+function chartLevelKnownKeys(chartType) {
+    const canonical = canonicalChartType(chartType) ?? chartType;
+    const perType = getChartOptions(canonical).map(o => o.key);
+    return [...UNIVERSAL_PROPERTIES, ...perType];
+}
+export function validateAst(ast) {
+    const issues = [];
+    const chartType = ast.chartType;
+    const chartTypeKnown = isKnownChartType(chartType);
+    if (!chartTypeKnown) {
+        const known = listCanonicalChartTypes();
+        issues.push({
+            code: 'E_UNKNOWN_CHART_TYPE',
+            path: 'chart',
+            message: `Unknown chart type "${chartType}". Known types: ${known.join(', ')}.`,
+            suggestion: nearestSuggestion(chartType, known),
+            context: { got: chartType, known },
+        });
+    }
+    // Chart-level property keys (only meaningful when the chart type is known)
+    if (chartTypeKnown) {
+        const known = chartLevelKnownKeys(chartType);
+        const knownSet = new Set(known);
+        for (const prop of ast.properties ?? []) {
+            if (!knownSet.has(prop.key)) {
+                issues.push({
+                    code: 'E_UNKNOWN_PROPERTY',
+                    path: `chart.${prop.key}`,
+                    message: `Unknown property "${prop.key}" on chart ${chartType}.`,
+                    suggestion: nearestSuggestion(prop.key, known),
+                    context: { got: prop.key, chartType },
+                });
+            }
+        }
+    }
+    // Data block
+    const dataEntries = ast.data?.entries ?? [];
+    if (dataEntries.length === 0) {
+        issues.push({
+            code: 'E_EMPTY_DATA',
+            path: 'data',
+            message: 'Chart has no data. Add a `data { … }` block with at least one entry.',
+        });
+    }
+    else {
+        for (const entry of dataEntries) {
+            // The `_series` pseudo-key is a multi-series header, not a row label.
+            if (entry.key === '_series') {
+                continue;
+            }
+            if (looksLikeUnquotedKey(entry)) {
+                issues.push({
+                    code: 'E_UNKNOWN_DATA_KEY',
+                    path: `data.${entry.key}`,
+                    message: `Data key "${entry.key}" looks like an identifier, but data rows expect quoted string labels (e.g. \`"${entry.key}" = …\`).`,
+                    context: { got: entry.key },
+                    suggestion: `"${entry.key}"`,
+                });
+            }
+        }
+    }
+    return issues;
+}

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

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