@webskill/sdk 0.14.0 → 0.15.0

package/dist/openUiSpecLang-DuOCdw9G.js

@@ -0,0 +1,1849 @@
+import { u as interactionToFormModel } from "./miniChart-owdCdaw-.js";
+import { toJSONSchema, z } from "zod";
+
+//#region ../ui/src/chart/echart.ts
+/** 与 catalog `Chart` 的 props 枚举逐字一致（`ui/catalog/uiCatalog.ts`） */
+const KINDS = /* @__PURE__ */ new Set([
+	"bar",
+	"line",
+	"area",
+	"pie",
+	"scatter",
+	"stacked-bar",
+	"dual-axis"
+]);
+const list = (value) => Array.isArray(value) ? value : [];
+/**
+* catalog `Chart` 节点 props → `ChartSpec`。四档共用这一份转换：
+* 此前 native / OpenUI / json-render / A2UI 各抄了一遍，改一处就会漂移。
+* 非法枚举**原样保留**，由 `toEchartsOption` 给出可见降级提示——
+* 此前偷偷改写成 `'line'`，画出的图与模型的意图无关且不可察觉。
+*/
+function chartSpecFromProps(props) {
+	const series = list(props["series"]);
+	return {
+		kind: typeof props["type"] === "string" ? props["type"] : "",
+		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 seriesNames = (chart) => chart.series.map((series) => series.name ?? "");
+/** 字号默认值的**全仓唯一来源**；`12` 是 echarts 的全局默认，显式写出后渲染不变 */
+const DEFAULT_CHART_FONT_SIZES = {
+	title: 14,
+	axisLabel: 12,
+	legend: 12
+};
+/** 逐字段兜底：宿主通常只想调大其中一两项 */
+function resolveChartFontSizes(sizes) {
+	return {
+		...DEFAULT_CHART_FONT_SIZES,
+		...sizes
+	};
+}
+/** echarts 的图例条目来源：饼图按标签分项，其余按系列名 */
+const legendEntries = (chart) => chart.kind === "pie" ? chart.labels : seriesNames(chart);
+/**
+* 非饼图的 series 形状表：catalog 声明的每种类型对应「基础 type + 零到一个修饰」。
+* 饼图不在表内——它的 data 要按 labels 重组，形状与其余六种不同。
+*/
+const SERIES_SHAPE = {
+	bar: { type: "bar" },
+	line: { type: "line" },
+	area: {
+		type: "line",
+		areaStyle: {}
+	},
+	scatter: { type: "scatter" },
+	"stacked-bar": {
+		type: "bar",
+		stack: "total"
+	},
+	"dual-axis": { type: "line" }
+};
+const FALLBACK_KIND = "bar";
+const fallbackNotice = (kind) => kind === "" ? `Missing chart type; rendered as a ${FALLBACK_KIND} chart.` : `Unsupported chart type "${kind}"; rendered as a ${FALLBACK_KIND} chart.`;
+/** `ChartSpec` → ECharts option：图表类型、数据系列、图例的唯一定义处 */
+function toEchartsOption(chart, fontSizes) {
+	const font = resolveChartFontSizes(fontSizes);
+	const known = KINDS.has(chart.kind);
+	const shape = SERIES_SHAPE[known ? chart.kind : FALLBACK_KIND];
+	const notice = known ? void 0 : fallbackNotice(chart.kind);
+	const valueAxis = {
+		type: "value",
+		axisLabel: { fontSize: font.axisLabel }
+	};
+	return {
+		animation: false,
+		title: chart.title || notice ? {
+			text: chart.title ?? "",
+			left: "center",
+			textStyle: { fontSize: font.title },
+			...notice ? { subtext: notice } : {}
+		} : void 0,
+		tooltip: { trigger: chart.kind === "pie" ? "item" : "axis" },
+		legend: {
+			bottom: 0,
+			textStyle: { fontSize: font.legend }
+		},
+		xAxis: chart.kind === "pie" ? void 0 : {
+			type: "category",
+			data: chart.labels,
+			axisLabel: { fontSize: font.axisLabel }
+		},
+		yAxis: chart.kind === "pie" ? void 0 : chart.kind === "dual-axis" ? [valueAxis, { ...valueAxis }] : valueAxis,
+		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, index) => ({
+			...shape,
+			name: series.name,
+			data: series.data,
+			...chart.kind === "dual-axis" ? { yAxisIndex: index === 0 ? 0 : 1 } : {}
+		}))
+	};
+}
+/**
+* 图表的 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");
+}
+/**
+* 一篇文档常同时挂载多张图表；共用同一个模块 promise，
+* 避免每个挂载点各自发起一次动态 import。
+*/
+let echartsModule;
+const loadEcharts = () => echartsModule ??= import("./echarts-BE7oV_Dl.js");
+/**
+* 框架无关的 echarts 挂载点：三档的 React 组件与 A2UI 档的 Lit 元素共用同一实现，
+* 图表不再因档位而异。echarts 走动态 import，不打进首屏。
+*/
+function mountEchart(container) {
+	let disposed = false;
+	let instance;
+	let queued;
+	let observer;
+	const apply = (chart, fontSizes) => {
+		instance?.setOption(toEchartsOption(chart, fontSizes), {
+			notMerge: true,
+			lazyUpdate: true
+		});
+	};
+	loadEcharts().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.chart, queued.fontSizes);
+	});
+	return {
+		setChart(chart, fontSizes) {
+			applyChartDomContract(container, chart);
+			queued = {
+				chart,
+				...fontSizes ? { fontSizes } : {}
+			};
+			apply(chart, fontSizes);
+		},
+		dispose() {
+			disposed = true;
+			observer?.disconnect();
+			observer = void 0;
+			instance?.dispose();
+			instance = void 0;
+		}
+	};
+}
+
+//#endregion
+//#region ../ui/src/catalog/gauge.ts
+/**
+* `Gauge` 的百分比换算（0.11.0 分册 19 FR-19.2）。
+*
+* catalog 的 React `SpecGauge` 与文档面的预置组件都读这一份：
+* 换算里有两个容易各写各的判断——`max === min` 时不能除零、越界值要夹紧——
+* 两处各写一遍就会在边界值上给出不同的条。
+*/
+function gaugePercent(value, min, max) {
+	const span = max - min;
+	if (span <= 0) return 0;
+	return Math.max(0, Math.min(100, (value - min) / span * 100));
+}
+
+//#endregion
+//#region ../ui/src/catalog/budget.ts
+/**
+* catalog 请求体积上限（0.11.0 分册 14 / AC-G20）的**数字单一来源**。
+*
+* 度量与报错格式在 `scripts/catalogBudget.mjs`（`check:contracts` 与 vitest 共用）；
+* 那边不重复这些数字，一律从本模块读——两处各写一份阈值就等于没有阈值。
+*
+* catalog 进入每一次 LLM 请求的有两处：系统提示词 `toPrompt()` 与
+* `render_ui` 入参 `toJsonSchema()`。只量前者会漏掉约 2/3 的成本。
+*
+* **超阈值的处置是砍组件或收窄枚举取值，不是抬高这里的数字。**
+*/
+/**
+* 预算阶段。0.11.0 分册 12 是那一版最后一处 catalog 增量，故切到 `'final'`：
+* 阈值收紧到实测终态 + 余量，且余量小于一个平均组件的成本
+* ——余量大于一个组件，等于默许下一版无声塞进一个。
+* 0.15.0 分册 13 新增 `OpenDocument` 后仍是 `'final'`，只是实测基线换了一份。
+*/
+const CATALOG_BUDGET_STAGE = "final";
+/**
+* 阈值 = **已落地实测** + 余量，余量须小于一个平均组件的成本。
+*
+* 2026-08-26 实测终态（0.15.0 分册 13 落地后）：prompt 13 372 / schema 22 184，31 个组件。
+* 平均组件成本 prompt 431 / schema 715。
+* 当前余量 prompt 278 / schema 316，均小于一个平均组件——再加一个组件必红。
+*
+* ⚠️ **这两个数字被上调过三次**，三次都由需求方裁决并改写了需求文档，
+* 不是实现阶段自行放宽：
+*
+* 1. 11 200 → 12 200 / 20 500 → 21 200（0.11.0 分册 29 §2 第 7 条）：分册 13 组件描述由短改长。
+*    `example` 是既有护栏的硬要求（`catalog.test.ts` 与 `catalogMatrix.test.tsx`
+*    逐个组件校验并四档渲染），靠省掉示例腾出的空间收不回来。
+* 2. 12 200 → 13 000 / 21 200 → 21 800（0.11.0 分册 29 §2.2）：分册 12 的 `Split` 实测 490 + 694，
+*    超出计划增量（403 + 1 047）的 prompt 侧。需求方裁定
+*    「描述要长，可用性大于预算阈值」——收紧措辞可省回 158 字节，
+*    但砍的正是各组件「何时改用 X」的辨析句，即选型准确率本身。
+* 3. 13 000 → 13 650 / 21 800 → 22 500（0.15.0 分册 13 §3，2026-08-26 裁决）：
+*    新增内置组件 `OpenDocument`，实测 prompt +372 / schema +384。
+*    该组件是本册消灭「站点技能在扩展里必然落到红框」的唯一手段，
+*    砍它等于砍掉整册需求；改用「catalog 里有些组件不广告」则引入一个新概念，
+*    模型看不见的组件与不存在的组件在它眼里没区别。需求方裁定取组件可用性、上调阈值，
+*    幅度以落地后实测为准、不得预留宽裕。
+*
+* 三次上调合计把单请求成本从 21.7 KB 抬到约 35.3 KB。
+* **AC-G20 原文「超了砍组件、不抬阈值」在这三处被推翻，每次都限于当版；
+* 后续再撞顶仍须回到需求方，本版同样不得成为第四次上调的先例。**
+*/
+const CATALOG_PROMPT_MAX = 13650;
+const CATALOG_SCHEMA_MAX = 22500;
+/**
+* **尚未落地**的计划增量。0.15.0 分册 13 已落地，故仍归零；
+* `CATALOG_BUDGET_STAGE` 保持 `'final'`，余量改由「小于一个平均组件」判定。
+*/
+const PLANNED_INCREMENT = {
+	prompt: 0,
+	schema: 0
+};
+
+//#endregion
+//#region ../ui/src/catalog/degradationCode.ts
+/** 码与人话之间的分隔符。放在消息最前面，`codeOfIssue` 才能从 zod 的 issue 里认出它。 */
+const SEPARATOR = ": ";
+/**
+* 给 zod 的 `error` 文案打上稳定码。
+*
+* 组件自己在 schema 里声明，sanitize 只负责把码搬到 `UiSpecDegradation.code` 上——
+* 这样新增一条策略性约束不需要去 sanitize 里加组件名分支（写死清单是本仓反复出问题的地方）。
+*/
+function codedError(code, message) {
+	return `${code}${SEPARATOR}${message}`;
+}
+/** 从 zod issue 的消息里取回码；没有码就返回 undefined（普通类型错误就是这种）。 */
+function codeOfIssue(message) {
+	const index = message.indexOf(SEPARATOR);
+	if (index <= 0) return void 0;
+	const head = message.slice(0, index);
+	return /^[A-Z][A-Z0-9_]*$/.test(head) ? head : void 0;
+}
+
+//#endregion
+//#region ../ui/src/catalog/sanitize.ts
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* 逐节点降级（FR-23.3）。
+*
+* 与 `validate` 的关系见 `UiCatalog.sanitize` 的注释：一个整块拒绝、一个逐节点救。
+*
+* **不写回 `safeParse` 的结果**是刻意的：zod 会剥离未声明的键，
+* 而渲染层确实在读若干未进 zod 的 prop（如 `suggestion`，由 SDK 侧下发而非模型生成）。
+* 写回等于把它们悄悄删掉。这里只删「确实解析失败」的那几个键。
+*/
+function sanitizeNode(catalog, byName, node, path, degradations) {
+	if (!isRecord$2(node)) {
+		degradations.push({
+			path,
+			kind: "node-dropped",
+			component: "unknown",
+			detail: "Node is not an object."
+		});
+		return;
+	}
+	const name = node["component"];
+	if (typeof name !== "string") {
+		degradations.push({
+			path,
+			kind: "node-dropped",
+			component: "unknown",
+			detail: "Node has no \"component\" name."
+		});
+		return;
+	}
+	const def = byName.get(name);
+	if (!def) {
+		degradations.push({
+			path,
+			kind: "unknown-component",
+			component: name,
+			detail: `Unknown component "${name}"; the catalog declares: ${catalog.components.map((c) => c.name).join(", ")}`
+		});
+		return;
+	}
+	const rawProps = isRecord$2(node["props"]) ? node["props"] : {};
+	let props = rawProps;
+	const parsed = def.props.safeParse(rawProps);
+	if (!parsed.success) {
+		const offending = new Set(parsed.error.issues.map((issue) => String(issue.path[0] ?? "")).filter((key) => key !== ""));
+		const codes = /* @__PURE__ */ new Map();
+		for (const issue of parsed.error.issues) {
+			const key = String(issue.path[0] ?? "");
+			const code = codeOfIssue(issue.message);
+			if (key !== "" && code !== void 0) codes.set(key, code);
+		}
+		const kept = {};
+		for (const [key, value] of Object.entries(rawProps)) if (!offending.has(key)) kept[key] = value;
+		const retry = def.props.safeParse(kept);
+		if (!retry.success) {
+			const carried = [...codes.values()].find((code) => code !== void 0);
+			degradations.push({
+				path,
+				kind: "node-dropped",
+				component: name,
+				detail: `Props cannot be repaired by dropping invalid keys: ${retry.error.issues.map((i) => i.message).join("; ")}`,
+				...carried === void 0 ? {} : { code: carried }
+			});
+			return;
+		}
+		for (const key of offending) {
+			const code = codes.get(key);
+			degradations.push({
+				path: `${path}.props.${key}`,
+				kind: "prop-dropped",
+				component: name,
+				detail: `Dropped invalid prop "${key}".`,
+				...code === void 0 ? {} : { code }
+			});
+		}
+		props = kept;
+	}
+	const sanitized = {
+		component: name,
+		props
+	};
+	if (typeof node["id"] === "string") sanitized.id = node["id"];
+	const children = node["children"];
+	if (children === void 0) return sanitized;
+	if (!Array.isArray(children)) {
+		degradations.push({
+			path: `${path}.children`,
+			kind: "constraint-ignored",
+			component: name,
+			detail: "children is not an array; rendered without children."
+		});
+		return sanitized;
+	}
+	if (def.children === void 0) {
+		degradations.push({
+			path: `${path}.children`,
+			kind: "constraint-ignored",
+			component: name,
+			detail: `Component "${name}" is a leaf; its children were dropped.`
+		});
+		return sanitized;
+	}
+	const allowed = def.children;
+	const singletons = /* @__PURE__ */ new Map();
+	const kept = [];
+	children.forEach((child, index) => {
+		const childPath = `${path}.children[${index}]`;
+		const childName = isRecord$2(child) && typeof child["component"] === "string" ? child["component"] : void 0;
+		if (allowed !== "any" && childName !== void 0 && !allowed.includes(childName)) {
+			degradations.push({
+				path: childPath,
+				kind: byName.has(childName) ? "node-dropped" : "unknown-component",
+				component: childName,
+				detail: byName.has(childName) ? `Component "${name}" only accepts children: ${[...allowed].join(", ")}` : `Unknown component "${childName}"; the catalog declares: ${catalog.components.map((c) => c.name).join(", ")}`
+			});
+			return;
+		}
+		if (childName !== void 0 && byName.get(childName)?.singletonPerContainer === true) {
+			const seen = (singletons.get(childName) ?? 0) + 1;
+			singletons.set(childName, seen);
+			if (seen > 1) {
+				degradations.push({
+					path: childPath,
+					kind: "node-dropped",
+					component: childName,
+					detail: `At most one "${childName}" per container; the extra one was dropped.`
+				});
+				return;
+			}
+		}
+		const sanitizedChild = sanitizeNode(catalog, byName, child, childPath, degradations);
+		if (sanitizedChild) kept.push(sanitizedChild);
+	});
+	sanitized.children = kept;
+	return sanitized;
+}
+function sanitizeUiSpec(catalog, byName, spec) {
+	const degradations = [];
+	return {
+		node: sanitizeNode(catalog, byName, spec, "root", degradations),
+		degradations
+	};
+}
+
+//#endregion
+//#region ../ui/src/catalog/defineCatalog.ts
+function componentSchema(def, rootDefs) {
+	const props = liftDefs(toJSONSchema(def.props, { io: "input" }), def.name, rootDefs);
+	const node = {
+		type: "object",
+		description: def.description,
+		properties: {
+			component: {
+				type: "string",
+				const: def.name
+			},
+			id: {
+				type: "string",
+				description: "Stable node id, reused on replay"
+			},
+			props
+		},
+		required: ["component"]
+	};
+	if (def.children !== void 0) node.properties = {
+		...node.properties,
+		children: {
+			type: "array",
+			description: def.children === "any" ? "Any catalog component" : `One of: ${[...def.children].join(", ")}`,
+			items: { $ref: "#" }
+		}
+	};
+	return node;
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const DEFS_REF_PREFIX = "#/$defs/";
+function rewriteDefRefs(node, renames) {
+	if (Array.isArray(node)) return node.map((child) => rewriteDefRefs(child, renames));
+	if (!isRecord$1(node)) return node;
+	const out = {};
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "$ref" && typeof value === "string" && value.startsWith(DEFS_REF_PREFIX)) {
+			const [head, ...tail] = value.slice(8).split("/");
+			const mapped = head === void 0 ? void 0 : renames.get(head);
+			out[key] = mapped === void 0 ? value : [`${DEFS_REF_PREFIX}${mapped}`, ...tail].join("/");
+			continue;
+		}
+		out[key] = rewriteDefRefs(value, renames);
+	}
+	return out;
+}
+/**
+* zod 每个组件各自产出 `$defs.__schemaN`，其 `#/$defs/...` 指的是那次转换自己的根；
+* 直接嵌进 catalog 大 schema 后那个 `#` 变成了 catalog 根，引用从产物根解析不到。
+* 提到根并以组件名限定，避免不同组件的同名定义互相覆盖。
+*/
+function liftDefs(schema, owner, rootDefs) {
+	const defs = schema["$defs"];
+	if (!isRecord$1(defs)) return schema;
+	const renames = /* @__PURE__ */ new Map();
+	for (const name of Object.keys(defs)) renames.set(name, `${owner}_${name}`);
+	for (const [name, def] of Object.entries(defs)) rootDefs[renames.get(name)] = rewriteDefRefs(def, renames);
+	const body = {};
+	for (const [key, value] of Object.entries(schema)) if (key !== "$defs") body[key] = value;
+	return rewriteDefRefs(body, renames);
+}
+function typeOf(schema) {
+	if (Array.isArray(schema.enum)) return schema.enum.map((option) => JSON.stringify(option)).join(" | ");
+	if (schema["const"] !== void 0) return JSON.stringify(schema["const"]);
+	const union = schema["anyOf"] ?? schema["oneOf"];
+	if (Array.isArray(union)) return union.map(typeOf).join(" | ");
+	if (schema.type === "array" && schema.items) return `${typeOf(schema.items)}[]`;
+	return typeof schema.type === "string" ? schema.type : "unknown";
+}
+function describeProps(def) {
+	const schema = toJSONSchema(def.props, { io: "input" });
+	const properties = schema.properties ?? {};
+	const required = new Set(schema.required ?? []);
+	const entries = Object.entries(properties).map(([key, value]) => `${key}${required.has(key) ? "" : "?"}: ${typeOf(value)}`);
+	return entries.length === 0 ? "—" : entries.join(", ");
+}
+function promptFor(catalog, options) {
+	const lines = [(options.mode === "tool-description" ? "" : `# ${catalog.title} (${catalog.version})\n\n`) + catalog.instructions.trim(), ""];
+	const groups = /* @__PURE__ */ new Map();
+	for (const def of catalog.components) groups.set(def.group, [...groups.get(def.group) ?? [], def]);
+	for (const [group, defs] of groups) {
+		lines.push(`## ${group}`, "");
+		for (const def of defs) {
+			lines.push(`### ${def.name}`, def.description, "", `props: ${describeProps(def)}`);
+			if (def.children !== void 0) lines.push(`children: ${def.children === "any" ? "any component" : [...def.children].join(" | ")}`);
+			for (const constraint of def.constraints ?? []) lines.push(`- ${constraint}`);
+			if (def.example) lines.push("", "```json", JSON.stringify(def.example), "```");
+			lines.push("");
+		}
+	}
+	if (catalog.actions.length > 0) {
+		lines.push("## actions", "");
+		for (const action of catalog.actions) lines.push(`- \`${action.name}\` — ${action.description}`);
+		lines.push("");
+	}
+	return lines.join("\n").trimEnd();
+}
+function validateNode(catalog, byName, node, path, issues) {
+	if (!isRecord$1(node)) {
+		issues.push({
+			path,
+			message: "Node must be an object"
+		});
+		return;
+	}
+	const name = node["component"];
+	if (typeof name !== "string") {
+		issues.push({
+			path,
+			message: "Node is missing a \"component\" name"
+		});
+		return;
+	}
+	const def = byName.get(name);
+	if (!def) {
+		issues.push({
+			path,
+			message: `Unknown component "${name}"; the catalog declares: ${catalog.components.map((c) => c.name).join(", ")}`
+		});
+		return;
+	}
+	const parsed = def.props.safeParse(node["props"] ?? {});
+	if (!parsed.success) for (const issue of parsed.error.issues) issues.push({
+		path: `${path}.props${issue.path.map((part) => `.${String(part)}`).join("")}`,
+		message: issue.message
+	});
+	const children = node["children"];
+	if (children === void 0) return;
+	if (!Array.isArray(children)) {
+		issues.push({
+			path: `${path}.children`,
+			message: "children must be an array"
+		});
+		return;
+	}
+	if (def.children === void 0) {
+		issues.push({
+			path: `${path}.children`,
+			message: `Component "${name}" is a leaf and cannot have children`
+		});
+		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") {
+			if (!allowed.includes(child["component"])) {
+				issues.push({
+					path: childPath,
+					message: `Component "${name}" only accepts children: ${[...allowed].join(", ")}`
+				});
+				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);
+	});
+}
+/**
+* 同一份定义派生出 JSON Schema / prompt / validator 三种投影，
+* 不允许任何一方手写副本（21 号文档 §1）。
+*/
+function defineUiCatalog(input) {
+	const byName = new Map(input.components.map((def) => [def.name, def]));
+	if (byName.size !== input.components.length) {
+		const seen = /* @__PURE__ */ new Set();
+		const duplicate = input.components.find((def) => seen.has(def.name) ? true : (seen.add(def.name), false));
+		throw new Error(`Duplicate component name "${duplicate?.name}" in UI catalog "${input.id}"`);
+	}
+	return {
+		...input,
+		componentNames: input.components.map((def) => def.name),
+		actionNames: input.actions.map((action) => action.name),
+		component: (name) => byName.get(name),
+		toJsonSchema: () => {
+			const $defs = {};
+			const oneOf = input.components.map((def) => componentSchema(def, $defs));
+			return {
+				$schema: "https://json-schema.org/draft/2020-12/schema",
+				$id: input.id,
+				title: input.title,
+				description: input.instructions,
+				...Object.keys($defs).length > 0 ? { $defs } : {},
+				oneOf
+			};
+		},
+		toPrompt: (options = {}) => promptFor(input, options),
+		validate: (spec) => {
+			const issues = [];
+			validateNode(input, byName, spec, "root", issues);
+			return issues.length === 0 ? { ok: true } : {
+				ok: false,
+				issues
+			};
+		},
+		sanitize: (spec) => sanitizeUiSpec(input, byName, spec)
+	};
+}
+
+//#endregion
+//#region ../ui/src/catalog/uiCatalog.ts
+const tone = z.enum([
+	"neutral",
+	"success",
+	"warning",
+	"info",
+	"destructive"
+]);
+/**
+* 装饰色。与 `tone` 语义**不重叠**：tone 表状态（success 是「成功」），
+* palette 表美观（「行程第三天」用绿色不代表它成功了）。
+* 取值是色板名不是颜色值——必须映射到 design token，深浅色主题才能自动跟随。
+*/
+const palette = z.enum([
+	"sky",
+	"violet",
+	"amber",
+	"rose",
+	"emerald"
+]);
+/**
+* surface 级视觉档（FR-13.4）。只在**根节点**上有意义，切的是一组 token
+* （圆角/阴影/底色），不是逐组件改样式；作用域限于该 surface 子树。
+* `office` 是缺省，与本版之前逐字节一致——它是回归基线。
+*/
+const surfaceTheme = z.enum([
+	"office",
+	"vivid",
+	"dashboard-dark"
+]);
+/** 图标白名单：任意名字会让模型产出渲染不出来的节点，且枚举长度直接计入每次请求 */
+const iconName = z.enum([
+	"info",
+	"check",
+	"alert",
+	"x",
+	"clock",
+	"calendar",
+	"user",
+	"star",
+	"search",
+	"settings",
+	"download",
+	"link",
+	"chart",
+	"file",
+	"folder",
+	"mail"
+]);
+/**
+* `Image.src` 的同源约束（AC-13.4）。**判定放在 schema 上，`validate` 与 `sanitize` 两条路径就都覆盖**；
+* 只写进组件描述等于把安全交给模型自觉——提示注入可以用 `src` 把数据带到任意主机上去。
+*
+* 同源按**语法**判：`data:image/` 与相对路径放行，任何带 scheme 的绝对 URL
+* 以及协议相对的 `//host/...` 一律拒。这样判定不需要知道当前 origin，
+* `@webskill/ui` 得以保持环境无关。
+*/
+const imageSrc = z.string().refine((src) => /^data:image\//i.test(src) || !/^([a-z][a-z0-9+.-]*:|\/\/)/i.test(src), { error: codedError("IMAGE_SRC_NOT_ALLOWED", "Image.src must be a same-origin path or a data:image URL; remote URLs are rejected by policy.") });
+const actionRef = z.object({
+	/** catalog actions 里声明过的名字 */
+	action: z.string().describe("Action name declared by the catalog"),
+	label: z.string(),
+	disabled: z.boolean().optional()
+});
+const CONTENT = [
+	"Stack",
+	"Card",
+	"Separator",
+	"Heading",
+	"Text",
+	"Markdown",
+	"Badge"
+];
+const DATA = [
+	"Metric",
+	"Table",
+	"Chart",
+	"Timeline",
+	"FileLink"
+];
+const INPUT = [
+	"Form",
+	"Field",
+	"FieldArray",
+	"Button"
+];
+/**
+* `visibleWhen` 的结构化条件（设计 23 §1.2）。用 `z.lazy` 自引用；
+* 语义深度上限不在 zod 里卡，由 `evaluateFieldCondition` 按 `MAX_CONDITION_DEPTH` 降级处理。
+*/
+const fieldCondition = z.lazy(() => z.union([
+	z.object({
+		field: z.string(),
+		equals: z.union([
+			z.string(),
+			z.number(),
+			z.boolean()
+		])
+	}),
+	z.object({
+		field: z.string(),
+		in: z.array(z.union([z.string(), z.number()]))
+	}),
+	z.object({
+		field: z.string(),
+		notEmpty: z.literal(true)
+	}),
+	z.object({ allOf: z.array(fieldCondition).min(1) }),
+	z.object({ anyOf: z.array(fieldCondition).min(1) })
+]));
+/** 选项既可以写死，也可以声明成异步取值（取值通道属分册 24） */
+const fieldOptions = z.array(z.object({
+	label: z.string(),
+	value: z.union([z.string(), z.number()])
+}));
+/** Tabs 的面板与 Grid 的格子必须自成容器，否则「每容器至多一个表单」就没有落脚点 */
+const PANEL = ["Card", "Stack"];
+/**
+* v3 首发 catalog：覆盖旧六类 surface（metric / chart / table / form / file / custom）的全部表达力，先窄后宽。
+* 只依赖 zod —— 不 import 任何 UI framework（21 号文档 §5.1）。
+*/
+const uiCatalog = defineUiCatalog({
+	id: "https://webskill.dev/catalogs/v1",
+	version: "1.0.0",
+	title: "WebSkill AI Component Catalog",
+	instructions: [
+		"Compose the answer UI from the components below. Rules:",
+		"",
+		"- The root node of a surface must be `Stack` or `Card`.",
+		"- 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 or scripts. `Image.src` must be same-origin or a data URL.",
+		"- 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: [
+		{
+			name: "Stack",
+			group: "layout",
+			description: "Vertical or horizontal container. Use it as the root of most surfaces.",
+			props: z.object({
+				direction: z.enum(["vertical", "horizontal"]).default("vertical"),
+				gap: z.enum([
+					"sm",
+					"md",
+					"lg"
+				]).default("md"),
+				align: z.enum([
+					"start",
+					"center",
+					"end",
+					"stretch"
+				]).optional(),
+				theme: surfaceTheme.optional()
+			}),
+			children: "any",
+			example: {
+				component: "Stack",
+				props: { direction: "vertical" },
+				children: [{
+					component: "Heading",
+					props: {
+						level: 2,
+						text: "Q4 results"
+					}
+				}]
+			}
+		},
+		{
+			name: "Card",
+			group: "layout",
+			description: "A titled section that groups related content.",
+			props: z.object({
+				title: z.string(),
+				description: z.string().optional(),
+				palette: palette.optional(),
+				theme: surfaceTheme.optional(),
+				span: z.union([z.literal(1), z.literal(2)]).default(1),
+				density: z.enum([
+					"compact",
+					"default",
+					"comfortable"
+				]).default("default")
+			}),
+			children: "any",
+			example: {
+				component: "Card",
+				props: { title: "Revenue" },
+				children: [{
+					component: "Metric",
+					props: {
+						label: "MRR",
+						value: "12,400"
+					}
+				}]
+			}
+		},
+		{
+			name: "Separator",
+			group: "layout",
+			description: "A horizontal rule between sections.",
+			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: "Split",
+			group: "layout",
+			description: "Two panes side by side at a fixed ratio — a chart next to its takeaways, a form next to its help text, a summary next to the detail it summarises. Takes exactly two children and stacks them vertically when the container is narrow, so the main pane always comes first. Use `Grid` when the cells are peers rather than a main/side pair.",
+			props: z.object({ ratio: z.enum([
+				"1:1",
+				"2:1",
+				"3:1",
+				"1:2"
+			]).default("1:1") }),
+			children: PANEL,
+			example: {
+				component: "Split",
+				props: { ratio: "2:1" },
+				children: [{
+					component: "Card",
+					props: { title: "Trend" }
+				}, {
+					component: "Card",
+					props: { title: "Notes" }
+				}]
+			}
+		},
+		{
+			name: "Grid",
+			group: "layout",
+			description: "Dashboard grid: several tiles, metrics or charts the reader scans in parallel. Each child is one cell and its own form container. Prefer `columns: 'auto'` with a `minColumnWidth` — it fits as many cells as the container allows and reflows when narrow, which a fixed count cannot do. Set a fixed count only when the layout really needs exactly N.",
+			props: z.object({
+				columns: z.union([
+					z.literal(2),
+					z.literal(3),
+					z.literal(4),
+					z.literal("auto")
+				]).default(2),
+				minColumnWidth: z.enum([
+					"sm",
+					"md",
+					"lg"
+				]).default("md")
+			}),
+			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",
+			description: "Section heading. Level 2 is the largest allowed inside a message.",
+			props: z.object({
+				level: z.union([
+					z.literal(2),
+					z.literal(3),
+					z.literal(4)
+				]).default(3),
+				text: z.string(),
+				palette: palette.optional()
+			}),
+			example: {
+				component: "Heading",
+				props: {
+					level: 3,
+					text: "Summary"
+				}
+			}
+		},
+		{
+			name: "Text",
+			group: "content",
+			description: "A paragraph of plain text.",
+			props: z.object({
+				text: z.string(),
+				tone: z.enum(["default", "muted"]).default("default")
+			}),
+			example: {
+				component: "Text",
+				props: { text: "Revenue grew 12% quarter over quarter." }
+			}
+		},
+		{
+			name: "Markdown",
+			group: "content",
+			description: "Restricted Markdown (no HTML). Use for lists and emphasis, not for tables.",
+			props: z.object({ text: z.string() }),
+			constraints: ["HTML tags are rejected; use Table for tabular data"],
+			example: {
+				component: "Markdown",
+				props: { text: "- first\n- second" }
+			}
+		},
+		{
+			name: "Badge",
+			group: "content",
+			description: "A short status label.",
+			props: z.object({
+				text: z.string(),
+				tone: tone.default("neutral"),
+				palette: palette.optional()
+			}),
+			example: {
+				component: "Badge",
+				props: {
+					text: "active",
+					tone: "success"
+				}
+			}
+		},
+		{
+			name: "Metric",
+			group: "data",
+			description: "A single headline number with an optional change indicator.",
+			props: z.object({
+				label: z.string(),
+				value: z.union([z.string(), z.number()]),
+				change: z.string().optional(),
+				trend: z.enum([
+					"up",
+					"down",
+					"neutral"
+				]).optional()
+			}),
+			example: {
+				component: "Metric",
+				props: {
+					label: "MRR",
+					value: "12,400",
+					trend: "up",
+					change: "+12%"
+				}
+			}
+		},
+		{
+			name: "Table",
+			group: "data",
+			description: "Tabular data with explicit columns. Prefer it over Markdown tables.",
+			props: z.object({
+				title: z.string().optional(),
+				columns: z.array(z.string()).min(1),
+				rows: z.array(z.array(z.union([
+					z.string(),
+					z.number(),
+					z.boolean(),
+					z.null()
+				]))),
+				/** 列宽权重，长度需与 columns 一致；不一致时整项忽略而不拒绝渲染 */
+				columnWidths: z.array(z.number().positive()).optional()
+			}),
+			example: {
+				component: "Table",
+				props: {
+					columns: ["Quarter", "Revenue"],
+					rows: [["Q3", 9800], ["Q4", 12400]]
+				}
+			}
+		},
+		{
+			name: "Chart",
+			group: "data",
+			description: "A bar, line, area, pie, scatter, stacked or dual-axis chart over labelled series.",
+			props: z.object({
+				type: z.enum([
+					"bar",
+					"line",
+					"area",
+					"pie",
+					"scatter",
+					"stacked-bar",
+					"dual-axis"
+				]),
+				title: z.string().optional(),
+				labels: z.array(z.string()).min(1),
+				series: z.array(z.object({
+					name: z.string(),
+					values: z.array(z.number())
+				})).min(1)
+			}),
+			example: {
+				component: "Chart",
+				props: {
+					type: "bar",
+					labels: ["Q3", "Q4"],
+					series: [{
+						name: "Revenue",
+						values: [9800, 12400]
+					}]
+				}
+			}
+		},
+		{
+			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",
+			description: "A download entry for a file. The host automatically renders every artifact the run produced as a download card, so never create a FileLink for those; use it only for files that are not run artifacts.",
+			props: z.object({
+				path: z.string(),
+				label: 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",
+					size: 2411724
+				}
+			}
+		},
+		{
+			name: "Form",
+			group: "input",
+			description: "Collects user input. Children must be Field nodes; actions go in the buttons prop.",
+			props: z.object({
+				title: z.string().optional(),
+				submitLabel: z.string().default("Submit"),
+				cancelLabel: z.string().optional()
+			}),
+			children: ["Field", "FieldArray"],
+			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" },
+				children: [{
+					component: "Field",
+					props: {
+						name: "email",
+						label: "Email",
+						type: "text",
+						required: true
+					}
+				}]
+			}
+		},
+		{
+			name: "Field",
+			group: "input",
+			description: "A single form control. Only valid inside a Form.",
+			props: z.object({
+				name: z.string(),
+				label: z.string(),
+				type: z.enum([
+					"text",
+					"number",
+					"date",
+					"textarea",
+					"select",
+					"multi-select",
+					"toggle",
+					"file",
+					"password"
+				]),
+				required: z.boolean().optional(),
+				description: z.string().optional(),
+				defaultValue: z.unknown().optional(),
+				options: fieldOptions.optional(),
+				/** 声明后选项由宕主异步提供；与写死的 options 互斥 */
+				optionsSource: z.string().optional(),
+				visibleWhen: fieldCondition.optional()
+			}),
+			constraints: [
+				"select / multi-select must provide options or optionsSource",
+				"password values are never persisted, never echoed and never enter the user profile",
+				"visibleWhen may only reference fields declared in the same Form"
+			],
+			example: {
+				component: "Field",
+				props: {
+					name: "range",
+					label: "Range",
+					type: "select",
+					options: []
+				}
+			}
+		},
+		{
+			name: "FieldArray",
+			group: "input",
+			description: "A repeatable group of fields. Only valid inside a Form; children must be Field nodes.",
+			props: z.object({
+				name: z.string(),
+				label: z.string(),
+				minItems: z.number().int().min(0).optional(),
+				maxItems: z.number().int().min(1).optional(),
+				addLabel: z.string().optional(),
+				removeLabel: z.string().optional()
+			}),
+			children: ["Field"],
+			constraints: ["Only valid inside a Form", "Submitted as an array of objects keyed by the inner Field names"],
+			example: {
+				component: "FieldArray",
+				props: {
+					name: "recipients",
+					label: "Recipients",
+					minItems: 1
+				},
+				children: [{
+					component: "Field",
+					props: {
+						name: "email",
+						label: "Email",
+						type: "text"
+					}
+				}]
+			}
+		},
+		{
+			name: "Button",
+			group: "input",
+			description: "Triggers one of the catalog actions.",
+			props: actionRef,
+			example: {
+				component: "Button",
+				props: {
+					action: "submit",
+					label: "Send"
+				}
+			}
+		},
+		{
+			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: "Icon",
+			group: "content",
+			description: "A small semantic icon, picked from the catalog whitelist. Use it to mark an item inside a list or next to a heading, never on its own as decoration. Names outside the whitelist are dropped by the renderer, so choose the closest listed name instead of inventing one.",
+			props: z.object({
+				name: iconName,
+				palette: palette.optional()
+			}),
+			example: {
+				component: "Icon",
+				props: {
+					name: "check",
+					palette: "emerald"
+				}
+			}
+		},
+		{
+			name: "Image",
+			group: "content",
+			description: "An image the host already serves. `src` must be same-origin or a data URL — remote URLs are rejected by policy, so never link to an image you found on the web. `alt` is required: it is what a screen reader and a later model read instead of the pixels.",
+			props: z.object({
+				src: imageSrc,
+				alt: z.string(),
+				ratio: z.enum([
+					"auto",
+					"1:1",
+					"4:3",
+					"16:9"
+				]).default("auto")
+			}),
+			example: {
+				component: "Image",
+				props: {
+					src: "/chart.png",
+					alt: "Revenue by region",
+					ratio: "16:9"
+				}
+			}
+		},
+		{
+			name: "Quote",
+			group: "content",
+			description: "Someone else's words, set apart from your own. Use it when you are repeating a customer comment, a policy sentence or a source document, so the reader can tell it apart from your summary. Do not use it for emphasis.",
+			props: z.object({
+				text: z.string(),
+				by: z.string().optional()
+			}),
+			example: {
+				component: "Quote",
+				props: {
+					text: "Delivery was two days late.",
+					by: "Order A-1002"
+				}
+			}
+		},
+		{
+			name: "Callout",
+			group: "content",
+			description: "A side note the reader may want but does not have to act on — background, a caveat, a definition. Use `Alert` instead when it is a state they must react to, and plain `Text` when it belongs in the flow of the answer.",
+			props: z.object({
+				title: z.string().optional(),
+				text: z.string(),
+				palette: palette.optional()
+			}),
+			example: {
+				component: "Callout",
+				props: {
+					title: "How this is counted",
+					text: "Refunds are excluded."
+				}
+			}
+		},
+		{
+			name: "KeyValue",
+			group: "data",
+			description: "Facts about one thing, as label/value pairs. Use it when a `Table` would have a single row, for example the details of one order. For several comparable rows use `Table`, and for one headline number use `Metric`.",
+			props: z.object({ items: z.array(z.object({
+				label: z.string(),
+				value: z.string()
+			})).min(1) }),
+			example: {
+				component: "KeyValue",
+				props: { items: [{
+					label: "Status",
+					value: "Shipped"
+				}, {
+					label: "Carrier",
+					value: "DHL"
+				}] }
+			}
+		},
+		{
+			name: "Gauge",
+			group: "data",
+			description: "One value read against a range — capacity used, budget spent, a score out of a maximum. Give `min` and `max` when the range is not 0-100. Use `Progress` for how far a task has come, and `Metric` when there is no range to compare against.",
+			props: z.object({
+				label: z.string().optional(),
+				value: z.number(),
+				min: z.number().default(0),
+				max: z.number().default(100),
+				tone: z.enum([
+					"neutral",
+					"success",
+					"warning"
+				]).default("neutral")
+			}),
+			example: {
+				component: "Gauge",
+				props: {
+					label: "Disk used",
+					value: 82,
+					tone: "warning"
+				}
+			}
+		},
+		{
+			name: "Accordion",
+			group: "layout",
+			description: "Sections the reader opens one at a time. Use it for a long report where most readers only need one part, so the answer stays scannable instead of becoming a wall of text. Use `Tabs` when the sections are alternatives rather than a sequence, and plain `Card`s when there are only two or three short ones.",
+			props: z.object({ items: z.array(z.object({
+				title: z.string(),
+				text: z.string()
+			})).min(1) }),
+			example: {
+				component: "Accordion",
+				props: { items: [{
+					title: "Method",
+					text: "Sampled hourly."
+				}, {
+					title: "Caveats",
+					text: "Week 12 is partial."
+				}] }
+			}
+		},
+		{
+			name: "Carousel",
+			group: "layout",
+			description: "Slides the reader scrolls through sideways — an itinerary day by day, a set of options, a small gallery. Each slide carries its own title and optional image, and only one is in view at a time. Use `Grid` when the reader should compare the items side by side instead of one at a time.",
+			props: z.object({ items: z.array(z.object({
+				title: z.string(),
+				text: z.string().optional(),
+				src: z.string().optional()
+			})).min(1) }),
+			example: {
+				component: "Carousel",
+				props: { items: [{
+					title: "Day 1",
+					text: "Arrival"
+				}, {
+					title: "Day 2",
+					text: "Old town"
+				}] }
+			}
+		},
+		{
+			name: "Alert",
+			group: "feedback",
+			description: "Draws attention to a state the user must know about.",
+			props: z.object({
+				tone: z.enum([
+					"info",
+					"warning",
+					"destructive"
+				]).default("info"),
+				title: z.string(),
+				description: z.string().optional()
+			}),
+			example: {
+				component: "Alert",
+				props: {
+					tone: "warning",
+					title: "Partial data"
+				}
+			}
+		},
+		{
+			name: "Custom",
+			group: "layout",
+			description: "Host extension point; the name must be registered in the host SurfaceRegistry.",
+			props: z.object({
+				name: z.string(),
+				props: z.record(z.string(), z.unknown()).default({})
+			}),
+			constraints: ["Rejected when the host has not registered the component name"],
+			example: {
+				component: "Custom",
+				props: {
+					name: "sales-map",
+					props: {}
+				}
+			}
+		},
+		{
+			name: "OpenDocument",
+			group: "layout",
+			description: "A button that asks the host to open a document artifact produced by this run in an isolated viewer. Use it for print-ready pages that do not fit inside the chat column; use Card/Table/Chart instead when the content belongs in the conversation.",
+			props: z.object({
+				artifact: z.string(),
+				style: z.string().optional(),
+				label: z.string().optional(),
+				dataSource: z.string()
+			}),
+			constraints: ["The artifact name is resolved inside the producing run artifact directory; path separators are rejected", "Renders nothing when the host has not wired a document surface"],
+			example: {
+				component: "OpenDocument",
+				props: {
+					artifact: "report.html",
+					dataSource: "fetchData: bugs / metrics"
+				}
+			}
+		}
+	],
+	actions: [
+		{
+			name: "submit",
+			description: "Submit the surface form values back to the waiting run."
+		},
+		{
+			name: "cancel",
+			description: "Dismiss the surface without submitting."
+		},
+		{
+			name: "select",
+			description: "Report a selected row or option."
+		},
+		{
+			name: "download",
+			description: "Download the referenced artifact."
+		},
+		{
+			name: "refresh",
+			description: "Ask the run to recompute the surface."
+		}
+	]
+});
+/** prompt / 文档里引用的分组顺序（Console 展示同序） */
+const UI_CATALOG_GROUPS = {
+	content: CONTENT,
+	data: DATA,
+	input: INPUT
+};
+/**
+* catalog 系统提示的体积上限（UTF-8 字节，FR-6.6）。
+*
+* **0.11.0 起只是 `CATALOG_PROMPT_MAX` 的别名**：旧值 20 480 相对实际 7 788 宽了 2.6 倍，
+* 拦不住任何东西；且它只量提示词，漏掉了 `render_ui` 入参 Schema 那约两分之一的成本。
+* @deprecated 用 `CATALOG_PROMPT_MAX` / `CATALOG_SCHEMA_MAX`（`./budget`）。
+*/
+const UI_CATALOG_PROMPT_BUDGET_BYTES = CATALOG_PROMPT_MAX;
+
+//#endregion
+//#region ../ui/src/catalog/formScopes.ts
+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;
+}
+
+//#endregion
+//#region ../ui/src/catalog/fieldCondition.ts
+/**
+* 条件树的语义深度上限。
+* `MAX_JSON_DEPTH` 管的是 props 的 JSON 深度，管不到这里——超它之前就能先把栈打爆。
+*/
+const MAX_CONDITION_DEPTH = 8;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isEmpty = (value) => value === void 0 || value === null || value === "" || Array.isArray(value) && value.length === 0;
+function invalid(path, detail) {
+	return {
+		visible: true,
+		degraded: {
+			path,
+			kind: "condition-invalid",
+			detail
+		}
+	};
+}
+function evaluate(condition, context, depth) {
+	if (depth > 8) return invalid(context.path, `Condition nesting exceeds ${8} levels.`);
+	if (!isRecord(condition)) return invalid(context.path, "Condition must be an object.");
+	if (Array.isArray(condition["allOf"]) || Array.isArray(condition["anyOf"])) {
+		const isAll = Array.isArray(condition["allOf"]);
+		const branches = isAll ? condition["allOf"] : condition["anyOf"];
+		if (branches.length === 0) return invalid(context.path, `"${isAll ? "allOf" : "anyOf"}" must not be empty.`);
+		let visible = isAll;
+		for (const branch of branches) {
+			const result = evaluate(branch, context, depth + 1);
+			if (result.degraded) return result;
+			visible = isAll ? visible && result.visible : visible || result.visible;
+		}
+		return { visible };
+	}
+	const field = condition["field"];
+	if (typeof field !== "string" || field === "") return invalid(context.path, "Condition needs a \"field\" name.");
+	const value = context.resolve(field);
+	if ("equals" in condition) {
+		const expected = condition["equals"];
+		if (typeof expected !== "string" && typeof expected !== "number" && typeof expected !== "boolean") return invalid(context.path, "\"equals\" must be a string, number or boolean.");
+		return { visible: value === expected };
+	}
+	if ("in" in condition) {
+		const options = condition["in"];
+		if (!Array.isArray(options)) return invalid(context.path, "\"in\" must be an array.");
+		return { visible: options.some((option) => option === value) };
+	}
+	if ("notEmpty" in condition) {
+		if (condition["notEmpty"] !== true) return invalid(context.path, "\"notEmpty\" must be true.");
+		return { visible: !isEmpty(value) };
+	}
+	return invalid(context.path, "Condition has no recognised operator (equals / in / notEmpty / allOf / anyOf).");
+}
+/**
+* 全仓唯一的条件求值实现（AC-23.4）。纯函数、无 React 依赖——
+* `useSurfaceForm` 在 ui-react 且是 hook，ui-vue 用不了它。
+*/
+function evaluateFieldCondition(condition, values, options = {}) {
+	const resolveField = options.resolveField;
+	return evaluate(condition, {
+		values,
+		resolve: (field) => values[resolveField ? resolveField(field) : field],
+		path: options.path ?? "visibleWhen"
+	}, 1);
+}
+
+//#endregion
+//#region ../ui/src/catalog/tableColumns.ts
+/**
+* 生成式表格的列模型（分册 15-03 定义 `priority`，分册 25 在同一结构上追加 `weight`）。
+*
+* 四个渲染档共用这一份：native / json-render / OpenUI 走 TS，a2ui 是 Lit，
+* 后者读不到 TS 常量，所以最小列宽以 **CSS 变量**交付，两侧引用同一个名字。
+*/
+/** 最小列宽的分档取值。`desktop` 沿用历史值，改它会动所有既有表格的视觉基线 */
+const SPEC_TABLE_MIN_COLUMN_WIDTH = {
+	desktop: "8rem",
+	mobile: "5rem"
+};
+/** CSS 侧的引用名：`surfaces.css` 与 a2ui 的 Lit 样式都只写这个变量，不写字面量 */
+const SPEC_TABLE_MIN_COLUMN_VAR = "--webskill-table-min-col";
+/**
+* 校验并归一化 `columnWidths`。
+*
+* **整项忽略**是刻意的：部分采纳（例如只丢掉那个负数）会让模型拿到一个
+* 「看起来生效了」的结果，更难发现自己写错了（FR-25.3）。
+*/
+function normalizeColumnWidths(raw, columnCount) {
+	const equal = () => Array.from({ length: columnCount }, () => 1);
+	if (raw === void 0) return { weights: equal() };
+	if (raw.length !== columnCount) return {
+		weights: equal(),
+		rejected: "length-mismatch"
+	};
+	if (raw.some((value) => typeof value !== "number" || !Number.isFinite(value))) return {
+		weights: equal(),
+		rejected: "non-finite"
+	};
+	if (raw.some((value) => value < 0)) return {
+		weights: equal(),
+		rejected: "negative"
+	};
+	if (raw.every((value) => value === 0)) return {
+		weights: equal(),
+		rejected: "all-zero"
+	};
+	return { weights: [...raw] };
+}
+/**
+* 按权重分配列宽，且每列不低于 `minWidth`。
+*
+* 朴素实现（按权重算一遍、低于下限的抬到下限）会让总宽超出容器，
+* 白白产生本可避免的横滚。这里迭代到不动点：每轮把触底的列钉住，
+* 剩余空间在剩余列间按权重重新分配（FR-25.2）。
+*
+* 容器本身放不下 `columnCount * minWidth` 时无解——此时全部取下限并返回，
+* 由调用方决定横滚（AC-25.4）。
+*/
+function resolveColumnWidths(weights, available, minWidth) {
+	const count = weights.length;
+	if (count === 0) return [];
+	if (available <= count * minWidth) return Array.from({ length: count }, () => minWidth);
+	const result = Array.from({ length: count }, () => 0);
+	const pinned = new Array(count).fill(false);
+	for (let round = 0; round <= count; round += 1) {
+		const freeIndexes = result.map((_, index) => index).filter((index) => !pinned[index]);
+		const remaining = available - result.reduce((sum, value, index) => pinned[index] ? sum + value : sum, 0);
+		const weightTotal = freeIndexes.reduce((sum, index) => sum + (weights[index] ?? 0), 0);
+		let changed = false;
+		for (const index of freeIndexes) {
+			const share = weightTotal > 0 ? remaining * (weights[index] ?? 0) / weightTotal : remaining / freeIndexes.length;
+			if (share < minWidth) {
+				result[index] = minWidth;
+				pinned[index] = true;
+				changed = true;
+			} else result[index] = share;
+		}
+		if (!changed) break;
+	}
+	return result;
+}
+
+//#endregion
+//#region ../ui/src/catalog/toJsonRenderSpec.ts
+/**
+* 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,
+			props: node.props ?? {},
+			...children.length > 0 ? { children } : {}
+		};
+		return key;
+	};
+	return {
+		root: walk(spec),
+		elements
+	};
+}
+
+//#endregion
+//#region ../ui/src/catalog/interactionToUiSpec.ts
+/** ControlModel 的控件词汇 → catalog `Field.type`（catalog 的 9 种是超集） */
+const FIELD_TYPE = {
+	text: "text",
+	number: "number",
+	boolean: "toggle",
+	select: "select",
+	textarea: "textarea",
+	file: "file",
+	password: "password",
+	date: "date"
+};
+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.accept ? { accept: [...control.accept] } : {},
+			...control.multiple ? { multiple: true } : {},
+			...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]
+	};
+}
+
+//#endregion
+//#region ../ui/src/adapters/openui/openUiSpecLang.ts
+const literal = (value) => JSON.stringify(value ?? null);
+/** 组件的位置参数顺序 = catalog props 的 schema key 顺序（OpenUI 的 param map 同源） */
+function propOrder(catalog) {
+	const branches = catalog.toJsonSchema()["oneOf"] ?? [];
+	const order = /* @__PURE__ */ new Map();
+	for (const branch of branches) {
+		const name = (branch.properties?.["component"])?.["const"];
+		const props = branch.properties?.["props"];
+		if (typeof name === "string") order.set(name, Object.keys(props?.properties ?? {}));
+	}
+	return order;
+}
+/**
+* catalog 声明树 → openui-lang 文本。语法为每行一条 `id = Component(位置参数…)`，
+* `root = …` 为入口；容器组件的子节点作为最后一个参数传 id 数组。
+*/
+function toOpenUiSpecLang(spec, catalog = uiCatalog) {
+	const order = propOrder(catalog);
+	const lines = [];
+	let counter = 0;
+	const walk = (node) => {
+		const id = node.id ?? `n${counter++}`;
+		const childIds = (node.children ?? []).map(walk);
+		const def = catalog.component(node.component);
+		const args = (order.get(node.component) ?? []).map((key) => literal(node.props?.[key]));
+		if (def?.children !== void 0) args.push(`[${childIds.join(", ")}]`);
+		lines.push(`${id} = ${node.component}(${args.join(", ")})`);
+		return id;
+	};
+	const rootId = walk(spec);
+	return [...lines.filter((line) => !line.startsWith(`${rootId} =`)), `root = ${lines.find((line) => line.startsWith(`${rootId} =`)).slice(rootId.length + 3)}`].join("\n");
+}
+
+//#endregion
+export { chartSpecFromProps as C, toEchartsOption as E, DEFAULT_CHART_FONT_SIZES as S, resolveChartFontSizes as T, CATALOG_BUDGET_STAGE as _, SPEC_TABLE_MIN_COLUMN_WIDTH as a, PLANNED_INCREMENT as b, MAX_CONDITION_DEPTH as c, collectScopedValues as d, qualifyFieldName as f, defineUiCatalog as g, uiCatalog as h, SPEC_TABLE_MIN_COLUMN_VAR as i, evaluateFieldCondition as l, UI_CATALOG_PROMPT_BUDGET_BYTES as m, interactionToUiSpec as n, normalizeColumnWidths as o, UI_CATALOG_GROUPS as p, toJsonRenderSpec as r, resolveColumnWidths as s, toOpenUiSpecLang as t, collectFormScopes as u, CATALOG_PROMPT_MAX as v, mountEchart as w, gaugePercent as x, CATALOG_SCHEMA_MAX as y };