@webskill/sdk 0.13.0 → 0.15.0

package/dist/ui.js

@@ -1,4 +1,1255 @@
-import { et as buildRenderResult } from "./dist-ExSQky4C.js";
-import { $ as uiPreset, A as ensureStyles, B as mountViewerComponents, C as applySuggestion, Ct as resolveSurfaceFormTexts, D as collectSpecActions, Dt as uiCatalog, E as collectScopedValues, Et as toEchartsOption, F as fromVercelToolResult, G as renderRenderResult, H as qualifyFieldName, I as gaugePercent, J as toA2uiSurfaceAction, K as resolveColumnWidths, L as interactionToUiSpec, M as fromA2uiSpecAction, N as fromA2uiSurfaceAction, O as collectValues, P as fromUiSurfaceActionDispatch, Q as toVercelToolInvocation, R as loadOpenUiPeers, S as WebFormBridge, St as resolveInteractionTexts, T as collectFormScopes, Tt as shapeInteractionValue, U as renderBlocks, V as normalizeColumnWidths, W as renderMiniChart, X as toOpenUiSpecLang, Y as toJsonRenderSpec, Z as toUiSurfaceActionDispatch, _ as VIEWER_FALLBACK_ATTR, _t as defineUiCatalog, a as A2UI_VERSION, at as DEFAULT_CHART_FONT_SIZES, b as WEBSKILL_STYLES_CSS, bt as renderMiniMarkdown, c as DOCUMENT_COMPONENTS, ct as DEFAULT_SURFACE_HOST_CONTROL_TEXTS, d as SPEC_TABLE_MIN_COLUMN_VAR, dt as UI_CATALOG_PROMPT_BUDGET_BYTES, f as SPEC_TABLE_MIN_COLUMN_WIDTH, ft as WEBSKILL_A2UI_CATALOG_ID, g as VIEWER_COMPONENT_ATTR, gt as chartSpecFromProps, h as VERCEL_INTERACTION_TOOL_NAME, ht as buildA2uiCatalogDefinition, i as A2UI_SURFACE_ACTION, it as CATALOG_SCHEMA_MAX, j as evaluateFieldCondition, k as createUiCatalogToolSource, l as MAX_CONDITION_DEPTH, lt as PLANNED_INCREMENT, m as UI_PRESET_NAMES, mt as a2uiComponentShapes, n as A2UI_SPEC_ACTION, nt as CATALOG_BUDGET_STAGE, o as CHART_PALETTE, ot as DEFAULT_INTERACTION_TEXTS, p as UI_PRESETS, pt as a2uiComponentSchema, q as toA2uiSpecMessages, r as A2UI_SPEC_FORM_PATH, rt as CATALOG_PROMPT_MAX, s as DESCRIBE_UI_PRESET_TOOL, st as DEFAULT_SURFACE_FORM_TEXTS, t as A2UI_BASIC_CATALOG_ID, tt as A2UI_COMMON_TYPES, u as RENDER_UI_TOOL, ut as UI_CATALOG_GROUPS, v as VIEWER_PROPS_ATTR, vt as interactionToFormModel, w as chartToTable, wt as resolveSurfaceHostControlTexts, x as WEBSKILL_SURFACE_ACTION, xt as resolveChartFontSizes, y as VercelUiBridge, yt as mountEchart, z as loadWebSkillLitCatalog } from "./dist-DqcL6jKO.js";
+import { t as WebSkillError } from "./errors-BDZNpC13.js";
+import { t as buildRenderResult } from "./renderResult-D9Q-Vu2x.js";
+import { a as applySuggestion, c as DEFAULT_SURFACE_FORM_TEXTS, d as resolveInteractionTexts, f as resolveSurfaceFormTexts, i as renderMiniMarkdown, l as DEFAULT_SURFACE_HOST_CONTROL_TEXTS, m as shapeInteractionValue, n as chartToTable, o as collectValues, p as resolveSurfaceHostControlTexts, r as renderMiniChart, s as DEFAULT_INTERACTION_TEXTS, t as CHART_PALETTE, u as interactionToFormModel } from "./miniChart-owdCdaw-.js";
+import { C as chartSpecFromProps, E as toEchartsOption, S as DEFAULT_CHART_FONT_SIZES, T as resolveChartFontSizes, _ as CATALOG_BUDGET_STAGE, a as SPEC_TABLE_MIN_COLUMN_WIDTH, b as PLANNED_INCREMENT, c as MAX_CONDITION_DEPTH, d as collectScopedValues, f as qualifyFieldName, g as defineUiCatalog, h as uiCatalog, i as SPEC_TABLE_MIN_COLUMN_VAR, l as evaluateFieldCondition, m as UI_CATALOG_PROMPT_BUDGET_BYTES, n as interactionToUiSpec, o as normalizeColumnWidths, p as UI_CATALOG_GROUPS, r as toJsonRenderSpec, s as resolveColumnWidths, t as toOpenUiSpecLang, u as collectFormScopes, v as CATALOG_PROMPT_MAX, w as mountEchart, x as gaugePercent, y as CATALOG_SCHEMA_MAX } from "./openUiSpecLang-DuOCdw9G.js";
 
