@webskill/sdk 0.3.0 → 0.5.0

package/dist/{dist-ZKaM8j06.js → dist-bewtXYlO.js}

@@ -1,7 +1,7 @@
 import { m as WebSkillError } from "./dist-8oQRa8Xz.js";
 import { toJSONSchema, z } from "zod";
 
-//#region ../ui/dist/webskillCatalog-B4pZvE74.js
+//#region ../ui/dist/webskillCatalog-B-IQxOKs.js
 /**
 * 最小子集 markdown → DOM：标题（#..###）、无序列表、代码块（```）、加粗、链接。
 * 全部内容经 textContent 写入，用户内容天然转义防 HTML 注入。
@@ -84,214 +84,112 @@ function renderMiniMarkdown(text, doc) {
 	}
 	return root;
 }
+const KINDS = /* @__PURE__ */ new Set([
+	"bar",
+	"line",
+	"pie"
+]);
+const list = (value) => Array.isArray(value) ? value : [];
 /**
-* 轻量 SVG 图表自绘（bar/line/pie，零依赖，三端复用单一来源）。
-* 全部经 doc.createElementNS 构建（内容来自技能输出，不拼 innerHTML）。
+* catalog `Chart` 节点 props → `ChartSpec`。四档共用这一份转换：
+* 此前 native / OpenUI / json-render / A2UI 各抄了一遍，改一处就会漂移。
+* catalog 的 `area` 在 `ChartSpec` 里没有对应枚举，按折线渲染——
+* 原先的裸 cast 会把非法枚举一路带进渲染器，画出空图。
 */
