fix(create-chart): clarify chart spec metadata

Author: LikiosSedo

mcp/create-chart/src/handler.test.ts

@@ -209,6 +209,8 @@ describe("handleRenderChart", () => {
     // up and mangle.
     expect(ready).not.toMatch(/\\"/);
     expect(meta.type).toBe("pie");
+    expect(meta.schema_version).toBe(1);
+    expect(meta.artifact_kind).toBe("chart_spec");
     expect(typeof meta.chart_id).toBe("string");
     expect((meta.chart_id as string).startsWith("pie-")).toBe(true);
     expect(typeof meta.bytes).toBe("number");
@@ -232,6 +234,7 @@ describe("handleRenderChart", () => {
     const inner = ready.replace(/^```chart\n/, "").replace(/\n```$/, "");
     const spec = JSON.parse(inner);
     expect(spec.type).toBe("bar");
+    expect(spec.schema_version).toBe(1);
     expect(spec.data.series[0].values).toEqual([10, 20]);
     expect(spec.title).toBe("Demo");
     expect(spec).not.toHaveProperty("extra_garbage");
@@ -247,10 +250,11 @@ describe("handleRenderChart", () => {
     const expectedDir = path.resolve(tmp, "chart-render");
     expect(existsSync(expectedDir)).toBe(true);
     const expectedFile = path.join(expectedDir, `${meta.chart_id as string}.json`);
-    expect(meta.svg_path).toBe(expectedFile);
+    expect(meta.svg_path).toBe("");
     expect(meta.spec_path).toBe(expectedFile);
     expect(existsSync(expectedFile)).toBe(true);
     const onDisk = JSON.parse(readFileSync(expectedFile, "utf8"));
+    expect(onDisk.schema_version).toBe(1);
     expect(onDisk.type).toBe("line");
     expect(onDisk.data.series[0].points).toEqual([{ x: 1, y: 2 }]);
     expect(readdirSync(expectedDir)).toContain(`${meta.chart_id as string}.json`);

mcp/create-chart/src/handler.ts

@@ -2,6 +2,8 @@ import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { RenderChartArgs, RenderChartResult } from "./types.js";
 
+const CHART_SPEC_VERSION = 1;
+
 export const RENDER_CHART_INPUT_SCHEMA = {
   type: "object",
   required: ["type", "data"],
@@ -46,7 +48,7 @@ export async function handleRenderChart(rawArgs: unknown): Promise<{
   const args = validate(rawArgs);
   const id = newChartId(args.type);
 
-  const spec = JSON.stringify(args);
+  const spec = JSON.stringify({ ...args, schema_version: CHART_SPEC_VERSION });
   const markdownEmbed = "```chart\n" + spec + "\n```";
 
   let specPath: string | undefined;
@@ -60,10 +62,12 @@ export async function handleRenderChart(rawArgs: unknown): Promise<{
   }
 
   const result: RenderChartResult = {
+    schema_version: CHART_SPEC_VERSION,
     chart_id: id,
     type: args.type,
+    artifact_kind: "chart_spec",
     spec_path: specPath ?? "",
-    svg_path: specPath ?? "",
+    svg_path: "",
     bytes: Buffer.byteLength(spec, "utf8"),
     embed_instructions:
       "Paste the READY_TO_PASTE block above verbatim into your reply where the chart should appear. Do not modify the JSON, add backslashes, escape non-ASCII characters, convert to ```svg, or inline an <img>.",

mcp/create-chart/src/types.ts

@@ -19,6 +19,7 @@ export interface LineSeries {
 }
 
 export interface ChartCommonOpts {
+  schema_version?: 1;
   title?: string;
   width?: number;
   height?: number;
@@ -35,9 +36,15 @@ export type RenderChartArgs =
   | ({ type: "line"; data: { series: LineSeries[] } } & ChartCommonOpts);
 
 export interface RenderChartResult {
+  schema_version: 1;
   chart_id: string;
   type: "pie" | "bar" | "line";
+  artifact_kind: "chart_spec";
   spec_path: string;
+  /**
+   * Kept for backwards-compatible metadata shape. Empty because render_chart
+   * persists a JSON chart spec; the portal renders SVG client-side.
+   */
   svg_path: string;
   bytes: number;
   embed_instructions: string;

portal-web/src/components/chat/ChartRenderer.test.ts

@@ -7,6 +7,7 @@ describe("tryParseChartSpec", () => {
       '{"type":"pie","data":{"slices":[{"label":"a","value":1},{"label":"b","value":2}]}}',
     )
     expect(spec?.type).toBe("pie")
+    expect(spec?.schema_version).toBe(1)
     expect(spec).toMatchObject({ data: { slices: [{ label: "a", value: 1 }, { label: "b", value: 2 }] } })
   })
 
@@ -30,6 +31,15 @@ describe("tryParseChartSpec", () => {
     expect(tryParseChartSpec('{"type":"pie"}')).toBeNull()
   })
 
+  it("accepts missing schema_version as v1 but rejects unknown versions", () => {
+    expect(
+      tryParseChartSpec('{"schema_version":1,"type":"pie","data":{"slices":[{"label":"a","value":1}]}}')?.schema_version,
+    ).toBe(1)
+    expect(
+      tryParseChartSpec('{"schema_version":2,"type":"pie","data":{"slices":[{"label":"a","value":1}]}}'),
+    ).toBeNull()
+  })
+
   // The chart spec round-trips through the LLM as text; the model sometimes
   // double-escapes non-ASCII, leaving literal \uXXXX sequences after JSON.parse.
   it("decodes stray \\uXXXX escapes in title and labels", () => {

portal-web/src/components/chat/Markdown.tsx

@@ -83,6 +83,10 @@ function permissiveUrlTransform(uri: string): string {
   return ""
 }
 
+function hasLanguageClass(className: string | undefined, language: string): boolean {
+  return className?.split(/\s+/).includes(`language-${language}`) ?? false
+}
+
 function ChartLoading() {
   return (
     <div
@@ -155,7 +159,7 @@ export function Markdown({ children }: MarkdownProps) {
             ? rawChildren.join("")
             : String(rawChildren ?? "")
 
-          if (className === "language-chart") {
+          if (hasLanguageClass(className, "chart")) {
             const trimmed = text.trim()
             const spec = tryParseChartSpec(trimmed)
             if (spec) return <ChartRenderer spec={spec} />

portal-web/src/components/chat/chart-utils.ts

@@ -13,7 +13,10 @@ export type BarSeries = { name: string; values: number[] }
 export type LinePoint = { x: number | string; y: number }
 export type LineSeries = { name: string; points: LinePoint[] }
 
+export const CHART_SPEC_VERSION = 1
+
 export interface CommonOpts {
+  schema_version?: typeof CHART_SPEC_VERSION
   title?: string
   x_label?: string
   y_label?: string
@@ -389,8 +392,10 @@ function toCleanString(v: unknown): string {
   return decodeStrayUnicodeEscapes(String(v))
 }
 
-function pickCommonOpts(obj: Record<string, unknown>): CommonOpts {
-  const out: CommonOpts = {}
+function pickCommonOpts(obj: Record<string, unknown>): CommonOpts | null {
+  const rawVersion = obj.schema_version
+  if (rawVersion !== undefined && rawVersion !== CHART_SPEC_VERSION) return null
+  const out: CommonOpts = { schema_version: CHART_SPEC_VERSION }
   for (const k of ["title", "x_label", "y_label"] as const) {
     if (typeof obj[k] === "string") out[k] = decodeStrayUnicodeEscapes(obj[k] as string)
   }
@@ -426,6 +431,7 @@ export function tryParseChartSpec(raw: string): ChartSpec | null {
     const data = obj.data as Record<string, unknown> | undefined
     if (!data || typeof data !== "object") return null
     const common = pickCommonOpts(obj)
+    if (!common) return null
 
     if (obj.type === "pie") {
       const rawSlices = data.slices