feat(core): export chart validation from flint-chart

CHANGELOG.md

@@ -11,6 +11,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Chart validation is now part of the core package. `validateChart(input,
+  backend)` returns `{ valid, warnings, errors, computedSize }` without
+  throwing, alongside `validateChartInput`, `validateSemanticTypes`,
+  `assembleForBackend`, and `stripPrivateKeys`, from `flint-chart` and the new
+  `flint-chart/validate` subpath. Hosts that let an agent author chart inputs
+  outside MCP get the same per-problem feedback the `validate_chart` tool
+  provides; `flint-chart-mcp` now consumes this implementation. Unregistered
+  `semantic_types` labels surface as `unknown_semantic_type` warnings, and
+  `isRegistered` / `getRegisteredTypes` are exported from `flint-chart/core`
+  ([#104](https://github.com/microsoft/flint-chart/issues/104)).
+
 ### Fixed
 
 - Keyboard targeting now navigates and emits `focus-element` through the

docs/api-reference.md

@@ -292,6 +292,37 @@ Re-exported from `flint-chart` and `flint-chart/core`:
 
 Key types: `ChartAssemblyInput`, `ChartEncoding`, `ChartTemplateDef`, `AssembleOptions`, `ChartWarning`, `ChannelSemantics`.
 
+## Validation
+
+Hosts that let an agent author a `ChartAssemblyInput` can validate it before
+rendering. `validateChart` never throws; it reports every warning the assembler
+emits plus a single `assembly_failed` error when the input cannot be compiled
+(unknown chart type, unsupported channel, nonexistent field, canvas caps).
+Re-exported from `flint-chart` and `flint-chart/validate`:
+
+```ts
+import { validateChart } from 'flint-chart/validate';
+
+const result = validateChart(input, 'vegalite');
+// { backend, chartType, valid, warnings, errors, computedSize? }
+if (!result.valid) {
+  // feed result.errors back to the agent
+}
+```
+
+| Symbol | Purpose |
+|--------|---------|
+| `validateChart(input, backend, options?)` | Validate and assemble; never throws |
+| `validateChartInput(input, backend?, options?)` | Shape checks only; throws on the first problem |
+| `validateSemanticTypes(semantic_types)` | `unknown_semantic_type` warnings for labels not in the type registry (also included by `validateChart`) |
+| `assembleForBackend(backend, input, options?)` | Assemble and split out `_warnings` / `_width` / `_height` |
+| `stripPrivateKeys(spec)` | Remove Flint's `_`-prefixed metadata from a spec |
+| `VALIDATION_BACKENDS` | Runtime list of accepted backends (`vegalite`, `echarts`, `chartjs`, `plotly`) |
+
+`options.maxDataRows` (default 100,000) and `options.maxCanvasDim` (default
+4000) cap input size. Inline `data.values` are required — resolve `data.url`
+to rows before validating.
+
 ---
 
 # §8 Overflow and warnings
@@ -325,6 +356,7 @@ Inspect `_warnings` or `ChartWarning` arrays in integration code to surface trun
 | `flint-chart/vegalite` | VL templates and `assembleVegaLite` |
 | `flint-chart/echarts` | ECharts templates and `assembleECharts` |
 | `flint-chart/chartjs` | Chart.js templates and `assembleChartjs` |
+| `flint-chart/validate` | `validateChart` and input validation helpers |
 | `flint-chart/test-data` | Gallery generators (`TEST_GENERATORS`) |
 
 ---

docs/zh-CN/api-reference.md

@@ -255,6 +255,35 @@ vlGetTemplateChannels('Scatter Plot');
 
 关键类型：`ChartAssemblyInput`、`ChartEncoding`、`ChartTemplateDef`、`AssembleOptions`、`ChartWarning`、`ChannelSemantics`。
 
+## 校验
+
+让 Agent 编写 `ChartAssemblyInput` 的宿主可以在渲染前先校验输入。`validateChart`
+不会抛出异常；它会返回 assembler 产生的全部警告，并在输入无法编译时（未知图表类型、
+不支持的通道、不存在的字段、画布上限）返回一条 `assembly_failed` 错误。
+从 `flint-chart` 与 `flint-chart/validate` 再导出：
+
+```ts
+import { validateChart } from 'flint-chart/validate';
+
+const result = validateChart(input, 'vegalite');
+// { backend, chartType, valid, warnings, errors, computedSize? }
+if (!result.valid) {
+  // 将 result.errors 反馈给 Agent
+}
+```
+
+| 符号 | 用途 |
+|--------|---------|
+| `validateChart(input, backend, options?)` | 校验并装配；不抛出异常 |
+| `validateChartInput(input, backend?, options?)` | 仅做结构检查；遇到第一个问题即抛出 |
+| `validateSemanticTypes(semantic_types)` | 对未在类型注册表中的标签返回 `unknown_semantic_type` 警告（`validateChart` 也会包含这些警告） |
+| `assembleForBackend(backend, input, options?)` | 装配并拆出 `_warnings` / `_width` / `_height` |
+| `stripPrivateKeys(spec)` | 从 spec 中移除 Flint 的 `_` 前缀元数据 |
+| `VALIDATION_BACKENDS` | 运行时可用的 backend 列表（`vegalite`、`echarts`、`chartjs`、`plotly`） |
+
+`options.maxDataRows`（默认 100,000）与 `options.maxCanvasDim`（默认 4000）限制输入
+大小。要求内联的 `data.values` —— 请在校验前先把 `data.url` 解析为行数据。
+
 ---
 
 # §8 溢出与警告
@@ -288,6 +317,7 @@ vlGetTemplateChannels('Scatter Plot');
 | `flint-chart/vegalite` | VL 模板与 `assembleVegaLite` |
 | `flint-chart/echarts` | ECharts 模板与 `assembleECharts` |
 | `flint-chart/chartjs` | Chart.js 模板与 `assembleChartjs` |
+| `flint-chart/validate` | `validateChart` 与输入校验辅助函数 |
 | `flint-chart/test-data` | 图库生成器（`TEST_GENERATORS`） |
 
 ---

packages/flint-js/README.md

@@ -80,6 +80,7 @@ const xl = assembleExcel(input);       // Native Excel chart artifact
 | `flint-chart/chartjs` | Chart.js backend |
 | `flint-chart/plotly` | Plotly backend |
 | `flint-chart/excel` | Native Excel / Office.js backend |
+| `flint-chart/validate` | `validateChart` — per-problem input validation for agent loops |
 | `flint-chart/test-data` | Sample data generators used by the gallery and tests |
 | `flint-chart/gallery` | Curated example specs |
 

packages/flint-js/package.json

@@ -70,6 +70,11 @@
       "import": "./dist/image-charts/index.js",
       "require": "./dist/image-charts/index.cjs"
     },
+    "./validate": {
+      "types": "./dist/validate/index.d.ts",
+      "import": "./dist/validate/index.js",
+      "require": "./dist/validate/index.cjs"
+    },
     "./interactive": {
       "types": "./dist/interactive/index.d.ts",
       "import": "./dist/interactive/index.js",

packages/flint-js/src/core/index.ts

@@ -196,6 +196,7 @@ export {
     resolveStackable,
     resolveSortDirection,
 } from './field-semantics';
+export { isRegistered, getRegisteredTypes } from './type-registry';
 
 // ThemeSpec: public visual-system vocabulary and chart-specific grounding
 export {

packages/flint-js/src/index.ts

@@ -26,6 +26,11 @@
  *   ecTemplateDefs / ecGetTemplateDef / ecGetTemplateChannels
  *   cjsTemplateDefs / cjsGetTemplateDef / cjsGetTemplateChannels
  *
+ * Validation (also available from 'flint-chart/validate'):
+ *   validateChart(input, backend)      — never throws; { valid, warnings, errors, computedSize }
+ *   validateChartInput(input, backend) — throws on the first problem
+ *   validateSemanticTypes(types)       — unregistered semantic_types labels
+ *
  * Usage:
  * ```ts
  * import { assembleVegaLite } from 'flint-chart';
@@ -60,3 +65,6 @@ export * from './excel';
 
 // Image-Charts backend: assembleImageCharts + hosted-image-URL artifact type
 export * from './image-charts';
+
+// Validation: validateChart, validateChartInput, assembleForBackend
+export * from './validate';