-const SVG_NS = "http://www.w3.org/2000/svg";
-/** 固定 8 色循环调色板 */
-const CHART_PALETTE = [
-	"#4e79a7",
-	"#f28e2b",
-	"#e15759",
-	"#76b7b2",
-	"#59a14f",
-	"#edc948",
-	"#b07aa1",
-	"#ff9da7"
-];
-const WIDTH = 320;
-const HEIGHT = 200;
-function el(doc, name, attrs) {
-	const node = doc.createElementNS(SVG_NS, name);
-	for (const [key, value] of Object.entries(attrs)) node.setAttribute(key, value);
-	return node;
-}
-function text$1(doc, x, y, content, attrs = {}) {
-	const node = el(doc, "text", {
-		x: String(x),
-		y: String(y),
-		"font-size": "9",
-		fill: "#555",
-		...attrs
-	});
-	node.textContent = content;
-	return node;
-}
-const fmt = (n) => Number.isInteger(n) ? String(n) : n.toFixed(1);
-function maxValue(chart) {
-	let max = 0;
-	for (const s of chart.series) for (const v of s.data) if (v > max) max = v;
-	return max;
-}
-function renderBar(chart, svg, doc) {
-	const plot = {
-		x0: 30,
-		y0: 24,
-		x1: 312,
-		y1: 164
+function chartSpecFromProps(props) {
+	const type = typeof props["type"] === "string" ? props["type"] : "bar";
+	const series = list(props["series"]);
+	return {
+		kind: KINDS.has(type) ? type : "line",
+		labels: list(props["labels"]),
+		series: series.map((item) => ({
+			...typeof item.name === "string" ? { name: item.name } : {},
+			data: list(item.values)
+		})),
+		...typeof props["title"] === "string" ? { title: props["title"] } : {}
 	};
-	const max = maxValue(chart);
-	svg.appendChild(el(doc, "line", {
-		x1: String(plot.x0),
-		y1: String(plot.y0),
-		x2: String(plot.x0),
-		y2: String(plot.y1),
-		stroke: "#999"
-	}));
-	svg.appendChild(el(doc, "line", {
-		x1: String(plot.x0),
-		y1: String(plot.y1),
-		x2: String(plot.x1),
-		y2: String(plot.y1),
-		stroke: "#999"
-	}));
-	if (max <= 0 || chart.labels.length === 0 || chart.series.length === 0) return;
-	const groupWidth = (plot.x1 - plot.x0) / chart.labels.length;
-	const barWidth = Math.max(1, groupWidth / chart.series.length * .7);
-	chart.series.forEach((series, si) => {
-		const color = CHART_PALETTE[si % CHART_PALETTE.length];
-		series.data.forEach((value, li) => {
-			if (li >= chart.labels.length) return;
-			const height = (plot.y1 - plot.y0) * value / max;
-			const x = plot.x0 + li * groupWidth + (groupWidth - barWidth * chart.series.length) / 2 + si * barWidth;
-			const y = plot.y1 - height;
-			svg.appendChild(el(doc, "rect", {
-				x: String(x),
-				y: String(y),
-				width: String(barWidth),
-				height: String(height),
-				fill: color,
-				"data-series": series.name ?? String(si)
-			}));
-			if (chart.series.length === 1) svg.appendChild(text$1(doc, x + barWidth / 2, y - 2, fmt(value), { "text-anchor": "middle" }));
-		});
-	});
-	chart.labels.forEach((label, li) => {
-		svg.appendChild(text$1(doc, plot.x0 + li * groupWidth + groupWidth / 2, plot.y1 + 12, label, { "text-anchor": "middle" }));
-	});
 }
-function renderLine(chart, svg, doc) {
-	const plot = {
-		x0: 30,
-		y0: 24,
-		x1: 312,
-		y1: 164
+const seriesNames = (chart) => chart.series.map((series) => series.name ?? "");
+/** echarts 的图例条目来源：饼图按标签分项，其余按系列名 */
+const legendEntries = (chart) => chart.kind === "pie" ? chart.labels : seriesNames(chart);
+/** `ChartSpec` → ECharts option：图表类型、数据系列、图例的唯一定义处 */
+function toEchartsOption(chart) {
+	return {
+		animation: false,
+		title: chart.title ? {
+			text: chart.title,
+			left: "center",
+			textStyle: { fontSize: 14 }
+		} : void 0,
+		tooltip: { trigger: chart.kind === "pie" ? "item" : "axis" },
+		legend: { bottom: 0 },
+		xAxis: chart.kind === "pie" ? void 0 : {
+			type: "category",
+			data: chart.labels
+		},
+		yAxis: chart.kind === "pie" ? void 0 : { type: "value" },
+		series: chart.kind === "pie" ? chart.series.map((series) => ({
+			type: "pie",
+			name: series.name,
+			data: chart.labels.map((label, index) => ({
+				name: label,
+				value: series.data[index] ?? 0
+			}))
+		})) : chart.series.map((series) => ({
+			type: chart.kind,
+			name: series.name,
+			data: series.data
+		}))
 	};
-	const max = maxValue(chart);
-	svg.appendChild(el(doc, "line", {
-		x1: String(plot.x0),
-		y1: String(plot.y0),
-		x2: String(plot.x0),
-		y2: String(plot.y1),
-		stroke: "#999"
-	}));
-	svg.appendChild(el(doc, "line", {
-		x1: String(plot.x0),
-		y1: String(plot.y1),
-		x2: String(plot.x1),
-		y2: String(plot.y1),
-		stroke: "#999"
-	}));
-	if (max <= 0 || chart.labels.length === 0 || chart.series.length === 0) return;
-	const step = chart.labels.length > 1 ? (plot.x1 - plot.x0) / (chart.labels.length - 1) : 0;
-	const px = (li) => chart.labels.length > 1 ? plot.x0 + li * step : (plot.x0 + plot.x1) / 2;
-	const py = (v) => plot.y1 - (plot.y1 - plot.y0) * v / max;
-	chart.series.forEach((series, si) => {
-		const color = CHART_PALETTE[si % CHART_PALETTE.length];
-		const points = series.data.slice(0, chart.labels.length).map((v, li) => `${px(li)},${py(v)}`).join(" ");
-		if (points !== "") svg.appendChild(el(doc, "polyline", {
-			points,
-			fill: "none",
-			stroke: color,
-			"stroke-width": "1.5"
-		}));
-		series.data.slice(0, chart.labels.length).forEach((v, li) => {
-			svg.appendChild(el(doc, "circle", {
-				cx: String(px(li)),
-				cy: String(py(v)),
-				r: "2",
-				fill: color
-			}));
-		});
-	});
-	chart.labels.forEach((label, li) => {
-		svg.appendChild(text$1(doc, px(li), plot.y1 + 12, label, { "text-anchor": "middle" }));
-	});
 }
-function renderPie(chart, svg, doc) {
-	const data = (chart.series[0]?.data ?? []).slice(0, chart.labels.length);
-	const total = data.reduce((sum, v) => sum + (v > 0 ? v : 0), 0);
-	const cx = 90;
-	const cy = 104;
-	const r = 72;
-	if (total <= 0) {
-		svg.appendChild(text$1(doc, cx, cy, "No data", { "text-anchor": "middle" }));
-		return;
-	}
-	let angle = -Math.PI / 2;
-	data.forEach((value, i) => {
-		const label = chart.labels[i] ?? String(i);
-		const color = CHART_PALETTE[i % CHART_PALETTE.length];
-		const slice = Math.max(value, 0) / total * Math.PI * 2;
-		const x0 = cx + r * Math.cos(angle);
-		const y0 = cy + r * Math.sin(angle);
-		const x1 = cx + r * Math.cos(angle + slice);
-		const y1 = cy + r * Math.sin(angle + slice);
-		const path = el(doc, "path", {
-			d: `M ${cx} ${cy} L ${x0} ${y0} A ${r} ${r} 0 ${slice > Math.PI ? "1" : "0"} 1 ${x1} ${y1} Z`,
-			fill: color,
-			"data-label": label
-		});
-		svg.appendChild(path);
-		angle += slice;
-		const ly = 40 + i * 14;
-		svg.appendChild(el(doc, "rect", {
-			x: "190",
-			y: String(ly - 7),
-			width: "8",
-			height: "8",
-			fill: color
-		}));
-		svg.appendChild(text$1(doc, 202, ly, `${label} (${fmt(value)})`));
-	});
+/**
+* 图表的 DOM 契约。echarts 画在 canvas 上，DOM 里读不到图表类型/系列/图例，
+* 「同一份 ChartSpec 在各档下一致」只能靠宿主元素上的这三个属性对拍。
+*/
+function applyChartDomContract(container, chart) {
+	container.setAttribute("data-webskill-chart", chart.kind);
+	container.setAttribute("data-webskill-chart-series", seriesNames(chart).join("|"));
+	container.setAttribute("data-webskill-chart-legend", legendEntries(chart).join("|"));
+	if (chart.title) container.setAttribute("aria-label", chart.title);
+	else container.removeAttribute("aria-label");
 }
 /**
-* ChartSpec → SVG（bar 等宽柱 + 值标签；line 折线 + 点；pie 扇形 + 图例；空数据容错）
-* @stable
+* 框架无关的 echarts 挂载点：三档的 React 组件与 A2UI 档的 Lit 元素共用同一实现，
+* 图表不再因档位而异。echarts 走动态 import，不打进首屏。
 */
-function renderMiniChart(chart, doc) {
-	const svg = el(doc, "svg", {
-		viewBox: `0 0 ${WIDTH} ${HEIGHT}`,
-		width: String(WIDTH),
-		height: String(HEIGHT),
-		class: `webskill-chart webskill-chart--${chart.kind}`,
-		role: "img"
+function mountEchart(container) {
+	let disposed = false;
+	let instance;
+	let queued;
+	let observer;
+	const apply = (chart) => {
+		instance?.setOption(toEchartsOption(chart), {
+			notMerge: true,
+			lazyUpdate: true
+		});
+	};
+	import("./echarts-DhNm2ene.js").then((echarts) => {
+		if (disposed) return;
+		instance = echarts.init(container);
+		if (typeof ResizeObserver !== "undefined") {
+			observer = new ResizeObserver(() => instance?.resize());
+			observer.observe(container);
+		}
+		if (queued) apply(queued);
 	});
-	if (chart.title) svg.appendChild(text$1(doc, WIDTH / 2, 14, chart.title, {
-		"text-anchor": "middle",
-		"font-size": "11",
-		fill: "#333"
-	}));
-	switch (chart.kind) {
-		case "bar":
-			renderBar(chart, svg, doc);
-			break;
-		case "line":
-			renderLine(chart, svg, doc);
-			break;
-		case "pie":
-			renderPie(chart, svg, doc);
-			break;
-	}
-	return svg;
-}
-/** A2UI/OpenUI 降级：chart → table（labels 为首列，series 各为一列） */
-function chartToTable(chart) {
 	return {
-		type: "table",
-		columns: ["label", ...chart.series.map((s, i) => s.name ?? `series ${i + 1}`)],
-		rows: chart.labels.map((label, li) => [label, ...chart.series.map((s) => s.data[li] ?? null)])
+		setChart(chart) {
+			applyChartDomContract(container, chart);
+			queued = chart;
+			apply(chart);
+		},
+		dispose() {
+			disposed = true;
+			observer?.disconnect();
+			observer = void 0;
+			instance?.dispose();
+			instance = void 0;
+		}
 	};
 }
 function componentSchema(def) {
@@ -407,6 +305,7 @@ function validateNode(catalog, byName, node, path, issues) {
 		return;
 	}
 	const allowed = def.children;
+	const singletons = /* @__PURE__ */ new Map();
 	children.forEach((child, index) => {
 		const childPath = `${path}.children[${index}]`;
 		if (allowed !== "any" && isRecord$1(child) && typeof child["component"] === "string") {
@@ -418,6 +317,17 @@ function validateNode(catalog, byName, node, path, issues) {
 				return;
 			}
 		}
+		if (isRecord$1(child) && typeof child["component"] === "string") {
+			const childName = child["component"];
+			if (byName.get(childName)?.singletonPerContainer === true) {
+				const seen = (singletons.get(childName) ?? 0) + 1;
+				singletons.set(childName, seen);
+				if (seen > 1) issues.push({
+					path: childPath,
+					message: `At most one "${childName}" per container; "${name}" already contains one`
+				});
+			}
+		}
 		validateNode(catalog, byName, child, childPath, issues);
 	});
 }
@@ -481,6 +391,7 @@ const DATA = [
 	"Metric",
 	"Table",
 	"Chart",
+	"Timeline",
 	"FileLink"
 ];
 const INPUT = [
@@ -488,8 +399,10 @@ const INPUT = [
 	"Field",
 	"Button"
 ];
+/** Tabs 的面板与 Grid 的格子必须自成容器，否则「每容器至多一个表单」就没有落脚点 */
+const PANEL = ["Card", "Stack"];
 /**
-* v3 首发 catalog：覆盖既有 `UiSurface` 六类的全部表达力，先窄后宽。
+* v3 首发 catalog：覆盖旧六类 surface（metric / chart / table / form / file / custom）的全部表达力，先窄后宽。
 * 只依赖 zod —— 不 import 任何 UI framework（21 号文档 §5.1）。
 */
 const uiCatalog = defineUiCatalog({
@@ -503,8 +416,13 @@ const uiCatalog = defineUiCatalog({
 		"- Ask for user input with `Form` + `Field`; never describe an input in `Text`.",
 		"- A `Button`'s `action` must be one of the catalog actions.",
 		"- Never emit HTML, scripts or remote images.",
-		"- Prefer `Table` for many rows, `Chart` for trends, `Metric` for a single number.",
-		"- At most one `Form` per surface."
+		"- Prefer `Table` for many rows, `Chart` for trends, `Metric` for a single number,",
+		"  `Timeline` for ordered steps and `Progress` for how far a long task has come.",
+		"- Match `Field.type` to the question instead of using `text` for everything:",
+		"  `select` / `multi-select` for a fixed set of options, `date` for dates,",
+		"  `toggle` for yes/no, `number` for quantities, `textarea` for several sentences.",
+		"- Group independent sections with `Tabs` or `Grid` instead of one long column.",
+		"- At most one `Form` per container; a `Tabs` panel and a `Grid` cell are separate containers."
 	].join("\n"),
 	components: [
 		{
@@ -566,6 +484,67 @@ const uiCatalog = defineUiCatalog({
 			props: z.object({}),
 			example: { component: "Separator" }
 		},
+		{
+			name: "Tabs",
+			group: "layout",
+			description: "Switchable panels. Each child is one panel and its own form container.",
+			props: z.object({ labels: z.array(z.string()).min(2) }),
+			children: PANEL,
+			constraints: ["One child per label, in the same order"],
+			example: {
+				component: "Tabs",
+				props: { labels: ["Filters", "Export"] },
+				children: [{
+					component: "Stack",
+					children: [{
+						component: "Text",
+						props: { text: "Pick a date range." }
+					}]
+				}, {
+					component: "Stack",
+					children: [{
+						component: "Text",
+						props: { text: "Choose a file format." }
+					}]
+				}]
+			}
+		},
+		{
+			name: "Grid",
+			group: "layout",
+			description: "Dashboard grid. Each child is one cell and its own form container.",
+			props: z.object({ columns: z.union([
+				z.literal(2),
+				z.literal(3),
+				z.literal(4)
+			]).default(2) }),
+			children: PANEL,
+			example: {
+				component: "Grid",
+				props: { columns: 2 },
+				children: [{
+					component: "Card",
+					props: { title: "Revenue" },
+					children: [{
+						component: "Metric",
+						props: {
+							label: "MRR",
+							value: "12,400"
+						}
+					}]
+				}, {
+					component: "Card",
+					props: { title: "Churn" },
+					children: [{
+						component: "Metric",
+						props: {
+							label: "Rate",
+							value: "2.1%"
+						}
+					}]
+				}]
+			}
+		},
 		{
 			name: "Heading",
 			group: "content",
@@ -701,6 +680,33 @@ const uiCatalog = defineUiCatalog({
 				}
 			}
 		},
+		{
+			name: "Timeline",
+			group: "data",
+			description: "Ordered steps or events, earliest first.",
+			props: z.object({ items: z.array(z.object({
+				title: z.string(),
+				time: z.string().optional(),
+				description: z.string().optional(),
+				state: z.enum([
+					"done",
+					"active",
+					"pending"
+				]).default("pending")
+			})).min(1) }),
+			example: {
+				component: "Timeline",
+				props: { items: [{
+					title: "Plan",
+					time: "Mon",
+					state: "done"
+				}, {
+					title: "Build",
+					time: "Tue",
+					state: "active"
+				}] }
+			}
+		},
 		{
 			name: "FileLink",
 			group: "data",
@@ -708,13 +714,18 @@ const uiCatalog = defineUiCatalog({
 			props: z.object({
 				path: z.string(),
 				label: z.string().optional(),
-				mimeType: z.string().optional()
+				mimeType: z.string().optional(),
+				/** 字节数；人类可读格式化是渲染层的事，不进 props */
+				size: z.number().int().nonnegative().optional(),
+				actions: z.array(actionRef).optional()
 			}),
+			constraints: ["size is a byte count, not a formatted string"],
 			example: {
 				component: "FileLink",
 				props: {
 					path: "report.csv",
-					label: "Download report"
+					label: "Download report",
+					size: 2411724
 				}
 			}
 		},
@@ -728,7 +739,8 @@ const uiCatalog = defineUiCatalog({
 				cancelLabel: z.string().optional()
 			}),
 			children: ["Field"],
-			constraints: ["At most one Form per surface", "Every Field name must be unique inside the Form"],
+			singletonPerContainer: true,
+			constraints: ["At most one Form per container", "Every Field name must be unique inside the Form"],
 			example: {
 				component: "Form",
 				props: { title: "Schedule report" },
@@ -792,6 +804,27 @@ const uiCatalog = defineUiCatalog({
 				}
 			}
 		},
+		{
+			name: "Progress",
+			group: "feedback",
+			description: "How far a long-running task has come, in percent.",
+			props: z.object({
+				label: z.string().optional(),
+				value: z.number().min(0).max(100),
+				tone: z.enum([
+					"neutral",
+					"success",
+					"warning"
+				]).default("neutral")
+			}),
+			example: {
+				component: "Progress",
+				props: {
+					label: "Indexing",
+					value: 42
+				}
+			}
+		},
 		{
 			name: "Alert",
 			group: "feedback",
@@ -860,6 +893,12 @@ const UI_CATALOG_GROUPS = {
 	data: DATA,
 	input: INPUT
 };
+/**
+* catalog 系统提示的体积上限（UTF-8 字节，FR-6.6）。
+* 描述每次请求都要重发，所以上限必须是可判定的数字而不是「尽量精简」。
+* 要改这个数字，先想清楚是否值得让每次请求都多付这些 token。
+*/
+const UI_CATALOG_PROMPT_BUDGET_BYTES = 20480;
 /** A2UI 协议公共类型（与 @a2ui/web_core 的 common-types 同一套定义） */
 const A2UI_COMMON_TYPES = "https://a2ui.org/specification/v0_9/common_types.json";
 const CHILD_LIST_REF = `${A2UI_COMMON_TYPES}#/$defs/ChildList`;
@@ -993,6 +1032,7 @@ function interactionToFormModel(request) {
 				...f.required ? { required: true } : {},
 				...f.description ? { description: f.description } : {},
 				...f.defaultValue !== void 0 ? { defaultValue: f.defaultValue } : {},
+				...f.suggestion ? { suggestion: f.suggestion } : {},
 				...f.options ? { options: f.options } : {}
 			})),
 			submitLabel: "Submit",
@@ -1067,16 +1107,247 @@ function collectValues(controls, container) {
 		missingRequired
 	};
 }
-/** RenderBlock → DOM（markdown/json/table/image/file/chart 六种） */
-function renderBlocks(container, blocks, doc) {
-	for (const block of blocks) switch (block.type) {
-		case "chart":
-			container.appendChild(renderMiniChart(block.chart, doc));
-			break;
-		case "markdown":
-			container.appendChild(renderMiniMarkdown(block.text, doc));
-			break;
-		case "json": {
+/**
+* 采纳建议值（FR-5.9）：把 `control.suggestion` 写进已渲染的控件。
+* 与 `collectValues` 共用同一套选择器与编码约定——两边分开实现的话，
+* select 的 JSON 编码值迟早会对不上。
+* @experimental
+*/
+function applySuggestion(control, container) {
+	if (control.suggestion === void 0) return;
+	const el = container.querySelector(controlSelector(control.name));
+	if (el === null) return;
+	const { value } = control.suggestion;
+	if (control.control === "boolean") {
+		el.checked = value === true;
+		return;
+	}
+	if (control.control === "select") {
+		el.value = JSON.stringify(value);
+		return;
+	}
+	el.value = value === void 0 || value === null ? "" : String(value);
+}
+/**
+* 轻量 SVG 图表自绘（bar/line/pie，零依赖，三端复用单一来源）。
+* 全部经 doc.createElementNS 构建（内容来自技能输出，不拼 innerHTML）。
+*/
+const SVG_NS = "http://www.w3.org/2000/svg";
+/** 固定 8 色循环调色板 */
+const CHART_PALETTE = [
+	"#4e79a7",
+	"#f28e2b",
+	"#e15759",
+	"#76b7b2",
+	"#59a14f",
+	"#edc948",
+	"#b07aa1",
+	"#ff9da7"
+];
+const WIDTH = 320;
+const HEIGHT = 200;
+function el(doc, name, attrs) {
+	const node = doc.createElementNS(SVG_NS, name);
+	for (const [key, value] of Object.entries(attrs)) node.setAttribute(key, value);
+	return node;
+}
+function text(doc, x, y, content, attrs = {}) {
+	const node = el(doc, "text", {
+		x: String(x),
+		y: String(y),
+		"font-size": "9",
+		fill: "#555",
+		...attrs
+	});
+	node.textContent = content;
+	return node;
+}
+const fmt = (n) => Number.isInteger(n) ? String(n) : n.toFixed(1);
+function maxValue(chart) {
+	let max = 0;
+	for (const s of chart.series) for (const v of s.data) if (v > max) max = v;
+	return max;
+}
+function renderBar(chart, svg, doc) {
+	const plot = {
+		x0: 30,
+		y0: 24,
+		x1: 312,
+		y1: 164
+	};
+	const max = maxValue(chart);
+	svg.appendChild(el(doc, "line", {
+		x1: String(plot.x0),
+		y1: String(plot.y0),
+		x2: String(plot.x0),
+		y2: String(plot.y1),
+		stroke: "#999"
+	}));
+	svg.appendChild(el(doc, "line", {
+		x1: String(plot.x0),
+		y1: String(plot.y1),
+		x2: String(plot.x1),
+		y2: String(plot.y1),
+		stroke: "#999"
+	}));
+	if (max <= 0 || chart.labels.length === 0 || chart.series.length === 0) return;
+	const groupWidth = (plot.x1 - plot.x0) / chart.labels.length;
+	const barWidth = Math.max(1, groupWidth / chart.series.length * .7);
+	chart.series.forEach((series, si) => {
+		const color = CHART_PALETTE[si % CHART_PALETTE.length];
+		series.data.forEach((value, li) => {
+			if (li >= chart.labels.length) return;
+			const height = (plot.y1 - plot.y0) * value / max;
+			const x = plot.x0 + li * groupWidth + (groupWidth - barWidth * chart.series.length) / 2 + si * barWidth;
+			const y = plot.y1 - height;
+			svg.appendChild(el(doc, "rect", {
+				x: String(x),
+				y: String(y),
+				width: String(barWidth),
+				height: String(height),
+				fill: color,
+				"data-series": series.name ?? String(si)
+			}));
+			if (chart.series.length === 1) svg.appendChild(text(doc, x + barWidth / 2, y - 2, fmt(value), { "text-anchor": "middle" }));
+		});
+	});
+	chart.labels.forEach((label, li) => {
+		svg.appendChild(text(doc, plot.x0 + li * groupWidth + groupWidth / 2, plot.y1 + 12, label, { "text-anchor": "middle" }));
+	});
+}
+function renderLine(chart, svg, doc) {
+	const plot = {
+		x0: 30,
+		y0: 24,
+		x1: 312,
+		y1: 164
+	};
+	const max = maxValue(chart);
+	svg.appendChild(el(doc, "line", {
+		x1: String(plot.x0),
+		y1: String(plot.y0),
+		x2: String(plot.x0),
+		y2: String(plot.y1),
+		stroke: "#999"
+	}));
+	svg.appendChild(el(doc, "line", {
+		x1: String(plot.x0),
+		y1: String(plot.y1),
+		x2: String(plot.x1),
+		y2: String(plot.y1),
+		stroke: "#999"
+	}));
+	if (max <= 0 || chart.labels.length === 0 || chart.series.length === 0) return;
+	const step = chart.labels.length > 1 ? (plot.x1 - plot.x0) / (chart.labels.length - 1) : 0;
+	const px = (li) => chart.labels.length > 1 ? plot.x0 + li * step : (plot.x0 + plot.x1) / 2;
+	const py = (v) => plot.y1 - (plot.y1 - plot.y0) * v / max;
+	chart.series.forEach((series, si) => {
+		const color = CHART_PALETTE[si % CHART_PALETTE.length];
+		const points = series.data.slice(0, chart.labels.length).map((v, li) => `${px(li)},${py(v)}`).join(" ");
+		if (points !== "") svg.appendChild(el(doc, "polyline", {
+			points,
+			fill: "none",
+			stroke: color,
+			"stroke-width": "1.5"
+		}));
+		series.data.slice(0, chart.labels.length).forEach((v, li) => {
+			svg.appendChild(el(doc, "circle", {
+				cx: String(px(li)),
+				cy: String(py(v)),
+				r: "2",
+				fill: color
+			}));
+		});
+	});
+	chart.labels.forEach((label, li) => {
+		svg.appendChild(text(doc, px(li), plot.y1 + 12, label, { "text-anchor": "middle" }));
+	});
+}
+function renderPie(chart, svg, doc) {
+	const data = (chart.series[0]?.data ?? []).slice(0, chart.labels.length);
+	const total = data.reduce((sum, v) => sum + (v > 0 ? v : 0), 0);
+	const cx = 90;
+	const cy = 104;
+	const r = 72;
+	if (total <= 0) {
+		svg.appendChild(text(doc, cx, cy, "No data", { "text-anchor": "middle" }));
+		return;
+	}
+	let angle = -Math.PI / 2;
+	data.forEach((value, i) => {
+		const label = chart.labels[i] ?? String(i);
+		const color = CHART_PALETTE[i % CHART_PALETTE.length];
+		const slice = Math.max(value, 0) / total * Math.PI * 2;
+		const x0 = cx + r * Math.cos(angle);
+		const y0 = cy + r * Math.sin(angle);
+		const x1 = cx + r * Math.cos(angle + slice);
+		const y1 = cy + r * Math.sin(angle + slice);
+		const path = el(doc, "path", {
+			d: `M ${cx} ${cy} L ${x0} ${y0} A ${r} ${r} 0 ${slice > Math.PI ? "1" : "0"} 1 ${x1} ${y1} Z`,
+			fill: color,
+			"data-label": label
+		});
+		svg.appendChild(path);
+		angle += slice;
+		const ly = 40 + i * 14;
+		svg.appendChild(el(doc, "rect", {
+			x: "190",
+			y: String(ly - 7),
+			width: "8",
+			height: "8",
+			fill: color
+		}));
+		svg.appendChild(text(doc, 202, ly, `${label} (${fmt(value)})`));
+	});
+}
+/**
+* ChartSpec → SVG（bar 等宽柱 + 值标签；line 折线 + 点；pie 扇形 + 图例；空数据容错）
+* @stable
+*/
+function renderMiniChart(chart, doc) {
+	const svg = el(doc, "svg", {
+		viewBox: `0 0 ${WIDTH} ${HEIGHT}`,
+		width: String(WIDTH),
+		height: String(HEIGHT),
+		class: `webskill-chart webskill-chart--${chart.kind}`,
+		role: "img"
+	});
+	if (chart.title) svg.appendChild(text(doc, WIDTH / 2, 14, chart.title, {
+		"text-anchor": "middle",
+		"font-size": "11",
+		fill: "#333"
+	}));
+	switch (chart.kind) {
+		case "bar":
+			renderBar(chart, svg, doc);
+			break;
+		case "line":
+			renderLine(chart, svg, doc);
+			break;
+		case "pie":
+			renderPie(chart, svg, doc);
+			break;
+	}
+	return svg;
+}
+/** A2UI/OpenUI 降级：chart → table（labels 为首列，series 各为一列） */
+function chartToTable(chart) {
+	return {
+		type: "table",
+		columns: ["label", ...chart.series.map((s, i) => s.name ?? `series ${i + 1}`)],
+		rows: chart.labels.map((label, li) => [label, ...chart.series.map((s) => s.data[li] ?? null)])
+	};
+}
+/** RenderBlock → DOM（markdown/json/table/image/file/chart 六种） */
+function renderBlocks(container, blocks, doc) {
+	for (const block of blocks) switch (block.type) {
+		case "chart":
+			container.appendChild(renderMiniChart(block.chart, doc));
+			break;
+		case "markdown":
+			container.appendChild(renderMiniMarkdown(block.text, doc));
+			break;
+		case "json": {
 			const pre = doc.createElement("pre");
 			pre.className = "webskill-result__json";
 			pre.textContent = JSON.stringify(block.data, null, 2);
@@ -1157,6 +1428,8 @@ const WEBSKILL_STYLES_CSS = `
 .webskill-form__error { font-size: 12px; color: #d33; display: none; }
 .webskill-form__control--invalid .webskill-form__error { display: block; }
 .webskill-form__input { padding: 6px 8px; border: 1px solid #bbb; border-radius: 4px; font-size: 14px; font-family: inherit; }
+.webskill-form__suggestion { display: flex; align-items: center; gap: 6px; font-size: 12px; color: #666; }
+.webskill-form__suggestion-use { padding: 1px 8px; border-radius: 4px; border: 1px solid #bbb; background: #fff; cursor: pointer; font-size: 12px; }
 .webskill-form__actions { display: flex; gap: 8px; margin-top: 12px; }
 .webskill-form__button { padding: 6px 14px; border-radius: 4px; border: 1px solid #bbb; background: #fff; cursor: pointer; font-size: 14px; }
 .webskill-form__button--primary { background: #2563eb; border-color: #2563eb; color: #fff; }
@@ -1350,6 +1623,7 @@ var WebFormBridge = class {
 		input.id = controlId;
 		input.setAttribute("aria-describedby", errorId);
 		wrapper.appendChild(input);
+		if (control.suggestion !== void 0) wrapper.appendChild(this.#renderSuggestion(control, wrapper));
 		const error = doc.createElement("div");
 		error.className = "webskill-form__error";
 		error.id = errorId;
@@ -1358,65 +1632,371 @@ var WebFormBridge = class {
 		wrapper.appendChild(error);
 		return wrapper;
 	}
+	/** 历史值以**建议**形态出现（FR-5.9）：控件初始值仍为空，点「使用」才写入 */
+	#renderSuggestion(control, container) {
+		const doc = this.#doc;
+		const row = doc.createElement("div");
+		row.className = "webskill-form__suggestion";
+		row.setAttribute("data-webskill-suggestion", control.name);
+		const preview = doc.createElement("span");
+		preview.className = "webskill-form__suggestion-value";
+		preview.textContent = `Last entered: ${String(control.suggestion?.value)}`;
+		row.appendChild(preview);
+		const use = doc.createElement("button");
+		use.type = "button";
+		use.className = "webskill-form__suggestion-use";
+		use.textContent = "Use";
+		use.setAttribute("data-webskill-suggestion-use", control.name);
+		use.addEventListener("click", () => applySuggestion(control, container));
+		row.appendChild(use);
+		return row;
+	}
 };
+function fieldNamesOf(form) {
+	const names = [];
+	const walk = (node) => {
+		const name = node.props?.["name"];
+		if (node.component === "Field" && typeof name === "string") names.push(name);
+		for (const child of node.children ?? []) walk(child);
+	};
+	walk(form);
+	return names;
+}
 /**
-* 保留的 custom 组件名：catalog 声明树整棵挂在这个 surface 上。
-* `UiSurface` 的六类联合表达不了通用节点树，改造它属破坏性变更（21 号文档 §7 已备案），
-* 因此本轮用一个保留 component 名承载，四档 registry 各自识别它。
+* 按出现序列出声明树里的每个 `Form`。
+*
+* 单表单时 action id 保持 `submit` / `cancel`，回传形状与容器级放宽前逐字节一致——
+* 向后兼容是 FR-6.3 的硬约束，不能让既有单表单卡片跟着改。
+* 多表单时每个表单拿到独立的 action id 与 `scopeId`，渲染层据此只收集本表单子树内的字段。
 */
-const UI_SPEC_COMPONENT = "webskill.ui-spec";
-function collectActions(node, out) {
-	if (node.component === "Button" && typeof node.props?.["action"] === "string") out.add(node.props["action"]);
-	if (node.component === "Form") {
-		out.add("submit");
-		if (typeof node.props?.["cancelLabel"] === "string") out.add("cancel");
-	}
-	for (const child of node.children ?? []) collectActions(child, out);
-}
-const INTENTS = /* @__PURE__ */ new Set([
-	"submit",
-	"cancel",
-	"select",
-	"download",
-	"refresh"
-]);
-/** 声明树 → `UiSurface`。id 缺省时由调用方给（工具源用 runtime 生成的 id）。 */
-function toSurface(catalog, spec, id) {
-	const names = /* @__PURE__ */ new Set();
-	collectActions(spec, names);
-	const actions = [...names].filter((name) => INTENTS.has(name)).map((intent) => ({
-		id: intent,
-		label: catalog.actions.find((action) => action.name === intent)?.name ?? intent,
-		intent,
-		...intent === "submit" ? { awaitResponse: true } : {}
-	}));
-	const props = {
-		catalogId: catalog.id,
-		catalogVersion: catalog.version,
-		spec,
-		actions: [...names]
-	};
-	return {
-		kind: "custom",
-		id,
-		component: UI_SPEC_COMPONENT,
-		props,
-		...actions.length > 0 ? { actions } : {}
+function collectFormScopes(spec) {
+	const forms = [];
+	const walk = (node) => {
+		if (node.component === "Form") forms.push(node);
+		for (const child of node.children ?? []) walk(child);
 	};
+	walk(spec);
+	if (forms.length === 1) {
+		const form = forms[0];
+		return [{
+			scopeId: form.id ?? "form",
+			submitActionId: "submit",
+			cancelActionId: "cancel",
+			fieldNames: fieldNamesOf(form),
+			form
+		}];
+	}
+	return forms.map((form, index) => {
+		const scopeId = form.id ?? `form-${index}`;
+		return {
+			scopeId,
+			submitActionId: `${scopeId}:submit`,
+			cancelActionId: `${scopeId}:cancel`,
+			fieldNames: fieldNamesOf(form),
+			form
+		};
+	});
 }
-/** surface 是否承载 catalog 声明树（四档 renderer 的分派入口） */
-function isUiSpecSurface(surface) {
-	return surface.kind === "custom" && surface.component === "webskill.ui-spec";
+/**
+* 多表单时字段值在渲染层的存储键。
+*
+* 跨表单重名过去不可能发生，容器级放宽后它变成合法输入：两个表单各有一个 `email`，
+* 共用一张扁平表就是后写的覆盖先写的，用户在 A 里输入会串到 B。
+* 因此多表单时按作用域限定键；单表单不加前缀，存储与草稿形状保持不变。
+*/
+function qualifyFieldName(name, scopeId) {
+	return scopeId === void 0 ? name : `${scopeId}.${name}`;
 }
 /**
-* catalog 声明树 → json-render 扁平 spec。纯数据变换，不 import json-render
-* （`@webskill/ui` 保持环境无关）。
+* 提交时回传的字段值。
+*
+* 不给 `scope` → 整张 surface 的扁平值，与容器级放宽前完全一致（FR-6.3 第 3 条）。
+* 给了 `scope` → 只取该表单子树内的字段，键回落成裸字段名，
+* 因此接收端看到的载荷形状与单表单时相同。
 */
-function toJsonRenderSpec(spec) {
-	const elements = {};
-	let counter = 0;
-	const walk = (node) => {
-		const key = node.id ?? `${node.component.toLowerCase()}-${counter++}`;
+function collectScopedValues(values, scope) {
+	if (!scope) return { ...values };
+	const out = {};
+	for (const name of scope.fieldNames) {
+		const key = qualifyFieldName(name, scope.scopeId);
+		if (key in values) out[name] = values[key];
+		else if (name in values) out[name] = values[name];
+	}
+	return out;
+}
+/** 五类场景预设（FR-6.4）。@experimental */
+const UI_PRESETS = [
+	{
+		name: "charts",
+		summary: "One question, one chart, with the takeaway spelled out above it.",
+		guidance: [
+			"Layout: `Card` → `Heading` (the takeaway, not \"Chart\") → `Chart` → optional `Text` for the caveat.",
+			"Pick the chart type from the question: `line` / `area` for time, `bar` for comparison, `pie` for shares.",
+			"Every series needs a name; labels and values must be the same length.",
+			"Never repeat the same numbers in a `Table` right under the chart."
+		].join("\n"),
+		example: {
+			component: "Card",
+			props: { title: "Revenue" },
+			children: [
+				{
+					component: "Heading",
+					props: {
+						level: 3,
+						text: "Revenue grew 27% in Q4"
+					}
+				},
+				{
+					component: "Chart",
+					props: {
+						type: "line",
+						labels: [
+							"Q1",
+							"Q2",
+							"Q3",
+							"Q4"
+						],
+						series: [{
+							name: "Revenue",
+							values: [
+								8,
+								9,
+								9.8,
+								12.4
+							]
+						}]
+					}
+				},
+				{
+					component: "Text",
+					props: {
+						text: "Figures in millions, unaudited.",
+						tone: "muted"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "cards",
+		summary: "A short list of comparable items, one `Card` each.",
+		guidance: [
+			"Layout: `Grid` (2 or 3 columns) → one `Card` per item.",
+			"Keep every card the same shape: title, one `Metric` or `Text`, at most one `Badge` for status.",
+			"Use `Grid` rather than a vertical `Stack` as soon as there are three or more items.",
+			"Put an action on a card only when the user can act on that single item."
+		].join("\n"),
+		example: {
+			component: "Grid",
+			props: { columns: 2 },
+			children: [{
+				component: "Card",
+				props: { title: "Checkout" },
+				children: [{
+					component: "Metric",
+					props: {
+						label: "Errors",
+						value: 12,
+						trend: "down"
+					}
+				}, {
+					component: "Badge",
+					props: {
+						text: "healthy",
+						tone: "success"
+					}
+				}]
+			}, {
+				component: "Card",
+				props: { title: "Search" },
+				children: [{
+					component: "Metric",
+					props: {
+						label: "Errors",
+						value: 143,
+						trend: "up"
+					}
+				}, {
+					component: "Badge",
+					props: {
+						text: "degraded",
+						tone: "warning"
+					}
+				}]
+			}]
+		}
+	},
+	{
+		name: "dashboards",
+		summary: "Headline numbers first, then detail, optionally split across `Tabs`.",
+		guidance: [
+			"Layout: `Stack` → `Grid` of `Metric` cards → `Chart` or `Table` for the detail.",
+			"Use `Tabs` when the detail splits into independent groups (filters, exports, alerts).",
+			"Each `Tabs` panel and each `Grid` cell is its own form container: at most one `Form` inside.",
+			"Show at most four headline metrics; anything more belongs in a `Table`."
+		].join("\n"),
+		example: {
+			component: "Stack",
+			children: [{
+				component: "Grid",
+				props: { columns: 2 },
+				children: [{
+					component: "Card",
+					props: { title: "MRR" },
+					children: [{
+						component: "Metric",
+						props: {
+							label: "This month",
+							value: "12,400",
+							trend: "up"
+						}
+					}]
+				}, {
+					component: "Card",
+					props: { title: "Churn" },
+					children: [{
+						component: "Metric",
+						props: {
+							label: "This month",
+							value: "2.1%",
+							trend: "down"
+						}
+					}]
+				}]
+			}, {
+				component: "Tabs",
+				props: { labels: ["Trend", "Breakdown"] },
+				children: [{
+					component: "Stack",
+					children: [{
+						component: "Chart",
+						props: {
+							type: "bar",
+							labels: ["Q3", "Q4"],
+							series: [{
+								name: "Revenue",
+								values: [9800, 12400]
+							}]
+						}
+					}]
+				}, {
+					component: "Stack",
+					children: [{
+						component: "Table",
+						props: {
+							columns: ["Region", "Revenue"],
+							rows: [["EMEA", 5400], ["AMER", 7e3]]
+						}
+					}]
+				}]
+			}]
+		}
+	},
+	{
+		name: "slides",
+		summary: "One idea per `Tabs` panel, headline plus at most three supporting lines.",
+		guidance: [
+			"Layout: `Tabs` → one `Stack` per slide, labelled with the slide title.",
+			"Each slide: one `Heading` (level 2) stating the point, then a `Chart`, `Metric` or short `Markdown` list.",
+			"Never put more than one idea on a slide; add a panel instead.",
+			"No `Form` inside slides — a deck is for reading, not for input."
+		].join("\n"),
+		example: {
+			component: "Tabs",
+			props: { labels: ["Where we are", "What we do next"] },
+			children: [{
+				component: "Stack",
+				children: [{
+					component: "Heading",
+					props: {
+						level: 2,
+						text: "Revenue grew 27% in Q4"
+					}
+				}, {
+					component: "Metric",
+					props: {
+						label: "Q4 revenue",
+						value: "12,400",
+						trend: "up"
+					}
+				}]
+			}, {
+				component: "Stack",
+				children: [{
+					component: "Heading",
+					props: {
+						level: 2,
+						text: "Double down on EMEA"
+					}
+				}, {
+					component: "Markdown",
+					props: { text: "- hire two AEs\n- localise pricing" }
+				}]
+			}]
+		}
+	},
+	{
+		name: "reports",
+		summary: "A long-form document: sections, tables and an optional `Timeline`.",
+		guidance: [
+			"Layout: `Stack` → `Heading` (level 2) → body → `Separator` between sections.",
+			"Use `Table` for figures, `Timeline` for what happened when, `Markdown` for prose.",
+			"Open with a one-paragraph summary before any detail.",
+			"Attach generated files with `FileLink` at the end rather than inlining raw data."
+		].join("\n"),
+		example: {
+			component: "Stack",
+			children: [
+				{
+					component: "Heading",
+					props: {
+						level: 2,
+						text: "Q4 incident review"
+					}
+				},
+				{
+					component: "Text",
+					props: { text: "Three incidents, all recovered within the hour." }
+				},
+				{ component: "Separator" },
+				{
+					component: "Timeline",
+					props: { items: [{
+						title: "Search latency spike",
+						time: "12 Nov",
+						state: "done"
+					}, {
+						title: "Checkout timeouts",
+						time: "03 Dec",
+						state: "done"
+					}] }
+				},
+				{
+					component: "FileLink",
+					props: {
+						path: "q4-incidents.csv",
+						label: "Full log",
+						size: 24117
+					}
+				}
+			]
+		}
+	}
+];
+const UI_PRESET_NAMES = UI_PRESETS.map((preset) => preset.name);
+/** Returns undefined for names outside the catalog presets. @experimental */
+function uiPreset(name) {
+	return UI_PRESETS.find((preset) => preset.name === name);
+}
+/**
+* catalog 声明树 → json-render 扁平 spec。纯数据变换，不 import json-render
+* （`@webskill/ui` 保持环境无关）。
+*/
+function toJsonRenderSpec(spec) {
+	const elements = {};
+	let counter = 0;
+	const walk = (node) => {
+		const key = node.id ?? `${node.component.toLowerCase()}-${counter++}`;
 		const children = (node.children ?? []).map(walk);
 		elements[key] = {
 			type: node.component,
@@ -1430,34 +2010,186 @@ function toJsonRenderSpec(spec) {
 		elements
 	};
 }
+/** ControlModel 的控件词汇 → catalog `Field.type`（catalog 的 8 种是超集） */
+const FIELD_TYPE = {
+	text: "text",
+	number: "number",
+	boolean: "toggle",
+	select: "select",
+	textarea: "textarea"
+};
+function toOptions(options) {
+	return (options ?? []).map((option) => ({
+		label: option.label,
+		value: typeof option.value === "number" ? option.value : String(option.value)
+	}));
+}
+function toField(control) {
+	return {
+		component: "Field",
+		props: {
+			name: control.name,
+			label: control.label,
+			type: FIELD_TYPE[control.control],
+			...control.required ? { required: true } : {},
+			...control.description ? { description: control.description } : {},
+			...control.defaultValue !== void 0 ? { defaultValue: control.defaultValue } : {},
+			...control.suggestion ? { suggestion: control.suggestion } : {},
+			...control.options ? { options: toOptions(control.options) } : {}
+		}
+	};
+}
+/**
+* 五类 `InteractionRequest` → catalog 声明树。
+*
+* 路径 A（runtime 发起的交互请求）与路径 B（模型产出的 surface）的差别只在「谁产出这棵树」；
+* 产出之后四档走的是同一条 spec 渲染路径，因此这份生成器全仓只写一份。
+*/
+function interactionToUiSpec(request, labels = {}) {
+	const model = interactionToFormModel(request);
+	const title = labels.title ?? model.title;
+	const cancelLabel = labels.cancelLabel ?? model.cancelLabel;
+	const form = {
+		component: "Form",
+		props: {
+			...title ? { title } : {},
+			submitLabel: labels.submitLabel ?? model.submitLabel,
+			...cancelLabel ? { cancelLabel } : {}
+		},
+		children: model.controls.map(toField)
+	};
+	if (model.controls.length > 0 || !model.message) return form;
+	return {
+		component: "Stack",
+		children: [{
+			component: "Text",
+			props: { text: model.message }
+		}, form]
+	};
+}
 const RENDER_UI_TOOL = "render_ui";
+const DESCRIBE_UI_PRESET_TOOL = "describe_ui_preset";
 const defaultId = () => `ui-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 /**
+* 工具描述只留一句指针：catalog 本体走 system 消息（C4）。
+* 工具 `description` 的长度上限与截断在各 provider 上不一致且是静默的，
+* 近 5000 字符的 catalog 放在那里，被截断时模型拿到的是半份规格而请求照样成功。
+*/
+const RENDER_UI_DESCRIPTION = [
+	"Render a UI for the answer instead of prose.",
+	"Use it for forms, tables, charts, metrics or file downloads.",
+	"The component catalog is in the system prompt."
+].join(" ");
+const INTENTS = /* @__PURE__ */ new Set([
+	"submit",
+	"cancel",
+	"select",
+	"download",
+	"refresh"
+]);
+function isIntent(value) {
+	return typeof value === "string" && INTENTS.has(value);
+}
+/**
+* 从节点树抽出 action 能力表。能力表走事件外壳而非树内：
+* 树是模型可写的，nonce 放进去就等于让模型自己签发能力。
+* action id 取节点 id；Button 未声明 id 时退回 intent 名（同 intent 只留一条）。
+* 表单的提交/取消取自作用域表：容器级放宽后一张 surface 可能有多个表单。
+*/
+function collectActions(node, out, scopes) {
+	if (node.component === "Button" && isIntent(node.props?.["action"])) {
+		const intent = node.props["action"];
+		const id = node.id ?? intent;
+		if (!out.has(id)) out.set(id, {
+			id,
+			intent,
+			...intent === "submit" ? { awaitResponse: true } : {}
+		});
+	}
+	const scope = scopes.get(node);
+	if (scope) {
+		if (!out.has(scope.submitActionId)) out.set(scope.submitActionId, {
+			id: scope.submitActionId,
+			intent: "submit",
+			awaitResponse: true
+		});
+		if (typeof node.props?.["cancelLabel"] === "string" && !out.has(scope.cancelActionId)) out.set(scope.cancelActionId, {
+			id: scope.cancelActionId,
+			intent: "cancel"
+		});
+	}
+	for (const child of node.children ?? []) collectActions(child, out, scopes);
+}
+/** 节点树声明的 action 能力表（renderer 据此生成按钮，runtime 据此签发 nonce）。@experimental */
+function collectSpecActions(spec) {
+	const actions = /* @__PURE__ */ new Map();
+	collectActions(spec, actions, new Map(collectFormScopes(spec).map((scope) => [scope.form, scope])));
+	return [...actions.values()];
+}
+/**
 * 把 catalog 变成一个工具的入参 Schema，让模型直接生成声明式 UI（21 号文档 §3）：
-* agentLoop / UiBridge / extractUiSurfaceEvents 全部零改动，装配处只多一个 externalTools 条目。
+* agentLoop / UiBridge / extractUiSpecEvents 全部零改动，装配处只多一个 externalTools 条目。
 */
 function createUiCatalogToolSource(options = {}) {
 	const catalog = options.catalog ?? uiCatalog;
 	const newSurfaceId = options.newSurfaceId ?? defaultId;
+	const presets = options.presets ? options.presets.flatMap((name) => uiPreset(name) ?? []) : UI_PRESETS;
+	const presetChoices = presets.map((preset) => `${preset.name} — ${preset.summary}`).join("\n");
+	const presetTool = () => ({
+		name: DESCRIBE_UI_PRESET_TOOL,
+		description: `Fetch the layout guidance for one scenario preset before calling ${RENDER_UI_TOOL}.\n${presetChoices}`,
+		inputSchema: {
+			type: "object",
+			properties: { preset: {
+				type: "string",
+				enum: presets.map((preset) => preset.name)
+			} },
+			required: ["preset"],
+			additionalProperties: false
+		}
+	});
+	const renderTool = () => ({
+		name: RENDER_UI_TOOL,
+		description: RENDER_UI_DESCRIPTION,
+		inputSchema: {
+			type: "object",
+			properties: {
+				spec: catalog.toJsonSchema(),
+				...presets.length > 0 ? { preset: {
+					type: "string",
+					enum: presets.map((preset) => preset.name),
+					description: `Scenario preset this surface follows; call ${DESCRIBE_UI_PRESET_TOOL} first for its layout guidance.`
+				} } : {}
+			},
+			required: ["spec"],
+			additionalProperties: false
+		}
+	});
 	return {
 		kind: "ui-catalog",
-		listToolSpecs: () => Promise.resolve([{
-			name: RENDER_UI_TOOL,
-			description: [
-				"Render a user interface for the answer instead of describing it in prose.",
-				"Call it when the user asks for a form, a table, a chart, a metric or a file download.",
-				"",
-				catalog.toPrompt({ mode: "tool-description" })
-			].join("\n"),
-			inputSchema: {
-				type: "object",
-				properties: { spec: catalog.toJsonSchema() },
-				required: ["spec"],
-				additionalProperties: false
+		systemPrompt: () => Promise.resolve(catalog.toPrompt()),
+		listToolSpecs: () => Promise.resolve(presets.length > 0 ? [renderTool(), presetTool()] : [renderTool()]),
+		canHandle: (name) => name === "render_ui" || presets.length > 0 && name === "describe_ui_preset",
+		call: (name, args) => {
+			if (name === "describe_ui_preset") {
+				const requested = args["preset"];
+				const preset = presets.find((candidate) => candidate.name === requested);
+				if (!preset) return Promise.resolve({
+					ok: false,
+					content: [],
+					error: {
+						code: "VALIDATION_FAILED",
+						message: `Unknown UI preset "${String(requested)}"; available presets: ${presets.map((candidate) => candidate.name).join(", ")}`
+					}
+				});
+				return Promise.resolve({
+					ok: true,
+					content: [{
+						type: "text",
+						text: `${preset.guidance}\n\nExample spec:\n${JSON.stringify(preset.example)}`
+					}]
+				});
 			}
-		}]),
-		canHandle: (name) => name === RENDER_UI_TOOL,
-		call: (_name, args) => {
 			const spec = args["spec"];
 			const result = catalog.validate(spec);
 			if (!result.ok) return Promise.resolve({
@@ -1468,65 +2200,28 @@ function createUiCatalogToolSource(options = {}) {
 					message: `The UI spec does not match the catalog: ${result.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`
 				}
 			});
-			const surface = toSurface(catalog, spec, newSurfaceId());
+			const node = spec;
+			const surfaceId = newSurfaceId();
+			const actions = collectSpecActions(node);
 			return Promise.resolve({
 				ok: true,
 				content: [{
 					type: "json",
 					data: { $surface: {
 						type: "open",
-						surface
+						id: surfaceId,
+						node,
+						...actions.length > 0 ? { actions } : {}
 					} }
 				}, {
 					type: "text",
-					text: `Rendered surface ${surface.id}.`
+					text: `Rendered surface ${surfaceId}.`
 				}]
 			});
 		}
 	};
 }
-const WEBSKILL_SURFACE_ACTION = "webskill:surface-action";
-function toUiSurfaceDescriptor(snapshot, provenance) {
-	return {
-		type: "webskill-surface",
-		snapshot,
-		provenance
-	};
-}
-function toUiSurfaceActionDispatch(snapshot, action, value) {
-	return {
-		...snapshot.runId ? { runId: snapshot.runId } : {},
-		surfaceId: snapshot.surface.id,
-		actionId: action.id,
-		intent: action.intent,
-		...action.nonce ? { nonce: action.nonce } : {},
-		...value ? { value } : {}
-	};
-}
-/** Returns undefined for malformed or non-WebSkill renderer events. @experimental */
-function fromUiSurfaceActionDispatch(value) {
-	if (typeof value !== "object" || value === null) return void 0;
-	const event = value;
-	if (typeof event["surfaceId"] !== "string" || typeof event["actionId"] !== "string" || !isSurfaceActionIntent(event["intent"])) return;
-	return {
-		...typeof event["runId"] === "string" ? { runId: event["runId"] } : {},
-		surfaceId: event["surfaceId"],
-		actionId: event["actionId"],
-		intent: event["intent"],
-		...typeof event["nonce"] === "string" ? { nonce: event["nonce"] } : {},
-		...isRecord(event["value"]) ? { value: event["value"] } : {},
-		...event["cancelled"] === true ? { cancelled: true } : {}
-	};
-}
-function isSurfaceActionIntent(value) {
-	return value === "submit" || value === "cancel" || value === "select" || value === "download" || value === "refresh";
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 const VERCEL_INTERACTION_TOOL_NAME = "webskill_interaction";
-const VERCEL_SURFACE_DATA_PART_TYPE = "data-webskill-surface";
-const VERCEL_SURFACE_ACTION_DATA_PART_TYPE = WEBSKILL_SURFACE_ACTION;
 /** InteractionRequest → SDK tool UI 结构（应用聊天 UI 直接消费） */
 function toVercelToolInvocation(request) {
 	return {
@@ -1549,20 +2244,6 @@ function fromVercelToolResult(part) {
 		value: p["output"] ?? p["result"] ?? p["value"]
 	};
 }
-/** UiSurfaceSnapshot → AI SDK data part; the SurfaceHost owns renderer selection. @experimental */
-function toVercelSurfaceDataPart(snapshot) {
-	return {
-		type: VERCEL_SURFACE_DATA_PART_TYPE,
-		id: `webskill-surface-${snapshot.surface.id}`,
-		data: toUiSurfaceDescriptor(snapshot, "vercel-surface-host")
-	};
-}
-/** Decodes a nonce-bound action data part emitted by a Vercel SurfaceHost. @experimental */
-function fromVercelSurfaceAction(part) {
-	const event = part;
-	if (event?.type !== "webskill:surface-action") return void 0;
-	return fromUiSurfaceActionDispatch(event.data);
-}
 /**
 * 薄桥接类：request → SDK tool UI 结构 → 应用的聊天 UI（sendInteraction 回调实现）
 * → SDK 回传 → InteractionResponse。
@@ -1576,154 +2257,6 @@ var VercelUiBridge = class {
 		return fromVercelToolResult(await this.#sendInteraction(toVercelToolInvocation(input)));
 	}
 };
-/**
-* InteractionRequest ↔ openui-lang 双向转换。
-* openui-lang 语法（@openuidev/react-lang 实测）：
-* - 每行一条语句 `identifier = Expression`，`root = Component(...)` 为入口
-* - 组件调用参数为位置参数；字符串双引号反斜杠转义
-* - 组件词汇（与应用 Library 约定）：Form(title, children)、
-*   Text(content)（纯展示文本，authorize 的能力描述用）、
-*   TextField(name, label, required?, defaultValue?)、NumberField、BooleanField(name, label, default?)、
-*   SelectField(name, label, options)、SubmitButton(label, actionType, requestId)、
-*   CancelButton(label, actionType, requestId)
-*/
-const OPENUI_SUBMIT_ACTION = "webskill:submit";
-const OPENUI_CANCEL_ACTION = "webskill:cancel";
-/** authorize 的 Allow 专用动作（提交即批准 → value:true；Deny 走 cancel → cancelled:true） */
-const OPENUI_AUTHORIZE_ACTION = "webskill:authorize";
-const OPENUI_SURFACE_ACTION = WEBSKILL_SURFACE_ACTION;
-const str = (s) => JSON.stringify(s);
-const val = (v) => JSON.stringify(v ?? null);
-function fieldStatements(fields) {
-	return fields.map((f, i) => {
-		const id = `f${i}`;
-		const required = f.required ? ", true" : "";
-		switch (f.control) {
-			case "number": return `${id} = NumberField(${str(f.name)}, ${str(f.label)}${required})`;
-			case "boolean": return `${id} = BooleanField(${str(f.name)}, ${str(f.label)}${f.defaultValue !== void 0 ? `, ${val(f.defaultValue)}` : ""})`;
-			case "select": return `${id} = SelectField(${str(f.name)}, ${str(f.label)}, ${val(f.options ?? [])})`;
-			case "textarea": return `${id} = TextField(${str(f.name)}, ${str(f.label)}${required})`;
-			default: {
-				const args = [str(f.name), str(f.label)];
-				if (f.required || f.defaultValue !== void 0) args.push(f.required ? "true" : "null");
-				if (f.defaultValue !== void 0) args.push(val(f.defaultValue));
-				return `${id} = TextField(${args.join(", ")})`;
-			}
-		}
-	});
-}
-/** @experimental */
-function toOpenUiLang(request) {
-	const lines = [];
-	let fields = [];
-	let title = null;
-	switch (request.type) {
-		case "ask":
-			title = "Question";
-			fields = [{
-				name: "answer",
-				label: request.message,
-				control: "text",
-				required: true
-			}];
-			break;
-		case "confirm":
-			title = "Confirm";
-			fields = [{
-				name: "confirmed",
-				label: request.message,
-				control: "boolean",
-				defaultValue: request.defaultValue ?? true
-			}];
-			break;
-		case "form":
-			title = request.title ?? "Form";
-			fields = request.fields.map((f) => ({
-				name: f.name,
-				label: f.label,
-				control: f.type,
-				...f.required ? { required: true } : {},
-				...f.defaultValue !== void 0 ? { defaultValue: f.defaultValue } : {},
-				...f.options ? { options: f.options } : {}
-			}));
-			break;
-		case "select":
-			title = "Select";
-			fields = [{
-				name: "selected",
-				label: request.message,
-				control: "select",
-				options: request.options
-			}];
-			break;
-		case "authorize":
-			title = "Authorization required";
-			fields = [];
-			break;
-	}
-	lines.push(...fieldStatements(fields));
-	const children = fields.map((_, i) => `f${i}`);
-	const isAuthorize = request.type === "authorize";
-	if (isAuthorize) {
-		lines.push(`message = Text(${str(request.message)})`);
-		children.push("message");
-	}
-	const submitAction = isAuthorize ? OPENUI_AUTHORIZE_ACTION : OPENUI_SUBMIT_ACTION;
-	lines.push(`submit = SubmitButton(${str(isAuthorize ? "Allow" : "Submit")}, ${str(submitAction)}, ${str(request.id)})`);
-	lines.push(`cancel = CancelButton(${str(isAuthorize ? "Deny" : "Cancel")}, ${str(OPENUI_CANCEL_ACTION)}, ${str(request.id)})`);
-	lines.push(`root = Form(${val(title)}, [${[
-		...children,
-		"submit",
-		"cancel"
-	].join(", ")}])`);
-	return lines.join("\n");
-}
-/**
-* UiSurfaceSnapshot → OpenUI library program. OpenUI applications provide WebSkillSurfaceHost;
-* its descriptor tells the host whether it is a native extension rather than an OpenUI-native component.
-* @experimental
-*/
-function toOpenUiSurfaceLang(snapshot) {
-	const descriptor = toUiSurfaceDescriptor(snapshot, snapshot.surface.kind === "chart" || snapshot.surface.kind === "table" || snapshot.surface.kind === "custom" ? "openui-extension" : "openui-library");
-	return `root = WebSkillSurfaceHost(${val(descriptor)})`;
-}
-/** Decodes a nonce-bound action emitted by an OpenUI WebSkillSurfaceHost. @experimental */
-function fromOpenUiSurfaceAction(action) {
-	const event = action;
-	if (event?.type !== "webskill:surface-action") return void 0;
-	return fromUiSurfaceActionDispatch(event.params);
-}
-/**
-* OpenUI ActionEvent → InteractionResponse（formState 优先，取消单独分支）
-* @experimental
-*/
-function fromOpenUiAction(action) {
-	const a = action ?? {};
-	const id = String(a.params?.["id"] ?? "");
-	if (a.type === "webskill:cancel") return {
-		id,
-		cancelled: true
-	};
-	if (a.type === "webskill:authorize") return {
-		id,
-		value: true
-	};
-	if (a.type === "webskill:submit") {
-		const formState = a.formState;
-		if (formState) return {
-			id,
-			value: Object.fromEntries(Object.entries(formState).map(([key, v]) => [key, typeof v === "object" && v !== null && "value" in v ? v.value : v]))
-		};
-		return {
-			id,
-			value: a.params?.["values"]
-		};
-	}
-	return {
-		id,
-		value: a.params
-	};
-}
 const literal = (value) => JSON.stringify(value ?? null);
 /** 组件的位置参数顺序 = catalog props 的 schema key 顺序（OpenUI 的 param map 同源） */
 function propOrder(catalog) {
@@ -1756,194 +2289,52 @@ function toOpenUiSpecLang(spec, catalog = uiCatalog) {
 	const rootId = walk(spec);
 	return [...lines.filter((line) => !line.startsWith(`${rootId} =`)), `root = ${lines.find((line) => line.startsWith(`${rootId} =`)).slice(rootId.length + 3)}`].join("\n");
 }
+const WEBSKILL_SURFACE_ACTION = "webskill:surface-action";
+function toUiSurfaceActionDispatch(snapshot, action, value, scopeId) {
+	return {
+		...snapshot.runId ? { runId: snapshot.runId } : {},
+		surfaceId: snapshot.id,
+		actionId: action.id,
+		intent: action.intent,
+		...action.nonce ? { nonce: action.nonce } : {},
+		...scopeId ? { scopeId } : {},
+		...value ? { value } : {}
+	};
+}
+/** Returns undefined for malformed or non-WebSkill renderer events. @experimental */
+function fromUiSurfaceActionDispatch(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const event = value;
+	if (typeof event["surfaceId"] !== "string" || typeof event["actionId"] !== "string" || !isSurfaceActionIntent(event["intent"])) return;
+	return {
+		...typeof event["runId"] === "string" ? { runId: event["runId"] } : {},
+		surfaceId: event["surfaceId"],
+		actionId: event["actionId"],
+		intent: event["intent"],
+		...typeof event["nonce"] === "string" ? { nonce: event["nonce"] } : {},
+		...typeof event["scopeId"] === "string" ? { scopeId: event["scopeId"] } : {},
+		...isRecord(event["value"]) ? { value: event["value"] } : {},
+		...event["cancelled"] === true ? { cancelled: true } : {}
+	};
+}
+function isSurfaceActionIntent(value) {
+	return value === "submit" || value === "cancel" || value === "select" || value === "download" || value === "refresh";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /**
-* InteractionRequest → A2UI 协议消息（v0.9.1，Basic Catalog）。
+* A2UI 协议常量与 surface 动作编解码（v0.9.1）。
 * 依据 https://a2ui.org/specification/v0.9-a2ui/：
 * - 信封 {version, createSurface|updateComponents|updateDataModel|deleteSurface}
 * - 组件为扁平邻接表（id 引用），root 必需
 * - 输入组件与数据模型经 JSON Pointer 双向绑定；action.context 回传
-* - createSurface.sendDataModel: true → 客户端动作时携带完整数据模型
 *
-* action 约定：submit → {name: 'webskill:submit', context: {requestId}}；
-* cancel → {name: 'webskill:cancel', context: {requestId}}。
+* 声明树 → A2UI 消息的转换在 `specToA2ui.ts`（四档共用的单一渲染路径）。
 */
 const A2UI_VERSION = "v0.9.1";
 const A2UI_BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json";
-const A2UI_SUBMIT_ACTION = "webskill:submit";
-const A2UI_CANCEL_ACTION = "webskill:cancel";
 const A2UI_SURFACE_ACTION = WEBSKILL_SURFACE_ACTION;
-const text = (id, content, variant) => ({
-	id,
-	component: "Text",
-	text: content,
-	...variant ? { variant } : {}
-});
-/** @experimental */
-function toA2uiMessages(request) {
-	const surfaceId = `webskill-${request.id}`;
-	const components = [];
-	const children = [];
-	const defaults = {};
-	if (request.type === "form" && request.title) {
-		components.push(text("title", request.title, "h3"));
-		children.push("title");
-	}
-	if (request.type === "authorize") {
-		components.push(text("title", "Authorization required", "h3"));
-		children.push("title");
-	}
-	const message = request.type === "ask" || request.type === "confirm" || request.type === "select" || request.type === "authorize" ? request.message : void 0;
-	if (message) {
-		components.push(text("message", message));
-		children.push("message");
-	}
-	const fields = request.type === "form" ? request.fields.map((f) => ({ ...f })) : request.type === "ask" ? [{
-		name: "answer",
-		label: request.message,
-		type: "text",
-		required: true
-	}] : request.type === "confirm" ? [{
-		name: "confirmed",
-		label: request.message,
-		type: "boolean",
-		defaultValue: request.defaultValue ?? true
-	}] : request.type === "authorize" ? [] : [{
-		name: "selected",
-		label: request.message,
-		type: "select",
-		options: request.options
-	}];
-	for (const field of fields) {
-		const path = `/form/${field.name}`;
-		if (field.defaultValue !== void 0) defaults[field.name] = field.defaultValue;
-		const checks = field.required ? [{
-			call: "required",
-			args: { value: { path } },
-			message: `${field.label} is required`
-		}] : void 0;
-		if (field.type === "boolean") components.push({
-			id: `field_${field.name}`,
-			component: "CheckBox",
-			label: field.label,
-			value: { path },
-			...checks ? { checks } : {}
-		});
-		else if (field.type === "select") components.push({
-			id: `field_${field.name}`,
-			component: "ChoicePicker",
-			variant: "mutuallyExclusive",
-			label: field.label,
-			options: (field.options ?? []).map((o) => ({
-				label: o.label,
-				value: typeof o.value === "string" ? o.value : JSON.stringify(o.value)
-			})),
-			value: { path },
-			...checks ? { checks } : {}
-		});
-		else components.push({
-			id: `field_${field.name}`,
-			component: "TextField",
-			label: field.label,
-			value: { path },
-			variant: field.type === "textarea" ? "longText" : "shortText",
-			...checks ? { checks } : {}
-		});
-		children.push(`field_${field.name}`);
-	}
-	components.push(text("submit_label", request.type === "authorize" ? "Allow" : "Submit"));
-	components.push({
-		id: "submit",
-		component: "Button",
-		child: "submit_label",
-		variant: "primary",
-		action: { event: {
-			name: A2UI_SUBMIT_ACTION,
-			context: { requestId: request.id }
-		} }
-	});
-	components.push(text("cancel_label", request.type === "authorize" ? "Deny" : "Cancel"));
-	components.push({
-		id: "cancel",
-		component: "Button",
-		child: "cancel_label",
-		variant: "borderless",
-		action: { event: {
-			name: A2UI_CANCEL_ACTION,
-			context: { requestId: request.id }
-		} }
-	});
-	children.push("submit", "cancel");
-	components.unshift({
-		id: "root",
-		component: "Column",
-		children,
-		justify: "start",
-		align: "stretch"
-	});
-	const messages = [{
-		version: A2UI_VERSION,
-		createSurface: {
-			surfaceId,
-			catalogId: A2UI_BASIC_CATALOG_ID,
-			sendDataModel: true
-		}
-	}, {
-		version: A2UI_VERSION,
-		updateComponents: {
-			surfaceId,
-			components
-		}
-	}];
-	if (Object.keys(defaults).length > 0) messages.push({
-		version: A2UI_VERSION,
-		updateDataModel: {
-			surfaceId,
-			path: "/form",
-			value: defaults
-		}
-	});
-	return messages;
-}
-/**
-* UiSurfaceSnapshot → A2UI extension-host messages.
-* Basic Catalog has no chart/table vocabulary, so a labelled WebSkill host owns these controlled renderers.
-* @experimental
-*/
-function toA2uiSurfaceMessages(snapshot) {
-	const surfaceId = `webskill-surface-${snapshot.surface.id}`;
-	const standard = snapshot.surface.kind === "metric" || snapshot.surface.kind === "file";
-	const descriptor = toUiSurfaceDescriptor(snapshot, standard ? "a2ui-standard" : "a2ui-extension");
-	const component = standard ? {
-		id: "content",
-		component: "Text",
-		text: snapshot.surface.kind === "metric" ? `${snapshot.surface.label}: ${snapshot.surface.value}` : snapshot.surface.kind === "file" ? snapshot.surface.path : ""
-	} : {
-		id: "content",
-		component: "WebSkillSurfaceHost",
-		descriptor,
-		provenance: "WebSkill extension host"
-	};
-	return [{
-		version: A2UI_VERSION,
-		createSurface: {
-			surfaceId,
-			catalogId: A2UI_BASIC_CATALOG_ID,
-			sendDataModel: true
-		}
-	}, {
-		version: A2UI_VERSION,
-		updateComponents: {
-			surfaceId,
-			components: [{
-				id: "root",
-				component: "Column",
-				children: ["content"],
-				justify: "start",
-				align: "stretch"
-			}, component]
-		}
-	}];
-}
 /** Decodes a nonce-bound action emitted by a WebSkill A2UI extension host. @experimental */
 function fromA2uiSurfaceAction(event) {
 	const action = event;
@@ -1951,80 +2342,10 @@ function fromA2uiSurfaceAction(event) {
 	return fromUiSurfaceActionDispatch(action.context);
 }
 /** Builds the A2UI event payload an extension host sends after a user action. @experimental */
-function toA2uiSurfaceAction(snapshot, action, value) {
+function toA2uiSurfaceAction(snapshot, action, value, scopeId) {
 	return {
 		name: A2UI_SURFACE_ACTION,
-		context: toUiSurfaceActionDispatch(snapshot, action, value)
-	};
-}
-/**
-* 按 InteractionRequest.type 解码提交值（绑定模型原样回传的是表单对象）：
-* confirm 仅 confirmed===true 批准；select 还原原始 option 值（非字符串值经 JSON 编码比对）；
-* form 的 number 字段转 number（NaN 保留原值）；ask 取 answer；authorize 提交即批准。
-* 纯转换器：任何直接使用 fromA2uiAction 的消费者都应经此拿到正确类型。
-* @experimental
-*/
-function decodeInteractionResponse(request, response) {
-	if (response.cancelled) return response;
-	const values = response.value;
-	switch (request.type) {
-		case "confirm": return {
-			...response,
-			value: values?.confirmed === true
-		};
-		case "ask": return {
-			...response,
-			value: values?.answer
-		};
-		case "select": {
-			const raw = values?.selected;
-			const option = request.options.find((o) => o.value === raw || JSON.stringify(o.value) === raw);
-			return {
-				...response,
-				value: option ? option.value : raw
-			};
-		}
-		case "form": {
-			if (typeof values !== "object" || values === null) return response;
-			const out = { ...values };
-			for (const field of request.fields) if (field.type === "number" && out[field.name] !== void 0) {
-				const n = Number(out[field.name]);
-				if (!Number.isNaN(n)) out[field.name] = n;
-			}
-			return {
-				...response,
-				value: out
-			};
-		}
-		case "authorize": return {
-			...response,
-			value: true
-		};
-		default: return response;
-	}
-}
-/**
-* A2UI client→server action 事件 → InteractionResponse。
-* 传入 request 时按类型解码提交值（见 decodeInteractionResponse）。
-* @experimental
-*/
-function fromA2uiAction(event, request) {
-	const e = event ?? {};
-	const id = String(e.context?.["requestId"] ?? "");
-	if (e.name === "webskill:cancel") return {
-		id,
-		cancelled: true
-	};
-	if (e.name === "webskill:submit") {
-		const response = {
-			id,
-			value: e.context?.["values"] ?? e.context?.["form"] ?? e.context
-		};
-		return request ? decodeInteractionResponse(request, response) : response;
-	}
-	return {
-		id,
-		value: e.context
+		context: toUiSurfaceActionDispatch(snapshot, action, value, scopeId)
 	};
 }
 /** 声明树里按钮触发的事件名（宿主据 context.actionId 回传 surface action） */
@@ -2122,73 +2443,6 @@ function fromA2uiSpecAction(event) {
 		context
 	};
 }
-let loading;
-function loadA2uiRuntime() {
-	loading ??= (async () => {
-		try {
-			const [core, lit] = await Promise.all([import("@a2ui/web_core/v0_9"), import("@a2ui/lit/v0_9")]);
-			lit.A2uiSurface;
-			return {
-				MessageProcessor: core.MessageProcessor,
-				basicCatalog: lit.basicCatalog
-			};
-		} catch (e) {
-			throw new WebSkillError("UI_UNAVAILABLE", "The A2UI Lit runtime is unavailable; install @a2ui/lit and @a2ui/web_core to use LitRendererBridge", e);
-		}
-	})();
-	return loading;
-}
-/** @experimental */
-var LitRendererBridge = class {
-	#mount;
-	#doc;
-	/** 进行中的交互：id → resolve 与 surface 元素（cancel 时清理并以 cancelled resolve） */
-	#pending = /* @__PURE__ */ new Map();
-	constructor(deps) {
-		this.#mount = deps.mount;
-		this.#doc = deps.document ?? deps.mount.ownerDocument;
-	}
-	async request(input) {
-		const { MessageProcessor, basicCatalog } = await loadA2uiRuntime();
-		const messages = toA2uiMessages(input);
-		const surfaceId = `webskill-${input.id}`;
-		return new Promise((resolve) => {
-			const entry = { resolve };
-			this.#pending.set(input.id, entry);
-			const processor = new MessageProcessor([basicCatalog], (action) => {
-				const surfaces = processor.getClientDataModel("v0.9.1")?.surfaces;
-				const formValues = typeof surfaces?.[surfaceId] === "object" && surfaces[surfaceId] !== null ? surfaces[surfaceId]["form"] ?? action.context : action.context;
-				this.#pending.delete(input.id);
-				entry.surfaceEl?.remove();
-				resolve(fromA2uiAction({
-					...action,
-					context: {
-						...action.context,
-						values: formValues
-					}
-				}, input));
-			}, { version: "v0.9.1" });
-			processor.onSurfaceCreated((surface) => {
-				const el = this.#doc.createElement("a2ui-surface");
-				el.surface = surface;
-				entry.surfaceEl = el;
-				this.#mount.appendChild(el);
-			});
-			processor.processMessages(messages);
-		});
-	}
-	/** runtime 交互超时/取消：移除 surface 并以 cancelled resolve pending Promise（防悬挂 + DOM 残留） */
-	cancel(id) {
-		const entry = this.#pending.get(id);
-		if (!entry) return;
-		this.#pending.delete(id);
-		entry.surfaceEl?.remove();
-		entry.resolve({
-			id,
-			cancelled: true
-		});
-	}
-};
 /**
 * BYOC Lit 元素的加载入口。
 *
@@ -2198,7 +2452,7 @@ var LitRendererBridge = class {
 */
 async function loadWebSkillLitCatalog() {
 	try {
-		const { webskillLitCatalog } = await import("./webskillLitCatalog-CNaUpasU-BslMcxRZ.js");
+		const { webskillLitCatalog } = await import("./webskillLitCatalog-_mugzRHx-DiuJpCuf.js");
 		return webskillLitCatalog();
 	} catch (cause) {
 		throw new WebSkillError("UI_UNAVAILABLE", "The WebSkill A2UI catalog is unavailable; install @a2ui/lit, @a2ui/web_core and lit to render catalog surfaces with A2UI", cause);
@@ -2223,4 +2477,4 @@ async function loadOpenUiPeers() {
 }
 
 //#endregion
-export { toVercelToolInvocation as $, fromOpenUiSurfaceAction as A, shapeInteractionValue as B, createUiCatalogToolSource as C, fromA2uiSpecAction as D, fromA2uiAction as E, isUiSpecSurface as F, toJsonRenderSpec as G, toA2uiSpecMessages as H, loadOpenUiPeers as I, toOpenUiSurfaceLang as J, toOpenUiLang as K, loadWebSkillLitCatalog as L, fromVercelSurfaceAction as M, fromVercelToolResult as N, fromA2uiSurfaceAction as O, interactionToFormModel as P, toVercelSurfaceDataPart as Q, renderBlocks as R, collectValues as S, ensureStyles as T, toA2uiSurfaceAction as U, toA2uiMessages as V, toA2uiSurfaceMessages as W, toUiSurfaceActionDispatch as X, toSurface as Y, toUiSurfaceDescriptor as Z, VERCEL_SURFACE_DATA_PART_TYPE as _, A2UI_SUBMIT_ACTION as a, a2uiComponentSchema as at, WEBSKILL_SURFACE_ACTION as b, LitRendererBridge as c, chartToTable as ct, OPENUI_SUBMIT_ACTION as d, renderMiniMarkdown as dt, A2UI_CHILDREN_PROP as et, OPENUI_SURFACE_ACTION as f, uiCatalog as ft, VERCEL_SURFACE_ACTION_DATA_PART_TYPE as g, VERCEL_INTERACTION_TOOL_NAME as h, A2UI_SPEC_FORM_PATH as i, WEBSKILL_A2UI_CATALOG_ID as it, fromUiSurfaceActionDispatch as j, fromOpenUiAction as k, OPENUI_AUTHORIZE_ACTION as l, defineUiCatalog as lt, UI_SPEC_COMPONENT as m, A2UI_CANCEL_ACTION as n, CHART_PALETTE as nt, A2UI_SURFACE_ACTION as o, a2uiComponentShapes as ot, RENDER_UI_TOOL as p, toOpenUiSpecLang as q, A2UI_SPEC_ACTION as r, UI_CATALOG_GROUPS as rt, A2UI_VERSION as s, buildA2uiCatalogDefinition as st, A2UI_BASIC_CATALOG_ID as t, A2UI_COMMON_TYPES as tt, OPENUI_CANCEL_ACTION as u, renderMiniChart as ut, VercelUiBridge as v, decodeInteractionResponse as w, WebFormBridge as x, WEBSKILL_STYLES_CSS as y, renderRenderResult as z };
+export { defineUiCatalog as $, loadOpenUiPeers as A, toOpenUiSpecLang as B, ensureStyles as C, fromVercelToolResult as D, fromUiSurfaceActionDispatch as E, renderRenderResult as F, A2UI_COMMON_TYPES as G, toVercelToolInvocation as H, shapeInteractionValue as I, WEBSKILL_A2UI_CATALOG_ID as J, UI_CATALOG_GROUPS as K, toA2uiSpecMessages as L, qualifyFieldName as M, renderBlocks as N, interactionToFormModel as O, renderMiniChart as P, chartSpecFromProps as Q, toA2uiSurfaceAction as R, createUiCatalogToolSource as S, fromA2uiSurfaceAction as T, uiPreset as U, toUiSurfaceActionDispatch as V, A2UI_CHILDREN_PROP as W, a2uiComponentShapes as X, a2uiComponentSchema as Y, buildA2uiCatalogDefinition as Z, chartToTable as _, A2UI_VERSION as a, collectSpecActions as b, RENDER_UI_TOOL as c, VERCEL_INTERACTION_TOOL_NAME as d, mountEchart as et, VercelUiBridge as f, applySuggestion as g, WebFormBridge as h, A2UI_SURFACE_ACTION as i, loadWebSkillLitCatalog as j, interactionToUiSpec as k, UI_PRESETS as l, WEBSKILL_SURFACE_ACTION as m, A2UI_SPEC_ACTION as n, uiCatalog as nt, CHART_PALETTE as o, WEBSKILL_STYLES_CSS as p, UI_CATALOG_PROMPT_BUDGET_BYTES as q, A2UI_SPEC_FORM_PATH as r, DESCRIBE_UI_PRESET_TOOL as s, A2UI_BASIC_CATALOG_ID as t, renderMiniMarkdown as tt, UI_PRESET_NAMES as u, collectFormScopes as v, fromA2uiSpecAction as w, collectValues as x, collectScopedValues as y, toJsonRenderSpec as z };