@webskill/sdk 0.10.0 → 0.12.0

package/dist/{dist-1OFC-zax.js → dist-DqcL6jKO.js}

@@ -1,7 +1,7 @@
 import { h as WebSkillError } from "./dist-Bev6i6Ip.js";
 import { toJSONSchema, z } from "zod";
 
-//#region ../ui/dist/webskillCatalog-BA7pjlS9.js
+//#region ../ui/dist/webskillCatalog-nTgkL9Xe.js
 const DEFAULT_INTERACTION_TEXTS = {
 	submit: "Submit",
 	cancel: "Cancel",
@@ -39,6 +39,19 @@ function resolveSurfaceFormTexts(texts) {
 		...texts
 	} : DEFAULT_SURFACE_FORM_TEXTS;
 }
+const DEFAULT_SURFACE_HOST_CONTROL_TEXTS = {
+	previousPage: "Previous page",
+	previous: "Previous",
+	nextPage: "Next page",
+	next: "Next",
+	carousel: "Carousel"
+};
+function resolveSurfaceHostControlTexts(texts) {
+	return texts ? {
+		...DEFAULT_SURFACE_HOST_CONTROL_TEXTS,
+		...texts
+	} : DEFAULT_SURFACE_HOST_CONTROL_TEXTS;
+}
 /** 提交值按请求类型归形（WebFormBridge 与框架组件库共享单一来源） */
 function shapeInteractionValue(model, values) {
 	switch (model.kind) {
@@ -216,23 +229,27 @@ function renderMiniMarkdown(text, doc) {
 	}
 	return root;
 }
+/** 与 catalog `Chart` 的 props 枚举逐字一致（`ui/catalog/uiCatalog.ts`） */
 const KINDS = /* @__PURE__ */ new Set([
 	"bar",
 	"line",
-	"pie"
+	"area",
+	"pie",
+	"scatter",
+	"stacked-bar",
+	"dual-axis"
 ]);
 const list = (value) => Array.isArray(value) ? value : [];
 /**
 * catalog `Chart` 节点 props → `ChartSpec`。四档共用这一份转换：
 * 此前 native / OpenUI / json-render / A2UI 各抄了一遍，改一处就会漂移。
-* catalog 的 `area` 在 `ChartSpec` 里没有对应枚举，按折线渲染——
-* 原先的裸 cast 会把非法枚举一路带进渲染器，画出空图。
+* 非法枚举**原样保留**，由 `toEchartsOption` 给出可见降级提示——
+* 此前偷偷改写成 `'line'`，画出的图与模型的意图无关且不可察觉。
 */
 function chartSpecFromProps(props) {
-	const type = typeof props["type"] === "string" ? props["type"] : "bar";
 	const series = list(props["series"]);
 	return {
-		kind: KINDS.has(type) ? type : "line",
+		kind: typeof props["type"] === "string" ? props["type"] : "",
 		labels: list(props["labels"]),
 		series: series.map((item) => ({
 			...typeof item.name === "string" ? { name: item.name } : {},
@@ -242,24 +259,70 @@ function chartSpecFromProps(props) {
 	};
 }
 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) {
+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 ? {
-			text: chart.title,
+		title: chart.title || notice ? {
+			text: chart.title ?? "",
 			left: "center",
-			textStyle: { fontSize: 14 }
+			textStyle: { fontSize: font.title },
+			...notice ? { subtext: notice } : {}
 		} : void 0,
 		tooltip: { trigger: chart.kind === "pie" ? "item" : "axis" },
-		legend: { bottom: 0 },
+		legend: {
+			bottom: 0,
+			textStyle: { fontSize: font.legend }
+		},
 		xAxis: chart.kind === "pie" ? void 0 : {
 			type: "category",
-			data: chart.labels
+			data: chart.labels,
+			axisLabel: { fontSize: font.axisLabel }
 		},
-		yAxis: chart.kind === "pie" ? void 0 : { type: "value" },
+		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,
@@ -267,10 +330,11 @@ function toEchartsOption(chart) {
 				name: label,
 				value: series.data[index] ?? 0
 			}))
-		})) : chart.series.map((series) => ({
-			type: chart.kind,
+		})) : chart.series.map((series, index) => ({
+			...shape,
 			name: series.name,
-			data: series.data
+			data: series.data,
+			...chart.kind === "dual-axis" ? { yAxisIndex: index === 0 ? 0 : 1 } : {}
 		}))
 	};
 }
