@ai-gui/plugin-chart 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liang Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @ai-gui/plugin-chart
+
+Chart plugin for [AIGUI](../../README.md), powered by [ECharts](https://echarts.apache.org). The model emits a ` ```chart ` fenced block containing an ECharts option JSON. Charts are complete-gated: a skeleton shows while the option streams, then the full chart renders (never partial-drawn).
+
+## Install
+
+```sh
+pnpm add @ai-gui/plugin-chart
+```
+
+## Usage
+
+```tsx
+import { chart } from "@ai-gui/plugin-chart"
+import { AIRenderer } from "@ai-gui/react"
+
+<AIRenderer plugins={[chart({ interactive: true })]} />
+```
+
+The model emits, e.g.:
+
+    ```chart {"xAxis":{"type":"category","data":["A","B"]},"yAxis":{"type":"value"},"series":[{"type":"bar","data":[1,2]}]}```
+
+## Options
+
+- `interactive?: boolean` — when true, complete options render a **live** ECharts instance (tooltip / dataZoom / click) via a `mount` output. When false/omitted, they render a static SSR SVG.
+- `gl?: boolean` — when true, render 3D charts via `echarts-gl` (WebGL, live-only; implies interactive). Enables 3D series like `bar3D`, `scatter3D`, `surface`, `line3D`, `globe`, `map3D`.
+- `width?: number` / `height?: number` — chart dimensions (default 600 × 400).
+
+## Exports
+
+- `chart(options)` — the plugin.
+- `chartPromptSpec()` — the prompt-spec string (also folded in automatically by `buildSystemPrompt` when the plugin is passed).
+
+See the [root README](../../README.md) for the full plugin list.

package/dist/index.cjs

@@ -0,0 +1,122 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const echarts = __toESM(require("echarts"));
+const __ai_gui_core = __toESM(require("@ai-gui/core"));
+
+//#region src/index.ts
+/** Memoized `echarts-gl` side-effect import, shared across all mounts. */
+let glReady = null;
+const loadGl = () => glReady ??= import("echarts-gl");
+/** Prompt spec describing the ```chart``` fence for LLM system prompts. */
+function chartPromptSpec() {
+	return [
+		"Charts (fenced): ```chart <ECharts option JSON>```.",
+		"Example: ```chart {\"xAxis\":{\"type\":\"category\",\"data\":[\"A\",\"B\"]},\"yAxis\":{\"type\":\"value\"},\"series\":[{\"type\":\"bar\",\"data\":[1,2]}]}```",
+		"When gl mode is enabled, 3D types are available: bar3D, scatter3D, surface, line3D, globe, map3D (WebGL, live-only)."
+	].join("\n");
+}
+/**
+* Chart plugin: claims the `chart` node type and renders an ECharts option JSON
+* to a framework-neutral SVG string via ECharts SSR. Sync, never throws.
+*/
+function chart(opts = {}) {
+	const width = opts.width ?? 600;
+	const height = opts.height ?? 400;
+	const gl = opts.gl ?? false;
+	const interactive = gl || (opts.interactive ?? false);
+	const render = (node) => {
+		const { data: option, complete } = (0, __ai_gui_core.parsePartialJSON)(node.content ?? "");
+		if (!complete || option == null || typeof option !== "object") return {
+			kind: "html",
+			html: `<div data-aigui-chart-loading></div>`
+		};
+		if (gl) {
+			const opt = option;
+			return {
+				kind: "mount",
+				mount: (el) => {
+					let inst;
+					let disposed = false;
+					loadGl().then(() => {
+						if (disposed) return;
+						inst = echarts.init(el, void 0, {
+							width,
+							height
+						});
+						inst.setOption(opt);
+					}).catch(() => {});
+					return () => {
+						disposed = true;
+						inst?.dispose();
+					};
+				}
+			};
+		}
+		if (interactive) {
+			const opt = option;
+			return {
+				kind: "mount",
+				mount: (el) => {
+					const inst = echarts.init(el, void 0, {
+						renderer: "svg",
+						width,
+						height
+					});
+					inst.setOption(opt);
+					return () => inst.dispose();
+				}
+			};
+		}
+		try {
+			const inst = echarts.init(null, null, {
+				renderer: "svg",
+				ssr: true,
+				width,
+				height
+			});
+			inst.setOption(option);
+			const svg = inst.renderToSVGString();
+			inst.dispose();
+			return {
+				kind: "html",
+				html: svg
+			};
+		} catch (e) {
+			return {
+				kind: "html",
+				html: `<pre data-aigui-chart-error>${String(e?.message ?? e)}</pre>`
+			};
+		}
+	};
+	return {
+		name: "chart",
+		nodeRenderers: { chart: render },
+		promptSpec: chartPromptSpec()
+	};
+}
+
+//#endregion
+exports.chart = chart
+exports.chartPromptSpec = chartPromptSpec

package/dist/index.d.cts

@@ -0,0 +1,30 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+
+//#region src/index.d.ts
+interface ChartOptions {
+  width?: number;
+  height?: number;
+  /**
+   * When true, complete options render a LIVE ECharts instance via the `mount`
+   * RenderOutput (enabling tooltip/dataZoom/click). When false/omitted, complete
+   * options render a static SSR SVG. Incomplete options always render the loading
+   * placeholder regardless of this flag.
+   */
+  interactive?: boolean;
+  /**
+   * When true, complete options render a LIVE ECharts instance using the
+   * `echarts-gl` extension and the canvas renderer (required by WebGL) via the
+   * `mount` RenderOutput. This enables 3D chart types (bar3D/scatter3D/surface/
+   * line3D/globe/map3D), which have no static SSR form. `gl` implies interactive.
+   * The `echarts-gl` module is lazily imported and memoized across mounts.
+   */
+  gl?: boolean;
+}
+/** Prompt spec describing the ```chart``` fence for LLM system prompts. */
+declare function chartPromptSpec(): string;
+/**
+ * Chart plugin: claims the `chart` node type and renders an ECharts option JSON
+ * to a framework-neutral SVG string via ECharts SSR. Sync, never throws.
+ */
+declare function chart(opts?: ChartOptions): AIGuiPlugin; //#endregion
+export { ChartOptions, chart, chartPromptSpec };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+
+//#region src/index.d.ts
+interface ChartOptions {
+  width?: number;
+  height?: number;
+  /**
+   * When true, complete options render a LIVE ECharts instance via the `mount`
+   * RenderOutput (enabling tooltip/dataZoom/click). When false/omitted, complete
+   * options render a static SSR SVG. Incomplete options always render the loading
+   * placeholder regardless of this flag.
+   */
+  interactive?: boolean;
+  /**
+   * When true, complete options render a LIVE ECharts instance using the
+   * `echarts-gl` extension and the canvas renderer (required by WebGL) via the
+   * `mount` RenderOutput. This enables 3D chart types (bar3D/scatter3D/surface/
+   * line3D/globe/map3D), which have no static SSR form. `gl` implies interactive.
+   * The `echarts-gl` module is lazily imported and memoized across mounts.
+   */
+  gl?: boolean;
+}
+/** Prompt spec describing the ```chart``` fence for LLM system prompts. */
+declare function chartPromptSpec(): string;
+/**
+ * Chart plugin: claims the `chart` node type and renders an ECharts option JSON
+ * to a framework-neutral SVG string via ECharts SSR. Sync, never throws.
+ */
+declare function chart(opts?: ChartOptions): AIGuiPlugin; //#endregion
+export { ChartOptions, chart, chartPromptSpec };

package/dist/index.js

@@ -0,0 +1,97 @@
+import * as echarts from "echarts";
+import { parsePartialJSON } from "@ai-gui/core";
+
+//#region src/index.ts
+/** Memoized `echarts-gl` side-effect import, shared across all mounts. */
+let glReady = null;
+const loadGl = () => glReady ??= import("echarts-gl");
+/** Prompt spec describing the ```chart``` fence for LLM system prompts. */
+function chartPromptSpec() {
+	return [
+		"Charts (fenced): ```chart <ECharts option JSON>```.",
+		"Example: ```chart {\"xAxis\":{\"type\":\"category\",\"data\":[\"A\",\"B\"]},\"yAxis\":{\"type\":\"value\"},\"series\":[{\"type\":\"bar\",\"data\":[1,2]}]}```",
+		"When gl mode is enabled, 3D types are available: bar3D, scatter3D, surface, line3D, globe, map3D (WebGL, live-only)."
+	].join("\n");
+}
+/**
+* Chart plugin: claims the `chart` node type and renders an ECharts option JSON
+* to a framework-neutral SVG string via ECharts SSR. Sync, never throws.
+*/
+function chart(opts = {}) {
+	const width = opts.width ?? 600;
+	const height = opts.height ?? 400;
+	const gl = opts.gl ?? false;
+	const interactive = gl || (opts.interactive ?? false);
+	const render = (node) => {
+		const { data: option, complete } = parsePartialJSON(node.content ?? "");
+		if (!complete || option == null || typeof option !== "object") return {
+			kind: "html",
+			html: `<div data-aigui-chart-loading></div>`
+		};
+		if (gl) {
+			const opt = option;
+			return {
+				kind: "mount",
+				mount: (el) => {
+					let inst;
+					let disposed = false;
+					loadGl().then(() => {
+						if (disposed) return;
+						inst = echarts.init(el, void 0, {
+							width,
+							height
+						});
+						inst.setOption(opt);
+					}).catch(() => {});
+					return () => {
+						disposed = true;
+						inst?.dispose();
+					};
+				}
+			};
+		}
+		if (interactive) {
+			const opt = option;
+			return {
+				kind: "mount",
+				mount: (el) => {
+					const inst = echarts.init(el, void 0, {
+						renderer: "svg",
+						width,
+						height
+					});
+					inst.setOption(opt);
+					return () => inst.dispose();
+				}
+			};
+		}
+		try {
+			const inst = echarts.init(null, null, {
+				renderer: "svg",
+				ssr: true,
+				width,
+				height
+			});
+			inst.setOption(option);
+			const svg = inst.renderToSVGString();
+			inst.dispose();
+			return {
+				kind: "html",
+				html: svg
+			};
+		} catch (e) {
+			return {
+				kind: "html",
+				html: `<pre data-aigui-chart-error>${String(e?.message ?? e)}</pre>`
+			};
+		}
+	};
+	return {
+		name: "chart",
+		nodeRenderers: { chart: render },
+		promptSpec: chartPromptSpec()
+	};
+}
+
+//#endregion
+export { chart, chartPromptSpec };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ai-gui/plugin-chart",
+  "version": "0.1.0",
+  "description": "ECharts chart plugin for AIGUI — static SVG, interactive, and 3D (echarts-gl).",
+  "keywords": [
+    "llm",
+    "ai",
+    "streaming",
+    "markdown",
+    "echarts",
+    "chart",
+    "visualization",
+    "3d",
+    "plugin",
+    "aigui"
+  ],
+  "license": "MIT",
+  "author": "Liang Li <ll_faw@hotmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liliang-cn/aigui.git",
+    "directory": "packages/plugin-chart"
+  },
+  "homepage": "https://github.com/liliang-cn/aigui#readme",
+  "bugs": "https://github.com/liliang-cn/aigui/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "echarts": "^5.5.1",
+    "echarts-gl": "^2.0.9",
+    "@ai-gui/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}