-export { A2UI_BASIC_CATALOG_ID, A2UI_COMMON_TYPES, A2UI_SPEC_ACTION, A2UI_SPEC_FORM_PATH, A2UI_SURFACE_ACTION, A2UI_VERSION, CATALOG_BUDGET_STAGE, CATALOG_PROMPT_MAX, CATALOG_SCHEMA_MAX, CHART_PALETTE, DEFAULT_CHART_FONT_SIZES, DEFAULT_INTERACTION_TEXTS, DEFAULT_SURFACE_FORM_TEXTS, DEFAULT_SURFACE_HOST_CONTROL_TEXTS, DESCRIBE_UI_PRESET_TOOL, DOCUMENT_COMPONENTS, MAX_CONDITION_DEPTH, PLANNED_INCREMENT, RENDER_UI_TOOL, SPEC_TABLE_MIN_COLUMN_VAR, SPEC_TABLE_MIN_COLUMN_WIDTH, UI_CATALOG_GROUPS, UI_CATALOG_PROMPT_BUDGET_BYTES, UI_PRESETS, UI_PRESET_NAMES, VERCEL_INTERACTION_TOOL_NAME, VIEWER_COMPONENT_ATTR, VIEWER_FALLBACK_ATTR, VIEWER_PROPS_ATTR, VercelUiBridge, WEBSKILL_A2UI_CATALOG_ID, WEBSKILL_STYLES_CSS, WEBSKILL_SURFACE_ACTION, WebFormBridge, a2uiComponentSchema, a2uiComponentShapes, applySuggestion, buildA2uiCatalogDefinition, buildRenderResult, chartSpecFromProps, chartToTable, collectFormScopes, collectScopedValues, collectSpecActions, collectValues, createUiCatalogToolSource, defineUiCatalog, ensureStyles, evaluateFieldCondition, fromA2uiSpecAction, fromA2uiSurfaceAction, fromUiSurfaceActionDispatch, fromVercelToolResult, gaugePercent, interactionToFormModel, interactionToUiSpec, loadOpenUiPeers, loadWebSkillLitCatalog, mountEchart, mountViewerComponents, normalizeColumnWidths, qualifyFieldName, renderBlocks, renderMiniChart, renderMiniMarkdown, renderRenderResult, resolveChartFontSizes, resolveColumnWidths, resolveInteractionTexts, resolveSurfaceFormTexts, resolveSurfaceHostControlTexts, shapeInteractionValue, toA2uiSpecMessages, toA2uiSurfaceAction, toEchartsOption, toJsonRenderSpec, toOpenUiSpecLang, toUiSurfaceActionDispatch, toVercelToolInvocation, uiCatalog, uiPreset };
+//#region ../ui/src/web/resultRenderer.ts
+/** 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);
+			container.appendChild(pre);
+			break;
+		}
+		case "table": {
+			const table = doc.createElement("table");
+			const thead = doc.createElement("thead");
+			const headRow = doc.createElement("tr");
+			for (const column of block.columns) {
+				const th = doc.createElement("th");
+				th.textContent = column;
+				headRow.appendChild(th);
+			}
+			thead.appendChild(headRow);
+			table.appendChild(thead);
+			const tbody = doc.createElement("tbody");
+			for (const row of block.rows) {
+				const tr = doc.createElement("tr");
+				for (const cell of row) {
+					const td = doc.createElement("td");
+					td.textContent = typeof cell === "object" ? JSON.stringify(cell) : String(cell ?? "");
+					tr.appendChild(td);
+				}
+				tbody.appendChild(tr);
+			}
+			table.appendChild(tbody);
+			container.appendChild(table);
+			break;
+		}
+		case "image": {
+			const img = doc.createElement("img");
+			img.src = block.url;
+			img.alt = block.alt ?? "";
+			container.appendChild(img);
+			break;
+		}
+		case "file": {
+			const div = doc.createElement("div");
+			div.className = "webskill-result__file";
+			const meta = [block.mimeType, block.size !== void 0 ? `${block.size} bytes` : void 0].filter(Boolean).join(", ");
+			div.textContent = meta ? `${block.path} (${meta})` : block.path;
+			container.appendChild(div);
+			break;
+		}
+	}
+}
+/** 完整 RenderResultRequest → DOM（summary 头 + blocks） */
+function renderRenderResult(request, doc) {
+	const root = doc.createElement("div");
+	root.className = "webskill-result";
+	if (request.title) {
+		const title = doc.createElement("div");
+		title.className = "webskill-form__title";
+		title.textContent = request.title;
+		root.appendChild(title);
+	}
+	if (request.summary) {
+		const summary = doc.createElement("div");
+		summary.className = "webskill-result__summary";
+		summary.textContent = request.summary;
+		root.appendChild(summary);
+	}
+	renderBlocks(root, request.blocks, doc);
+	return root;
+}
+
+//#endregion
+//#region ../ui/src/viewer/presetComponents.ts
+/**
+* viewer 的宿主预置组件（0.11.0 分册 18 FR-18.5 / 分册 19）。
+*
+* 技能**不写 JS**：文档 HTML 里只留占位，由这里挂载真实组件。
+* 交互只落在图表上——表格排序的例子已作废（分册 29 §2 登记 #13）。
+*
+* 三条硬约束：
+* - props 用 **catalog 自己的 zod schema** 解析，同形因此是机制上成立的，
+*   不是靠一句「记得同步」的注释（FR-19.2）；
+* - 值一律经 `textContent` 落地，**永不** `innerHTML`（FR-19.4 / AC-19.5）；
+* - 白名单外的名字只渲染降级提示，**不触发任何按名 import**（FR-19.3）。
+*/
+/** 占位元素的属性名，模板与挂载方共用（FR-19.1 的契约） */
+const VIEWER_COMPONENT_ATTR = "data-webskill-component";
+const VIEWER_PROPS_ATTR = "data-webskill-props";
+/** 降级提示的标记；模板 CSS 与判据都认这个属性，不认某个 class 名 */
+const VIEWER_FALLBACK_ATTR = "data-webskill-fallback";
+/** 文档面可用的组件白名单（FR-19.3）。字面量数组——不接受任何按名动态加载 */
+const DOCUMENT_COMPONENTS = [
+	"Chart",
+	"Table",
+	"Metric",
+	"Gauge",
+	"KeyValue"
+];
+const WHITELIST = new Set(DOCUMENT_COMPONENTS);
+/**
+* 扫描 `root` 下的占位并挂载预置组件。
+*
+* 逐个占位独立处理：一个坏占位只降级它自己，不会让整篇文档变空白。
+*/
+function mountViewerComponents(root, options) {
+	const handles = [];
+	for (const node of Array.from(root.querySelectorAll(`[${VIEWER_COMPONENT_ATTR}]`))) {
+		const element = node;
+		const name = element.getAttribute("data-webskill-component") ?? "";
+		if (!WHITELIST.has(name)) {
+			fallback(element, `Unsupported component "${name}"`);
+			continue;
+		}
+		const props = readProps(element, name);
+		if (!props) continue;
+		const handle = render(element, name, props, options?.fontSizes);
+		if (handle) handles.push(handle);
+	}
+	return { dispose: () => {
+		for (const handle of handles) handle.dispose();
+		handles.length = 0;
+	} };
+}
+/** 用 catalog 的 schema 解析：多余字段被丢弃，缺省值与 catalog 完全一致 */
+function readProps(element, name) {
+	const raw = element.getAttribute(VIEWER_PROPS_ATTR);
+	if (raw === null || raw === "") {
+		fallback(element, `Component "${name}" is missing ${VIEWER_PROPS_ATTR}`);
+		return;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		fallback(element, `Component "${name}" has invalid props JSON`);
+		return;
+	}
+	const schema = uiCatalog.component(name)?.props;
+	if (!schema) {
+		fallback(element, `Component "${name}" is not declared in the catalog`);
+		return;
+	}
+	const result = schema.safeParse(parsed);
+	if (!result.success) {
+		fallback(element, `Component "${name}" has props the catalog rejects`);
+		return;
+	}
+	return result.data;
+}
+function render(element, name, props, fontSizes) {
+	const doc = element.ownerDocument;
+	element.replaceChildren();
+	switch (name) {
+		case "Chart": {
+			const handle = mountEchart(element);
+			handle.setChart(chartSpecFromProps(props), fontSizes);
+			return handle;
+		}
+		case "Table":
+			renderBlocks(element, [{
+				type: "table",
+				columns: props["columns"],
+				rows: props["rows"]
+			}], doc);
+			return;
+		case "Metric": {
+			append(doc, element, "span", String(props["label"]), { "data-webskill-metric": "label" });
+			append(doc, element, "strong", String(props["value"]), { "data-webskill-metric": "value" });
+			const change = props["change"];
+			if (typeof change === "string") append(doc, element, "span", change, {
+				"data-webskill-metric": "change",
+				"data-trend": String(props["trend"] ?? "neutral")
+			});
+			return;
+		}
+		case "Gauge": {
+			const value = props["value"];
+			const min = props["min"];
+			const max = props["max"];
+			const label = typeof props["label"] === "string" ? props["label"] : "";
+			element.setAttribute("data-tone", String(props["tone"]));
+			if (label !== "") append(doc, element, "span", label, { "data-webskill-gauge": "label" });
+			const fill = append(doc, append(doc, element, "div", "", {
+				role: "meter",
+				"aria-label": label === "" ? "Gauge" : label,
+				"aria-valuenow": String(value),
+				"aria-valuemin": String(min),
+				"aria-valuemax": String(max),
+				"data-webskill-gauge": "track"
+			}), "div", "", { "data-webskill-gauge": "fill" });
+			fill.style.width = `${gaugePercent(value, min, max)}%`;
+			append(doc, element, "span", String(value), { "data-webskill-gauge": "value" });
+			return;
+		}
+		case "KeyValue": {
+			const dl = append(doc, element, "dl", "", {});
+			for (const item of props["items"]) {
+				append(doc, dl, "dt", item.label, {});
+				append(doc, dl, "dd", item.value, {});
+			}
+			return;
+		}
+	}
+}
+function append(doc, parent, tag, text, attrs) {
+	const el = doc.createElement(tag);
+	for (const [key, value] of Object.entries(attrs)) el.setAttribute(key, value);
+	if (text !== "") el.textContent = text;
+	parent.appendChild(el);
+	return el;
+}
+/**
+* 可见降级（AC-19.4）。
+*
+* 静默留空是最坏的结果：文档看着「渲染成功」，作者却不知道自己写错了组件名。
+* 原有内容整体替换，避免半截渲染与提示并存。
+*/
+function fallback(element, reason) {
+	element.setAttribute(VIEWER_FALLBACK_ATTR, "true");
+	element.textContent = reason;
+}
+
+//#endregion
+//#region ../ui/src/web/styles.ts
+/** 最小样式（BEM class，应用可整体覆写） */
+const WEBSKILL_STYLES_CSS = `
+.webskill-form { display: block; padding: 12px; border: 1px solid #d0d0d0; border-radius: 8px; font-family: system-ui, sans-serif; max-width: 420px; }
+.webskill-form__title { margin: 0 0 8px; font-size: 15px; font-weight: 600; }
+.webskill-form__message { margin: 0 0 10px; font-size: 14px; }
+.webskill-form__control { margin-bottom: 10px; display: flex; flex-direction: column; gap: 4px; }
+.webskill-form__control--invalid .webskill-form__input { border-color: #d33; }
+.webskill-form__label { font-size: 13px; font-weight: 500; }
+.webskill-form__label-required::after { content: ' *'; color: #d33; }
+.webskill-form__description { font-size: 12px; color: #666; }
+.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; }
+.webskill-form__button--ghost { background: transparent; }
+.webskill-result { font-family: system-ui, sans-serif; font-size: 14px; }
+.webskill-result__summary { font-size: 12px; color: #666; margin-bottom: 6px; }
+.webskill-result__json { background: #f5f5f5; padding: 8px; border-radius: 4px; overflow-x: auto; }
+.webskill-result__file { padding: 4px 0; font-size: 13px; }
+.webskill-md pre { background: #f5f5f5; padding: 8px; border-radius: 4px; overflow-x: auto; }
+.webskill-md h1, .webskill-md h2, .webskill-md h3 { margin: 8px 0 4px; }
+.webskill-md p { margin: 4px 0; }
+.webskill-md ul { margin: 4px 0; padding-left: 20px; }
+`;
+/** 每个 document 只注入一次 */
+function ensureStyles(doc) {
+	if (doc.querySelector("style[data-webskill]")) return;
+	const style = doc.createElement("style");
+	style.setAttribute("data-webskill", "");
+	style.textContent = WEBSKILL_STYLES_CSS;
+	doc.head.appendChild(style);
+}
+
+//#endregion
+//#region ../ui/src/web/webFormBridge.ts
+const CONTROL_TAG = "data-webskill-control";
+/**
+* 框架无关原生 DOM 的 UiBridge：request 渲染表单并返回 Promise
+* （提交 resolve / 取消 {cancelled:true}），完成后卸载 DOM。
+* document 可注入（jsdom 测试）；BEM class 样式可覆写。
+*/
+var WebFormBridge = class {
+	#mount;
+	#doc;
+	#styles;
+	#progressEl;
+	#texts;
+	#interactionTexts;
+	/** 等待中的 request 取消句柄（id → 触发 cancelled 并卸载 DOM） */
+	#pending = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.#mount = options.mount;
+		this.#doc = options.document ?? options.mount.ownerDocument;
+		this.#styles = options.styles ?? true;
+		this.#interactionTexts = options.texts;
+		this.#texts = resolveSurfaceFormTexts(options.texts);
+	}
+	request(input) {
+		if (this.#styles) ensureStyles(this.#doc);
+		this.#clearProgress();
+		const model = interactionToFormModel(input, this.#interactionTexts);
+		const { form, cleanup } = this.#renderForm(model);
+		return new Promise((resolve) => {
+			const cancel = () => {
+				cleanup();
+				this.#pending.delete(input.id);
+				resolve({
+					id: input.id,
+					cancelled: true
+				});
+			};
+			this.#pending.set(input.id, cancel);
+			form.addEventListener("submit", (event) => {
+				event.preventDefault();
+				const { values, missingRequired } = collectValues(model.controls, form);
+				if (missingRequired.length > 0) {
+					for (const name of missingRequired) {
+						const wrapper = form.querySelector(`[${CONTROL_TAG}="${name}"]`)?.closest(".webskill-form__control");
+						wrapper?.classList.add("webskill-form__control--invalid");
+						wrapper?.querySelector(".webskill-form__input")?.setAttribute("aria-invalid", "true");
+					}
+					return;
+				}
+				this.#pending.delete(input.id);
+				cleanup();
+				resolve({
+					id: input.id,
+					value: shapeInteractionValue(model, values)
+				});
+			});
+			form.querySelector("[data-webskill-cancel]")?.addEventListener("click", (event) => {
+				event.preventDefault();
+				cancel();
+			});
+			this.#mount.appendChild(form);
+		});
+	}
+	/** 尽力取消等待中的 request（超时后清理遗留表单） */
+	cancel(id) {
+		this.#pending.get(id)?.();
+	}
+	async renderResult(input) {
+		if (this.#styles) ensureStyles(this.#doc);
+		this.#clearProgress();
+		this.#mount.querySelector(".webskill-result")?.remove();
+		this.#mount.appendChild(renderRenderResult(input, this.#doc));
+	}
+	async progress(input) {
+		if (!this.#progressEl) {
+			this.#progressEl = this.#doc.createElement("div");
+			this.#progressEl.className = "webskill-result__summary";
+			this.#mount.appendChild(this.#progressEl);
+		}
+		const pct = input.value !== void 0 ? ` (${Math.round(input.value * 100)}%)` : "";
+		this.#progressEl.textContent = `${input.message}${pct}`;
+	}
+	/** 新一轮交互/结果渲染开始时移除遗留 progress 元素 */
+	#clearProgress() {
+		this.#progressEl?.remove();
+		this.#progressEl = void 0;
+	}
+	#renderForm(model) {
+		const doc = this.#doc;
+		const form = doc.createElement("form");
+		form.className = "webskill-form";
+		form.noValidate = true;
+		if (model.title) {
+			const title = doc.createElement("div");
+			title.className = "webskill-form__title";
+			title.textContent = model.title;
+			form.appendChild(title);
+		}
+		if (model.message && model.kind !== "confirm" && model.kind !== "ask" && model.kind !== "select") {
+			const message = doc.createElement("p");
+			message.className = "webskill-form__message";
+			message.textContent = model.message;
+			form.appendChild(message);
+		}
+		for (const control of model.controls) form.appendChild(this.#renderControl(control));
+		const actions = doc.createElement("div");
+		actions.className = "webskill-form__actions";
+		const submit = doc.createElement("button");
+		submit.type = "submit";
+		submit.className = "webskill-form__button webskill-form__button--primary";
+		submit.textContent = model.submitLabel;
+		actions.appendChild(submit);
+		if (model.cancelLabel) {
+			const cancel = doc.createElement("button");
+			cancel.type = "button";
+			cancel.className = "webskill-form__button webskill-form__button--ghost";
+			cancel.textContent = model.cancelLabel;
+			cancel.setAttribute("data-webskill-cancel", "");
+			actions.appendChild(cancel);
+		}
+		form.appendChild(actions);
+		return {
+			form,
+			cleanup: () => form.remove()
+		};
+	}
+	#renderControl(control) {
+		const doc = this.#doc;
+		const wrapper = doc.createElement("div");
+		wrapper.className = "webskill-form__control";
+		const controlId = `webskill-field-${control.name}`;
+		const errorId = `webskill-error-${control.name}`;
+		const label = doc.createElement("label");
+		label.className = control.required ? "webskill-form__label webskill-form__label-required" : "webskill-form__label";
+		label.textContent = control.label;
+		label.htmlFor = controlId;
+		wrapper.appendChild(label);
+		if (control.description) {
+			const desc = doc.createElement("div");
+			desc.className = "webskill-form__description";
+			desc.textContent = control.description;
+			wrapper.appendChild(desc);
+		}
+		let input;
+		if (control.control === "select") {
+			const select = doc.createElement("select");
+			select.className = "webskill-form__input";
+			for (const option of control.options ?? []) {
+				const opt = doc.createElement("option");
+				opt.value = JSON.stringify(option.value);
+				opt.textContent = option.label;
+				if (control.defaultValue !== void 0 && JSON.stringify(control.defaultValue) === opt.value) opt.selected = true;
+				select.appendChild(opt);
+			}
+			input = select;
+		} else if (control.control === "boolean") {
+			const checkbox = doc.createElement("input");
+			checkbox.type = "checkbox";
+			checkbox.className = "webskill-form__input";
+			checkbox.checked = control.defaultValue === true;
+			input = checkbox;
+		} else if (control.control === "textarea") {
+			const textarea = doc.createElement("textarea");
+			textarea.className = "webskill-form__input";
+			textarea.value = control.defaultValue !== void 0 ? String(control.defaultValue) : "";
+			input = textarea;
+		} else {
+			const textInput = doc.createElement("input");
+			textInput.type = control.control === "number" ? "number" : control.control === "date" ? "date" : "text";
+			textInput.className = "webskill-form__input";
+			if (control.defaultValue !== void 0) textInput.value = String(control.defaultValue);
+			input = textInput;
+		}
+		input.setAttribute(CONTROL_TAG, control.name);
+		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;
+		error.setAttribute("role", "alert");
+		error.textContent = this.#texts.required;
+		wrapper.appendChild(error);
+		return wrapper;
+	}
+	/** 建议值以**建议**形态出现（FR-19.4）：控件初始值仍为空，点「使用」才写入 */
+	#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 = `Suggested: ${String(control.suggestion?.value)}`;
+		row.appendChild(preview);
+		const reason = control.suggestion?.reason;
+		if (reason !== void 0 && reason !== "") {
+			const why = doc.createElement("span");
+			why.className = "webskill-form__suggestion-reason";
+			why.textContent = `(${reason})`;
+			row.appendChild(why);
+		}
+		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;
+	}
+};
+
+//#endregion
+//#region ../ui/src/catalog/presets.ts
+const charts = {
+	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"
+				}
+			}
+		]
+	}
+};
+const cards = {
+	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"
+				}
+			}]
+		}]
+	}
+};
+const dashboards = {
+	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]]
+					}
+				}]
+			}]
+		}]
+	}
+};
+const slides = {
+	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" }
+			}]
+		}]
+	}
+};
+const reports = {
+	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
+				}
+			}
+		]
+	}
+};
+/** 五类场景预设（FR-6.4）。@experimental */
+const UI_PRESETS = [
+	charts,
+	cards,
+	dashboards,
+	slides,
+	reports
+];
+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);
+}
+
+//#endregion
+//#region ../ui/src/catalog/uiCatalogToolSource.ts
+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"
+]);
+/** 去重靠指纹兜底，但重复调用本身也浪费一轮，所以先在提示词里劝阻（FR-21.5） */
+const NO_DUPLICATE_RENDER = "If a skill has already rendered a surface for this request, do not call render_ui again with the same content.";
+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 / 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",
+		systemPrompt: () => Promise.resolve(`${catalog.toPrompt()}\n\n${NO_DUPLICATE_RENDER}`),
+		listToolSpecs: () => Promise.resolve(presets.length > 0 ? [renderTool(), presetTool()] : [renderTool()]),
+		canHandle: (name) => name === "render_ui" || presets.length > 0 && name === "describe_ui_preset",
+		argCaptureTrust: (name) => name === "render_ui" || name === "describe_ui_preset" ? { tier: "reviewed" } : void 0,
+		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)}`
+					}]
+				});
+			}
+			const spec = args["spec"];
+			const result = catalog.validate(spec);
+			if (!result.ok) return Promise.resolve({
+				ok: false,
+				content: [],
+				error: {
+					code: "UI_SPEC_INVALID",
+					message: `The UI spec does not match the catalog: ${result.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`
+				}
+			});
+			const node = spec;
+			const surfaceId = newSurfaceId();
+			const actions = collectSpecActions(node);
+			return Promise.resolve({
+				ok: true,
+				content: [{
+					type: "json",
+					data: { $surface: {
+						type: "open",
+						id: surfaceId,
+						node,
+						...actions.length > 0 ? { actions } : {}
+					} }
+				}, {
+					type: "text",
+					text: `Rendered surface ${surfaceId}.`
+				}]
+			});
+		}
+	};
+}
+
+//#endregion
+//#region ../ui/src/adapters/vercel/vercelPayload.ts
+const VERCEL_INTERACTION_TOOL_NAME = "webskill_interaction";
+/** InteractionRequest → SDK tool UI 结构（应用聊天 UI 直接消费） */
+function toVercelToolInvocation(request) {
+	return {
+		type: "tool-call",
+		toolCallId: request.id,
+		toolName: VERCEL_INTERACTION_TOOL_NAME,
+		input: request
+	};
+}
+/** SDK 回传（tool result / output）→ InteractionResponse */
+function fromVercelToolResult(part) {
+	const p = part ?? {};
+	const id = String(p["toolCallId"] ?? p["id"] ?? "");
+	if (p["cancelled"] === true) return {
+		id,
+		cancelled: true
+	};
+	return {
+		id,
+		value: p["output"] ?? p["result"] ?? p["value"]
+	};
+}
+
+//#endregion
+//#region ../ui/src/adapters/vercel/vercelUiBridge.ts
+/**
+* 薄桥接类：request → SDK tool UI 结构 → 应用的聊天 UI（sendInteraction 回调实现）
+* → SDK 回传 → InteractionResponse。
+*/
+var VercelUiBridge = class {
+	#sendInteraction;
+	constructor(deps) {
+		this.#sendInteraction = deps.sendInteraction;
+	}
+	async request(input) {
+		return fromVercelToolResult(await this.#sendInteraction(toVercelToolInvocation(input)));
+	}
+};
+
+//#endregion
+//#region ../ui/src/adapters/surface/surfaceDescriptor.ts
+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);
+}
+
+//#endregion
+//#region ../ui/src/adapters/a2ui/a2uiMessages.ts
+/**
+* A2UI 协议常量与 surface 动作编解码（v0.9.1）。
+* 依据 https://a2ui.org/specification/v0.9-a2ui/：
+* - 信封 {version, createSurface|updateComponents|updateDataModel|deleteSurface}
+* - 组件为扁平邻接表（id 引用），root 必需
+* - 输入组件与数据模型经 JSON Pointer 双向绑定；action.context 回传
+*
+* 声明树 → 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_SURFACE_ACTION = WEBSKILL_SURFACE_ACTION;
+/** Decodes a nonce-bound action emitted by a WebSkill A2UI extension host. @experimental */
+function fromA2uiSurfaceAction(event) {
+	const action = event;
+	if (action?.name !== A2UI_SURFACE_ACTION) return void 0;
+	return fromUiSurfaceActionDispatch(action.context);
+}
+/** Builds the A2UI event payload an extension host sends after a user action. @experimental */
+function toA2uiSurfaceAction(snapshot, action, value, scopeId) {
+	return {
+		name: A2UI_SURFACE_ACTION,
+		context: toUiSurfaceActionDispatch(snapshot, action, value, scopeId)
+	};
+}
+
+//#endregion
+//#region ../ui/src/adapters/a2ui/a2uiComponentShape.ts
+/** 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`;
+const ACTION_REF = `${A2UI_COMMON_TYPES}#/$defs/Action`;
+const DYNAMIC_VALUE_REF = `${A2UI_COMMON_TYPES}#/$defs/DynamicValue`;
+/** catalog 里承载 action 名的 props 字段 */
+const ACTION_PROP = "action";
+/** 表单控件的标识字段；有它才谈得上把值写进数据模型 */
+const NAME_PROP = "name";
+const SUBMIT_LABEL_PROP = "submitLabel";
+const CANCEL_LABEL_PROP = "cancelLabel";
+/** A2UI 线上形状里表单控件的取值字段 */
+const A2UI_VALUE_PROP = "value";
+/** A2UI 线上形状里的子节点字段 */
+const A2UI_CHILDREN_PROP = "children";
+/** catalog → 每个组件的 A2UI 线上形状 */
+function a2uiComponentShapes(catalog) {
+	const branches = catalog.toJsonSchema()["oneOf"] ?? [];
+	const byName = /* @__PURE__ */ new Map();
+	for (const branch of branches) {
+		const name = (branch.properties?.["component"])?.["const"];
+		if (typeof name === "string") byName.set(name, branch);
+	}
+	return catalog.components.map((def) => {
+		const branch = byName.get(def.name);
+		const props = branch?.properties?.["props"] ?? { type: "object" };
+		const keys = Object.keys(props.properties ?? {});
+		const childrenDescription = (branch?.properties?.["children"])?.description;
+		return {
+			name: def.name,
+			description: def.description,
+			props,
+			staticProps: keys.filter((key) => key !== ACTION_PROP),
+			childList: def.children !== void 0,
+			...childrenDescription ? { childListDescription: childrenDescription } : {},
+			actionProps: keys.filter((key) => key === ACTION_PROP),
+			valueProps: def.group === "input" && def.children === void 0 && keys.includes(NAME_PROP) ? [A2UI_VALUE_PROP] : [],
+			...keys.includes(SUBMIT_LABEL_PROP) ? { submitLabelProp: SUBMIT_LABEL_PROP } : {},
+			...keys.includes(CANCEL_LABEL_PROP) ? { cancelLabelProp: CANCEL_LABEL_PROP } : {}
+		};
+	});
+}
+/** 单个组件的 A2UI props JSON Schema（协议要求每个组件是一份 schema） */
+function a2uiComponentSchema(shape) {
+	const properties = { ...shape.props.properties ?? {} };
+	for (const key of shape.actionProps) properties[key] = {
+		$ref: ACTION_REF,
+		description: "What happens when the user activates this component."
+	};
+	for (const key of shape.valueProps) properties[key] = {
+		$ref: DYNAMIC_VALUE_REF,
+		description: "Two-way binding to the surface data model."
+	};
+	if (shape.childList) properties[A2UI_CHILDREN_PROP] = {
+		$ref: CHILD_LIST_REF,
+		description: shape.childListDescription ? `${shape.childListDescription}. Children are referenced by id, never inlined.` : "Child component ids, in render order."
+	};
+	return {
+		...shape.props,
+		description: shape.description,
+		properties
+	};
+}
+
+//#endregion
+//#region ../ui/src/adapters/a2ui/webskillCatalog.ts
+/** 自定义 catalog 的协议 id（对齐 https://a2ui.org/specification/v1_0/catalog_definition.json） */
+const WEBSKILL_A2UI_CATALOG_ID = "https://webskill.dev/a2ui/catalogs/v1/catalog.json";
+/**
+* WebSkill catalog → A2UI `catalog_definition.json`。
+* 组件 schema 由 catalog 的 JSON Schema 投影经 `a2uiComponentShapes` 改写成 A2UI 线上形状
+* （嵌套变 id 引用、action 名变协议信封），不手写第二份词汇表——
+* Lit 元素的 zod API 也由同一份 shape 派生。
+*/
+function buildA2uiCatalogDefinition(catalog) {
+	const components = {};
+	for (const shape of a2uiComponentShapes(catalog)) components[shape.name] = a2uiComponentSchema(shape);
+	return {
+		catalogId: WEBSKILL_A2UI_CATALOG_ID,
+		title: catalog.title,
+		description: `${catalog.title} ${catalog.version}`,
+		instructions: catalog.instructions,
+		components,
+		functions: Object.fromEntries(catalog.actions.map((action) => [action.name, { description: action.description }]))
+	};
+}
+
+//#endregion
+//#region ../ui/src/adapters/a2ui/specToA2ui.ts
+/** 声明树里按钮触发的事件名（宿主据 context.actionId 回传 surface action） */
+const A2UI_SPEC_ACTION = "webskill:spec-action";
+/** 表单值在 A2UI 数据模型里的根路径 */
+const A2UI_SPEC_FORM_PATH = "/form";
+/**
+* catalog 声明树 → A2UI 消息序列。
+*
+* 协议要求组件是扁平邻接表且根节点 id 为 `root`，因此这里做树 → 邻接表的展开。
+* 三处改写全部由 `a2uiComponentShapes` 决定，本函数不认识任何具体组件名：
+* - 子节点变成 props.children 里的 id 引用
+* - 表单控件的值经 JSON Pointer 与数据模型双向绑定
+* - 自带提交/取消标签的组件（A2UI 没有表单提交事件）把按钮物化成 Button 子节点，
+*   与 `toA2uiMessages` 对交互请求的处理同一手法
+*/
+function toA2uiSpecMessages(catalog, spec, options) {
+	const shapes = new Map(a2uiComponentShapes(catalog).map((shape) => [shape.name, shape]));
+	const components = [];
+	const defaults = {};
+	let counter = 0;
+	const event = (actionId) => ({ event: {
+		name: A2UI_SPEC_ACTION,
+		context: {
+			...options.context,
+			actionId
+		}
+	} });
+	const button = (id, text, actionId) => {
+		components.push({
+			id,
+			component: "Button",
+			label: text,
+			action: event(actionId)
+		});
+		return id;
+	};
+	const walk = (node, id) => {
+		const props = { ...node.props };
+		const shape = shapes.get(node.component);
+		const children = (node.children ?? []).map((child) => walk(child, child.id ?? `n${counter++}`));
+		for (const key of shape?.valueProps ?? []) {
+			const name = typeof props["name"] === "string" ? props["name"] : id;
+			if (props["defaultValue"] !== void 0) defaults[name] = props["defaultValue"];
+			props[key] = { path: `${A2UI_SPEC_FORM_PATH}/${name}` };
+		}
+		for (const key of shape?.actionProps ?? []) props[key] = event(typeof props[key] === "string" ? props[key] : "select");
+		if (shape?.submitLabelProp) {
+			const text = props[shape.submitLabelProp];
+			children.push(button(`${id}-submit`, typeof text === "string" ? text : "Submit", "submit"));
+		}
+		if (shape?.cancelLabelProp && typeof props[shape.cancelLabelProp] === "string") children.push(button(`${id}-cancel`, props[shape.cancelLabelProp], "cancel"));
+		if (children.length > 0) props[A2UI_CHILDREN_PROP] = children;
+		components.push({
+			...props,
+			id,
+			component: node.component
+		});
+		return id;
+	};
+	walk(spec, "root");
+	const messages = [{
+		version: A2UI_VERSION,
+		createSurface: {
+			surfaceId: options.surfaceId,
+			catalogId: options.catalogId ?? "https://webskill.dev/a2ui/catalogs/v1/catalog.json",
+			sendDataModel: true
+		}
+	}, {
+		version: A2UI_VERSION,
+		updateComponents: {
+			surfaceId: options.surfaceId,
+			components
+		}
+	}];
+	if (Object.keys(defaults).length > 0) messages.push({
+		version: A2UI_VERSION,
+		updateDataModel: {
+			surfaceId: options.surfaceId,
+			path: A2UI_SPEC_FORM_PATH,
+			value: defaults
+		}
+	});
+	return messages;
+}
+/** A2UI action 事件 → 声明树 action（非本 catalog 的事件返回 undefined） */
+function fromA2uiSpecAction(event) {
+	const action = event;
+	if (action?.name !== "webskill:spec-action") return void 0;
+	const context = action.context ?? {};
+	const actionId = context["actionId"];
+	if (typeof actionId !== "string") return void 0;
+	return {
+		actionId,
+		context
+	};
+}
+
+//#endregion
+//#region ../ui/src/a2uiRuntime/loadLitCatalog.ts
+/**
+* BYOC Lit 元素的加载入口。
+*
+* 元素模块静态依赖 `lit` 与 `@a2ui/*`（三者都是 optional peer），
+* 因此只能经动态 import 进来：未用 A2UI 档的应用不为这段体积买单，
+* 缺依赖时给出带安装提示的 `UI_UNAVAILABLE`，而不是一个空白 surface。
+*/
+async function loadWebSkillLitCatalog() {
+	try {
+		const { webskillLitCatalog } = await import("./webskillLitCatalog-DSqVFQjK.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);
+	}
+}
+
+//#endregion
+//#region ../ui/src/optionalPeers/openUiRuntime.ts
+/**
+* Loads the optional OpenUI peers (@openuidev/react-lang and zod) for the OpenUI
+* interaction/surface paths. Throws a WebSkillError with code UI_UNAVAILABLE and an
+* install hint when either peer is missing, so callers can fall back to native
+* rendering instead of leaving a blank surface.
+*/
+async function loadOpenUiPeers() {
+	try {
+		const [openuiModule, zodModule] = await Promise.all([import("./dist-CTsxblSD.js"), import("zod")]);
+		return {
+			openui: openuiModule,
+			z: zodModule.z
+		};
+	} catch (cause) {
+		throw new WebSkillError("UI_UNAVAILABLE", "The OpenUI renderer is unavailable; install @openuidev/react-lang and zod to render surfaces and interactions with the OpenUI track", cause);
+	}
+}
+
+//#endregion
+export { A2UI_BASIC_CATALOG_ID, A2UI_COMMON_TYPES, A2UI_SPEC_ACTION, A2UI_SPEC_FORM_PATH, A2UI_SURFACE_ACTION, A2UI_VERSION, CATALOG_BUDGET_STAGE, CATALOG_PROMPT_MAX, CATALOG_SCHEMA_MAX, CHART_PALETTE, DEFAULT_CHART_FONT_SIZES, DEFAULT_INTERACTION_TEXTS, DEFAULT_SURFACE_FORM_TEXTS, DEFAULT_SURFACE_HOST_CONTROL_TEXTS, DESCRIBE_UI_PRESET_TOOL, DOCUMENT_COMPONENTS, MAX_CONDITION_DEPTH, PLANNED_INCREMENT, RENDER_UI_TOOL, SPEC_TABLE_MIN_COLUMN_VAR, SPEC_TABLE_MIN_COLUMN_WIDTH, UI_CATALOG_GROUPS, UI_CATALOG_PROMPT_BUDGET_BYTES, UI_PRESETS, UI_PRESET_NAMES, VERCEL_INTERACTION_TOOL_NAME, VIEWER_COMPONENT_ATTR, VIEWER_FALLBACK_ATTR, VIEWER_PROPS_ATTR, VercelUiBridge, WEBSKILL_A2UI_CATALOG_ID, WEBSKILL_STYLES_CSS, WEBSKILL_SURFACE_ACTION, WebFormBridge, a2uiComponentSchema, a2uiComponentShapes, applySuggestion, buildA2uiCatalogDefinition, buildRenderResult, chartSpecFromProps, chartToTable, collectFormScopes, collectScopedValues, collectSpecActions, collectValues, createUiCatalogToolSource, defineUiCatalog, ensureStyles, evaluateFieldCondition, fromA2uiSpecAction, fromA2uiSurfaceAction, fromUiSurfaceActionDispatch, fromVercelToolResult, gaugePercent, interactionToFormModel, interactionToUiSpec, loadOpenUiPeers, loadWebSkillLitCatalog, mountEchart, mountViewerComponents, normalizeColumnWidths, qualifyFieldName, renderBlocks, renderMiniChart, renderMiniMarkdown, renderRenderResult, resolveChartFontSizes, resolveColumnWidths, resolveInteractionTexts, resolveSurfaceFormTexts, resolveSurfaceHostControlTexts, shapeInteractionValue, A2UI_CHILDREN_PROP as t, toA2uiSpecMessages, toA2uiSurfaceAction, toEchartsOption, toJsonRenderSpec, toOpenUiSpecLang, toUiSurfaceActionDispatch, toVercelToolInvocation, uiCatalog, uiPreset };