@changfenhuang/dsh-genui 0.9.6 → 0.9.7

package/lib/index.js

@@ -1,5 +1,6 @@
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 //#region src/client/spec.ts
 /**
@@ -138,7 +139,7 @@ function enu(v, values) {
 	return inEnum(v, values) ? v : void 0;
 }
 /** Plain object (not array, not null). */
-function obj(v) {
+function obj$1(v) {
 	return typeof v === "object" && v !== null && !Array.isArray(v) ? v : void 0;
 }
 /**
@@ -280,7 +281,7 @@ function repairItems(list, ctx, depth) {
 }
 function repairNode(value, ctx, depth) {
 	if (depth > GENUI_LIMITS.maxDepth) return null;
-	const v = obj(value);
+	const v = obj$1(value);
 	if (v === void 0) return null;
 	const type = v.type;
 	if (typeof type !== "string") return null;
@@ -369,6 +370,15 @@ function repairNode(value, ctx, depth) {
 				...opt("href", safeHref(v.href))
 			};
 		}
+		case "image": {
+			const src = safeMediaSrc(v.src);
+			if (src === void 0) return null;
+			return {
+				type: "image",
+				src,
+				...opt("alt", str(v.alt, GENUI_LIMITS.maxString))
+			};
+		}
 		case "audio": {
 			const src = safeMediaSrc(v.src);
 			if (src === void 0) return null;
@@ -720,7 +730,7 @@ function repairListItems(v, cap, ctx, depth) {
 			out.push(item.slice(0, GENUI_LIMITS.maxString));
 			continue;
 		}
-		const o = obj(item);
+		const o = obj$1(item);
 		const title = o === void 0 ? void 0 : str(o.title, GENUI_LIMITS.maxString);
 		if (title !== void 0) {
 			out.push({
@@ -759,7 +769,7 @@ function repairChartData(v, cap) {
 	const out = [];
 	for (const datum of v) {
 		if (out.length >= cap) break;
-		const o = obj(datum);
+		const o = obj$1(datum);
 		const label = o === void 0 ? void 0 : str(o.label, 128);
 		const value = o === void 0 ? void 0 : num(o.value, -0xe8d4a51000, 0xe8d4a51000);
 		if (label === void 0 || value === void 0) continue;
@@ -776,7 +786,7 @@ function repairSeries(v, cap, pointCap) {
 	const out = [];
 	for (const s of v) {
 		if (out.length >= cap) break;
-		const o = obj(s);
+		const o = obj$1(s);
 		const label = o === void 0 ? void 0 : str(o.label, 128);
 		const data = o === void 0 ? void 0 : repairChartData(o.data, pointCap);
 		if (label === void 0 || data === void 0) continue;
@@ -793,7 +803,7 @@ function repairTabs(v, ctx, depth) {
 	const out = [];
 	for (const tab of v) {
 		if (out.length >= GENUI_LIMITS.maxTabs) break;
-		const o = obj(tab);
+		const o = obj$1(tab);
 		const label = o === void 0 ? void 0 : str(o.label, 128);
 		if (label === void 0 || o === void 0) continue;
 		const rawItems = o.items !== void 0 ? o.items : o.content !== void 0 ? Array.isArray(o.content) ? o.content : [o.content] : void 0;
@@ -806,7 +816,7 @@ function repairTabs(v, ctx, depth) {
 }
 /** Header text for an object-shaped table column ({title,key} antd style). */
 function columnHeaderText(c) {
-	const o = obj(c);
+	const o = obj$1(c);
 	if (o === void 0) return String(c);
 	for (const k of [
 		"title",
@@ -821,7 +831,7 @@ function columnHeaderText(c) {
 }
 /** Row key for an object-shaped column, mirroring columnHeaderText's order. */
 function columnKeyOf(c) {
-	const o = obj(c);
+	const o = obj$1(c);
 	if (o === void 0) return void 0;
 	for (const k of [
 		"key",
@@ -847,13 +857,13 @@ function repairPlotSeries(v, cap) {
 	const out = [];
 	for (const s of v) {
 		if (out.length >= cap) break;
-		const o = obj(s);
+		const o = obj$1(s);
 		const expr = o === void 0 ? void 0 : str(o.expr, 512);
 		if (expr === void 0 || o === void 0) continue;
 		const params = [];
 		if (Array.isArray(o.params)) for (const p of o.params) {
 			if (params.length >= GENUI_LIMITS.maxPlotParams) break;
-			const po = obj(p);
+			const po = obj$1(p);
 			const name = po === void 0 ? void 0 : str(po.name, 64);
 			const value = po === void 0 ? void 0 : num(po.value, -1e9, 1e9);
 			if (name === void 0 || value === void 0) continue;
@@ -883,7 +893,7 @@ function repairSteps(v) {
 	const out = [];
 	for (const s of v) {
 		if (out.length >= GENUI_LIMITS.maxSteps) break;
-		const o = obj(s);
+		const o = obj$1(s);
 		const title = o === void 0 ? void 0 : str(o.title, 256);
 		if (title === void 0) continue;
 		out.push({
@@ -898,7 +908,7 @@ function repairPairs(v, cap) {
 	const out = [];
 	for (const p of v) {
 		if (out.length >= cap) break;
-		const o = obj(p);
+		const o = obj$1(p);
 		const key = o === void 0 ? void 0 : str(o.key, 256);
 		const value = o === void 0 ? void 0 : str(o.value, GENUI_LIMITS.maxString);
 		if (key === void 0 || value === void 0) continue;
@@ -914,7 +924,7 @@ function repairDiffs(v) {
 	const out = [];
 	for (const d of v) {
 		if (out.length >= 24) break;
-		const o = obj(d);
+		const o = obj$1(d);
 		const path = o === void 0 ? void 0 : str(o.path, 1024);
 		const newText = o === void 0 ? void 0 : str(o.newText, 2e4);
 		if (path === void 0 || newText === void 0) continue;
@@ -932,7 +942,7 @@ function repairAccordion(v, ctx, depth) {
 	const out = [];
 	for (const item of v) {
 		if (out.length >= GENUI_LIMITS.maxAccordionItems) break;
-		const o = obj(item);
+		const o = obj$1(item);
 		const title = o === void 0 ? void 0 : str(o.title, 256);
 		if (title === void 0 || o === void 0) continue;
 		out.push({
@@ -947,7 +957,7 @@ function repairMeshes(v) {
 	const out = [];
 	for (const m of v) {
 		if (out.length >= GENUI_LIMITS.maxMeshes) break;
-		const o = obj(m);
+		const o = obj$1(m);
 		const shape = o === void 0 ? void 0 : enu(o.shape, MESH_SHAPES);
 		if (shape === void 0) continue;
 		const scale = o === void 0 ? void 0 : num(o.scale, -1e6, 1e6) ?? tuple3(o.scale);
@@ -983,7 +993,7 @@ function repairDiagramNodes(v) {
 	const seen = /* @__PURE__ */ new Set();
 	for (const raw of v) {
 		if (out.length >= GENUI_LIMITS.maxDiagramNodes) break;
-		const o = obj(raw);
+		const o = obj$1(raw);
 		if (o === void 0) continue;
 		const id = str(o.id, 128);
 		const label = str(o.label, GENUI_LIMITS.maxString);
@@ -1015,7 +1025,7 @@ function repairDiagramEdges(v) {
 	const out = [];
 	for (const raw of v) {
 		if (out.length >= GENUI_LIMITS.maxDiagramEdges) break;
-		const o = obj(raw);
+		const o = obj$1(raw);
 		if (o === void 0) continue;
 		const from = str(o.from, 128);
 		const to = str(o.to, 128);
@@ -1031,7 +1041,7 @@ function repairDiagramEdges(v) {
 	return out;
 }
 function repairDiagramTheme(v) {
-	const o = obj(v);
+	const o = obj$1(v);
 	if (o === void 0) return void 0;
 	const out = {};
 	for (const key of [
@@ -1056,7 +1066,7 @@ function repairDiagramZones(v) {
 	const out = [];
 	for (const raw of v) {
 		if (out.length >= GENUI_LIMITS.maxDiagramZones) break;
-		const o = obj(raw);
+		const o = obj$1(raw);
 		if (o === void 0) continue;
 		const label = str(o.label, 64);
 		if (label === void 0) continue;
@@ -1071,7 +1081,7 @@ function repairDiagramZones(v) {
 	return out;
 }
 function repairDiagram(v) {
-	const o = obj(v);
+	const o = obj$1(v);
 	if (o === void 0) return null;
 	const kind = enu(o.kind, DIAGRAM_KINDS);
 	if (kind === void 0) return null;
@@ -1097,7 +1107,7 @@ function repairTimeline(v, cap) {
 	const out = [];
 	for (const item of v) {
 		if (out.length >= cap) break;
-		const o = obj(item);
+		const o = obj$1(item);
 		const title = o === void 0 ? void 0 : str(o.title, 256);
 		if (title === void 0) continue;
 		out.push({
@@ -1116,7 +1126,7 @@ function walkTree(v, cap, depthLeft) {
 	const out = [];
 	for (const item of v) {
 		if (out.length >= cap) break;
-		const o = obj(item);
+		const o = obj$1(item);
 		const name = o === void 0 ? void 0 : str(o.name, 256);
 		if (name === void 0) continue;
 		const children = o !== void 0 && depthLeft > 0 && Array.isArray(o.children) ? walkTree(o.children, cap, depthLeft - 1) : void 0;
@@ -1133,7 +1143,7 @@ function repairQuizOptions(v, answer) {
 	const out = [];
 	for (const optItem of v) {
 		if (out.length >= GENUI_LIMITS.maxQuizOptions) break;
-		const o = obj(optItem);
+		const o = obj$1(optItem);
 		const label = typeof optItem === "string" ? str(optItem, 512) : o === void 0 ? void 0 : str(o.label, 512);
 		if (label === void 0) continue;
 		out.push({
@@ -1200,7 +1210,7 @@ function sanitizeEChartOption(v, depth, budget) {
 		}
 		return arr.length > 0 ? arr : void 0;
 	}
-	const o = obj(v);
+	const o = obj$1(v);
 	if (o === void 0) return void 0;
 	const out = {};
 	for (const [key, val] of Object.entries(o)) {
@@ -1220,7 +1230,7 @@ function sanitizeEChartOption(v, depth, budget) {
 * no-op.
 */
 function repairGenuiSpec(value) {
-	const v = obj(value);
+	const v = obj$1(value);
 	if (v === void 0) return null;
 	if (!Array.isArray(v.items)) {
 		const wrapped = wrapSingleComponentRoot(value);
@@ -1252,28 +1262,28 @@ function countGenuiNodes(value, cap = Number.POSITIVE_INFINITY) {
 		for (const item of list) {
 			if (count >= cap) return;
 			count += 1;
-			const v = obj(item);
+			const v = obj$1(item);
 			if (v === void 0) continue;
 			if (v.type === "tabs" && Array.isArray(v.tabs)) for (const t of v.tabs) {
 				if (count >= cap) return;
-				const to = obj(t);
+				const to = obj$1(t);
 				if (to !== void 0) walk(to.items);
 			}
 			else if (v.type === "accordion" && Array.isArray(v.items)) for (const it of v.items) {
 				if (count >= cap) return;
-				const io = obj(it);
+				const io = obj$1(it);
 				if (io !== void 0) walk(io.items);
 			}
 			else if ((v.type === "row" || v.type === "col" || v.type === "grid" || v.type === "card") && Array.isArray(v.items)) walk(v.items);
 			else if (v.type === "file-tree" && Array.isArray(v.items)) walk(v.items);
 			else if (v.type === "list" && Array.isArray(v.items)) for (const li of v.items) {
 				if (count >= cap) return;
-				const lo = obj(li);
+				const lo = obj$1(li);
 				if (lo !== void 0 && typeof lo.type === "string") walk([lo]);
 			}
 		}
 	};
-	const root = obj(value);
+	const root = obj$1(value);
 	walk(root === void 0 ? [] : root.items);
 	return count;
 }
@@ -1298,6 +1308,7 @@ const GENUI_NODE_TYPES = /* @__PURE__ */ new Set([
 	"divider",
 	"file-tree",
 	"grid",
+	"image",
 	"input",
 	"json",
 	"keyvalue",
@@ -1327,47 +1338,108 @@ const GENUI_NODE_TYPES = /* @__PURE__ */ new Set([
 	"diagram"
 ]);
 /**
-* Count DECLARED nodes in a raw spec tree: objects whose `type` is a
+* Visit and count declared nodes in a raw spec tree: objects whose `type` is a
 * white-listed string, descending the same containers `countGenuiNodes`
-* walks. `validate_dsh_ui` compares this with the repaired count to surface
-* children the repair silently dropped (blank-render class of bugs, issue
-* #42) instead of reporting a green check on a half-empty tree.
+* walks. Callers can inspect field semantics or compare the count with the
+* repaired tree without maintaining another traversal.
 */
-function countDeclaredGenuiNodes(value, cap = Number.POSITIVE_INFINITY) {
+function visitDeclaredGenuiNodes(value, cap, visit) {
 	let count = 0;
 	const declared = (candidate) => {
-		const o = obj(candidate);
+		const o = obj$1(candidate);
 		return o !== void 0 && typeof o.type === "string" && GENUI_NODE_TYPES.has(o.type);
 	};
-	const walk = (list) => {
+	function walk(list, path) {
 		if (!Array.isArray(list)) return;
-		for (const item of list) {
+		for (let index = 0; index < list.length; index++) {
+			walkNode(list[index], `${path}[${index}]`);
 			if (count >= cap) return;
-			if (!declared(item)) continue;
-			count += 1;
-			const v = obj(item);
-			if (v === void 0) continue;
-			if (v.type === "tabs" && Array.isArray(v.tabs)) for (const t of v.tabs) walkItemsOf(t);
-			else if (v.type === "accordion" && Array.isArray(v.items)) for (const it of v.items) walkItemsOf(it);
-			else if ((v.type === "row" || v.type === "col" || v.type === "grid" || v.type === "card") && Array.isArray(v.items)) walk(v.items);
-			else if (v.type === "list" && Array.isArray(v.items)) {
-				for (const li of v.items) if (declared(li)) walk([li]);
-			}
 		}
-	};
-	const walkItemsOf = (holder) => {
-		const o = obj(holder);
+	}
+	function walkNode(item, at) {
+		if (count >= cap || !declared(item)) return;
+		const v = obj$1(item);
+		if (v === void 0) return;
+		count += 1;
+		visit(v, at);
+		if (v.type === "tabs" && Array.isArray(v.tabs)) for (let tab = 0; tab < v.tabs.length; tab++) walkItemsOf(v.tabs[tab], `${at}.tabs[${tab}]`);
+		else if (v.type === "accordion" && Array.isArray(v.items)) for (let row = 0; row < v.items.length; row++) walkItemsOf(v.items[row], `${at}.items[${row}]`);
+		else if ((v.type === "row" || v.type === "col" || v.type === "grid" || v.type === "card") && Array.isArray(v.items)) walk(v.items, `${at}.items`);
+		else if (v.type === "list" && Array.isArray(v.items)) for (let row = 0; row < v.items.length; row++) walkNode(v.items[row], `${at}.items[${row}]`);
+	}
+	function walkItemsOf(holder, path) {
+		const o = obj$1(holder);
 		if (o === void 0) return;
 		const items = o.items !== void 0 ? o.items : o.content;
-		if (Array.isArray(items)) walk(items);
-		else if (declared(items)) walk([items]);
-	};
-	const root = obj(value);
+		if (Array.isArray(items)) walk(items, `${path}.items`);
+		else walkNode(items, `${path}.items`);
+	}
+	const root = obj$1(value);
 	if (root === void 0) return count;
-	if (!Array.isArray(root.items) && declared(value)) walk([value]);
-	else walk(root.items);
+	if (!Array.isArray(root.items) && declared(value)) walkNode(value, "spec");
+	else walk(root.items, "items");
 	return count;
 }
+/**
+* Count white-listed nodes declared by a raw spec before repair drops invalid entries.
+* @param value - raw GenUI spec.
+* @param cap - traversal ceiling.
+* @returns declared node count up to the ceiling.
+*/
+function countDeclaredGenuiNodes(value, cap = Number.POSITIVE_INFINITY) {
+	return visitDeclaredGenuiNodes(value, cap, () => {});
+}
+/**
+* Return field-level chart errors without changing other repairable component families.
+* @param value - raw GenUI spec.
+* @returns chart semantic errors in tree order.
+*/
+function validateGenuiChartSemantics(value) {
+	const errors = [];
+	visitDeclaredGenuiNodes(value, GENUI_LIMITS.maxNodes + 1, (node, at) => {
+		if (node.type !== "chart") return;
+		validateChartNode(node, at, errors);
+	});
+	return errors;
+}
+function validateChartData(value, at, errors) {
+	if (!Array.isArray(value)) return;
+	for (let index = 0; index < value.length; index++) {
+		const datum = obj$1(value[index]);
+		const path = `${at}[${index}]`;
+		if (datum === void 0) {
+			errors.push(`${path} must be an object`);
+			continue;
+		}
+		if (typeof datum.label !== "string") errors.push(`${path}.label must be a string`);
+		if (typeof datum.value !== "number" || !Number.isFinite(datum.value)) errors.push(`${path}.value must be a finite number`);
+		if (datum.color !== void 0 && typeof datum.color !== "string") errors.push(`${path}.color must be a string`);
+	}
+}
+function validateChartSeries(value, at, errors) {
+	if (!Array.isArray(value)) return;
+	for (let index = 0; index < value.length; index++) {
+		const series = obj$1(value[index]);
+		const path = `${at}[${index}]`;
+		if (series === void 0) {
+			errors.push(`${path} must be an object`);
+			continue;
+		}
+		if (typeof series.label !== "string") errors.push(`${path}.label must be a string`);
+		if (series.color !== void 0 && typeof series.color !== "string") errors.push(`${path}.color must be a string`);
+		if (!Array.isArray(series.data)) errors.push(`${path}.data must be an array`);
+		validateChartData(series.data, `${path}.data`, errors);
+	}
+}
+function validateChartNode(v, at, errors) {
+	if (!Array.isArray(v.data) && !Array.isArray(v.series)) errors.push(`${at}: type 'chart' requires data or series (array)`);
+	if (v.variant !== void 0) errors.push(`${at}.variant is unsupported; use kind`);
+	if (v.data !== void 0 && !Array.isArray(v.data)) errors.push(`${at}.data must be an array`);
+	if (v.series !== void 0 && !Array.isArray(v.series)) errors.push(`${at}.series must be an array`);
+	if (v.kind !== void 0 && (typeof v.kind !== "string" || !CHART_KINDS.includes(v.kind))) errors.push(`${at}.kind must be bars, line, or donut`);
+	validateChartData(v.data, `${at}.data`, errors);
+	validateChartSeries(v.series, `${at}.series`, errors);
+}
 //#endregion
 //#region src/shared/fence-repair.ts
 /**
@@ -1478,6 +1550,83 @@ function completeFenceJson(raw) {
 	}
 }
 //#endregion
+//#region src/plugin/chart-contract.ts
+/** Plain object helper for raw model-authored specs. */
+function obj(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+/**
+* Visit chart nodes through the component-bearing containers understood by
+* the GenUI guard. This deliberately does not recursively inspect arbitrary
+* objects (for example `json.value` or `echart.option`), where a nested
+* `{type:"chart"}` is data rather than a GenUI node.
+*/
+function visitChartNodes(value, visit) {
+	function walkNode(value, at) {
+		const node = obj(value);
+		if (node === void 0 || typeof node.type !== "string") return;
+		if (node.type === "chart") visit(node, at);
+		if ((node.type === "row" || node.type === "col" || node.type === "grid" || node.type === "card") && Array.isArray(node.items)) {
+			walk(node.items, `${at}.items`);
+			return;
+		}
+		if (node.type === "tabs" && Array.isArray(node.tabs)) {
+			for (let index = 0; index < node.tabs.length; index++) {
+				const tab = obj(node.tabs[index]);
+				if (tab === void 0) continue;
+				const items = tab.items !== void 0 ? tab.items : tab.content;
+				if (Array.isArray(items)) walk(items, `${at}.tabs[${index}].items`);
+				else walkNode(items, `${at}.tabs[${index}].items`);
+			}
+			return;
+		}
+		if (node.type === "accordion" && Array.isArray(node.items)) {
+			for (let index = 0; index < node.items.length; index++) {
+				const item = obj(node.items[index]);
+				if (item === void 0) continue;
+				const items = item.items !== void 0 ? item.items : item.content;
+				if (Array.isArray(items)) walk(items, `${at}.items[${index}].items`);
+				else walkNode(items, `${at}.items[${index}].items`);
+			}
+			return;
+		}
+		if (node.type === "list" && Array.isArray(node.items)) for (let index = 0; index < node.items.length; index++) walkNode(node.items[index], `${at}.items[${index}]`);
+	}
+	function walk(list, path) {
+		if (!Array.isArray(list)) return;
+		for (let index = 0; index < list.length; index++) walkNode(list[index], `${path}[${index}]`);
+	}
+	const root = obj(value);
+	if (root === void 0) return;
+	if (!Array.isArray(root.items) && root.type === "chart") walkNode(root, "spec");
+	else walk(root.items, "items");
+}
+/**
+* Validate the native chart contract all the way to something the renderer
+* can actually draw. The shared guard still owns field/type validation; this
+* layer adds renderer-specific invariants that would otherwise produce an
+* empty line/donut chart or a grouped-bars shell with no points.
+*/
+function validateRenderableChartSemantics(value) {
+	const errors = validateGenuiChartSemantics(value);
+	visitChartNodes(value, (node, at) => {
+		const kind = node.kind === void 0 ? "bars" : node.kind;
+		if (Array.isArray(node.data) && node.data.length === 0) errors.push(`${at}.data must not be empty`);
+		if (Array.isArray(node.series)) {
+			if (node.series.length === 0) errors.push(`${at}.series must not be empty`);
+			for (let index = 0; index < node.series.length; index++) {
+				const series = obj(node.series[index]);
+				if (series !== void 0 && Array.isArray(series.data) && series.data.length === 0) errors.push(`${at}.series[${index}].data must not be empty`);
+			}
+		}
+		if (kind === "line" || kind === "donut") {
+			if (node.series !== void 0) errors.push(`${at}.series is only supported for bars`);
+			if (node.data === void 0) errors.push(`${at}.data is required for ${kind}`);
+		}
+	});
+	return errors;
+}
+//#endregion
 //#region src/plugin/tool.ts
 /**
 * Arguments schema: an open `spec` slot. The schema must NOT reject anything
@@ -1616,7 +1765,10 @@ function createRenderUiTool() {
 			}
 		},
 		async execute(args) {
-			const spec = repairGenuiSpec(specOf(args));
+			const input = specOf(args);
+			const chartErrors = validateRenderableChartSemantics(input);
+			if (chartErrors.length > 0) throw new Error("render_ui spec invalid: " + chartErrors.join("; "));
+			const spec = repairGenuiSpec(input);
 			if (spec === null) return "render_ui：spec 无效 —— 根对象需要 \"items\" 数组（组件树白名单见系统提示词），请修正后重试。";
 			return `已渲染 UI「${spec.title ?? "未命名"}」（${countNodes(spec)} 个组件）。用户现在可以看到这张卡片；组件带 action 时，用户交互会以 [genui-action] 消息发回给你，届时请重新渲染更新后的界面。`;
 		},
@@ -1719,6 +1871,11 @@ function bracketDiagnostic(raw) {
 	return diffs.length === 0 ? "" : `  括号计数：${diffs.join("；")}（长表格最易在收尾处错位，如把 ]]}]} 写成 ]}]}]}）\n`;
 }
 const COMMON_CAUSES = "常见原因：① 收尾括号错位/缺失（{ 与 }、[ 与 ] 数量不相等）② 字符串值内用了半角引号 \"（中文引语请用 “” 或 「」）③ 尾随逗号 ④ 字符串未闭合";
+/** Return the model-facing chart field failure for one parsed fence body. */
+function chartValidationFailure(value) {
+	const errors = validateRenderableChartSemantics(value);
+	return errors.length === 0 ? void 0 : `❌ chart 字段验证失败：\n- ${errors.join("\n- ")}`;
+}
 /** Build the validate_dsh_ui tool definition (registered alongside render_ui). */
 function createValidateDshUiTool() {
 	return {
@@ -1746,9 +1903,16 @@ function createValidateDshUiTool() {
 			} catch (error) {
 				const detail = error instanceof Error ? error.message : String(error);
 				const repaired = completeFenceJson(raw);
-				if (repaired !== null && repairGenuiSpec(JSON.parse(repaired.text)) !== null) return `❌ dsh-ui 围栏 JSON 解析失败：${detail}。\n${bracketDiagnostic(raw)}  已自动修复 ${repaired.repairs} 处，下面是修复后的 JSON，直接作为围栏正文发出即可（无需再验证）：\n\`\`\`\n${repaired.text}\n\`\`\``;
+				if (repaired !== null) {
+					const repairedValue = JSON.parse(repaired.text);
+					const chartFailure = chartValidationFailure(repairedValue);
+					if (chartFailure !== void 0) return chartFailure;
+					if (repairGenuiSpec(repairedValue) !== null) return `❌ dsh-ui 围栏 JSON 解析失败：${detail}。\n${bracketDiagnostic(raw)}  已自动修复 ${repaired.repairs} 处，下面是修复后的 JSON，直接作为围栏正文发出即可（无需再验证）：\n\`\`\`\n${repaired.text}\n\`\`\``;
+				}
 				return `❌ dsh-ui 围栏 JSON 解析失败：${detail}。\n${bracketDiagnostic(raw)}  自动修复未能恢复（结构损坏），请按错误信息修正后重新调用本工具验证，通过后再发出围栏。\n${COMMON_CAUSES}`;
 			}
+			const chartFailure = chartValidationFailure(parsed);
+			if (chartFailure !== void 0) return chartFailure;
 			const spec = repairGenuiSpec(parsed);
 			if (spec === null) return "❌ 不是合法 GenUI spec：根对象需要 \"items\" 数组，且每个节点 type 必须在白名单内（见系统提示词）。请修正后重新验证。";
 			const validCount = countNodes(spec);
@@ -1843,7 +2007,7 @@ The spec is a white-listed component tree rendered inline where the fence sits.
 
 - 布局: text · row · col · grid · card · divider · spacer
 - 展示: badge · stat · progress · list · table · keyvalue · avatar · audio · video · timeline · file-tree · breadcrumb · callout · steps · diff · json · code · copy
-- 图表: chart (bars|line|donut) · echart (preset|option) · plot (函数图)
+- 图表: chart {"type":"chart","kind":"bars|line|donut","data":[{"label":"...","value":n,"color":"#hex?"}],"series":[...]?}（series 仅 bars；未知扩展字段可通过校验，但原生 chart repair/render 会忽略） · echart (preset|option) · plot (函数图)
 - 交互: button · input · textarea · select · checkbox · switch · slider · radio · submit · quiz · link · tabs · accordion
 - 高级: mermaid (flowchart/sequence/class/gantt/pie/er/state/journey) · diagram (编辑级架构/流程图，27 种 kind) · scene3d (3D WebGL)
 
@@ -1862,6 +2026,51 @@ Rules:
 * @param ctx - cordis context.
 */
 const inject = ["systemPrompt"];
+const BUNDLED_SKILL_RANK = 600;
+const BUNDLED_SKILL_PROVIDER = "dsh-genui";
+const BUNDLED_SKILL_DESCRIPTION = "GenUI 完整组件与字段规范，用于生成 dsh-ui 结构化交互界面。";
+const BUNDLED_SKILL_INVOCATION = {
+	modelInvocable: true,
+	userInvocable: true
+};
+/** Register through the provider path so source=bundled also gets bundled precedence. */
+function bundledSkillProvider() {
+	const moduleDirectory = dirname(fileURLToPath(new URL(import.meta.url)));
+	const path = basename(moduleDirectory) === "plugin" ? resolve(moduleDirectory, "../../SKILL.md") : resolve(moduleDirectory, "../SKILL.md");
+	const raw = readFileSync(path, "utf8");
+	const end = raw.indexOf("\n---\n", 4);
+	if (!raw.startsWith("---\n") || end < 0) throw new Error("genui SKILL.md has invalid frontmatter");
+	return {
+		name: BUNDLED_SKILL_PROVIDER,
+		list: () => Promise.resolve([{
+			name: "genui",
+			description: BUNDLED_SKILL_DESCRIPTION,
+			invocation: BUNDLED_SKILL_INVOCATION,
+			source: "bundled",
+			provider: BUNDLED_SKILL_PROVIDER,
+			path,
+			resourceBase: {
+				kind: "directory",
+				path: dirname(path)
+			},
+			rank: BUNDLED_SKILL_RANK,
+			locator: path
+		}]),
+		get: () => Promise.resolve({
+			name: "genui",
+			description: BUNDLED_SKILL_DESCRIPTION,
+			invocation: BUNDLED_SKILL_INVOCATION,
+			source: "bundled",
+			provider: BUNDLED_SKILL_PROVIDER,
+			path,
+			resourceBase: {
+				kind: "directory",
+				path: dirname(path)
+			},
+			content: raw.slice(end + 5)
+		})
+	};
+}
 function apply(ctx) {
 	ctx.systemPrompt.section({
 		name: "genui:fence",
@@ -1881,6 +2090,9 @@ function apply(ctx) {
 	ctx.on("internal/service", (name, value) => {
 		if (name === "tools") tryRegister(value);
 	});
+	ctx.inject(["skills"], (skillCtx) => {
+		skillCtx.skills.registerProvider(() => bundledSkillProvider());
+	});
 	let assetsRegistered = false;
 	const tryRegisterAssets = (value) => {
 		if (assetsRegistered) return;

package/lib/types/client/GenuiBlock.d.ts

@@ -1,7 +1,10 @@
 import type { GenuiBlockProps } from './blocks/state.ts';
 export declare const GENUI_ACTION_DEBOUNCE_MS = 300;
 /**
- * Render a GenUI spec as an inline block. Falls back to nothing when the spec
- * carries no items (the fence renderer already refused non-specs before us).
+ * Render a GenUI spec as an inline block. `stateKey` is also the durable
+ * component identity: changing it remounts the stateful implementation so
+ * state loaded for one block can never leak into or be saved under another
+ * key. Identity-less streaming renders deliberately share one stable
+ * volatile instance, preserving local interaction state as the spec grows.
  */
 export declare const GenuiBlock: import("react").NamedExoticComponent<GenuiBlockProps>;

package/lib/types/client/blocks/advanced.d.ts

@@ -101,4 +101,4 @@ export declare const BreadcrumbNode: import("react").NamedExoticComponent<{
  * names stay independent. The model round-trip takes seconds, so a few
  * hundred ms of trailing delay is imperceptible — and it stops bursts of
  * queued user turns.
- */
+ */ 

package/lib/types/client/blocks/image.d.ts

@@ -0,0 +1,6 @@
+import { type ReactNode } from 'react';
+import type { GenuiImage } from '../spec.ts';
+/** Native image display; source safety is enforced by repairGenuiSpec/safeMediaSrc. */
+export declare function ImageNode({ node }: {
+    node: GenuiImage;
+}): ReactNode;

package/lib/types/client/blocks/state.d.ts

@@ -19,6 +19,8 @@ export interface GenuiBlockProps {
      * v2.7: durable-state key (session + slot + content fingerprint). When set,
      * interaction state (radio answers, submit lock, field values) persists to
      * localStorage and restores on refresh / re-render of the same content.
+     * Changing this key also starts a fresh in-memory interaction-state lifetime;
+     * callers only provide stateKey — GenuiBlock owns the matching React identity.
      */
     stateKey?: string | undefined;
 }

package/lib/types/client/fence-render.d.ts

@@ -39,6 +39,9 @@ export interface GenuiFenceContext {
  * - Tier-2 completion (missing quotes/brackets): settled renders only —
  *   `context.source` exists exclusively once the message finished, so
  *   streaming halves are never completed early.
+ * - Native chart semantics are checked before repair on every candidate so
+ *   aliases, empty collections, or line/donut series cannot repair into a
+ *   default/blank chart.
  */
 export declare function resolveGenuiSpec(raw: string, context?: GenuiFenceContext): GenuiSpec | null;
 /**

package/lib/types/client/gallery.d.ts

@@ -1,9 +1,7 @@
 /**
- * GenUI gallery: one spec exercising every white-listed node type, used as
- * the canonical full-vocabulary sample (tests render it and assert every
- * component family appears; docs and demos reuse it as the "show everything"
- * fence).
+ * GenUI gallery: canonical broad-coverage sample of built-in node types.
+ * Docs, demos, and renderer tests reuse it as the component gallery fence.
  */
 import type { GenuiSpec } from './spec.ts';
-/** A single spec covering all 40 node types in the vocabulary. */
+/** Canonical gallery spec for the built-in GenUI component vocabulary. */
 export declare const gallerySpec: GenuiSpec;