@webskill/sdk 0.4.0 → 0.5.0

package/dist/{dist-D9Lcn5Pp.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-CpIg33vd.js
+//#region ../ui/dist/webskillCatalog-B-IQxOKs.js
 /**
 * 最小子集 markdown → DOM：标题（#..###）、无序列表、代码块（```）、加粗、链接。
 * 全部内容经 textContent 写入，用户内容天然转义防 HTML 注入。
@@ -305,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") {
@@ -316,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);
 	});
 }
@@ -379,6 +391,7 @@ const DATA = [
 	"Metric",
 	"Table",
 	"Chart",
+	"Timeline",
 	"FileLink"
 ];
 const INPUT = [
@@ -386,6 +399,8 @@ const INPUT = [
 	"Field",
 	"Button"
 ];
+/** Tabs 的面板与 Grid 的格子必须自成容器，否则「每容器至多一个表单」就没有落脚点 */
+const PANEL = ["Card", "Stack"];
 /**
 * v3 首发 catalog：覆盖旧六类 surface（metric / chart / table / form / file / custom）的全部表达力，先窄后宽。
 * 只依赖 zod —— 不 import 任何 UI framework（21 号文档 §5.1）。
@@ -401,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: [
 		{
@@ -464,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",
@@ -599,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",
@@ -631,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" },
@@ -695,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",
@@ -763,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`;
@@ -896,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",
@@ -971,6 +1108,27 @@ function collectValues(controls, container) {
 	};
 }
 /**
+* 采纳建议值（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）。
 */
@@ -1270,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; }
@@ -1463,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;
@@ -1471,7 +1632,362 @@ 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;
+}
+/**
+* 按出现序列出声明树里的每个 `Form`。
+*
+* 单表单时 action id 保持 `submit` / `cancel`，回传形状与容器级放宽前逐字节一致——
+* 向后兼容是 FR-6.3 的硬约束，不能让既有单表单卡片跟着改。
+* 多表单时每个表单拿到独立的 action id 与 `scopeId`，渲染层据此只收集本表单子树内的字段。
+*/
+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
+		};
+	});
+}
+/**
+* 多表单时字段值在渲染层的存储键。
+*
+* 跨表单重名过去不可能发生，容器级放宽后它变成合法输入：两个表单各有一个 `email`，
+* 共用一张扁平表就是后写的覆盖先写的，用户在 A 里输入会串到 B。
+* 因此多表单时按作用域限定键；单表单不加前缀，存储与草稿形状保持不变。
+*/
+function qualifyFieldName(name, scopeId) {
+	return scopeId === void 0 ? name : `${scopeId}.${name}`;
+}
+/**
+* 提交时回传的字段值。
+*
+* 不给 `scope` → 整张 surface 的扁平值，与容器级放宽前完全一致（FR-6.3 第 3 条）。
+* 给了 `scope` → 只取该表单子树内的字段，键回落成裸字段名，
+* 因此接收端看到的载荷形状与单表单时相同。
+*/
+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` 保持环境无关）。
@@ -1518,6 +2034,7 @@ function toField(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) } : {}
 		}
 	};
@@ -1551,6 +2068,7 @@ function interactionToUiSpec(request, labels = {}) {
 	};
 }
 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）。
@@ -1576,8 +2094,9 @@ function isIntent(value) {
 * 从节点树抽出 action 能力表。能力表走事件外壳而非树内：
 * 树是模型可写的，nonce 放进去就等于让模型自己签发能力。
 * action id 取节点 id；Button 未声明 id 时退回 intent 名（同 intent 只留一条）。
+* 表单的提交/取消取自作用域表：容器级放宽后一张 surface 可能有多个表单。
 */
-function collectActions(node, out) {
+function collectActions(node, out, scopes) {
 	if (node.component === "Button" && isIntent(node.props?.["action"])) {
 		const intent = node.props["action"];
 		const id = node.id ?? intent;
@@ -1587,23 +2106,24 @@ function collectActions(node, out) {
 			...intent === "submit" ? { awaitResponse: true } : {}
 		});
 	}
-	if (node.component === "Form") {
-		if (!out.has("submit")) out.set("submit", {
-			id: "submit",
+	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("cancel")) out.set("cancel", {
-			id: "cancel",
+		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);
+	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);
+	collectActions(spec, actions, new Map(collectFormScopes(spec).map((scope) => [scope.form, scope])));
 	return [...actions.values()];
 }
 /**
@@ -1613,21 +2133,63 @@ function collectSpecActions(spec) {
 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",
 		systemPrompt: () => Promise.resolve(catalog.toPrompt()),
-		listToolSpecs: () => Promise.resolve([{
-			name: RENDER_UI_TOOL,
-			description: RENDER_UI_DESCRIPTION,
-			inputSchema: {
-				type: "object",
-				properties: { spec: catalog.toJsonSchema() },
-				required: ["spec"],
-				additionalProperties: false
+		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({
@@ -1728,13 +2290,14 @@ function toOpenUiSpecLang(spec, catalog = uiCatalog) {
 	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) {
+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 } : {}
 	};
 }
@@ -1749,6 +2312,7 @@ function fromUiSurfaceActionDispatch(value) {
 		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 } : {}
 	};
@@ -1778,10 +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)
+		context: toUiSurfaceActionDispatch(snapshot, action, value, scopeId)
 	};
 }
 /** 声明树里按钮触发的事件名（宿主据 context.actionId 回传 surface action） */
@@ -1888,7 +2452,7 @@ function fromA2uiSpecAction(event) {
 */
 async function loadWebSkillLitCatalog() {
 	try {
-		const { webskillLitCatalog } = await import("./webskillLitCatalog-CSTbhBe_-CYIs5BX8.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);
@@ -1913,4 +2477,4 @@ async function loadOpenUiPeers() {
 }
 
 //#endregion
-export { toA2uiSpecMessages as A, a2uiComponentSchema as B, interactionToUiSpec as C, renderMiniChart as D, renderBlocks as E, toVercelToolInvocation as F, mountEchart as G, buildA2uiCatalogDefinition as H, A2UI_CHILDREN_PROP as I, renderMiniMarkdown as K, A2UI_COMMON_TYPES as L, toJsonRenderSpec as M, toOpenUiSpecLang as N, renderRenderResult as O, toUiSurfaceActionDispatch as P, UI_CATALOG_GROUPS as R, interactionToFormModel as S, loadWebSkillLitCatalog as T, chartSpecFromProps as U, a2uiComponentShapes as V, defineUiCatalog as W, ensureStyles as _, A2UI_VERSION as a, fromUiSurfaceActionDispatch as b, VERCEL_INTERACTION_TOOL_NAME as c, WEBSKILL_SURFACE_ACTION as d, WebFormBridge as f, createUiCatalogToolSource as g, collectValues as h, A2UI_SURFACE_ACTION as i, toA2uiSurfaceAction as j, shapeInteractionValue as k, VercelUiBridge as l, collectSpecActions as m, A2UI_SPEC_ACTION as n, CHART_PALETTE as o, chartToTable as p, uiCatalog as q, A2UI_SPEC_FORM_PATH as r, RENDER_UI_TOOL as s, A2UI_BASIC_CATALOG_ID as t, WEBSKILL_STYLES_CSS as u, fromA2uiSpecAction as v, loadOpenUiPeers as w, fromVercelToolResult as x, fromA2uiSurfaceAction as y, WEBSKILL_A2UI_CATALOG_ID 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 };