@@ -286,6 +350,12 @@ function applyChartDomContract(container, chart) {
 	else container.removeAttribute("aria-label");
 }
 /**
+* 一篇文档常同时挂载多张图表；共用同一个模块 promise，
+* 避免每个挂载点各自发起一次动态 import。
+*/
+let echartsModule;
+const loadEcharts = () => echartsModule ??= import("./echarts-De78wXqV.js");
+/**
 * 框架无关的 echarts 挂载点：三档的 React 组件与 A2UI 档的 Lit 元素共用同一实现，
 * 图表不再因档位而异。echarts 走动态 import，不打进首屏。
 */
@@ -294,26 +364,29 @@ function mountEchart(container) {
 	let instance;
 	let queued;
 	let observer;
-	const apply = (chart) => {
-		instance?.setOption(toEchartsOption(chart), {
+	const apply = (chart, fontSizes) => {
+		instance?.setOption(toEchartsOption(chart, fontSizes), {
 			notMerge: true,
 			lazyUpdate: true
 		});
 	};
-	import("./echarts-DhNm2ene.js").then((echarts) => {
+	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);
+		if (queued) apply(queued.chart, queued.fontSizes);
 	});
 	return {
-		setChart(chart) {
+		setChart(chart, fontSizes) {
 			applyChartDomContract(container, chart);
-			queued = chart;
-			apply(chart);
+			queued = {
+				chart,
+				...fontSizes ? { fontSizes } : {}
+			};
+			apply(chart, fontSizes);
 		},
 		dispose() {
 			disposed = true;
@@ -324,6 +397,74 @@ function mountEchart(container) {
 		}
 	};
 }
+/**
+* catalog 请求体积上限（0.11.0 分册 14 / AC-G20）的**数字单一来源**。
+*
+* 度量与报错格式在 `scripts/catalogBudget.mjs`（`check:contracts` 与 vitest 共用）；
+* 那边不重复这些数字，一律从本模块读——两处各写一份阈值就等于没有阈值。
+*
+* catalog 进入每一次 LLM 请求的有两处：系统提示词 `toPrompt()` 与
+* `render_ui` 入参 `toJsonSchema()`。只量前者会漏掉约 2/3 的成本。
+*
+* **超阈值的处置是砍组件或收窄枚举取值，不是抬高这里的数字。**
+*/
+/**
+* 预算阶段。分册 12 是本版最后一处 catalog 增量（分册 11 只把 `date` 加进
+* 已有的 `Field.type`，分册 23 不碰 catalog），故在此切到 `'final'`：
+* 阈值收紧到实测终态 + 余量，且余量小于一个平均组件的成本
+* ——余量大于一个组件，等于默许下一版无声塞进一个。
+*/
+const CATALOG_BUDGET_STAGE = "final";
+/**
+* 阈值 = **已落地实测** + 余量，余量须小于一个平均组件的成本。
+*
+* 2026-08-14 实测终态（分册 12 落地后）：prompt 12 744 / schema 21 470，30 个组件。
+* 平均组件成本 prompt 425 / schema 716。
+* 当前余量 prompt 256 / schema 330，均小于一个平均组件——再加一个组件必红。
+*
+* ⚠️ **本版这两个数字被上调过两次**，两次都由需求方裁决并改写了需求文档
+* （分册 29 §2 范围订正 第 7 条与 §2.2），不是实现阶段自行放宽：
+*
+* 1. 11 200 → 12 200 / 20 500 → 21 200：分册 13 组件描述由短改长。
+*    `example` 是既有护栏的硬要求（`catalog.test.ts` 与 `catalogMatrix.test.tsx`
+*    逐个组件校验并四档渲染），靠省掉示例腾出的空间收不回来。
+* 2. 12 200 → 13 000 / 21 200 → 21 800：分册 12 的 `Split` 实测 490 + 694，
+*    超出计划增量（403 + 1 047）的 prompt 侧。需求方裁定
+*    「描述要长，可用性大于预算阈值」——收紧措辞可省回 158 字节，
+*    但砍的正是各组件「何时改用 X」的辨析句，即选型准确率本身。
+*
+* 两次上调合计把单请求成本从 21.7 KB 抬到约 34.2 KB。
+* **AC-G20 原文「超了砍组件、不抬阈值」已被推翻，但仅限本版；
+* 后续再撞顶仍须回到需求方，不得沿用本版作为先例。**
+*/
+const CATALOG_PROMPT_MAX = 13e3;
+const CATALOG_SCHEMA_MAX = 21800;
+/**
+* **尚未落地**的计划增量。本版已无剩余 catalog 增量，故归零；
+* `CATALOG_BUDGET_STAGE` 同时切到 `'final'`，余量改由「小于一个平均组件」判定。
+*/
+const PLANNED_INCREMENT = {
+	prompt: 0,
+	schema: 0
+};
+/** 码与人话之间的分隔符。放在消息最前面，`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;
+}
 function isRecord$1$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -371,24 +512,36 @@ function sanitizeNode(catalog, byName, node, path, degradations) {
 	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("; ")}`
+				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) degradations.push({
-			path: `${path}.props.${key}`,
-			kind: "prop-dropped",
-			component: name,
-			detail: `Dropped invalid prop "${key}".`
-		});
+		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 = {
@@ -457,8 +610,8 @@ function sanitizeUiSpec(catalog, byName, spec) {
 		degradations
 	};
 }
-function componentSchema(def) {
-	const props = toJSONSchema(def.props, { io: "input" });
+function componentSchema(def, rootDefs) {
+	const props = liftDefs(toJSONSchema(def.props, { io: "input" }), def.name, rootDefs);
 	const node = {
 		type: "object",
 		description: def.description,
@@ -488,6 +641,37 @@ function componentSchema(def) {
 function isRecord$2(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$2(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$2(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"]);
@@ -612,13 +796,18 @@ function defineUiCatalog(input) {
 		componentNames: input.components.map((def) => def.name),
 		actionNames: input.actions.map((action) => action.name),
 		component: (name) => byName.get(name),
-		toJsonSchema: () => ({
-			$schema: "https://json-schema.org/draft/2020-12/schema",
-			$id: input.id,
-			title: input.title,
-			description: input.instructions,
-			oneOf: input.components.map(componentSchema)
-		}),
+		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 = [];
@@ -638,6 +827,56 @@ const tone = z.enum([
 	"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"),
@@ -711,7 +950,7 @@ const uiCatalog = defineUiCatalog({
 		"- 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, scripts or remote images.",
+		"- 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:",
@@ -737,7 +976,8 @@ const uiCatalog = defineUiCatalog({
 					"center",
 					"end",
 					"stretch"
-				]).optional()
+				]).optional(),
+				theme: surfaceTheme.optional()
 			}),
 			children: "any",
 			example: {
@@ -758,7 +998,15 @@ const uiCatalog = defineUiCatalog({
 			description: "A titled section that groups related content.",
 			props: z.object({
 				title: z.string(),
-				description: z.string().optional()
+				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: {
@@ -805,15 +1053,46 @@ const uiCatalog = defineUiCatalog({
 				}]
 			}
 		},
+		{
+			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. Each child is one cell and its own form container.",
-			props: z.object({ columns: z.union([
-				z.literal(2),
-				z.literal(3),
-				z.literal(4)
-			]).default(2) }),
+			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",
@@ -851,7 +1130,8 @@ const uiCatalog = defineUiCatalog({
 					z.literal(3),
 					z.literal(4)
 				]).default(3),
-				text: z.string()
+				text: z.string(),
+				palette: palette.optional()
 			}),
 			example: {
 				component: "Heading",
@@ -891,7 +1171,8 @@ const uiCatalog = defineUiCatalog({
 			description: "A short status label.",
 			props: z.object({
 				text: z.string(),
-				tone: tone.default("neutral")
+				tone: tone.default("neutral"),
+				palette: palette.optional()
 			}),
 			example: {
 				component: "Badge",
@@ -952,13 +1233,16 @@ const uiCatalog = defineUiCatalog({
 		{
 			name: "Chart",
 			group: "data",
-			description: "A bar, line, area or pie chart over labelled series.",
+			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"
+					"pie",
+					"scatter",
+					"stacked-bar",
+					"dual-axis"
 				]),
 				title: z.string().optional(),
 				labels: z.array(z.string()).min(1),
@@ -1160,6 +1444,160 @@ const uiCatalog = defineUiCatalog({
 				}
 			}
 		},
+		{
+			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",
@@ -1230,10 +1668,12 @@ const UI_CATALOG_GROUPS = {
 };
 /**
 * catalog 系统提示的体积上限（UTF-8 字节，FR-6.6）。
-* 描述每次请求都要重发，所以上限必须是可判定的数字而不是「尽量精简」。
-* 要改这个数字，先想清楚是否值得让每次请求都多付这些 token。
+*
+* **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 = 20480;
+const UI_CATALOG_PROMPT_BUDGET_BYTES = CATALOG_PROMPT_MAX;
 /** 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`;
@@ -1568,7 +2008,8 @@ function renderPie(chart, svg, doc) {
 	});
 }
 /**
-* ChartSpec → SVG（bar 等宽柱 + 值标签；line 折线 + 点；pie 扇形 + 图例；空数据容错）
+* ChartSpec → SVG（bar 等宽柱 + 值标签；line 折线 + 点；pie 扇形 + 图例；空数据容错）。
+* mini 档只有这三种画法，其余类型走最接近的一种并在图内注明是近似呈现。
 * @stable
 */
 function renderMiniChart(chart, doc) {
@@ -1587,6 +2028,7 @@ function renderMiniChart(chart, doc) {
 	}));
 	switch (chart.kind) {
 		case "bar":
+		case "stacked-bar":
 			renderBar(chart, svg, doc);
 			break;
 		case "line":
@@ -1595,7 +2037,11 @@ function renderMiniChart(chart, doc) {
 		case "pie":
 			renderPie(chart, svg, doc);
 			break;
+		default:
+			renderLine(chart, svg, doc);
+			break;
 	}
+	if (chart.kind !== "bar" && chart.kind !== "line" && chart.kind !== "pie") svg.appendChild(text(doc, WIDTH / 2, HEIGHT - 4, `Approximate rendering of "${chart.kind}"`, { "text-anchor": "middle" }));
 	return svg;
 }
 /** A2UI/OpenUI 降级：chart → table（labels 为首列，series 各为一列） */
@@ -1606,6 +2052,18 @@ function chartToTable(chart) {
 		rows: chart.labels.map((label, li) => [label, ...chart.series.map((s) => s.data[li] ?? null)])
 	};
 }
+/**
+* `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));
+}
 /** RenderBlock → DOM（markdown/json/table/image/file/chart 六种） */
 function renderBlocks(container, blocks, doc) {
 	for (const block of blocks) switch (block.type) {
@@ -1683,6 +2141,154 @@ function renderRenderResult(request, doc) {
 	renderBlocks(root, request.blocks, doc);
 	return root;
 }
+/**
+* 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;
+}
 /** 最小样式（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; }
@@ -1886,7 +2492,7 @@ var WebFormBridge = class {
 			input = textarea;
 		} else {
 			const textInput = doc.createElement("input");
-			textInput.type = control.control === "number" ? "number" : "text";
+			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;
@@ -2433,7 +3039,8 @@ const FIELD_TYPE = {
 	select: "select",
 	textarea: "textarea",
 	file: "file",
-	password: "password"
+	password: "password",
+	date: "date"
 };
 function toOptions(options) {
 	return (options ?? []).map((option) => ({
@@ -2591,6 +3198,7 @@ function createUiCatalogToolSource(options = {}) {
 		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"];
@@ -2873,7 +3481,7 @@ function fromA2uiSpecAction(event) {
 */
 async function loadWebSkillLitCatalog() {
 	try {
-		const { webskillLitCatalog } = await import("./webskillLitCatalog-BJrphK0y-SGmRXaaO.js");
+		const { webskillLitCatalog } = await import("./webskillLitCatalog-D_zCqeQF-C9lrvvMr.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);
@@ -2898,4 +3506,4 @@ async function loadOpenUiPeers() {
 }
 
 //#endregion
-export { UI_CATALOG_PROMPT_BUDGET_BYTES as $, fromUiSurfaceActionDispatch as A, resolveColumnWidths as B, collectSpecActions as C, evaluateFieldCondition as D, ensureStyles as E, normalizeColumnWidths as F, toUiSurfaceActionDispatch as G, toA2uiSurfaceAction as H, qualifyFieldName as I, A2UI_CHILDREN_PROP as J, toVercelToolInvocation as K, renderBlocks as L, interactionToUiSpec as M, loadOpenUiPeers as N, fromA2uiSpecAction as O, loadWebSkillLitCatalog as P, UI_CATALOG_GROUPS as Q, renderMiniChart as R, collectScopedValues as S, createUiCatalogToolSource as T, toJsonRenderSpec as U, toA2uiSpecMessages as V, toOpenUiSpecLang as W, DEFAULT_INTERACTION_TEXTS as X, A2UI_COMMON_TYPES as Y, DEFAULT_SURFACE_FORM_TEXTS as Z, WEBSKILL_SURFACE_ACTION as _, A2UI_VERSION as a, defineUiCatalog as at, chartToTable as b, MAX_CONDITION_DEPTH as c, renderMiniMarkdown as ct, SPEC_TABLE_MIN_COLUMN_WIDTH as d, shapeInteractionValue as dt, WEBSKILL_A2UI_CATALOG_ID as et, UI_PRESETS as f, uiCatalog as ft, WEBSKILL_STYLES_CSS as g, VercelUiBridge as h, A2UI_SURFACE_ACTION as i, chartSpecFromProps as it, fromVercelToolResult as j, fromA2uiSurfaceAction as k, RENDER_UI_TOOL as l, resolveInteractionTexts as lt, VERCEL_INTERACTION_TOOL_NAME as m, A2UI_SPEC_ACTION as n, a2uiComponentShapes as nt, CHART_PALETTE as o, interactionToFormModel as ot, UI_PRESET_NAMES as p, uiPreset as q, A2UI_SPEC_FORM_PATH as r, buildA2uiCatalogDefinition as rt, DESCRIBE_UI_PRESET_TOOL as s, mountEchart as st, A2UI_BASIC_CATALOG_ID as t, a2uiComponentSchema as tt, SPEC_TABLE_MIN_COLUMN_VAR as u, resolveSurfaceFormTexts as ut, WebFormBridge as v, collectValues as w, collectFormScopes as x, applySuggestion as y, renderRenderResult as z };
+export { uiPreset as $, ensureStyles as A, mountViewerComponents as B, applySuggestion as C, resolveSurfaceFormTexts as Ct, collectSpecActions as D, uiCatalog as Dt, collectScopedValues as E, toEchartsOption as Et, fromVercelToolResult as F, renderRenderResult as G, qualifyFieldName as H, gaugePercent as I, toA2uiSurfaceAction as J, resolveColumnWidths as K, interactionToUiSpec as L, fromA2uiSpecAction as M, fromA2uiSurfaceAction as N, collectValues as O, fromUiSurfaceActionDispatch as P, toVercelToolInvocation as Q, loadOpenUiPeers as R, WebFormBridge as S, resolveInteractionTexts as St, collectFormScopes as T, shapeInteractionValue as Tt, renderBlocks as U, normalizeColumnWidths as V, renderMiniChart as W, toOpenUiSpecLang as X, toJsonRenderSpec as Y, toUiSurfaceActionDispatch as Z, VIEWER_FALLBACK_ATTR as _, defineUiCatalog as _t, A2UI_VERSION as a, DEFAULT_CHART_FONT_SIZES as at, WEBSKILL_STYLES_CSS as b, renderMiniMarkdown as bt, DOCUMENT_COMPONENTS as c, DEFAULT_SURFACE_HOST_CONTROL_TEXTS as ct, SPEC_TABLE_MIN_COLUMN_VAR as d, UI_CATALOG_PROMPT_BUDGET_BYTES as dt, A2UI_CHILDREN_PROP as et, SPEC_TABLE_MIN_COLUMN_WIDTH as f, WEBSKILL_A2UI_CATALOG_ID as ft, VIEWER_COMPONENT_ATTR as g, chartSpecFromProps as gt, VERCEL_INTERACTION_TOOL_NAME as h, buildA2uiCatalogDefinition as ht, A2UI_SURFACE_ACTION as i, CATALOG_SCHEMA_MAX as it, evaluateFieldCondition as j, createUiCatalogToolSource as k, MAX_CONDITION_DEPTH as l, PLANNED_INCREMENT as lt, UI_PRESET_NAMES as m, a2uiComponentShapes as mt, A2UI_SPEC_ACTION as n, CATALOG_BUDGET_STAGE as nt, CHART_PALETTE as o, DEFAULT_INTERACTION_TEXTS as ot, UI_PRESETS as p, a2uiComponentSchema as pt, toA2uiSpecMessages as q, A2UI_SPEC_FORM_PATH as r, CATALOG_PROMPT_MAX as rt, DESCRIBE_UI_PRESET_TOOL as s, DEFAULT_SURFACE_FORM_TEXTS as st, A2UI_BASIC_CATALOG_ID as t, A2UI_COMMON_TYPES as tt, RENDER_UI_TOOL as u, UI_CATALOG_GROUPS as ut, VIEWER_PROPS_ATTR as v, interactionToFormModel as vt, chartToTable as w, resolveSurfaceHostControlTexts as wt, WEBSKILL_SURFACE_ACTION as x, resolveChartFontSizes as xt, VercelUiBridge as y, mountEchart as yt, loadWebSkillLitCatalog as z };