@webskill/sdk 0.21.0 → 0.23.0

package/dist/browser.js

@@ -1,14 +1,15 @@
-import { n as messageOf, t as WebSkillError } from "./errors-BDZNpC13.js";
-import { A as SKILL_MANIFEST_FILE, D as verifySkillSignature, M as buildManifest, O as MANIFEST_EXCLUDED_FILES, P as verifyManifest, b as parseSkillMarkdown, c as unzipWithLimits, f as SKILL_PACK_FILE, i as buildCatalog, k as SKILLS_LOCKFILE, m as parseSkillPackManifest, n as SkillDiscovery, o as readResponseWithLimit, p as exportSkills, t as validateSkills, u as detectSkillArchiveShapeFromFs, w as readSkillSignature, y as isValidSkillName } from "./skill-CAJMsLod.js";
-import { a as atomicWriteText, o as isAtomicTempPath, r as resolveInsideRoot } from "./pathSecurity-B1owvJAF.js";
+import { n as messageOf$1, t as WebSkillError } from "./errors-BDZNpC13.js";
+import { A as SKILL_MANIFEST_FILE, D as verifySkillSignature, M as buildManifest, O as MANIFEST_EXCLUDED_FILES, P as verifyManifest, b as parseSkillMarkdown, c as unzipWithLimits, f as SKILL_PACK_FILE, i as buildCatalog, k as SKILLS_LOCKFILE, m as parseSkillPackManifest, n as SkillDiscovery, o as readResponseWithLimit, p as exportSkills, t as validateSkills, u as detectSkillArchiveShapeFromFs, w as readSkillSignature, y as isValidSkillName } from "./skill-WSUDp6A1.js";
+import { o as atomicWriteText, r as resolveInsideRoot, s as isAtomicTempPath } from "./pathSecurity-CirkQwWP.js";
 import { t as assertRemoteUrlAllowed } from "./urlSafety-CiSuCJvX.js";
-import { t as ATTACHMENT_TEXT_LIMIT } from "./kind-DaKqLX2F.js";
-import { _ as FsRunSnapshotStore, a as networkPolicyLibSource, c as bridgeError, ct as ProgressiveRouter, d as FsMemoryStore, l as parseBridgeRequest, m as AgentLoop, r as normalizeToolError, s as UPLOAD_FILES_UNAVAILABLE, t as CapabilityApproval, u as FsArtifactStore } from "./approval-DwN2o2QG.js";
+import { t as ATTACHMENT_TEXT_LIMIT } from "./kind-Dc8x0HWz.js";
+import { _ as FsRunSnapshotStore, a as networkPolicyLibSource, c as bridgeError, ct as ProgressiveRouter, d as FsMemoryStore, l as parseBridgeRequest, m as AgentLoop, r as normalizeToolError, s as UPLOAD_FILES_UNAVAILABLE, t as CapabilityApproval, u as FsArtifactStore } from "./approval-7CuZS3Z4.js";
 import { a as GoogleGenAiClient, o as AnthropicClient, s as OpenAiCompatibleClient, t as MockLlmClient } from "./llm-eIQNO9tr.js";
-import { o as toBase64$1, u as SPREADSHEET_MIME_TYPE } from "./linkedDocument-C0gj1sMq.js";
+import { c as toBase64$1, f as SPREADSHEET_MIME_TYPE } from "./linkedDocument-CZZOl9cO.js";
 import { n as normalizeToolContent, t as mergeCatalogEntries } from "./external-_ZRQe-V9.js";
-import { t as createWebSkillApi } from "./webSkillApi-Cib6G-94.js";
-import { _ as frameSteps, a as defersImage, c as isPdfTextTrustworthy, g as frameLabel, h as toFrameScopes, m as toActionFrameScopes, o as takesImage, t as PDF_LARGE_IMAGE_RATIO } from "./toolSource-C9oNuKmr.js";
+import { t as createWebSkillApi } from "./webSkillApi-D5VMUnrv.js";
+import { A as frameSteps, D as SCROLL_DIRECTIONS, E as toActionFrameScopes, O as toFrameScopes, _ as defersImage, a as columnWidthToPixels, b as isPdfTextTrustworthy, f as readImageSize, k as frameLabel, l as parseCellAddress, n as EMU_PER_POINT, o as fitWithin, p as PDF_LARGE_IMAGE_RATIO, r as EMU_PER_TWIP$1, s as formatCellAddress, t as EMU_PER_PIXEL, u as parseCellRange, v as takesImage } from "./geometry-CRhuySKV.js";
+import { zipSync } from "fflate";
 
 //#region ../browser/src/fs/featureDetection.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -542,7 +543,7 @@ var TsTranspiler = class {
 		try {
 			esbuild = await loadEsbuild(this.#options);
 		} catch (e) {
-			throw new WebSkillError("TS_TRANSPILER_UNAVAILABLE", `Failed to load the TypeScript transpiler from "${this.#options.esbuildUrl}": ${messageOf(e)}`, e);
+			throw new WebSkillError("TS_TRANSPILER_UNAVAILABLE", `Failed to load the TypeScript transpiler from "${this.#options.esbuildUrl}": ${messageOf$1(e)}`, e);
 		}
 		let code;
 		try {
@@ -552,7 +553,7 @@ var TsTranspiler = class {
 				format: "esm"
 			})).code;
 		} catch (e) {
-			throw new WebSkillError("TS_TRANSPILE_FAILED", `Failed to transpile ${scriptPath}: ${messageOf(e)}`, e);
+			throw new WebSkillError("TS_TRANSPILE_FAILED", `Failed to transpile ${scriptPath}: ${messageOf$1(e)}`, e);
 		}
 		await this.#fs.writeText(cacheKey, code);
 		return code;
@@ -625,7 +626,7 @@ const PRESERVED_INSTALL_CODES = /* @__PURE__ */ new Set([
 	"SIGNATURE_UNSUPPORTED",
 	"SKILL_DUPLICATE_NAME"
 ]);
-const asInstallFailed = (e) => e instanceof WebSkillError && (e.code === "INSTALL_FAILED" || e.code === "TOOL_UNSUPPORTED" || PRESERVED_INSTALL_CODES.has(e.code)) ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf(e)}`, e);
+const asInstallFailed = (e) => e instanceof WebSkillError && (e.code === "INSTALL_FAILED" || e.code === "TOOL_UNSUPPORTED" || PRESERVED_INSTALL_CODES.has(e.code)) ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf$1(e)}`, e);
 const lockfilePath = (root) => `${root}/${SKILLS_LOCKFILE}`;
 /** 未注入信任库时的空实现：策略仍然生效，只是没有任何受信公钥 */
 const EMPTY_TRUSTED_KEYS = {
@@ -696,7 +697,7 @@ var BrowserSkillManager = class {
 					res = await (this.#fetchImpl ?? fetch)(url.href);
 				} catch (e) {
 					if (e instanceof WebSkillError) throw e;
-					throw new WebSkillError("INSTALL_FAILED", `Download failed: ${messageOf(e)}`, e);
+					throw new WebSkillError("INSTALL_FAILED", `Download failed: ${messageOf$1(e)}`, e);
 				}
 				if (!res.ok) throw new WebSkillError("INSTALL_FAILED", `Download failed with HTTP ${res.status}`);
 				data = await readResponseWithLimit(res, this.#archiveLimits);
@@ -725,7 +726,7 @@ var BrowserSkillManager = class {
 				name = metadata.name;
 				version = typeof metadata["version"] === "string" ? metadata["version"] : void 0;
 			} catch (e) {
-				throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md: ${messageOf(e)}`, e);
+				throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md: ${messageOf$1(e)}`, e);
 			}
 			if (!isValidSkillName(name)) throw new WebSkillError("INSTALL_FAILED", `Invalid skill name in SKILL.md (path traversal rejected): ${JSON.stringify(name)}`);
 			if (options?.replace === "reject" && await fs.exists(`${this.#managedRoot}/${name}`)) throw new WebSkillError("SKILL_DUPLICATE_NAME", `A skill named "${name}" is already installed. Installing it again replaces the existing files; use the packages flow if that is intended.`);
@@ -797,7 +798,7 @@ var BrowserSkillManager = class {
 					name = metadata.name;
 					versions.set(name, typeof metadata["version"] === "string" ? metadata["version"] : void 0);
 				} catch (e) {
-					throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md of pack entry "${entry.name}": ${messageOf(e)}`, e);
+					throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md of pack entry "${entry.name}": ${messageOf$1(e)}`, e);
 				}
 				if (name !== entry.name) throw new WebSkillError("INSTALL_FAILED", `Skill pack entry "${entry.name}" does not match the SKILL.md name "${name}"`);
 				await copyDir(fs, skillDir, `${finalRoot}/${name}`);
@@ -899,7 +900,7 @@ var BrowserSkillManager = class {
 			await this.#removeLockEntry(name);
 			this.#onChanged?.();
 		} catch (e) {
-			throw new WebSkillError("UNINSTALL_FAILED", `Failed to uninstall "${name}": ${messageOf(e)}`, e);
+			throw new WebSkillError("UNINSTALL_FAILED", `Failed to uninstall "${name}": ${messageOf$1(e)}`, e);
 		}
 	}
 	async verifyIntegrity(name) {
@@ -919,7 +920,7 @@ var BrowserSkillManager = class {
 		try {
 			return JSON.parse(await this.#fs.readText(path));
 		} catch (e) {
-			throw new WebSkillError("INTEGRITY_FAILED", `Skills lockfile at ${path} is corrupted: ${messageOf(e)}`, e);
+			throw new WebSkillError("INTEGRITY_FAILED", `Skills lockfile at ${path} is corrupted: ${messageOf$1(e)}`, e);
 		}
 	}
 	/**
@@ -975,7 +976,7 @@ var BrowserSkillManager = class {
 		try {
 			return JSON.parse(await this.#fs.readText(path));
 		} catch (e) {
-			throw new WebSkillError("INTEGRITY_FAILED", `Skill manifest at ${path} is corrupted: ${messageOf(e)}`, e);
+			throw new WebSkillError("INTEGRITY_FAILED", `Skill manifest at ${path} is corrupted: ${messageOf$1(e)}`, e);
 		}
 	}
 	async #upsertLockEntry(name, entry) {
@@ -1008,7 +1009,7 @@ const DEFAULT_BINARY_EXTENSIONS = [
 ];
 const trimTrailingSlash = (value) => value.replace(/\/+$/, "");
 const joinUrl = (baseUrl, path) => `${baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`}${path.replace(/^\/+/, "")}`;
-const extensionOf = (file) => {
+const extensionOf$1 = (file) => {
 	const dot = file.lastIndexOf(".");
 	return dot === -1 ? "" : file.slice(dot + 1).toLowerCase();
 };
@@ -1043,7 +1044,7 @@ async function seedSkillsFromHttp(fs, options) {
 			const url = joinUrl(baseUrl, `${sourceRoot}/${skill}/${file}`);
 			const response = await fetchImpl(url);
 			if (!response.ok) throw new Error(`Builtin skill asset missing: ${url} (HTTP ${response.status})`);
-			if (binary.has(extensionOf(file))) {
+			if (binary.has(extensionOf$1(file))) {
 				await fs.writeBinary(`${skillRoot}/${file}`, new Uint8Array(await response.arrayBuffer()));
 				continue;
 			}
@@ -1392,7 +1393,7 @@ var BrowserWorkerScriptExecutor = class {
 				content: [],
 				error: {
 					code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
-					message: messageOf(e)
+					message: messageOf$1(e)
 				}
 			};
 		}
@@ -1437,7 +1438,7 @@ var BrowserWorkerScriptExecutor = class {
 				content: [],
 				error: {
 					code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
-					message: messageOf(e)
+					message: messageOf$1(e)
 				}
 			};
 		} finally {
@@ -1472,7 +1473,7 @@ var BrowserWorkerScriptExecutor = class {
 						respond(bridgeError("unknown", "TOOL_EXECUTION_FAILED", "invalid bridge request"));
 						return;
 					}
-					onBridge(request).then(respond, (e) => respond(bridgeError(request.id, "TOOL_EXECUTION_FAILED", messageOf(e))));
+					onBridge(request).then(respond, (e) => respond(bridgeError(request.id, "TOOL_EXECUTION_FAILED", messageOf$1(e))));
 					return;
 				}
 				if (data.id !== id || settled) return;
@@ -1590,7 +1591,7 @@ var BrowserWorkerScriptExecutor = class {
 					};
 			}
 		} catch (e) {
-			return bridgeError(request.id, e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", messageOf(e));
+			return bridgeError(request.id, e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", messageOf$1(e));
 		}
 	}
 };
@@ -1660,10 +1661,10 @@ async function probeChromeBuiltinAvailability() {
 		};
 	}
 }
-const textOf$1 = (message) => message.content.map((part) => part.type === "text" ? part.text : `[${part.type}]`).join("").trim();
+const textOf$3 = (message) => message.content.map((part) => part.type === "text" ? part.text : `[${part.type}]`).join("").trim();
 /** tool 角色 Prompt API 不认识，降级成 user 文本——内置模型本来就不做工具调用 */
 function toInitialPrompt(message) {
-	const text = textOf$1(message);
+	const text = textOf$3(message);
 	if (message.role === "assistant") return {
 		role: "assistant",
 		content: text
@@ -1674,7 +1675,7 @@ function toInitialPrompt(message) {
 	};
 }
 function splitInput(input) {
-	const system = input.messages.filter((m) => m.role === "system").map(textOf$1).filter((text) => text !== "");
+	const system = input.messages.filter((m) => m.role === "system").map(textOf$3).filter((text) => text !== "");
 	const rest = input.messages.filter((m) => m.role !== "system");
 	const last = rest.at(-1);
 	return {
@@ -2102,12 +2103,12 @@ async function captureImg(element, id, maxBytes) {
 	const inline = splitDataUrl(src);
 	if (inline) {
 		const bytes = Uint8Array.from(atob(inline.data), (char) => char.charCodeAt(0));
-		return toBudget(id, "src", await toDeliverableBlob(new Blob([bytes], { type: inline.mimeType }), oversized), maxBytes);
+		return toBudget(id, "src", (await toDeliverableBlob(new Blob([bytes], { type: inline.mimeType }), { oversized })).blob, maxBytes);
 	}
 	const response = await fetch(src, { mode: "cors" });
 	if (response.type === "opaque") throw new Error("the response is opaque, so its bytes cannot be read");
 	if (!response.ok) throw new Error(`fetching the source returned HTTP ${response.status}`);
-	return toBudget(id, "src", await toDeliverableBlob(await response.blob(), oversized), maxBytes);
+	return toBudget(id, "src", (await toDeliverableBlob(await response.blob(), { oversized })).blob, maxBytes);
 }
 /** L2：`<canvas>` 读回。画布被跨域内容污染时 `toDataURL` 抛 SecurityError，不再兜底（裁决 D-3） */
 async function captureCanvas(element, id, maxBytes) {
@@ -2246,6 +2247,16 @@ const DELIVERABLE_IMAGE_MIME_TYPES = /* @__PURE__ */ new Set([
 	"image/gif",
 	"image/webp"
 ]);
+/**
+* 投放与导出通道的目标集：`docx` 与 `pptxgenjs` 都不吃 WebP，
+* 而 WebP 在现代网页上遍地都是。归一化放在写进 `src` 之前，
+* 下游三处永远只见得到 PNG 与 JPEG（设计 12 §4.2）。
+*
+* 导出编码器判断「这张图嵌不嵌得进去」必须读同一份清单（0.22.0 FR-14.3）：
+* 各写一遍就会出现「投放时归一成了 A，导出却认为 A 不受支持」。
+* @experimental
+*/
+const DOCUMENT_IMAGE_MIME_TYPES = /* @__PURE__ */ new Set(["image/png", "image/jpeg"]);
 /** 用于认出 SVG 正文的前缀嗅探长度：`<?xml`、注释、DOCTYPE 都可能排在 `<svg` 之前 */
 const SVG_SNIFF_BYTES = 1024;
 /**
@@ -2308,7 +2319,13 @@ async function rasterizeToPng(blob) {
 		const ctx = canvas.getContext("2d");
 		if (ctx === null) throw new Error("a 2D canvas context is unavailable");
 		ctx.drawImage(image, 0, 0, width, height);
-		return await toPngBlob(canvas);
+		return {
+			blob: await toPngBlob(canvas),
+			size: {
+				width,
+				height
+			}
+		};
 	} finally {
 		URL.revokeObjectURL(url);
 	}
@@ -2328,21 +2345,61 @@ async function rasterizeToPng(blob) {
 * - **超长边**：横幅类素材常见 7680×120 这种尺寸，字节数却很小，
 *   纯按字节压缩的预算根本不会触发，原样发出去就撞上端点的边长上限。
 *
-* @param oversized 调用方已知原图长边超限（`<img>` 能直接读到 `naturalWidth`，不必为此解码）
+* @param options.oversized 调用方已知原图长边超限（`<img>` 能直接读到 `naturalWidth`，不必为此解码）
+* @param options.targets 目标类型集。模型图片通道与投放/导出通道的可接受集合不同（设计 12 §4.2）
 */
-async function toDeliverableBlob(blob, oversized = false) {
+async function toDeliverableBlob(blob, options = {}) {
+	const targets = options.targets ?? DELIVERABLE_IMAGE_MIME_TYPES;
 	const declared = blob.type.split(";")[0]?.trim().toLowerCase() ?? "";
 	const head = new Uint8Array(await blob.slice(0, SVG_SNIFF_BYTES).arrayBuffer());
 	const sniffed = sniffImageMime(head);
-	if (sniffed !== void 0 && DELIVERABLE_IMAGE_MIME_TYPES.has(sniffed)) {
+	if (sniffed !== void 0 && targets.has(sniffed)) {
 		const typed = sniffed === declared ? blob : new Blob([blob], { type: sniffed });
 		const animated = sniffed === "image/gif" || sniffed === "image/webp" && isAnimatedWebp(head) || sniffed === "image/png" && isAnimatedPng(head);
-		return oversized || animated ? await rasterizeToPng(typed) : typed;
+		return options.oversized === true || animated ? await rasterizeToPng(typed) : { blob: typed };
 	}
 	const mimeType = sniffed ?? (declared.startsWith("image/") ? declared : void 0);
 	if (mimeType === void 0) throw new Error(`the response is not a recognizable image (the server described it as "${blob.type === "" ? "no content type" : blob.type}")`);
 	return await rasterizeToPng(new Blob([blob], { type: mimeType }));
 }
+/** 直通分支只差尺寸：解一次位图读完立刻释放，任何时刻只持有一张（设计 12 §4.2） */
+async function imageSizeOf(blob) {
+	if (typeof createImageBitmap !== "function") throw new Error("this environment cannot decode images, so the image dimensions cannot be measured");
+	const bitmap = await createImageBitmap(blob);
+	try {
+		return {
+			width: bitmap.width,
+			height: bitmap.height
+		};
+	} finally {
+		bitmap.close();
+	}
+}
+/**
+* 把任意来源的图片字节归一成投放文档能显示、两个导出编码器都收得下的形态（0.22.0 FR-11.6）。
+*
+* 上传图、页面图、外链图在这里走的是**同一个函数**——AC-G1 要的不是三条分支行为一致，
+* 而是根本只有一条分支，所以这个签名里没有「来源」这个参数。
+*
+* 宽高一律实测：像素数是投放载荷预算的硬兜底维度（FR-10.7），采信声明等于让被限制方自报限额。
+* 失败抛错并带可执行的原因，由调用方转成丢图归因（FR-11.8）。
+* @experimental
+*/
+async function toDocumentImage(bytes, options) {
+	const deliverable = await toDeliverableBlob(new Blob([new Uint8Array(bytes)], { type: options.declaredMimeType ?? "" }), { targets: DOCUMENT_IMAGE_MIME_TYPES });
+	const compressed = await compressImageToBudget(deliverable.blob, options.maxBytes);
+	const size = compressed.scaled || deliverable.size === void 0 ? await imageSizeOf(compressed.blob) : deliverable.size;
+	const mimeType = compressed.blob.type.split(";")[0]?.trim().toLowerCase() ?? "";
+	if (!DOCUMENT_IMAGE_MIME_TYPES.has(mimeType)) throw new Error(`the bytes normalized to "${mimeType === "" ? "no content type" : mimeType}", which is not one of ${[...DOCUMENT_IMAGE_MIME_TYPES].join(", ")}`);
+	const buffer = await compressed.blob.arrayBuffer();
+	return {
+		data: base64Of(new Uint8Array(buffer)),
+		mimeType,
+		width: size.width,
+		height: size.height,
+		bytes: compressed.compressedBytes
+	};
+}
 /**
 * 取一个元素的图像（0.6.0 FR-12.1）。
 *
@@ -2381,16 +2438,169 @@ async function toDeliverableBlob(blob, oversized = false) {
 	}
 	return {
 		id,
-		reason: `<${element.tagName.toLowerCase()}> is not a capturable element`,
+		reason: `<${element.tagName.toLowerCase()}> is not a capturable element; only ${[...CAPTURABLE_TAGS].map((t) => `<${t.toLowerCase()}>`).join(", ")} can be captured`,
 		triedLevels: []
 	};
 }
+/**
+* 取一张宿主页面上的图，并归一成投放 / 导出通道吃得下的形态（0.22.0 FR-12.1）。
+*
+* 取像本身**原样复用** `captureElementImage`：两级策略与「互不兜底」的裁决 D-3 一字未改。
+* 这里只把归一化的目标集换成 `png` / `jpeg`——产物一旦落盘就该是下游直接能用的格式，
+* 否则「投放看得见、导出才消失」会以另一种形态回来。
+* @experimental
+*/
+async function captureDocumentImage(element, options) {
+	const captured = await captureElementImage(element, options);
+	if (isCaptureFailure(captured)) return captured;
+	try {
+		return await toDocumentImage(Uint8Array.from(atob(captured.data), (c) => c.charCodeAt(0)), {
+			maxBytes: options.maxBytes,
+			declaredMimeType: captured.mimeType
+		});
+	} catch (e) {
+		return {
+			id: options.id,
+			reason: `the captured bytes could not be converted for documents: ${describeError(e)}`,
+			triedLevels: [captured.level]
+		};
+	}
+}
 function describeError(e) {
 	if (e instanceof DOMException && e.name === "SecurityError") return "the canvas is tainted by cross-origin data";
 	if (e instanceof TypeError) return "the request was blocked, most likely by CORS";
 	return e instanceof Error ? e.message : String(e);
 }
 
+//#endregion
+//#region ../browser/src/net/fetchImage.ts
+/** 单次抓取超时（设计 14 §5.1）。一个不响应的 URL 不得把整个 run 拖死 @experimental */
+const REMOTE_IMAGE_TIMEOUT_MS = 15e3;
+/** 单张外链图的原始字节上界（设计 14 §5.1）。超限先压，压不下去才丢 @experimental */
+const MAX_REMOTE_IMAGE_BYTES = 32 * 1024 * 1024;
+/**
+* 把一次抓取失败归档（AC-13.4）。
+*
+* 纯函数：实测表明扩展上 `http` 全通（设计 14 §1），「被浏览器阻断」在 e2e 里
+* 根本构造不出来，所以这一档的正确性只能由单测按真实错误形态喂进来验。
+* @experimental
+*/
+function classifyFetchFailure(error, response) {
+	if (response !== void 0 && !response.ok) return "refused";
+	if (error instanceof DOMException && error.name === "AbortError") return "timeout";
+	if (error instanceof Error && error.name === "TimeoutError") return "timeout";
+	if (error instanceof TypeError) {
+		const text = error.message.toLowerCase();
+		if (text.includes("blocked") || text.includes("mixed content") || text.includes("cors")) return "blocked";
+		return "unreachable";
+	}
+	return "unreachable";
+}
+/** 分类 → 一句能照着做的话。措辞面向模型，因此一律英文（AGENTS.md） */
+function reasonOf(kind, url, detail) {
+	const host = hostOf(url);
+	switch (kind) {
+		case "blocked": return `the browser blocked the request to ${host}${detail}; an https:// address is usually allowed where an http:// one is not`;
+		case "unreachable": return `${host} could not be reached${detail}; check the address or use a different image`;
+		case "refused": return `${host} refused to serve the image${detail}`;
+		case "not-an-image": return `${host} answered, but the response is not an image${detail}`;
+		case "too-large": return `the image at ${host} is too large${detail}`;
+		case "timeout": return `${host} did not answer${detail}`;
+	}
+}
+function hostOf(url) {
+	try {
+		return new URL(url).host;
+	} catch {
+		return url;
+	}
+}
+/**
+* 抓一张外链图并归一成可直接写进文档的形态（分册 13 FR-13.1 ~ FR-13.5）。
+*
+* **授权不在这里**：调用方必须在调用之前拿到用户同意（AC-13.5 要求断言网络层零请求，
+* 所以判定必须发生在 `fetch` 之前，不能靠拿到响应再丢弃）。
+*
+* SSRF 由 `assertRemoteUrlAllowed` 原样兜住，不另写一份（FR-13.5）。已知口子：
+* 它校验的是**初始 URL**，跟随重定向落到私有网段它管不着（见 docs/deferred-items.md）。
+* @experimental
+*/
+async function fetchRemoteImage(url, options) {
+	const maxSourceBytes = options.maxSourceBytes ?? 33554432;
+	const timeoutMs = options.timeoutMs ?? 15e3;
+	const doFetch = options.fetch ?? globalThis.fetch;
+	try {
+		assertRemoteUrlAllowed(url, { allowHttp: true });
+	} catch (e) {
+		if (e instanceof WebSkillError) throw e;
+		throw new WebSkillError("VALIDATION_FAILED", `Not a usable image URL: ${JSON.stringify(url)}`);
+	}
+	const controller = new AbortController();
+	const timer = setTimeout(() => {
+		controller.abort();
+	}, timeoutMs);
+	let response;
+	try {
+		response = await doFetch(url, {
+			signal: controller.signal,
+			redirect: "follow"
+		});
+		if (!response.ok) return {
+			kind: "refused",
+			reason: reasonOf("refused", url, ` (HTTP ${String(response.status)})`)
+		};
+		const declared = Number(response.headers.get("content-length") ?? NaN);
+		if (Number.isFinite(declared) && declared > maxSourceBytes) return {
+			kind: "too-large",
+			reason: reasonOf("too-large", url, ` (${describeBytes(declared)}, limit ${describeBytes(maxSourceBytes)})`)
+		};
+		const blob = await response.blob();
+		if (blob.size > maxSourceBytes) return {
+			kind: "too-large",
+			reason: reasonOf("too-large", url, ` (${describeBytes(blob.size)}, limit ${describeBytes(maxSourceBytes)})`)
+		};
+		const bytes = new Uint8Array(await blob.arrayBuffer());
+		try {
+			return await toDocumentImage(bytes, {
+				maxBytes: options.maxBytes,
+				declaredMimeType: blob.type
+			});
+		} catch (e) {
+			return {
+				kind: "not-an-image",
+				reason: reasonOf("not-an-image", url, `: ${messageOf(e)}`)
+			};
+		}
+	} catch (e) {
+		if (e instanceof WebSkillError) throw e;
+		const kind = classifyFetchFailure(e, response);
+		return {
+			kind,
+			reason: reasonOf(kind, url, kind === "timeout" ? ` within ${String(Math.round(timeoutMs / 1e3))}s` : ` (${messageOf(e)})`)
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** @experimental */
+function isRemoteImageFailure(result) {
+	return "kind" in result;
+}
+/** @experimental */
+function createRemoteImageHost(options = {}) {
+	return { fetch: (url, maxBytes) => fetchRemoteImage(url, {
+		maxBytes,
+		...options.fetch === void 0 ? {} : { fetch: options.fetch }
+	}) };
+}
+function describeBytes(bytes) {
+	const mb = bytes / (1024 * 1024);
+	return mb >= 1 ? `${mb.toFixed(1)} MB` : `${String(Math.round(bytes / 1024))} KB`;
+}
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+
 //#endregion
 //#region ../browser/src/dom/promotion.ts
 /**
@@ -2424,24 +2634,56 @@ const ROUTE_ATTRIBUTES = [
 * 选项往往就是不带 role 的 `<li>`（0.17.0 分册 11）。它与另外三个一样受
 * 「有可操作后代就不提升」约束，所以真正的语义列表不会被误伤。
 *
-* 这张白名单**只约束启发式信号**。宿主探针点名的元素走另一条路（分册 12）。
+* 判据是「条目 / 单元」对「容器」（0.23.0 FR-11.1）：一格、一项、一栏能承载一次点击，
+* `grid` / `menu` / `tablist` 这类容器不能，所以它们不在这里。
+*
+* 0.23.0 补齐了显式 ARIA 写法：过去 `<td>`（隐式 `cell`）能被提升，而
+* `<td role="gridcell">` 不能——把无障碍角色写对反而被降级。自绘日历、菜单、
+* 下拉普遍写显式角色，于是整片点不到（0.23.0 分册 11）。
+*
+* 这张白名单**只约束启发式信号**，放宽的是「够不够格被考察」，不是「够不够格被提升」：
+* 后面三道闸门（自身可操作 / 有可操作后代 / 看起来可交互）一个都没松。
+* 宿主探针点名的元素走另一条路（分册 12）。
 */
 const PROMOTABLE_ROLES = /* @__PURE__ */ new Set([
 	"generic",
 	"img",
 	"cell",
-	"listitem"
+	"listitem",
+	"columnheader",
+	"gridcell",
+	"rowheader",
+	"option",
+	"treeitem",
+	"tab",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio"
 ]);
 /** 合成名的前缀，必须让模型看得出「这不是页面上的字，别拿它去搜」（FR-15.4 第 3 级） */
 const SYNTHETIC_NAME_PREFIX = "unlabeled control";
 /** 往上找具名祖先的层数上限：再往上就是整页容器，拿它当限定语反而更含糊 */
 const SYNTHETIC_NAME_LOOKUP_DEPTH = 5;
 const classAndId = (element) => `${element.getAttribute("class") ?? ""} ${element.getAttribute("id") ?? ""}`;
-/** `cursor: pointer` —— 页面自己声明了可点。`getComputedStyle` 最贵，殿后 */
+/**
+* `cursor: pointer` —— 页面自己声明了可点。`getComputedStyle` 最贵，殿后。
+*
+* 只认元素**自身引入**的那一次声明：`cursor` 是 CSS 继承属性，一句
+* `.card { cursor: pointer }` 会让整张卡片里的每段文字计算值都是 `pointer`。
+* 实测某差旅站点首页 1537 个可见元素里 **1050 个**仅凭继承来的 `cursor`
+* 就被判成可交互，感知里因此冒出 826 个「按钮」（0.23.0 FR-16.1）。
+*
+* 判据是与父元素的计算值**有没有差异**：没有差异就当作继承来的。
+* 父子都显式声明 `pointer` 的情形分辨不了（没有任何 DOM API 能做到），
+* 那类元素由其余四级信号兜底，见 0.23.0 设计 17 §3。
+*/
 function looksClickable(element, view) {
 	if (view === null) return false;
 	try {
-		return view.getComputedStyle(element).cursor === "pointer";
+		if (view.getComputedStyle(element).cursor !== "pointer") return false;
+		const parent = element.parentElement;
+		if (parent === null) return true;
+		return view.getComputedStyle(parent).cursor !== "pointer";
 	} catch {
 		return false;
 	}
@@ -2691,7 +2933,9 @@ function nameOf(element, doc) {
 	}
 	if (FORM_CONTROL_TAGS.has(element.tagName)) return externalNameOf(element);
 	const own = ownText(element);
-	return own === "" ? void 0 : own;
+	if (own !== "") return own;
+	const title = element.getAttribute("title");
+	return title !== null && title.trim() !== "" ? clip(title) : void 0;
 }
 function valueOf(element) {
 	if (element.tagName === "INPUT") {
@@ -2724,6 +2968,35 @@ function hidden$1(element, view) {
 	}
 	return false;
 }
+/**
+* 页面是否有真实布局。jsdom 有 `getComputedStyle` 却没有布局引擎，那里所有元素的
+* rect 都是 0×0，把零尺寸判定套上去会让**全部**控件失去句柄（0.23.0 FR-10.4）。
+*
+* 判据与被判据用**同一种测量手段**：拿根元素的 rect 为下面的 rect 背书。
+* 真实浏览器里根元素必有尺寸，jsdom 里恒为 0×0。
+*
+* 不用 `clientHeight`，更不用 `view.innerHeight`：
+* 前者与 rect 是两套独立机制，测试桩（以及 `overflow` 的各种写法）可以只动其中一套，
+* 用 A 去为 B 背书会得出「有布局」却量不到尺寸的矛盾结论；
+* 后者在 jsdom 里被编了 1024×768，两边根本看不出区别。
+*/
+function hasLayout(doc) {
+	const rect = doc.documentElement.getBoundingClientRect();
+	return rect.width > 0 || rect.height > 0;
+}
+/**
+* 元素在屏幕上不占任何像素（0.23.0 FR-10.1）。人的鼠标点不到它，
+* 用户也无从在逐次确认卡上核对它——`act_on_page` 的安全模型建立在「用户看得懂自己批准了什么」上。
+*
+* 不复用 `measuredSizeOf()`：那个函数在 rect 为 0 时会回退去读 naturalWidth /
+* canvas 属性 / viewBox，为的是「测不到尺寸就别过滤图片」。这里要的恰恰相反：
+* 必须分得清「确实量到了 0」和「没有布局」，一档都不能回退。
+*/
+function occupiesNoSpace(element) {
+	if (!hasLayout(element.ownerDocument)) return false;
+	const rect = element.getBoundingClientRect();
+	return rect.width === 0 || rect.height === 0;
+}
 /** script / style 的正文是代码，不是页面内容 */
 const SKIPPED_TAGS = /* @__PURE__ */ new Set([
 	"SCRIPT",
@@ -2733,6 +3006,33 @@ const SKIPPED_TAGS = /* @__PURE__ */ new Set([
 ]);
 /** 活动模态的三种形态；Radix 之流用 aria-modal，原生用 <dialog open> */
 const MODAL_SELECTOR = "[role=dialog][open], dialog[open], [aria-modal=true]";
+const scrollsOverflow = (overflow) => overflow === "auto" || overflow === "scroll" || overflow === "overlay";
+/**
+* 该元素**自身**还能往哪些方向滚（0.23.0 分册 22 FR-22.1）。
+*
+* 先读布局属性再查计算样式，顺序不能倒：实测某 ERP 页 2488 个元素里只有 18 个
+* 在第一道过筛（1.4ms），对这 18 个查 overflow 只要 0.1ms；对全部 2488 个查要 5.8ms。
+* 这与 `looksClickable` 把 `getComputedStyle` 殿后是同一条原则。
+*
+* 只判元素自身、不上溯，标示因此只落在容器节点上（FR-22.3）。
+* jsdom 没有布局，这些尺寸恒为 0，筛子自然不命中。
+*/
+function scrollableDirectionsOf(element, view) {
+	const overflowsX = element.scrollWidth > element.clientWidth;
+	const overflowsY = element.scrollHeight > element.clientHeight;
+	if (!overflowsX && !overflowsY) return [];
+	const style = view.getComputedStyle(element);
+	const out = [];
+	if (overflowsX && scrollsOverflow(style.overflowX)) {
+		if (element.scrollLeft > 0) out.push("left");
+		if (element.scrollLeft < element.scrollWidth - element.clientWidth - 1) out.push("right");
+	}
+	if (overflowsY && scrollsOverflow(style.overflowY)) {
+		if (element.scrollTop > 0) out.push("up");
+		if (element.scrollTop < element.scrollHeight - element.clientHeight - 1) out.push("down");
+	}
+	return out;
+}
 /** 按尺寸落选取像的说明（FR-20.3）；与「超名额」「取像失败」必须可区分，三者排查方向不同 */
 const ICON_SKIPPED_NOTE = "Not captured: this image is smaller than the icon threshold";
 /**
@@ -2758,6 +3058,8 @@ function describe(element, excluded, doc, view, capture, handles, frame, provena
 	const value = valueOf(element);
 	let role = roleOf$1(element);
 	let promotedHref;
+	let roleBeforePromotion;
+	let nameWasSynthesized = false;
 	if (promotion !== void 0) {
 		const promoted = promoteRole({
 			element,
@@ -2768,14 +3070,37 @@ function describe(element, excluded, doc, view, capture, handles, frame, provena
 			context: promotion
 		});
 		if (promoted !== void 0) {
+			roleBeforePromotion = role;
 			role = promoted.role;
 			promotedHref = promoted.href;
-			if (name === void 0) name = clip(iconHintOf(element) ?? synthesizeName(element, (a) => nameOf(a, doc)));
+			if (name === void 0) {
+				name = clip(iconHintOf(element) ?? synthesizeName(element, (a) => nameOf(a, doc)));
+				nameWasSynthesized = true;
+			}
 		}
 	}
+	let ref = handles?.issue(element, role, frame);
+	if (roleBeforePromotion !== void 0 && ref === void 0) {
+		role = roleBeforePromotion;
+		promotedHref = void 0;
+		if (nameWasSynthesized) name = void 0;
+		ref = handles?.issue(element, role, frame);
+	}
 	const href = promotedHref ?? (role === "link" ? hrefOf(element) : void 0);
-	if (role === "generic" && name === void 0 && value === void 0 && children.length === 0) return void 0;
-	if (promotion !== void 0 && role === "generic" && name === void 0 && value === void 0) {
+	let scrollable;
+	let scrollRef;
+	if (view !== null) {
+		const directions = scrollableDirectionsOf(element, view);
+		if (directions.length > 0) {
+			const issued = ref ?? handles?.issueScrollable(element, frame);
+			if (issued !== void 0) {
+				scrollable = directions;
+				scrollRef = issued;
+			}
+		}
+	}
+	if (role === "generic" && name === void 0 && value === void 0 && children.length === 0 && scrollable === void 0) return;
+	if (promotion !== void 0 && role === "generic" && name === void 0 && value === void 0 && scrollable === void 0) {
 		if (children.length === 1) return children[0];
 	}
 	const node = {
@@ -2787,13 +3112,23 @@ function describe(element, excluded, doc, view, capture, handles, frame, provena
 		...provenance !== void 0 ? { provenance } : {},
 		...children.length > 0 ? { children } : {}
 	};
-	const ref = handles?.issue(element, role, frame);
 	if (ref !== void 0) node.ref = ref;
-	if (capture !== void 0 && isCapturableElement(element)) if (isBelowMinArea(element, capture.minImageArea)) node.imageNote = ICON_SKIPPED_NOTE;
-	else capture.targets.push({
-		element,
-		node
-	});
+	if (scrollable !== void 0) {
+		node.ref = scrollRef;
+		node.scrollable = scrollable;
+	}
+	if (isCapturableElement(element)) {
+		const captureRef = node.ref ?? handles?.issueCapture(element, frame);
+		if (captureRef !== void 0) {
+			node.ref = captureRef;
+			node.capturable = true;
+		}
+		if (capture !== void 0) if (isBelowMinArea(element, capture.minImageArea)) node.imageNote = ICON_SKIPPED_NOTE;
+		else capture.targets.push({
+			element,
+			node
+		});
+	}
 	return node;
 }
 /**
@@ -2899,6 +3234,7 @@ var HandleIssuer = class {
 		if (!this.#actionable.has(element) || this.#excluded.has(element)) return void 0;
 		const kind = ACTIONABLE_ROLES.has(role) ? "action" : ANCHOR_ROLES.has(role) ? "anchor" : void 0;
 		if (kind === void 0) return void 0;
+		if (kind === "action" && occupiesNoSpace(element)) return void 0;
 		const known = this.#refByElement.get(element);
 		if (known !== void 0 && this.#table.has(known)) {
 			this.#table.set(known, {
@@ -2908,6 +3244,34 @@ var HandleIssuer = class {
 			});
 			return known;
 		}
+		return this.#mint(element, kind, frame);
+	}
+	/**
+	* 取像句柄（0.22.0 FR-12.1）。**不过操作范围那道闸**：取像是读，而该元素已经在
+	* 感知输出里，读它的授权就是读页面的授权；写的授权另有 `capture_page_image` 的卡。
+	*
+	* 已有句柄就原样复用且**不改 kind**：一个被提升成按钮的 `<img>` 仍然点得动。
+	*/
+	issueCapture(element, frame) {
+		if (this.#excluded.has(element)) return void 0;
+		const known = this.#refByElement.get(element);
+		if (known !== void 0 && this.#table.has(known)) return known;
+		return this.#mint(element, "image", frame);
+	}
+	/**
+	* 可滚容器的句柄（0.23.0 分册 22）。角色白名单之外——表格容器往往是个 `generic` div，
+	* 但 `scroll` 确实作用在它身上。不发就成了「标了能滚、模型指认不了」，正是 AC-G8 禁的那种幽灵能力。
+	*
+	* 仍过操作范围与零尺寸两道闸（FR-22.12）；已有句柄就原样复用且**不改 kind**。
+	*/
+	issueScrollable(element, frame) {
+		if (!this.#actionable.has(element) || this.#excluded.has(element)) return void 0;
+		if (occupiesNoSpace(element)) return void 0;
+		const known = this.#refByElement.get(element);
+		if (known !== void 0 && this.#table.has(known)) return known;
+		return this.#mint(element, "action", frame);
+	}
+	#mint(element, kind, frame) {
 		const bytes = /* @__PURE__ */ new Uint8Array(8);
 		crypto.getRandomValues(bytes);
 		const ref = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -3380,9 +3744,42 @@ function hidden(element) {
 	}
 	return false;
 }
+/**
+* 「开着的浮层」里必须有可操作的东西。空的定位容器（装饰角标、测量层、定位锚点）
+* 满页都是，只看定位会把它们全当成浮层——实测该页面误伤 337/400（0.23.0 设计 16 §3.1）。
+*/
+const POPOVER_CONTENT_SELECTOR = "a[href],button,input,select,textarea,[role=\"button\"],[role=\"link\"],[role=\"option\"],[role=\"menuitem\"],[role=\"gridcell\"],[role=\"tab\"],[role=\"checkbox\"],[role=\"radio\"]";
+/**
+* 这个元素旁边是不是已经有一个开着的浮层（0.23.0 FR-15.1）。
+*
+* 零 DOM 变更有两种成因：元素真的不响应，和**页面已经处于这个动作要达成的状态**。
+* 后者按分册 12 的原判据会被报成 `noop`，模型于是放弃一条已经走通的路。
+*
+* 只看**父元素这一层**：自绘下拉的写法是触发器与浮层同属一个包装容器，
+* 往上多走一层就开始把无关区块算进来（误伤 3/400 → 31/400）。
+*
+* 用 `hidden()` 而不是尺寸：jsdom 没有布局，`getBoundingClientRect()` 恒为 0，
+* 依赖尺寸这条判据就没法被测试守住（设计 16 §3.2）。
+*/
+function popoverOpenBeside(element) {
+	if (element.getAttribute("aria-expanded") === "true") return true;
+	const parent = element.parentElement;
+	if (parent === null) return false;
+	const view = element.ownerDocument.defaultView;
+	if (view === null) return false;
+	for (const candidate of parent.querySelectorAll("*")) {
+		if (candidate === element || element.contains(candidate) || candidate.contains(element)) continue;
+		const position = view.getComputedStyle(candidate).position;
+		if (position !== "absolute" && position !== "fixed") continue;
+		if (hidden(candidate)) continue;
+		if (candidate.querySelector(POPOVER_CONTENT_SELECTOR) === null) continue;
+		return true;
+	}
+	return false;
+}
 const inputType = (element) => (element.getAttribute("type") ?? "text").toLowerCase();
 const isSecret = (element) => element.tagName === "INPUT" && SECRET_INPUT_TYPES.has(inputType(element));
-const textOf = (element) => element?.textContent?.replace(/\s+/g, " ").trim() ?? "";
+const textOf$2 = (element) => element?.textContent?.replace(/\s+/g, " ").trim() ?? "";
 /**
 * 可访问名称，按 accname 的优先级取。
 *
@@ -3394,19 +3791,19 @@ function accessibleName(element) {
 	const labelledBy = element.getAttribute("aria-labelledby");
 	if (labelledBy !== null && labelledBy.trim() !== "") {
 		const doc = element.ownerDocument;
-		const joined = labelledBy.split(/\s+/).map((id) => textOf(doc.getElementById(id))).filter((part) => part !== "").join(" ");
+		const joined = labelledBy.split(/\s+/).map((id) => textOf$2(doc.getElementById(id))).filter((part) => part !== "").join(" ");
 		if (joined !== "") return joined;
 	}
 	const label = element.getAttribute("aria-label");
 	if (label !== null && label.trim() !== "") return label.trim();
 	const labels = element.labels;
 	if (labels && labels.length > 0) {
-		const joined = [...labels].map((node) => textOf(node)).filter((part) => part !== "").join(" ");
+		const joined = [...labels].map((node) => textOf$2(node)).filter((part) => part !== "").join(" ");
 		if (joined !== "") return joined;
 	}
-	const own = textOf(element);
+	const own = textOf$2(element);
 	if (own !== "") return own;
-	const wrapping = textOf(element.closest("label"));
+	const wrapping = textOf$2(element.closest("label"));
 	if (wrapping !== "") return wrapping;
 	const placeholder = element.getAttribute("placeholder");
 	if (placeholder !== null && placeholder.trim() !== "") return placeholder.trim();
@@ -3519,6 +3916,187 @@ async function waitFor(probe, timeoutMs = 2e3) {
 		await new Promise((resolve) => setTimeout(resolve, 25));
 	}
 }
+/** 元素中心点的视口坐标，指针类事件都按它构造 */
+function centerOf(element) {
+	const rect = element.getBoundingClientRect();
+	return {
+		clientX: rect.left + rect.width / 2,
+		clientY: rect.top + rect.height / 2
+	};
+}
+/** 指针事件构造器；跨 realm 时要拿目标自己那个 window 上的，不能用全局的 */
+function pointerCtorOf(element) {
+	return element.ownerDocument.defaultView?.PointerEvent;
+}
+/**
+* 一次「像人一样」的悬停（FR-17.2）。
+*
+* `enter` 那两个**不冒泡**，必须单独派发：只发 `over` 的话 React 的 `onMouseEnter`
+* 一个都收不到，而它正是组件库开浮层最常用的那个钩子。
+* 末尾补 `move` 是因为不少实现按「指针在里面动过」才认，静止的 over 被当成误触。
+*
+* ⚠️ 这套合成事件改变不了 CSS `:hover` 伪类——它由浏览器按**真实**指针位置判定。
+* 纯 CSS 开的浮层因此打不开，调用方要靠 `noop` 把这件事如实说给模型（FR-17.3）。
+*/
+function hoverOver(element) {
+	const base = {
+		bubbles: true,
+		cancelable: true,
+		composed: true,
+		...centerOf(element)
+	};
+	const noBubble = {
+		...base,
+		bubbles: false
+	};
+	const pointer = {
+		pointerId: 1,
+		pointerType: "mouse",
+		isPrimary: true
+	};
+	const Pointer = pointerCtorOf(element);
+	if (Pointer !== void 0) element.dispatchEvent(new Pointer("pointerover", {
+		...base,
+		...pointer
+	}));
+	if (Pointer !== void 0) element.dispatchEvent(new Pointer("pointerenter", {
+		...noBubble,
+		...pointer
+	}));
+	element.dispatchEvent(new MouseEvent("mouseover", base));
+	element.dispatchEvent(new MouseEvent("mouseenter", noBubble));
+	if (Pointer !== void 0) element.dispatchEvent(new Pointer("pointermove", {
+		...base,
+		...pointer
+	}));
+	element.dispatchEvent(new MouseEvent("mousemove", base));
+}
+/**
+* 悬停之后页面有没有动（FR-17.3）。
+*
+* 用 `MutationObserver` 而不是比对快照：浮层可能挂到 `document.body` 末尾、
+* 也可能只是把某个节点的 `hidden` 去掉，逐一枚举会漏，而漏判的代价是向模型报假成功。
+* 观察器在派发**之前**挂上——晚一步就会错过同步执行的那批监听器。
+*/
+function watchMutations(element) {
+	const doc = element.ownerDocument;
+	const Observer = doc.defaultView?.MutationObserver;
+	if (Observer === void 0) return {
+		changed: () => true,
+		stop: () => void 0
+	};
+	let seen = false;
+	const observer = new Observer(() => {
+		seen = true;
+	});
+	observer.observe(doc, {
+		subtree: true,
+		childList: true,
+		attributes: true,
+		characterData: true
+	});
+	return {
+		changed: () => {
+			if (observer.takeRecords().length > 0) seen = true;
+			return seen;
+		},
+		stop: () => observer.disconnect()
+	};
+}
+/**
+* 一次拖拽（FR-17.5）。真实页面有两套互不相通的机制，按起点自动选：
+*
+* - 起点带 `draggable` 且环境给得出 `DragEvent`/`DataTransfer` → HTML5 拖放；
+* - 否则 → 指针拖拽，`pointerdown` 起点、`pointermove` / `pointerup` 落终点坐标。
+*
+* 指针那一套的 `move` / `up` 必须冒泡：这类实现为了不被换位打断，
+* 监听是挂在 `document` 上的（把手一旦在 DOM 里搬走，指针捕获就断了），
+* 不冒泡的话一路只动得了第一格，甚至一格都不动。
+*
+* 构造器缺失时**降级**而不是抛：执行器的契约是一律给出结构化结果，
+* 抛出去会连带跳过策略层的审计，那比操作失败本身更糟（同 `attachFiles` 的理由）。
+*
+* @returns 失败原因；成功返回 `undefined`
+*/
+function dragBetween(from, to) {
+	const view = from.ownerDocument.defaultView;
+	const start = centerOf(from);
+	const end = centerOf(to);
+	const Drag = view?.DragEvent;
+	const Transfer = view?.DataTransfer;
+	if (from.closest("[draggable=\"true\"]") !== null && Drag !== void 0 && Transfer !== void 0) {
+		const init = {
+			bubbles: true,
+			cancelable: true,
+			composed: true,
+			dataTransfer: new Transfer()
+		};
+		from.dispatchEvent(new Drag("dragstart", {
+			...init,
+			...start
+		}));
+		to.dispatchEvent(new Drag("dragenter", {
+			...init,
+			...end
+		}));
+		const accepted = !to.dispatchEvent(new Drag("dragover", {
+			...init,
+			...end
+		}));
+		if (accepted) to.dispatchEvent(new Drag("drop", {
+			...init,
+			...end
+		}));
+		from.dispatchEvent(new Drag("dragend", {
+			...init,
+			...end
+		}));
+		return accepted ? void 0 : "The destination does not accept dropped items.";
+	}
+	const Pointer = view?.PointerEvent;
+	const mouse = {
+		bubbles: true,
+		cancelable: true,
+		composed: true,
+		button: 0
+	};
+	const pointer = {
+		...mouse,
+		pointerId: 1,
+		pointerType: "mouse",
+		isPrimary: true
+	};
+	if (Pointer !== void 0) from.dispatchEvent(new Pointer("pointerdown", {
+		...pointer,
+		...start,
+		buttons: 1
+	}));
+	from.dispatchEvent(new MouseEvent("mousedown", {
+		...mouse,
+		...start,
+		buttons: 1
+	}));
+	if (Pointer !== void 0) to.dispatchEvent(new Pointer("pointermove", {
+		...pointer,
+		...end,
+		buttons: 1
+	}));
+	to.dispatchEvent(new MouseEvent("mousemove", {
+		...mouse,
+		...end,
+		buttons: 1
+	}));
+	if (Pointer !== void 0) to.dispatchEvent(new Pointer("pointerup", {
+		...pointer,
+		...end,
+		buttons: 0
+	}));
+	to.dispatchEvent(new MouseEvent("mouseup", {
+		...mouse,
+		...end,
+		buttons: 0
+	}));
+}
 /**
 * 一个动作覆盖三种选择控件（FR-25.2）：原生 select 直接设值，
 * ARIA 组合与日期格点走「点开 → 等浮层 → 按可访问名匹配 → 点中」。
@@ -3615,6 +4193,12 @@ function attachFiles(input, files) {
 	input.dispatchEvent(new Event("change", { bubbles: true }));
 }
 const scrolls = (overflow) => overflow === "auto" || overflow === "scroll" || overflow === "overlay";
+const axisOf = (direction) => direction === "left" || direction === "right" ? "x" : "y";
+/** 该元素自身在这条轴上能不能滚。两个条件的合取，见 `scrollTargetOf` 的注释 */
+function scrollsOn(node, axis, view) {
+	const style = view.getComputedStyle(node);
+	return axis === "y" ? scrolls(style.overflowY) && node.scrollHeight > node.clientHeight : scrolls(style.overflowX) && node.scrollWidth > node.clientWidth;
+}
 /**
 * 滚动落点（FR-10.3）：从被指认元素**自身**起沿祖先链上溯，取第一个真正能滚的容器。
 *
@@ -3628,20 +4212,21 @@ const scrolls = (overflow) => overflow === "auto" || overflow === "scroll" || ov
 * 根滚动容器单独兜底而不是靠链上命中：`documentElement` 的 `overflow-y` 计算值
 * 通常是 `visible`（滚动被传播到视口），不会被上面的判据命中，但文档确实可滚。
 * 顺序必须是先链后兜底——嵌套场景下先命中的必须是内层列表。
+*
+* **按轴判（0.23.0 分册 22 FR-22.7）**：同一个容器常常只在一条轴上溢出，
+* 拿纵向判据去找横向落点会整体判成不可滚，那正是横向滚动此前失败的原因。
 */
-function scrollTargetOf(element) {
+function scrollTargetOf(element, axis) {
 	const doc = element.ownerDocument;
 	const view = doc.defaultView;
 	if (view === null) return void 0;
-	for (let node = element; node !== null; node = node.parentElement) {
-		const style = view.getComputedStyle(node);
-		if (scrolls(style.overflowY) && node.scrollHeight > node.clientHeight) return {
-			container: node,
-			isRoot: false
-		};
-	}
+	for (let node = element; node !== null; node = node.parentElement) if (scrollsOn(node, axis, view)) return {
+		container: node,
+		isRoot: false
+	};
 	const root = doc.scrollingElement ?? doc.documentElement;
-	if (root !== null && root.scrollHeight > root.clientHeight) return {
+	const rootOverflows = root !== null && (axis === "y" ? root.scrollHeight > root.clientHeight : root.scrollWidth > root.clientWidth);
+	if (root !== null && rootOverflows) return {
 		container: root,
 		isRoot: true
 	};
@@ -3746,11 +4331,12 @@ function createDomPageActionExecutor(options) {
 	* 稳定化是滚动自己的收尾，见 `watchQuiescence`。
 	*/
 	const scrollRegion = async (element, target, direction) => {
-		const found = scrollTargetOf(element);
+		const axis = axisOf(direction);
+		const found = scrollTargetOf(element, axis);
 		if (found === void 0) return {
 			ok: false,
 			target,
-			reason: "This area cannot be scrolled: nothing around this element has a scrollable region."
+			reason: `This area cannot be scrolled ${direction}: nothing around this element scrolls ${axis === "y" ? "vertically" : "horizontally"}.`
 		};
 		const { container, isRoot } = found;
 		if (!isRoot && !reader.inActionScope(container)) return {
@@ -3758,17 +4344,22 @@ function createDomPageActionExecutor(options) {
 			target,
 			reason: "The scrollable region around this element is outside the actionable scope."
 		};
-		const step = Math.max(container.clientHeight - SCROLL_OVERLAP_PX, Math.round(container.clientHeight / 2), 1);
-		const before = container.scrollTop;
+		const extent = axis === "y" ? container.clientHeight : container.clientWidth;
+		const step = Math.max(extent - SCROLL_OVERLAP_PX, Math.round(extent / 2), 1);
+		const forward = direction === "down" || direction === "right";
+		const before = axis === "y" ? container.scrollTop : container.scrollLeft;
 		const watch = watchQuiescence(container);
-		container.scrollTop = direction === "down" ? before + step : before - step;
+		const next = forward ? before + step : before - step;
+		if (axis === "y") container.scrollTop = next;
+		else container.scrollLeft = next;
 		await watch.settle(clampScrollSettleMs(options.scrollSettleMs?.()));
-		const after = container.scrollTop;
+		const after = axis === "y" ? container.scrollTop : container.scrollLeft;
+		const limit = axis === "y" ? container.scrollHeight - container.clientHeight - 1 : container.scrollWidth - container.clientWidth - 1;
 		return {
 			ok: true,
 			target,
 			scrolled: {
-				atEnd: direction === "down" ? after >= container.scrollHeight - container.clientHeight - 1 : after <= 0,
+				atEnd: forward ? after >= limit : after <= 0,
 				movedBy: Math.abs(after - before)
 			}
 		};
@@ -3788,9 +4379,11 @@ function createDomPageActionExecutor(options) {
 			reason
 		});
 		if (reader.handleKindOf(request.ref) === "anchor") return fail("That reference points at a container, which cannot be acted on. Use it with perceive_page to read inside it, then act on an element that carries its own reference. If nothing inside it has one, this part of the page offers no action and retrying here will not help.");
+		if (reader.handleKindOf(request.ref) === "image") return fail("That reference points at an image, which cannot be acted on. Use it with capture_page_image to read the picture itself.");
 		if (reader.modalStateOf(element) === "unelevated") return fail("That dialog is not in the authorized scope because it was opened manually. Ask me to open it, or add it to the host allowlist.");
 		if (reader.modalStateOf(element) !== "elevated" && !reader.inActionScope(element)) return fail("The element is no longer inside the actionable scope.");
 		if (hidden(element)) return fail("The element is not visible.");
+		if (occupiesNoSpace(element)) return fail("The element takes up no space on screen, so it cannot be clicked or pointed at.");
 		if (element.hasAttribute("disabled")) return fail("The element is disabled.");
 		const modalsBefore = reader.modalSnapshot();
 		const frameView = element.ownerDocument.defaultView;
@@ -3817,15 +4410,22 @@ function createDomPageActionExecutor(options) {
 			};
 		};
 		if (request.action === "click") {
+			const watch = watchMutations(element);
 			press(element);
-			return await done({
+			const outcome = await done({
 				ok: true,
 				target
 			});
+			const changed = watch.changed();
+			watch.stop();
+			return changed || outcome.navigated === true || outcome.elevatedModal !== void 0 || popoverOpenBeside(element) ? outcome : {
+				...outcome,
+				noop: true
+			};
 		}
 		if (request.action === "fill") {
 			if (!FILLABLE_TAGS.has(element.tagName)) return fail("The element is not a text control.");
-			if (element.hasAttribute("readonly")) return fail("The element is read-only.");
+			if (element.hasAttribute("readonly")) return fail("The element is read-only. Read-only text fields often open a picker when clicked, so try the click action on this same element.");
 			fillValue(element, request.value ?? "");
 			return await done({
 				ok: true,
@@ -3844,9 +4444,36 @@ function createDomPageActionExecutor(options) {
 		}
 		if (request.action === "set") return await done(setToggle(element, request.value ?? "", target));
 		if (request.action === "scroll") {
-			if (request.value !== "down" && request.value !== "up") return fail("Use \"down\" or \"up\".");
+			if (!SCROLL_DIRECTIONS.includes(request.value)) return fail(`Use ${SCROLL_DIRECTIONS.map((d) => `"${d}"`).join(" / ")}.`);
 			return await scrollRegion(element, target, request.value);
 		}
+		if (request.action === "hover") {
+			const watch = watchMutations(element);
+			hoverOver(element);
+			await waitFor(() => watch.changed() ? true : void 0, 500);
+			const changed = watch.changed();
+			watch.stop();
+			return await done({
+				ok: true,
+				target,
+				...changed || popoverOpenBeside(element) ? {} : { noop: true }
+			});
+		}
+		if (request.action === "drag") {
+			const destination = request.value ?? "";
+			if (destination === "") return fail("The drag action needs a value holding the destination ref.");
+			const dropTarget = reader.resolve(destination);
+			if (dropTarget === void 0) return fail("The destination reference is unknown or expired.");
+			if (reader.handleKindOf(destination) === "image") return fail("The destination reference points at an image, which cannot receive a drop.");
+			if (reader.modalStateOf(dropTarget) !== "elevated" && !reader.inActionScope(dropTarget)) return fail("The destination is no longer inside the actionable scope.");
+			if (hidden(dropTarget)) return fail("The destination is not visible.");
+			const refused = dragBetween(element, dropTarget);
+			if (refused !== void 0) return fail(refused);
+			return await done({
+				ok: true,
+				target
+			});
+		}
 		if (request.action === "attach") {
 			const files = await options.pickFiles?.();
 			if (files === void 0 || files.length === 0) return {
@@ -4034,21 +4661,76 @@ async function roundTrip(transport, request, expect, code, timeoutMs) {
 */
 function createRemotePerceptionReader(options) {
 	const { transport, targets, timeoutMs = DEFAULT_PAGE_AGENT_TIMEOUT_MS, onDocument } = options;
-	return { async read(scope, capture) {
-		const reply = await roundTrip(transport, {
-			type: "perceive",
-			scope,
-			...capture !== void 0 ? { capture } : {}
-		}, "perceive-result", "PERCEPTION_FAILED", timeoutMs);
-		targets.replace(reply.targets, reply.document);
-		if (reply.document !== void 0) onDocument?.(reply.document);
-		return reply.result;
-	} };
-}
-
-//#endregion
-//#region ../browser/src/remote/executor.ts
-/**
+	/**
+	* 上一批写进分片的条目（0.23.0 分册 13 / FR-13.4）。
+	*
+	* `registry.replace` 是**整体替换分片**，而子树读取只回传子树内的条目——
+	* 照搬就等于「读完日期面板，页面别处全部失去句柄」。本地形态没有这个问题：
+	* `HandleIssuer` 的表跨感知保留，子树读取只是少发几个 ref，既有的一个都不丢。
+	* 差值由这里补出来，而不是转嫁给模型。
+	*
+	* 状态留在发起方而不是给 `RemoteTargetRegistry` 加 `merge()`：
+	* 后者对所有实现方都是破坏性变更，需求 §2.2 把它列为禁止项。
+	*/
+	let lastShard;
+	const commit = (entries, document, merge) => {
+		const sameDocument = lastShard !== void 0 && lastShard.key === document?.key;
+		let next = entries;
+		if (merge && sameDocument && lastShard !== void 0) {
+			const byRef = /* @__PURE__ */ new Map();
+			for (const entry of lastShard.entries) byRef.set(entry.ref, entry);
+			for (const entry of entries) byRef.set(entry.ref, entry);
+			next = [...byRef.values()];
+		}
+		targets.replace(next, document);
+		lastShard = {
+			key: document?.key,
+			entries: next
+		};
+		if (document !== void 0) onDocument?.(document);
+	};
+	return {
+		async read(scope, capture) {
+			const reply = await roundTrip(transport, {
+				type: "perceive",
+				scope,
+				...capture !== void 0 ? { capture } : {}
+			}, "perceive-result", "PERCEPTION_FAILED", timeoutMs);
+			commit(reply.targets, reply.document, false);
+			return reply.result;
+		},
+		/**
+		* 子树续读（0.23.0 分册 13 / FR-13.1）。
+		*
+		* 本地形态早就有这个方法，缺的只是这一段跨上下文接线；不实现它，
+		* policy 会直接抛 `PERCEPTION_SUBTREE_UNSUPPORTED`，模型在浏览器扩展这类
+		* 宿主里就永远没有「第一段没找到 → 展开某个子树再看」这条自救路径。
+		*/
+		async readSubtree(scope, ref, capture) {
+			let reply;
+			try {
+				reply = await roundTrip(transport, {
+					type: "perceive",
+					scope,
+					ref,
+					...capture !== void 0 ? { capture } : {}
+				}, "perceive-result", "PERCEPTION_FAILED", timeoutMs);
+			} catch (e) {
+				if (e instanceof WebSkillError) {
+					if (e.code === "PERCEPTION_SUBTREE_OUT_OF_SCOPE") return { rejected: "out-of-scope" };
+					if (e.code === "PERCEPTION_SUBTREE_UNKNOWN_REF") return { rejected: "unknown-ref" };
+				}
+				throw e;
+			}
+			commit(reply.targets, reply.document, true);
+			return reply.result;
+		}
+	};
+}
+
+//#endregion
+//#region ../browser/src/remote/executor.ts
+/**
 * 跨上下文的页面操作执行器（分册 13 / FR-13.3）。
 * @experimental
 */
@@ -4080,6 +4762,27 @@ function createRemotePageActionExecutor(options) {
 	};
 }
 
+//#endregion
+//#region ../browser/src/remote/pageImage.ts
+/**
+* 跨上下文的取像端口（分册 12 §2）。
+*
+* 与 `createRemotePageActionExecutor` 同一条装配规矩：句柄表在页面那一侧，
+* 这边只负责把一次请求送过去。**不与感知期的取像共用任何状态**——
+* 那条流是为了让模型看懂，这条流是为了落产物，两者不得互相触发。
+* @experimental
+*/
+function createRemotePageImageHost(options) {
+	const { transport, timeoutMs = DEFAULT_PAGE_AGENT_TIMEOUT_MS } = options;
+	return { async capture(ref, maxBytes) {
+		return (await roundTrip(transport, {
+			type: "capture-image",
+			ref,
+			maxBytes
+		}, "capture-image-result", "TOOL_EXECUTION_FAILED", timeoutMs)).result;
+	} };
+}
+
 //#endregion
 //#region ../browser/src/remote/handler.ts
 /** 深度收集句柄；顺序即遍历序，便于与本地形态逐条比对 */
@@ -4091,6 +4794,24 @@ function collectRefs(nodes, out = []) {
 	return out;
 }
 /**
+* 子树被拒 → 既有的 `error` 应答变体（0.23.0 分册 13 / FR-13.5）。
+* 不新增应答形态，是把本册的契约变更压到「一个可选请求字段」的关键。
+*
+* 这两个错误码本来就在 `WebSkillErrorCode` 里，远程 reader 靠它们还原出
+* `{ rejected }`，policy 那边的 `#recordDenied` 才能照常留痕。
+*/
+function rejectionReply(rejected) {
+	return rejected === "out-of-scope" ? {
+		type: "error",
+		code: "PERCEPTION_SUBTREE_OUT_OF_SCOPE",
+		message: "that reference is outside the perception scope, so its subtree cannot be read"
+	} : {
+		type: "error",
+		code: "PERCEPTION_SUBTREE_UNKNOWN_REF",
+		message: "that reference is not on this page any more; perceive the page again to get a fresh reference"
+	};
+}
+/**
 * 页面侧处理器（分册 13 / FR-13.7）。
 *
 * 必须是工厂而不是裸函数：`DomPerceptionReader` **是有状态的**——
@@ -4134,8 +4855,15 @@ function createPageAgentHandler(options = {}) {
 	return { async handle(request) {
 		try {
 			if (request.type === "perceive") {
-				const raw = request.capture === void 0 ? reader.read(request.scope) : await reader.read(request.scope, request.capture);
-				const result = Array.isArray(raw) ? { nodes: raw } : raw;
+				let result;
+				if (request.ref !== void 0) {
+					const out = request.capture === void 0 ? await reader.readSubtree(request.scope, request.ref) : await reader.readSubtree(request.scope, request.ref, request.capture);
+					if ("rejected" in out) return rejectionReply(out.rejected);
+					result = out;
+				} else {
+					const raw = request.capture === void 0 ? reader.read(request.scope) : await reader.read(request.scope, request.capture);
+					result = Array.isArray(raw) ? { nodes: raw } : raw;
+				}
 				const targets = [];
 				for (const ref of collectRefs(result.nodes)) {
 					const target = executor.describe(ref);
@@ -4152,6 +4880,24 @@ function createPageAgentHandler(options = {}) {
 					...identity !== void 0 ? { document: identity } : {}
 				};
 			}
+			if (request.type === "capture-image") {
+				const element = reader.resolve(request.ref);
+				if (element === void 0) return {
+					type: "capture-image-result",
+					result: {
+						id: request.ref,
+						reason: "that reference is not on this page any more; perceive the page again to get a fresh reference",
+						triedLevels: []
+					}
+				};
+				return {
+					type: "capture-image-result",
+					result: await captureDocumentImage(element, {
+						id: request.ref,
+						maxBytes: request.maxBytes
+					})
+				};
+			}
 			return {
 				type: "execute-result",
 				outcome: await executor.execute(request.request)
@@ -4357,9 +5103,14 @@ function createFrameRouter(options) {
 		const address = refFrames.get(request.request.ref) ?? await options.dispatcher.mainFrame();
 		return (await options.dispatcher.send(address, request)).reply;
 	}
+	async function captureImage(request) {
+		const address = refFrames.get(request.ref) ?? await options.dispatcher.mainFrame();
+		return (await options.dispatcher.send(address, request)).reply;
+	}
 	return {
 		perceive,
-		execute
+		execute,
+		captureImage
 	};
 }
 
@@ -5413,8 +6164,8 @@ function fail(message) {
 	throw new WebSkillError("TOOL_EXECUTION_FAILED", message);
 }
 /** 按 localName 取子孙元素，忽略命名空间前缀：不同生成器的前缀写法并不统一 */
-const byTag$1 = (scope, name) => [...scope.getElementsByTagNameNS("*", name)];
-function parseXml$2(bytes, what) {
+const byTag$3 = (scope, name) => [...scope.getElementsByTagNameNS("*", name)];
+function parseXml$3(bytes, what) {
 	const doc = new DOMParser().parseFromString(new TextDecoder().decode(bytes), "application/xml");
 	if (doc.getElementsByTagName("parsererror").length > 0) fail(`The workbook ${what} could not be parsed as XML.`);
 	return doc;
@@ -5461,14 +6212,14 @@ function isDateFormatCode(code) {
 /** 单元格样式索引 → 是否日期格式 */
 function readDateStyles(bytes) {
 	if (bytes === void 0) return [];
-	const doc = parseXml$2(bytes, "styles");
+	const doc = parseXml$3(bytes, "styles");
 	const custom = /* @__PURE__ */ new Map();
-	for (const fmt of byTag$1(doc, "numFmt")) {
+	for (const fmt of byTag$3(doc, "numFmt")) {
 		const id = Number(fmt.getAttribute("numFmtId"));
 		const code = fmt.getAttribute("formatCode");
 		if (Number.isFinite(id) && code !== null) custom.set(id, code);
 	}
-	const cellXfs = byTag$1(doc, "cellXfs")[0];
+	const cellXfs = byTag$3(doc, "cellXfs")[0];
 	if (cellXfs === void 0) return [];
 	return [...cellXfs.children].filter((xf) => xf.localName === "xf").map((xf) => {
 		const id = Number(xf.getAttribute("numFmtId") ?? "0");
@@ -5506,7 +6257,7 @@ function serialToIso(serial, date1904) {
 	return `${iso}T${pad(h)}:${pad(m)}:${pad(s)}`;
 }
 /** 一个 `<c>` 的呈现文本（FR-12.3） */
-function cellText(cell, shared, dateStyles, date1904) {
+function cellText$1(cell, shared, dateStyles, date1904) {
 	const type = cell.getAttribute("t");
 	if (type === "inlineStr") {
 		const is = [...cell.children].find((child) => child.localName === "is");
@@ -5533,7 +6284,7 @@ function cellText(cell, shared, dateStyles, date1904) {
 function sheetLines(doc, shared, dateStyles, date1904) {
 	const lines = [];
 	let previousRow = 0;
-	for (const row of byTag$1(doc, "row")) {
+	for (const row of byTag$3(doc, "row")) {
 		const declared = Number(row.getAttribute("r"));
 		const rowNumber = Number.isInteger(declared) && declared > 0 ? declared : previousRow + 1;
 		for (let gap = previousRow + 1; gap < rowNumber; gap++) lines.push("");
@@ -5544,7 +6295,7 @@ function sheetLines(doc, shared, dateStyles, date1904) {
 			if (cell.localName !== "c") continue;
 			const column = columnIndex(cell.getAttribute("r")) ?? nextColumn;
 			for (let gap = cells.length; gap < column; gap++) cells.push("");
-			const text = cellText(cell, shared, dateStyles, date1904);
+			const text = cellText$1(cell, shared, dateStyles, date1904);
 			if (cells.length > column) cells[column] = text;
 			else cells.push(text);
 			nextColumn = column + 1;
@@ -5576,21 +6327,21 @@ async function readXlsxWorkbook(bytes) {
 	const parts = new Map(entries);
 	const workbookBytes = parts.get(WORKBOOK);
 	if (workbookBytes === void 0) fail(`This file is not an Excel workbook: it has no ${WORKBOOK} entry.`);
-	const workbook = parseXml$2(workbookBytes, "index");
-	const workbookPr = byTag$1(workbook, "workbookPr")[0];
+	const workbook = parseXml$3(workbookBytes, "index");
+	const workbookPr = byTag$3(workbook, "workbookPr")[0];
 	const date1904 = workbookPr?.getAttribute("date1904") === "1" || workbookPr?.getAttribute("date1904") === "true";
 	const relsBytes = parts.get(WORKBOOK_RELS);
 	const targets = /* @__PURE__ */ new Map();
-	if (relsBytes !== void 0) for (const rel of byTag$1(parseXml$2(relsBytes, "relationships"), "Relationship")) {
+	if (relsBytes !== void 0) for (const rel of byTag$3(parseXml$3(relsBytes, "relationships"), "Relationship")) {
 		const id = rel.getAttribute("Id");
 		const target = rel.getAttribute("Target");
 		if (id !== null && target !== null) targets.set(id, resolveSheetPath(target));
 	}
 	const sharedBytes = parts.get(SHARED_STRINGS);
-	const shared = sharedBytes === void 0 ? [] : byTag$1(parseXml$2(sharedBytes, "shared strings"), "si").map(sharedStringText);
+	const shared = sharedBytes === void 0 ? [] : byTag$3(parseXml$3(sharedBytes, "shared strings"), "si").map(sharedStringText);
 	const dateStyles = readDateStyles(parts.get(STYLES));
 	const sheets = [];
-	for (const [ordinal, sheet] of byTag$1(workbook, "sheet").entries()) {
+	for (const [ordinal, sheet] of byTag$3(workbook, "sheet").entries()) {
 		const name = sheet.getAttribute("name") ?? `Sheet${ordinal + 1}`;
 		const relId = sheet.getAttributeNS("http://schemas.openxmlformats.org/officeDocument/2006/relationships", "id") ?? sheet.getAttribute("r:id");
 		const path = relId !== null ? targets.get(relId) : void 0;
@@ -5599,7 +6350,7 @@ async function readXlsxWorkbook(bytes) {
 		sheets.push({
 			name,
 			path,
-			lines: sheetLines(parseXml$2(sheetBytes, `worksheet "${name}"`), shared, dateStyles, date1904)
+			lines: sheetLines(parseXml$3(sheetBytes, `worksheet "${name}"`), shared, dateStyles, date1904)
 		});
 	}
 	return {
@@ -5660,7 +6411,7 @@ function imageBlockOf(path, data) {
 *
 * 零新增依赖，沿用同一条路：zip 走 `unzipWithLimits`，XML 走 `DOMParser`。
 */
-const DOCUMENT = "word/document.xml";
+const DOCUMENT$1 = "word/document.xml";
 const RELS = "word/_rels/document.xml.rels";
 /** 图宽占正文宽度的门槛：低于它的是签名章、页眉 logo、装饰线（FR-22.9） @experimental */
 const DOCX_IMAGE_WIDTH_RATIO = .3;
@@ -5671,7 +6422,7 @@ const DEFAULT_BODY_TWIPS = 9360;
 function attr(node, name) {
 	for (const item of node.attributes) if (item.name === name || item.localName === name) return item.value;
 }
-function parseXml$1(bytes, what) {
+function parseXml$2(bytes, what) {
 	const doc = new DOMParser().parseFromString(new TextDecoder().decode(bytes), "application/xml");
 	if (doc.getElementsByTagName("parsererror").length > 0) throw new WebSkillError("TOOL_EXECUTION_FAILED", `The Word document's ${what} could not be parsed as XML.`);
 	return doc;
@@ -5732,12 +6483,12 @@ function createDocxBlockReader() {
 async function readDocxBlocks(bytes) {
 	const entries = await unzipWithLimits(bytes);
 	const files = new Map(entries);
-	const main = files.get(DOCUMENT);
-	if (main === void 0) throw new WebSkillError("TOOL_EXECUTION_FAILED", `This file is not a Word document: it has no ${DOCUMENT} entry.`);
-	const doc = parseXml$1(main, "body");
+	const main = files.get(DOCUMENT$1);
+	if (main === void 0) throw new WebSkillError("TOOL_EXECUTION_FAILED", `This file is not a Word document: it has no ${DOCUMENT$1} entry.`);
+	const doc = parseXml$2(main, "body");
 	const targets = /* @__PURE__ */ new Map();
 	const rels = files.get(RELS);
-	if (rels !== void 0) for (const rel of parseXml$1(rels, "relationships").getElementsByTagName("Relationship")) {
+	if (rels !== void 0) for (const rel of parseXml$2(rels, "relationships").getElementsByTagName("Relationship")) {
 		const id = attr(rel, "Id");
 		const target = attr(rel, "Target");
 		if (id !== void 0 && target !== void 0) targets.set(id, `word/${target.replace(/^\.?\//, "")}`);
@@ -5779,13 +6530,13 @@ const XLSX_IMAGE_MIN_COLUMNS = 2;
 /** @experimental */
 const XLSX_IMAGE_MIN_ROWS = 3;
 const RELATIONSHIPS_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
-const byTag = (scope, name) => [...scope.getElementsByTagNameNS("*", name)];
-function parseXml(bytes) {
+const byTag$2 = (scope, name) => [...scope.getElementsByTagNameNS("*", name)];
+function parseXml$1(bytes) {
 	const doc = new DOMParser().parseFromString(new TextDecoder().decode(bytes), "application/xml");
 	return doc.getElementsByTagName("parsererror").length > 0 ? void 0 : doc;
 }
 /** rels 的 Target 可能是 `../media/x.png` 这种相对路径，得按所在目录归一化 */
-function resolveRelative(baseDir, target) {
+function resolveRelative$1(baseDir, target) {
 	if (target.startsWith("/")) return target.slice(1);
 	const segments = [...baseDir.split("/").filter((part) => part !== ""), ...target.split("/")];
 	const out = [];
@@ -5801,17 +6552,17 @@ const relsOf = (path) => `${dirOf(path)}_rels/${path.slice(path.lastIndexOf("/")
 function readRels(parts, path) {
 	const out = /* @__PURE__ */ new Map();
 	const bytes = parts.get(relsOf(path));
-	const doc = bytes === void 0 ? void 0 : parseXml(bytes);
+	const doc = bytes === void 0 ? void 0 : parseXml$1(bytes);
 	if (doc === void 0) return out;
-	for (const rel of byTag(doc, "Relationship")) {
+	for (const rel of byTag$2(doc, "Relationship")) {
 		const id = rel.getAttribute("Id");
 		const target = rel.getAttribute("Target");
-		if (id !== null && target !== null) out.set(id, resolveRelative(dirOf(path), target));
+		if (id !== null && target !== null) out.set(id, resolveRelative$1(dirOf(path), target));
 	}
 	return out;
 }
 const anchorNumber = (anchor, name) => {
-	const node = anchor === void 0 ? void 0 : byTag(anchor, name)[0];
+	const node = anchor === void 0 ? void 0 : byTag$2(anchor, name)[0];
 	const value = Number(node?.textContent ?? NaN);
 	return Number.isInteger(value) && value >= 0 ? value : 0;
 };
@@ -5822,17 +6573,17 @@ function imagesOf(parts, sheetPath) {
 	for (const [, target] of sheetRels) {
 		if (!target.includes("/drawings/")) continue;
 		const drawingBytes = parts.get(target);
-		const drawing = drawingBytes === void 0 ? void 0 : parseXml(drawingBytes);
+		const drawing = drawingBytes === void 0 ? void 0 : parseXml$1(drawingBytes);
 		if (drawing === void 0) continue;
 		const drawingRels = readRels(parts, target);
-		for (const anchor of byTag(drawing, "twoCellAnchor")) {
-			const from = byTag(anchor, "from")[0];
-			const to = byTag(anchor, "to")[0];
+		for (const anchor of byTag$2(drawing, "twoCellAnchor")) {
+			const from = byTag$2(anchor, "from")[0];
+			const to = byTag$2(anchor, "to")[0];
 			const fromRow = anchorNumber(from, "row");
 			const columns = anchorNumber(to, "col") - anchorNumber(from, "col");
 			const rows = anchorNumber(to, "row") - fromRow;
 			if (columns < 2 || rows < 3) continue;
-			const blip = byTag(anchor, "blip")[0];
+			const blip = byTag$2(anchor, "blip")[0];
 			const relId = blip?.getAttributeNS(RELATIONSHIPS_NS, "embed") ?? blip?.getAttribute("r:embed");
 			const path = relId === null || relId === void 0 ? void 0 : drawingRels.get(relId);
 			const data = path === void 0 ? void 0 : parts.get(path);
@@ -5874,6 +6625,1122 @@ async function readXlsxBlocks(bytes) {
 	return { sheets: out };
 }
 
+//#endregion
+//#region ../browser/src/document/pptxBlocks.ts
+/**
+* pptx → 逐页的块序列（0.22.0 分册 18）。
+*
+* 这不是渲染器。OOXML 包里**没有**渲染好的页面图，浏览器里也没有 pptx 渲染器，
+* 所以这条路给得出「这一页写了什么、插了哪几张图」，给不出「这一页长什么样」。
+* 要版式只能退到截屏。
+*
+* 与 docx/xlsx 同一条路：zip 走 `unzipWithLimits`，XML 走 `DOMParser`，
+* 解不了的媒体走 `imageBlockOf` 的 `skipped`——不假装读完是硬要求（FR-22.14）。
+*/
+const PRESENTATION = "ppt/presentation.xml";
+const MAIN_NS$1 = "http://schemas.openxmlformats.org/drawingml/2006/main";
+/** `p:sldId` / `p:spTree` 在 presentationml 里，不在 drawingml 里 */
+const PRESENTATION_NS = "http://schemas.openxmlformats.org/presentationml/2006/main";
+const REL_NS$2 = "http://schemas.openxmlformats.org/package/2006/relationships";
+const DOC_REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+function parseXml(files, path, what) {
+	const bytes = files.get(path);
+	if (bytes === void 0) return void 0;
+	const doc = new DOMParser().parseFromString(new TextDecoder().decode(bytes), "application/xml");
+	if (doc.getElementsByTagName("parsererror").length > 0) throw new WebSkillError("TOOL_EXECUTION_FAILED", `The presentation's ${what} could not be parsed as XML.`);
+	return doc;
+}
+/**
+* 某个部件的关系表，键是 `rId`，值是**已经解算成包内绝对路径**的 target。
+* 外部链接（`TargetMode="External"`）不收：那是别处的 URL，不是包里的东西。
+*/
+function relationshipsOf(files, part) {
+	const slash = part.lastIndexOf("/");
+	const dir = part.slice(0, slash);
+	const doc = parseXml(files, `${dir}/_rels/${part.slice(slash + 1)}.rels`, "relationships");
+	const map = /* @__PURE__ */ new Map();
+	if (doc === void 0) return map;
+	for (const node of Array.from(doc.getElementsByTagNameNS(REL_NS$2, "Relationship"))) {
+		const id = node.getAttribute("Id");
+		const target = node.getAttribute("Target");
+		if (id === null || target === null || node.getAttribute("TargetMode") === "External") continue;
+		map.set(id, resolveTarget(dir, target));
+	}
+	return map;
+}
+/** `../media/image1.png` 相对于部件所在目录解算，得到包内绝对路径 */
+function resolveTarget(dir, target) {
+	if (target.startsWith("/")) return target.slice(1);
+	const segments = dir.split("/");
+	for (const part of target.split("/")) {
+		if (part === "." || part === "") continue;
+		if (part === "..") segments.pop();
+		else segments.push(part);
+	}
+	return segments.join("/");
+}
+/**
+* 放映顺序取自 `p:sldIdLst`，**不是**文件名里的数字。
+* `slide7.xml` 完全可以排在第二张——删过页的文稿里这是常态。
+*/
+function slideOrder(files) {
+	const presentation = parseXml(files, PRESENTATION, "presentation part");
+	if (presentation === void 0) return [];
+	const rels = relationshipsOf(files, PRESENTATION);
+	const ordered = [];
+	for (const node of Array.from(presentation.getElementsByTagNameNS(PRESENTATION_NS, "sldId"))) {
+		const id = node.getAttributeNS(DOC_REL_NS, "id");
+		const target = id === null ? void 0 : rels.get(id);
+		if (target !== void 0 && files.has(target)) ordered.push(target);
+	}
+	if (ordered.length > 0) return ordered;
+	return [...files.keys()].filter((name) => /^ppt\/slides\/slide\d+\.xml$/.test(name)).sort((a, b) => slideNumber(a) - slideNumber(b));
+}
+function slideNumber(path) {
+	return Number(/(\d+)\.xml$/.exec(path)?.[1] ?? 0);
+}
+/** 段落之间换行，段落内的多个 run 直接相接——run 的切分是格式造成的，不是语义 */
+function textOf$1(node) {
+	const lines = [];
+	for (const paragraph of Array.from(node.getElementsByTagNameNS(MAIN_NS$1, "p"))) {
+		const line = Array.from(paragraph.getElementsByTagNameNS(MAIN_NS$1, "t")).map((run) => run.textContent ?? "").join("").trim();
+		if (line !== "") lines.push(line);
+	}
+	return lines.join("\n");
+}
+/**
+* 备注页的文本。多一道过滤：备注页上除备注框外还挂着页码之类的字段占位符，
+* 取值是一个孤零零的符号。**不含任何字母或数字的条目不是备注**。
+*/
+function notesOf(files, rels) {
+	const target = [...rels.values()].find((value) => value.includes("/notesSlides/"));
+	const doc = target === void 0 ? void 0 : parseXml(files, target, "speaker notes");
+	if (doc === void 0) return "";
+	const lines = [];
+	for (const tree of Array.from(doc.getElementsByTagNameNS(PRESENTATION_NS, "spTree"))) for (const shape of Array.from(tree.children)) {
+		const text = textOf$1(shape);
+		if (text !== "" && /[\p{L}\p{N}]/u.test(text)) lines.push(text);
+	}
+	return lines.join("\n");
+}
+function readSlide(files, path) {
+	const doc = parseXml(files, path, "slide");
+	if (doc === void 0) return { blocks: [] };
+	const rels = relationshipsOf(files, path);
+	const blocks = [];
+	for (const tree of Array.from(doc.getElementsByTagNameNS(PRESENTATION_NS, "spTree"))) for (const shape of Array.from(tree.children)) {
+		const text = textOf$1(shape);
+		if (text !== "") blocks.push({
+			kind: "text",
+			text
+		});
+	}
+	for (const target of rels.values()) {
+		if (!target.startsWith("ppt/media/")) continue;
+		const bytes = files.get(target);
+		if (bytes === void 0) continue;
+		blocks.push(imageBlockOf(target, () => toBase64$1(bytes)));
+	}
+	const notes = notesOf(files, rels);
+	if (notes !== "") blocks.push({
+		kind: "text",
+		text: `Speaker notes: ${notes}`
+	});
+	return { blocks };
+}
+/** @experimental */
+function createPptxBlockReader() {
+	return { read: readPptxBlocks };
+}
+/**
+* @throws WebSkillError 归档损坏、缺 `ppt/presentation.xml`、XML 解析失败
+* @experimental
+*/
+async function readPptxBlocks(bytes) {
+	const files = new Map(await unzipWithLimits(bytes));
+	if (!files.has(PRESENTATION)) throw new WebSkillError("TOOL_EXECUTION_FAILED", `This file is not a PowerPoint presentation: it has no ${PRESENTATION} entry.`);
+	return { slides: slideOrder(files).map((path) => readSlide(files, path)) };
+}
+
+//#endregion
+//#region ../browser/src/document/pptx.ts
+/**
+* pptx 正文抽取（0.22.0 分册 18）。
+*
+* 与 `readPptxBlocks` 同源：文本形态只是把逐页的文本块按放映顺序拼起来，
+* 两条路给出的文字因此**永远一致**——同一份文稿不会因为走哪条路而多出或少掉一段。
+*
+* ⚠️ 与 docx/xlsx 一样依赖 `DOMParser`，所以只在 `@webskill/browser`。
+*/
+/**
+* **不抽取**的内容，逐条写明而不是笼统说「尽力而为」：
+* 版式、动画、切换效果、母版与版式上的模板文字、图表的底层数据。
+*
+* 插图不在此列但也不在文本里：图要按页取，走 `read_document`。
+*/
+const PPTX_UNEXTRACTED = [
+	"layout and positioning",
+	"animations and transitions",
+	"master and layout placeholders",
+	"chart source data",
+	"pictures"
+];
+/** 抽不出任何文字时的占位，与 docx/xlsx 同款口径 @experimental */
+const PPTX_UNEXTRACTED_NOTICE = "This presentation has no extractable text: its slides are most likely pictures. Use read_document to look at them.";
+/**
+* @throws WebSkillError 归档损坏、缺 `ppt/presentation.xml`、XML 解析失败
+* @experimental
+*/
+async function extractPptxText(bytes) {
+	const { slides } = await readPptxBlocks(bytes);
+	const pages = [];
+	slides.forEach((slide, index) => {
+		const text = slide.blocks.filter((block) => block.kind === "text").map((block) => block.text).join("\n");
+		if (text.trim() !== "") pages.push(`--- Slide ${index + 1} ---\n${text}`);
+	});
+	return pages.length === 0 ? PPTX_UNEXTRACTED_NOTICE : pages.join("\n\n");
+}
+
+//#endregion
+//#region ../browser/src/document/ooxmlPart.ts
+/**
+* OOXML 包的拆装地基（0.22.0 分册 42 · 设计 43 §1.1、§1.7）。
+*
+* 这一册的整条路子是「解开模板 zip，只改承载数据的那几个部件，其余字节原样写回」。
+* 地基只做三件事，xlsx 与 docx 两侧都走它，谁都不许自己碰 XML 声明。
+*/
+const CONTENT_TYPES = "[Content_Types].xml";
+const XML_DECLARATION = /^<\?xml[^?]*\?>\r?\n?/;
+/**
+* 切下 XML 声明。
+*
+* 设计 43 §1.1 实测：jsdom 的 `XMLSerializer` 丢掉声明，Chromium 保留它却吃掉结尾的 `\r\n`。
+* 两个引擎两种错法，而且只有在真实浏览器里才会碰到第二种——所以声明必须在解析前切下来留着，
+* 序列化之后把**原始那几个字节**原样拼回去，任何路径都不读序列化器吐出来的前言。
+*/
+function splitXmlDeclaration(text) {
+	const declaration = XML_DECLARATION.exec(text)?.[0] ?? "";
+	return {
+		declaration,
+		body: text.slice(declaration.length)
+	};
+}
+/** @throws WebSkillError 该部件不存在或不是合法 XML */
+function parseXmlPart(pkg, path) {
+	const bytes = pkg.get(path);
+	if (bytes === void 0) throw new WebSkillError("TEMPLATE_UNSUPPORTED", `The template package has no ${path} part.`);
+	const { declaration, body } = splitXmlDeclaration(new TextDecoder().decode(bytes));
+	const doc = new DOMParser().parseFromString(body, "application/xml");
+	if (doc.getElementsByTagName("parsererror").length > 0) throw new WebSkillError("TEMPLATE_UNSUPPORTED", `The ${path} part of the template is not well-formed XML.`);
+	return {
+		declaration,
+		doc
+	};
+}
+/** 序列化并把原始声明原样拼回（见 {@link splitXmlDeclaration}）。 */
+function serializeXmlPart(declaration, doc) {
+	const { body } = splitXmlDeclaration(new XMLSerializer().serializeToString(doc));
+	return new TextEncoder().encode(declaration + body);
+}
+/** @throws WebSkillError 归档损坏，或不是 OOXML（缺 `[Content_Types].xml`） */
+async function readOoxmlPackage(bytes) {
+	const entries = await unzipWithLimits(bytes);
+	const pkg = new Map(entries.filter(([path]) => !path.endsWith("/")));
+	if (!pkg.has(CONTENT_TYPES)) throw new WebSkillError("TEMPLATE_UNSUPPORTED", `This file is not an Office Open XML document: it has no ${CONTENT_TYPES} entry.`);
+	return pkg;
+}
+function writeOoxmlPackage(pkg) {
+	return zipSync(Object.fromEntries(pkg), { level: 6 });
+}
+/** `../media/x.png` 这种相对 Target 按所在目录归一化 */
+function resolveRelative(baseDir, target) {
+	if (target.startsWith("/")) return target.slice(1);
+	const out = [];
+	for (const segment of [...baseDir.split("/"), ...target.split("/")]) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") out.pop();
+		else out.push(segment);
+	}
+	return out.join("/");
+}
+const extensionOf = (path) => {
+	const dot = path.lastIndexOf(".");
+	return dot < 0 ? "" : path.slice(dot + 1).toLowerCase();
+};
+/**
+* 结构自检（AC-42.27）。
+*
+* 「打开不提示修复」没法进 CI（本仓没有可脚本化的 Office 实现，见设计 10 §6.2），
+* 但迄今实测出的坏文件成因都是结构性的：悬空关系、没登记的扩展名、解析不了的部件。
+* 这三条能当场查出来，所以每次重封之前都查一遍。
+*
+* @returns 英文问题描述，空数组表示干净
+*/
+function auditOoxmlPackage(pkg) {
+	const problems = [];
+	const contentTypes = pkg.get(CONTENT_TYPES);
+	if (contentTypes === void 0) return [`missing ${CONTENT_TYPES}`];
+	const types = new TextDecoder().decode(contentTypes);
+	const defaults = new Set([...types.matchAll(/<Default\s+Extension="([^"]+)"/g)].map((match) => (match[1] ?? "").toLowerCase()));
+	const overrides = new Set([...types.matchAll(/<Override\s+PartName="([^"]+)"/g)].map((match) => match[1]));
+	for (const path of pkg.keys()) {
+		if (path === CONTENT_TYPES) continue;
+		if (!defaults.has(extensionOf(path)) && !overrides.has(`/${path}`)) problems.push(`part is not covered by [Content_Types].xml: ${path}`);
+	}
+	for (const [path, bytes] of pkg) {
+		if (!path.endsWith(".rels")) continue;
+		const relsDir = path.slice(0, path.lastIndexOf("_rels/"));
+		for (const match of new TextDecoder().decode(bytes).matchAll(/<Relationship\s[^>]*>/g)) {
+			const tag = match[0];
+			if (/TargetMode="External"/.test(tag)) continue;
+			const target = /Target="([^"]+)"/.exec(tag)?.[1];
+			if (target === void 0 || /^[a-z]+:/i.test(target)) continue;
+			const resolved = resolveRelative(relsDir, decodeURIComponent(target));
+			if (!pkg.has(resolved)) problems.push(`dangling relationship in ${path}: ${target}`);
+		}
+	}
+	for (const [path, bytes] of pkg) {
+		if (extensionOf(path) !== "xml" && !path.endsWith(".rels")) continue;
+		const { body } = splitXmlDeclaration(new TextDecoder().decode(bytes));
+		if (new DOMParser().parseFromString(body, "application/xml").getElementsByTagName("parsererror").length > 0) problems.push(`part is not well-formed XML: ${path}`);
+	}
+	return problems;
+}
+/** @throws WebSkillError 自检不干净——宁可当场失败，也不要交一个会弹修复的文件 */
+function assertOoxmlPackage(pkg) {
+	const problems = auditOoxmlPackage(pkg);
+	if (problems.length > 0) throw new WebSkillError("TOOL_EXECUTION_FAILED", `The generated Office file would be structurally invalid: ${problems.join("; ")}.`);
+}
+/**
+* 往 `[Content_Types].xml` 补一条 `<Default Extension>`，已有则原样返回。
+*
+* 插图时必须补（AC-42.18 只允许这一处变化）；不插图时一个字节都不能动（FR-42.20）。
+*/
+function ensureDefaultExtension(pkg, extension, contentType) {
+	const bytes = pkg.get(CONTENT_TYPES);
+	if (bytes === void 0) return;
+	const text = new TextDecoder().decode(bytes);
+	if (new RegExp(`<Default\\s+Extension="${extension}"`, "i").test(text)) return;
+	const { declaration, body } = splitXmlDeclaration(text);
+	const inserted = body.replace("<Default", `<Default Extension="${extension}" ContentType="${contentType}"/><Default`);
+	pkg.set(CONTENT_TYPES, new TextEncoder().encode(declaration + inserted));
+}
+/** 往 `[Content_Types].xml` 补一条 `<Override PartName>`，已有则原样返回。 */
+function ensureOverride(pkg, partName, contentType) {
+	const bytes = pkg.get(CONTENT_TYPES);
+	if (bytes === void 0) return;
+	const text = new TextDecoder().decode(bytes);
+	if (text.includes(`PartName="${partName}"`)) return;
+	const { declaration, body } = splitXmlDeclaration(text);
+	const inserted = body.replace("</Types>", `<Override PartName="${partName}" ContentType="${contentType}"/></Types>`);
+	pkg.set(CONTENT_TYPES, new TextEncoder().encode(declaration + inserted));
+}
+/** 摘掉一个部件连同它在 `[Content_Types].xml` 与指定 rels 里的登记（FR-42.4 修订项）。 */
+function dropPart(pkg, partName, relsPath) {
+	if (!pkg.delete(partName)) return;
+	const fileName = partName.slice(partName.lastIndexOf("/") + 1);
+	const types = pkg.get(CONTENT_TYPES);
+	if (types !== void 0) {
+		const { declaration, body } = splitXmlDeclaration(new TextDecoder().decode(types));
+		const stripped = body.replace(new RegExp(`<Override\\s+PartName="/${partName}"[^>]*/>`), "");
+		pkg.set(CONTENT_TYPES, new TextEncoder().encode(declaration + stripped));
+	}
+	const rels = pkg.get(relsPath);
+	if (rels !== void 0) {
+		const { declaration, body } = splitXmlDeclaration(new TextDecoder().decode(rels));
+		const stripped = body.replace(new RegExp(`<Relationship\\s[^>]*Target="[^"]*${fileName}"[^>]*/>`), "");
+		pkg.set(relsPath, new TextEncoder().encode(declaration + stripped));
+	}
+}
+/** VBA 工程部件的 content type 前缀。宏的判据看这个，不看文件路径。 */
+const VBA_CONTENT_TYPE = "application/vnd.ms-office.vbaProject";
+/** macroEnabled 的主部件 content type → 对应的非宏值（0.23.0 分册 25 设计 26 §3.1）。 */
+const NON_MACRO_MAIN_TYPE = /* @__PURE__ */ new Map([
+	["application/vnd.ms-excel.sheet.macroEnabled.main+xml", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"],
+	["application/vnd.ms-excel.template.macroEnabled.main+xml", "application/vnd.openxmlformats-officedocument.spreadsheetml.template.main+xml"],
+	["application/vnd.ms-word.document.macroEnabled.main+xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"],
+	["application/vnd.ms-word.template.macroEnabled.main+xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.template.main+xml"]
+]);
+const attributeOf = (tag, name) => new RegExp(`${name}="([^"]*)"`).exec(tag)?.[1] ?? "";
+/**
+* 把宏痕迹从包里摘干净（0.23.0 分册 25 · FR-25.4）。
+*
+* 我们填完模板交出去的文件叫 `.xlsx` / `.docx`，声明的也是非宏 MIME。如果里面还留着
+* macroEnabled 的 content type 或 `vbaProject.bin`，文件就自相矛盾，Excel 会拒绝打开。
+* 宿主报来的那类文件更极端：`vbaProject.bin` 本身已经损坏或丢失，只剩标记——所以判据是
+* **`[Content_Types].xml` 里的登记**，不是「包里有没有那个部件」。
+*
+* 不是宏包时**一个字节都不改**（FR-25.5）：无条件重写 `[Content_Types].xml` 会动到属性顺序
+* 和空白，非宏模板的产物字节就跟着变了。所以第一件事是判断，不中就原样返回。
+*/
+function stripMacros(pkg) {
+	const typesBytes = pkg.get(CONTENT_TYPES);
+	if (typesBytes === void 0) return;
+	const text = new TextDecoder().decode(typesBytes);
+	if (!text.includes(VBA_CONTENT_TYPE) && !text.includes("macroEnabled.main+xml")) return;
+	const { declaration, body } = splitXmlDeclaration(text);
+	let rewritten = body;
+	for (const match of body.matchAll(/<Override\s[^>]*\/>/g)) {
+		const tag = match[0];
+		const contentType = attributeOf(tag, "ContentType");
+		if (contentType.startsWith(VBA_CONTENT_TYPE)) {
+			pkg.delete(attributeOf(tag, "PartName").replace(/^\//, ""));
+			rewritten = rewritten.replace(tag, "");
+			continue;
+		}
+		const replacement = NON_MACRO_MAIN_TYPE.get(contentType);
+		if (replacement !== void 0) rewritten = rewritten.replace(tag, tag.replace(contentType, replacement));
+	}
+	pkg.set(CONTENT_TYPES, new TextEncoder().encode(declaration + rewritten));
+	for (const [path, bytes] of pkg) {
+		if (!path.endsWith(".rels")) continue;
+		const split = splitXmlDeclaration(new TextDecoder().decode(bytes));
+		let strippedRels = split.body;
+		for (const match of split.body.matchAll(/<Relationship\s[^>]*\/>/g)) if (attributeOf(match[0], "Type").includes("/vbaProject")) strippedRels = strippedRels.replace(match[0], "");
+		if (strippedRels !== split.body) pkg.set(path, new TextEncoder().encode(split.declaration + strippedRels));
+	}
+}
+
+//#endregion
+//#region ../browser/src/document/xlsxTemplate.ts
+/**
+* 照着 xlsx 模板出新文件（0.22.0 分册 42 · 设计 43 §4）。
+*
+* 不从零生成，而是解开模板 zip 只改 `sheet*.xml`，其余字节原样写回。
+* 模板里的空单元格本来就是带样式索引的空壳 `<c r="B3" s="6"/>`，
+* 所以「填值保格式」不是要实现的特性，是不要破坏的既有事实（设计 43 §1.2）。
+*/
+const MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+const REL_NS$1 = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const PACKAGE_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships";
+const DRAWING_NS = "http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing";
+const DRAWING_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.drawing+xml";
+const DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\r\n";
+const byTag$1 = (scope, name) => [...scope.getElementsByTagNameNS("*", name)];
+/** 工作表名 → 部件路径。名字来自 workbook.xml，路径要经 rels 绕一道。 */
+function listSheets(pkg) {
+	const { doc } = parseXmlPart(pkg, "xl/workbook.xml");
+	const { doc: relsDoc } = parseXmlPart(pkg, "xl/_rels/workbook.xml.rels");
+	const targets = /* @__PURE__ */ new Map();
+	for (const rel of byTag$1(relsDoc, "Relationship")) {
+		const id = rel.getAttribute("Id");
+		const target = rel.getAttribute("Target");
+		if (id !== null && target !== null) targets.set(id, target.startsWith("/") ? target.slice(1) : `xl/${target}`);
+	}
+	const sheets = [];
+	for (const sheet of byTag$1(doc, "sheet")) {
+		const name = sheet.getAttribute("name");
+		const id = sheet.getAttributeNS(REL_NS$1, "id") ?? sheet.getAttribute("r:id");
+		const path = id === null ? void 0 : targets.get(id);
+		if (name !== null && path !== void 0) sheets.push({
+			name,
+			path
+		});
+	}
+	return sheets;
+}
+/** @throws WebSkillError 模板里没有这个工作表 */
+function resolveSheet(sheets, name) {
+	if (name === void 0) {
+		const first = sheets[0];
+		if (first === void 0) throw new WebSkillError("TEMPLATE_UNSUPPORTED", "The template has no worksheet.");
+		return first;
+	}
+	const found = sheets.find((sheet) => sheet.name === name);
+	if (found === void 0) throw new WebSkillError("TEMPLATE_TARGET_MISSING", `The template has no sheet named "${name}". Available sheets: ${sheets.map((s) => s.name).join(", ")}.`);
+	return found;
+}
+function sharedStringsOf(pkg) {
+	if (!pkg.has("xl/sharedStrings.xml")) return [];
+	const { doc } = parseXmlPart(pkg, "xl/sharedStrings.xml");
+	return byTag$1(doc, "si").map((si) => byTag$1(si, "t").map((node) => node.textContent ?? "").join(""));
+}
+function cellText(cell, shared) {
+	const type = cell.getAttribute("t");
+	if (type === "inlineStr") return byTag$1(cell, "t").map((node) => node.textContent ?? "").join("");
+	const value = byTag$1(cell, "v")[0]?.textContent ?? "";
+	if (type === "s") {
+		const index = Number(value);
+		return Number.isInteger(index) ? shared[index] ?? "" : "";
+	}
+	return value;
+}
+/** 共享公式的宿主：`si` → 公式体与宿主所在行 */
+function sharedFormulaHosts(doc) {
+	const hosts = /* @__PURE__ */ new Map();
+	for (const formula of byTag$1(doc, "f")) {
+		const si = formula.getAttribute("si");
+		const body = formula.textContent ?? "";
+		if (si === null || body === "") continue;
+		const address = formula.parentElement?.getAttribute("r");
+		if (address === null || address === void 0) continue;
+		hosts.set(si, {
+			body,
+			row: parseCellAddress(address).row
+		});
+	}
+	return hosts;
+}
+/** 共享公式的引用格本身不带公式体，按行差从宿主展开，模型才知道它读的是哪几格 */
+function formulaTextOf(cell, hosts) {
+	const formula = [...cell.children].find((child) => child.localName === "f");
+	if (formula === void 0) return void 0;
+	const body = formula.textContent ?? "";
+	if (body !== "") return body;
+	const host = hosts.get(formula.getAttribute("si") ?? "");
+	const address = cell.getAttribute("r");
+	if (host === void 0 || address === null) return "";
+	return offsetFormulaRows(host.body, parseCellAddress(address).row - host.row);
+}
+/** 读带坐标的骨架（FR-42.1）。模型据此决定往哪儿写。 */
+async function readXlsxTemplate(bytes) {
+	const pkg = await readOoxmlPackage(bytes);
+	const shared = sharedStringsOf(pkg);
+	const sheets = [];
+	for (const entry of listSheets(pkg)) {
+		const { doc } = parseXmlPart(pkg, entry.path);
+		const hosts = sharedFormulaHosts(doc);
+		const cells = [];
+		for (const cell of byTag$1(doc, "c")) {
+			const address = cell.getAttribute("r");
+			if (address === null) continue;
+			const text = cellText(cell, shared);
+			const formula = formulaTextOf(cell, hosts);
+			if (formula !== void 0) cells.push({
+				address,
+				text,
+				formula
+			});
+			else if (text !== "") cells.push({
+				address,
+				text
+			});
+		}
+		const columnWidths = [];
+		for (const col of byTag$1(doc, "col")) {
+			const min = Number(col.getAttribute("min"));
+			const max = Number(col.getAttribute("max"));
+			const width = Number(col.getAttribute("width"));
+			if (!Number.isInteger(min) || !Number.isInteger(max) || !Number.isFinite(width)) continue;
+			for (let index = min; index <= max; index += 1) columnWidths[index - 1] = width;
+		}
+		sheets.push({
+			name: entry.name,
+			range: byTag$1(doc, "dimension")[0]?.getAttribute("ref") ?? "",
+			cells,
+			merges: byTag$1(doc, "mergeCell").map((merge) => merge.getAttribute("ref")).filter((ref) => ref !== null),
+			columnWidths
+		});
+	}
+	return { sheets };
+}
+const rowNumberOf = (element) => Number(element.getAttribute("r") ?? NaN);
+function rowsOf(doc) {
+	const sheetData = byTag$1(doc, "sheetData")[0];
+	return sheetData === void 0 ? [] : [...sheetData.children].filter((node) => node.localName === "row");
+}
+/** 把一个元素上的行号整体平移：`<row r>` 与其中每个 `<c r>` */
+function shiftRow(row, delta) {
+	const next = rowNumberOf(row) + delta;
+	row.setAttribute("r", String(next));
+	for (const cell of byTag$1(row, "c")) {
+		const address = cell.getAttribute("r");
+		if (address === null) continue;
+		const parsed = parseCellAddress(address);
+		cell.setAttribute("r", formatCellAddress({
+			column: parsed.column,
+			row: next - 1
+		}));
+	}
+}
+const shiftAddress = (address, at, count) => {
+	const parsed = parseCellAddress(address);
+	return parsed.row + 1 >= at ? formatCellAddress({
+		...parsed,
+		row: parsed.row + count
+	}) : address;
+};
+/**
+* 插行（FR-42.7）。设计 43 §1.5 实测：必须同时改六处，少动一处就是一个会弹修复的文件。
+*
+* @throws WebSkillError 插入位置越界
+*/
+function insertRows(pkg, doc, insert) {
+	const { at, count } = insert;
+	const rows = rowsOf(doc);
+	const lastRow = rows[rows.length - 1];
+	const last = lastRow === void 0 ? 0 : rowNumberOf(lastRow);
+	if (!Number.isInteger(at) || at < 2 || at > last + 1 || !Number.isInteger(count) || count < 1) throw new WebSkillError("TEMPLATE_ROW_INSERT_RANGE", `Cannot insert ${count} row(s) at row ${at}: the sheet has rows 1..${last}.`);
+	const styleRowNumber = insert.copyStyleFrom ?? at - 1;
+	const template = rows.find((row) => rowNumberOf(row) === styleRowNumber);
+	if (template === void 0) throw new WebSkillError("TEMPLATE_ROW_INSERT_RANGE", `Cannot copy style from row ${styleRowNumber}: that row does not exist in the sheet.`);
+	const formulas = formulasOf(template);
+	for (const row of [...rows].reverse()) if (rowNumberOf(row) >= at) shiftRow(row, count);
+	const sheetData = byTag$1(doc, "sheetData")[0];
+	const anchor = rowsOf(doc).find((row) => rowNumberOf(row) >= at + count) ?? null;
+	const made = [];
+	for (let index = 0; index < count; index += 1) {
+		const row = template.cloneNode(true);
+		row.setAttribute("r", String(at + index));
+		for (const cell of byTag$1(row, "c")) {
+			const address = cell.getAttribute("r");
+			if (address !== null) {
+				const parsed = parseCellAddress(address);
+				cell.setAttribute("r", formatCellAddress({
+					column: parsed.column,
+					row: at + index - 1
+				}));
+			}
+			cell.removeAttribute("t");
+			while (cell.firstChild !== null) cell.removeChild(cell.firstChild);
+		}
+		sheetData?.insertBefore(row, anchor);
+		made.push(row);
+	}
+	for (const formula of byTag$1(doc, "f")) {
+		const ref = formula.getAttribute("ref");
+		if (ref !== null) formula.setAttribute("ref", growRange(ref, at, count));
+		const body = formula.textContent;
+		if (body !== null && body !== "") formula.textContent = growFormulaRanges(body, at, count);
+	}
+	for (const merge of byTag$1(doc, "mergeCell")) {
+		const ref = merge.getAttribute("ref");
+		if (ref === null) continue;
+		const [from = "", to] = ref.split(":");
+		merge.setAttribute("ref", to === void 0 ? shiftAddress(from, at, count) : `${shiftAddress(from, at, count)}:${shiftAddress(to, at, count)}`);
+	}
+	const dimension = byTag$1(doc, "dimension")[0];
+	const dimensionRef = dimension?.getAttribute("ref");
+	if (dimension !== void 0 && dimensionRef != null) dimension.setAttribute("ref", growRange(dimensionRef, at, count));
+	dropPart(pkg, "xl/calcChain.xml", "xl/_rels/workbook.xml.rels");
+	for (const [index, row] of made.entries()) restoreFormulas(row, formulas, at + index - styleRowNumber);
+}
+/**
+* 记下一行里每个格的 `<f>`。
+*
+* 共享公式宿主（带 `ref`）不能被复制成第二个宿主——同一个 `si` 只许一个宿主，
+* 多一个 Excel 就报损坏。复制出来的一律降级成引用：`<f t="shared" si="0"/>`。
+*/
+function formulasOf(row) {
+	const copied = [];
+	for (const cell of byTag$1(row, "c")) {
+		const address = cell.getAttribute("r");
+		const formula = [...cell.children].find((child) => child.localName === "f");
+		if (address === null || formula === void 0) continue;
+		const host = formula.getAttribute("ref") !== null;
+		const value = [...cell.children].find((child) => child.localName === "v");
+		copied.push({
+			column: parseCellAddress(address).column,
+			attributes: [...formula.attributes].filter((attribute) => attribute.name !== "ref").map((attribute) => [attribute.name, attribute.value]),
+			body: host || formula.getAttribute("t") === "shared" ? "" : formula.textContent ?? "",
+			cached: value?.textContent ?? void 0,
+			type: cell.getAttribute("t") ?? void 0
+		});
+	}
+	return copied;
+}
+function restoreFormulas(row, formulas, delta) {
+	if (formulas.length === 0) return;
+	const byColumn = new Map(byTag$1(row, "c").map((cell) => [parseCellAddress(cell.getAttribute("r") ?? "A1").column, cell]));
+	for (const formula of formulas) {
+		const cell = byColumn.get(formula.column);
+		if (cell === void 0) continue;
+		const doc = row.ownerDocument;
+		const made = doc.createElementNS(MAIN_NS, "f");
+		for (const [name, value] of formula.attributes) made.setAttribute(name, value);
+		if (formula.body !== "") made.textContent = offsetFormulaRows(formula.body, delta);
+		cell.appendChild(made);
+		if (formula.cached === void 0) continue;
+		if (formula.type !== void 0) cell.setAttribute("t", formula.type);
+		const value = doc.createElementNS(MAIN_NS, "v");
+		value.textContent = formula.cached;
+		cell.appendChild(value);
+	}
+}
+/** 公式里的相对行引用按行差重写，`$12` 这种绝对行原样不动——就是 Excel 向下填充的语义 */
+const RELATIVE_ROW = /(\$?[A-Z]{1,3})(\$?)([1-9][0-9]*)/g;
+function offsetFormulaRows(body, delta) {
+	return body.replace(RELATIVE_ROW, (match, column, absolute, row) => absolute === "$" ? match : `${column}${Math.max(1, Number(row) + delta)}`);
+}
+/** 区间的下界在插入点之后才平移，上界只要不在插入点之前就跟着长 */
+function growRange(ref, at, count) {
+	const [from = "", to] = ref.split(":");
+	if (to === void 0) return shiftAddress(from, at, count);
+	const start = parseCellAddress(from);
+	const end = parseCellAddress(to);
+	const nextStart = start.row + 1 >= at ? {
+		...start,
+		row: start.row + count
+	} : start;
+	const nextEnd = end.row + 1 >= at - 1 ? {
+		...end,
+		row: end.row + count
+	} : end;
+	return `${formatCellAddress(nextStart)}:${formatCellAddress(nextEnd)}`;
+}
+const RANGE_IN_FORMULA = /\$?([A-Z]{1,3})\$?([1-9][0-9]*):\$?([A-Z]{1,3})\$?([1-9][0-9]*)/g;
+/** `SUM(G6:G12)` → `SUM(G6:G25)`：公式里的区间同样要跟着长 */
+function growFormulaRanges(formula, at, count) {
+	return formula.replace(RANGE_IN_FORMULA, (whole, startCol, startRow, endCol, endRow) => {
+		const start = Number(startRow);
+		const end = Number(endRow);
+		const nextStart = start >= at ? start + count : start;
+		const nextEnd = end >= at - 1 ? end + count : end;
+		return nextStart === start && nextEnd === end ? whole : `${startCol}${nextStart}:${endCol}${nextEnd}`;
+	});
+}
+/**
+* 写值（FR-42.5）。数字写成数字，其余写成文本，不做类型推断（FR-42.26）。
+*
+* 用 `inlineStr` 而不是往共享串表追加：改动的数据部件从两个降到一个（设计 43 §1.4）。
+* 单元格有三种形态（空壳 / 带值 / 不存在），三支都显式处理——静默跳过正是 FR-42.6 要禁的。
+*
+* @throws WebSkillError 目标格是公式格
+*/
+function fillCell(doc, address, value) {
+	const parsed = parseCellAddress(address);
+	const normalized = formatCellAddress(parsed);
+	const row = rowsOf(doc).find((candidate) => rowNumberOf(candidate) === parsed.row + 1) ?? createRow(doc, parsed.row + 1);
+	let cell = byTag$1(row, "c").find((candidate) => candidate.getAttribute("r") === normalized);
+	if (cell === void 0) cell = createCell(doc, row, parsed.column, normalized);
+	const formula = [...cell.children].find((child) => child.localName === "f");
+	if (formula !== void 0) {
+		const body = formula.textContent ?? "";
+		throw new WebSkillError("TEMPLATE_CELL_IS_FORMULA", `Cell ${normalized} is computed by the template${body === "" ? "" : ` (=${body})`} and must not be overwritten. Fill the cells it reads instead; the template works this one out when the file is opened.`);
+	}
+	while (cell.firstChild !== null) cell.removeChild(cell.firstChild);
+	if (value === "") {
+		cell.removeAttribute("t");
+		return;
+	}
+	if (looksNumeric(value)) {
+		cell.removeAttribute("t");
+		const v = doc.createElementNS(MAIN_NS, "v");
+		v.textContent = value;
+		cell.appendChild(v);
+		return;
+	}
+	cell.setAttribute("t", "inlineStr");
+	const is = doc.createElementNS(MAIN_NS, "is");
+	const t = doc.createElementNS(MAIN_NS, "t");
+	if (value !== value.trim()) t.setAttribute("xml:space", "preserve");
+	t.textContent = value;
+	is.appendChild(t);
+	cell.appendChild(is);
+}
+/**
+* 只有**原样往返**的才算数字：`Number(x)` 转回字符串必须与原文逐字符相同。
+*
+* 这一条同时挡住了 `"0123"`（编号、身份证、电话）与 `" 12 "`（带空白的文本），
+* 它们转回来分别是 `"123"` 和 `"12"`，与原文不同，所以仍然写成文本（AC-42.9）。
+*/
+function looksNumeric(value) {
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && String(parsed) === value;
+}
+/** 新建节点必须用 createElementNS：在有默认命名空间的文档里 createElement 会带出 `xmlns=""`，Excel 拒收 */
+function createRow(doc, rowNumber) {
+	const sheetData = byTag$1(doc, "sheetData")[0];
+	if (sheetData === void 0) throw new WebSkillError("TEMPLATE_UNSUPPORTED", "The worksheet part has no sheetData element.");
+	const row = doc.createElementNS(MAIN_NS, "row");
+	row.setAttribute("r", String(rowNumber));
+	const anchor = rowsOf(doc).find((candidate) => rowNumberOf(candidate) > rowNumber) ?? null;
+	sheetData.insertBefore(row, anchor);
+	return row;
+}
+function createCell(doc, row, column, address) {
+	const cell = doc.createElementNS(MAIN_NS, "c");
+	cell.setAttribute("r", address);
+	const anchor = byTag$1(row, "c").find((candidate) => {
+		const other = candidate.getAttribute("r");
+		return other !== null && parseCellAddress(other).column > column;
+	}) ?? null;
+	row.insertBefore(cell, anchor);
+	return cell;
+}
+function geometryOf(doc) {
+	const columnWidths = [];
+	for (const col of byTag$1(doc, "col")) {
+		const min = Number(col.getAttribute("min"));
+		const max = Number(col.getAttribute("max"));
+		const width = Number(col.getAttribute("width"));
+		if (!Number.isInteger(min) || !Number.isInteger(max) || !Number.isFinite(width)) continue;
+		for (let index = min; index <= max; index += 1) columnWidths[index - 1] = width;
+	}
+	const rowHeights = /* @__PURE__ */ new Map();
+	for (const row of rowsOf(doc)) {
+		const height = Number(row.getAttribute("ht"));
+		if (Number.isFinite(height)) rowHeights.set(rowNumberOf(row), height);
+	}
+	return {
+		columnWidths,
+		rowHeights,
+		defaultRowHeight: Number(byTag$1(doc, "sheetFormatPr")[0]?.getAttribute("defaultRowHeight") ?? 15),
+		merges: byTag$1(doc, "mergeCell").map((merge) => merge.getAttribute("ref")).filter((ref) => ref !== null)
+	};
+}
+const DEFAULT_COLUMN_WIDTH = 8.43;
+/** 锚格所在的框。落在合并区左上角时按整个合并区算（FR-42.11）。 */
+function anchorBox(geometry, address) {
+	const cell = parseCellAddress(address);
+	let lastColumn = cell.column;
+	let lastRow = cell.row;
+	for (const ref of geometry.merges) {
+		const range = parseCellRange(ref);
+		if (range.start.column === cell.column && range.start.row === cell.row) {
+			lastColumn = range.end.column;
+			lastRow = range.end.row;
+			break;
+		}
+	}
+	let width = 0;
+	for (let column = cell.column; column <= lastColumn; column += 1) width += columnWidthToPixels(geometry.columnWidths[column] ?? DEFAULT_COLUMN_WIDTH) * EMU_PER_PIXEL;
+	let height = 0;
+	for (let row = cell.row; row <= lastRow; row += 1) height += (geometry.rowHeights.get(row + 1) ?? geometry.defaultRowHeight) * EMU_PER_POINT;
+	return {
+		width,
+		height,
+		span: lastColumn - cell.column + 1
+	};
+}
+function xmlPart(text) {
+	return new TextEncoder().encode(DECLARATION + text);
+}
+/** 给工作表装上 drawing 全家桶：drawing 部件、两条 rels、media、Content_Types 登记 */
+function attachImages(pkg, doc, sheetPath, images, geometry) {
+	if (images.length === 0) return;
+	const sheetFile = sheetPath.slice(sheetPath.lastIndexOf("/") + 1);
+	const sheetIndex = /(\d+)\.xml$/.exec(sheetFile)?.[1] ?? "1";
+	const drawingPath = `xl/drawings/drawing${sheetIndex}.xml`;
+	const anchors = [];
+	const drawingRels = [];
+	images.forEach((image, index) => {
+		const size = readImageSize(image.bytes);
+		if (size === void 0) throw new WebSkillError("TEMPLATE_IMAGE_UNRESOLVED", `The image for cell ${image.address} is not a PNG or JPEG file.`);
+		const mediaName = `image${index + 1}.${image.extension}`;
+		pkg.set(`xl/media/${mediaName}`, image.bytes);
+		ensureDefaultExtension(pkg, image.extension, image.contentType);
+		drawingRels.push(`<Relationship Id="rIdImg${index + 1}" Type="${REL_NS$1}/image" Target="../media/${mediaName}"/>`);
+		const box = anchorBox(geometry, image.address);
+		const fitted = fitWithin({
+			width: size.width * EMU_PER_PIXEL,
+			height: size.height * EMU_PER_PIXEL
+		}, box);
+		const cell = parseCellAddress(image.address);
+		const id = index + 1;
+		anchors.push(`<xdr:oneCellAnchor><xdr:from><xdr:col>${cell.column}</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>${cell.row}</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:from><xdr:ext cx="${fitted.width}" cy="${fitted.height}"/><xdr:pic><xdr:nvPicPr><xdr:cNvPr id="${id}" name="Picture ${id}"/><xdr:cNvPicPr><a:picLocks noChangeAspect="1"/></xdr:cNvPicPr></xdr:nvPicPr><xdr:blipFill><a:blip xmlns:r="${REL_NS$1}" r:embed="rIdImg${id}"/><a:stretch><a:fillRect/></a:stretch></xdr:blipFill><xdr:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${fitted.width}" cy="${fitted.height}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></xdr:spPr></xdr:pic><xdr:clientData/></xdr:oneCellAnchor>`);
+	});
+	pkg.set(drawingPath, xmlPart(`<xdr:wsDr xmlns:xdr="${DRAWING_NS}" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">${anchors.join("")}</xdr:wsDr>`));
+	pkg.set(`xl/drawings/_rels/drawing${sheetIndex}.xml.rels`, xmlPart(`<Relationships xmlns="${PACKAGE_REL_NS}">${drawingRels.join("")}</Relationships>`));
+	ensureOverride(pkg, `/${drawingPath}`, DRAWING_CONTENT_TYPE);
+	const relId = addSheetRelationship(pkg, `xl/worksheets/_rels/${sheetFile}.rels`, `${REL_NS$1}/drawing`, `../drawings/drawing${sheetIndex}.xml`);
+	const existing = byTag$1(doc, "drawing")[0];
+	if (existing !== void 0) existing.setAttributeNS(REL_NS$1, "r:id", relId);
+	else {
+		const drawing = doc.createElementNS(MAIN_NS, "drawing");
+		drawing.setAttributeNS(REL_NS$1, "r:id", relId);
+		doc.documentElement.appendChild(drawing);
+	}
+}
+/** 工作表的 rels 可能整个不存在（工作面移交表就没有），缺了就建 */
+function addSheetRelationship(pkg, relsPath, type, target) {
+	const existing = pkg.get(relsPath);
+	if (existing === void 0) {
+		pkg.set(relsPath, xmlPart(`<Relationships xmlns="${PACKAGE_REL_NS}"><Relationship Id="rIdDrawing" Type="${type}" Target="${target}"/></Relationships>`));
+		return "rIdDrawing";
+	}
+	const text = new TextDecoder().decode(existing);
+	const already = new RegExp(`<Relationship[^>]*Target="${target.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"[^>]*/>`).exec(text);
+	if (already !== null) return /Id="([^"]+)"/.exec(already[0])?.[1] ?? "rIdDrawing";
+	const updated = text.replace("</Relationships>", `<Relationship Id="rIdDrawing" Type="${type}" Target="${target}"/></Relationships>`);
+	pkg.set(relsPath, new TextEncoder().encode(updated));
+	return "rIdDrawing";
+}
+/**
+* 照模板出新文件。
+*
+* 顺序是**先插行、后填值**：填值用的地址是插行之后的坐标，反过来会逼模型心算偏移。
+*
+* @throws WebSkillError 模板不是 xlsx、地址不合法、目标不存在、插行越界
+*/
+async function fillXlsxTemplate(bytes, spec) {
+	const pkg = await readOoxmlPackage(bytes);
+	const sheets = listSheets(pkg);
+	const touched = /* @__PURE__ */ new Map();
+	const partOf = (name) => {
+		const entry = resolveSheet(sheets, name);
+		const cached = touched.get(entry.path) ?? parseXmlPart(pkg, entry.path);
+		touched.set(entry.path, cached);
+		return {
+			entry,
+			...cached
+		};
+	};
+	for (const insert of spec.rows ?? []) {
+		const { doc } = partOf(insert.sheet);
+		insertRows(pkg, doc, insert);
+	}
+	for (const fill of spec.cells ?? []) {
+		const { doc } = partOf(fill.sheet);
+		fillCell(doc, fill.address, fill.value);
+	}
+	const bySheet = /* @__PURE__ */ new Map();
+	for (const image of spec.images ?? []) {
+		const { entry } = partOf(image.sheet);
+		bySheet.set(entry.path, [...bySheet.get(entry.path) ?? [], image]);
+	}
+	for (const [path, images] of bySheet) {
+		const cached = touched.get(path);
+		if (cached === void 0) continue;
+		attachImages(pkg, cached.doc, path, images, geometryOf(cached.doc));
+	}
+	if ([...touched.values()].some(({ doc }) => byTag$1(doc, "f").length > 0)) requestFullCalcOnLoad(pkg);
+	for (const [path, { declaration, doc }] of touched) pkg.set(path, serializeXmlPart(declaration, doc));
+	stripMacros(pkg);
+	assertOoxmlPackage(pkg);
+	return writeOoxmlPackage(pkg);
+}
+/** `<calcPr>` 在 CT_Workbook 的序列里排在这几个之后；追加到末尾会落到 `extLst` 后面，那是不合法的 */
+const BEFORE_CALC_PR = [
+	"sheets",
+	"functionGroups",
+	"externalReferences",
+	"definedNames"
+];
+/**
+* 让 Excel 打开时重算一遍（FR-42.27）。
+*
+* 公式格里存着上一次的计算结果。改了它依赖的那些格之后，这个结果就是错的，
+* 而 Excel 默认信任缓存——用户看到的是一张「明细都填好了、合计还是 0」的表，
+* 直到他随手双击一个格才恢复正常。只在动过的表里确实有公式时才写这一笔。
+*/
+function requestFullCalcOnLoad(pkg) {
+	const { declaration, doc } = parseXmlPart(pkg, "xl/workbook.xml");
+	const existing = byTag$1(doc, "calcPr")[0];
+	const calcPr = existing ?? doc.createElementNS(MAIN_NS, "calcPr");
+	calcPr.setAttribute("fullCalcOnLoad", "1");
+	if (existing === void 0) {
+		const workbook = doc.documentElement;
+		const after = [...workbook.children].filter((node) => BEFORE_CALC_PR.includes(node.localName)).pop();
+		workbook.insertBefore(calcPr, after?.nextSibling ?? null);
+	}
+	pkg.set("xl/workbook.xml", serializeXmlPart(declaration, doc));
+}
+
+//#endregion
+//#region ../browser/src/document/docxTemplate.ts
+/**
+* 照着 docx 模板出新文件（0.22.0 分册 42 · 设计 43 §5）。
+*
+* 与 xlsx 同一条路，结构还更简单：只有 `word/document.xml` 一个数据部件。
+* 保格式的办法也同构——改已有 run 的文字而不是重建 run，`<w:rPr>` 就自己活下来了。
+*/
+const WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+const REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const DOCUMENT = "word/document.xml";
+const DOCUMENT_RELS = "word/_rels/document.xml.rels";
+const byTag = (scope, name) => [...scope.getElementsByTagNameNS("*", name)];
+const childrenNamed = (scope, name) => [...scope.children].filter((node) => node.localName === name);
+/** 顶层表格（不含嵌套表），顺序即模型看到的表序 */
+function tablesOf(doc) {
+	const body = byTag(doc, "body")[0];
+	return body === void 0 ? [] : childrenNamed(body, "tbl");
+}
+/** 正文段落：只算 body 的直接子节点，表格内的段落不计入序号 */
+function paragraphsOf(doc) {
+	const body = byTag(doc, "body")[0];
+	return body === void 0 ? [] : childrenNamed(body, "p");
+}
+const textOf = (scope) => byTag(scope, "t").map((node) => node.textContent ?? "").join("");
+const intAttr = (element, name) => {
+	const raw = element?.getAttributeNS(WORD_NS, name) ?? element?.getAttribute(`w:${name}`) ?? element?.getAttribute(name);
+	const value = Number(raw);
+	return Number.isFinite(value) ? value : void 0;
+};
+/** 读带坐标的骨架（FR-42.1） */
+async function readDocxTemplate(bytes) {
+	const { doc } = parseXmlPart(await readOoxmlPackage(bytes), DOCUMENT);
+	const paragraphs = paragraphsOf(doc).map((paragraph, index) => ({
+		index,
+		text: textOf(paragraph)
+	}));
+	const cells = [];
+	tablesOf(doc).forEach((table, tableIndex) => {
+		childrenNamed(table, "tr").forEach((row, rowIndex) => {
+			childrenNamed(row, "tc").forEach((cell, columnIndex) => {
+				const properties = childrenNamed(cell, "tcPr")[0];
+				const gridSpan = properties === void 0 ? void 0 : intAttr(childrenNamed(properties, "gridSpan")[0], "val");
+				const merge = properties === void 0 ? void 0 : childrenNamed(properties, "vMerge")[0];
+				cells.push({
+					table: tableIndex,
+					row: rowIndex,
+					column: columnIndex,
+					text: textOf(cell),
+					...gridSpan === void 0 ? {} : { gridSpan },
+					...merge === void 0 ? {} : { vMerge: merge.getAttributeNS(WORD_NS, "val") ?? merge.getAttribute("w:val") ?? "continue" }
+				});
+			});
+		});
+	});
+	return {
+		paragraphs,
+		cells
+	};
+}
+/** @throws WebSkillError 坐标指到不存在的表 / 行 / 列 / 段落 */
+function locate(doc, target) {
+	if (target.table !== void 0) {
+		const tables = tablesOf(doc);
+		const table = tables[target.table];
+		if (table === void 0) throw new WebSkillError("TEMPLATE_TARGET_MISSING", `The document has no table at index ${target.table}; it has ${tables.length} table(s).`);
+		const rows = childrenNamed(table, "tr");
+		const row = rows[target.row ?? -1];
+		if (row === void 0) throw new WebSkillError("TEMPLATE_TARGET_MISSING", `Table ${target.table} has no row at index ${target.row}; it has ${rows.length} row(s).`);
+		const cells = childrenNamed(row, "tc");
+		const cell = cells[target.column ?? -1];
+		if (cell === void 0) throw new WebSkillError("TEMPLATE_TARGET_MISSING", `Row ${target.row} of table ${target.table} has no cell at index ${target.column}; it has ${cells.length} cell(s).`);
+		return cell;
+	}
+	const paragraphs = paragraphsOf(doc);
+	const paragraph = paragraphs[target.paragraph ?? -1];
+	if (paragraph === void 0) throw new WebSkillError("TEMPLATE_TARGET_MISSING", `The document has no body paragraph at index ${target.paragraph}; it has ${paragraphs.length} paragraph(s).`);
+	return paragraph;
+}
+/**
+* 写文字：改已有 run 的 `<w:t>`，多余的 run 删掉。
+*
+* 不重建 run，是因为 `<w:rPr>`（字体、字号、加粗）就挂在 run 上——
+* 与 xlsx 那边靠 `<c>` 的 `s` 属性保格式是同一个道理（设计 43 §1.2）。
+*/
+function fillText(doc, scope, value) {
+	const paragraphs = scope.localName === "p" ? [scope] : childrenNamed(scope, "p");
+	const first = paragraphs[0];
+	if (first === void 0) throw new WebSkillError("TEMPLATE_TARGET_MISSING", "The target has no paragraph to write text into.");
+	paragraphs.slice(1).forEach((paragraph) => {
+		for (const run of childrenNamed(paragraph, "r")) paragraph.removeChild(run);
+	});
+	const runs = childrenNamed(first, "r").filter((run) => byTag(run, "drawing").length === 0);
+	const keep = runs[0];
+	runs.slice(1).forEach((run) => first.removeChild(run));
+	if (keep === void 0) {
+		if (value === "") return;
+		const run = doc.createElementNS(WORD_NS, "w:r");
+		run.appendChild(textNode(doc, value));
+		first.appendChild(run);
+		return;
+	}
+	if (value === "") {
+		first.removeChild(keep);
+		return;
+	}
+	for (const node of childrenNamed(keep, "t")) keep.removeChild(node);
+	keep.appendChild(textNode(doc, value));
+}
+/** 新建节点用 createElementNS 带前缀：document.xml 的默认命名空间不是 w，裸 createElement 会带出 xmlns="" */
+function textNode(doc, value) {
+	const node = doc.createElementNS(WORD_NS, "w:t");
+	if (value !== value.trim()) node.setAttribute("xml:space", "preserve");
+	node.textContent = value;
+	return node;
+}
+/** 版心宽度：`pgSz` 减两边 `pgMar`（twip） */
+function bodyWidthTwips(doc) {
+	const size = byTag(doc, "pgSz")[0];
+	const margin = byTag(doc, "pgMar")[0];
+	const width = intAttr(size, "w") ?? 11906;
+	const left = intAttr(margin, "left") ?? 1440;
+	const right = intAttr(margin, "right") ?? 1440;
+	return Math.max(width - left - right, 0);
+}
+/**
+* 落点的可用框（twip）。
+*
+* 宽度优先取单元格自己的 `tcW`——`工作面移交表.docx` 的表格是故意比版心宽的，
+* 退回版心宽会把图算小（设计 43 §1.6）。`tcW` 缺失时按 `gridSpan` 累加 `tblGrid`。
+* 行声明了 `trHeight` 才有高度约束，没有就只受宽度约束。
+*/
+function boxTwipsOf(doc, scope) {
+	if (scope.localName !== "tc") return {
+		width: bodyWidthTwips(doc),
+		height: 0
+	};
+	const properties = childrenNamed(scope, "tcPr")[0];
+	const width = intAttr(properties === void 0 ? void 0 : childrenNamed(properties, "tcW")[0], "w");
+	const row = scope.parentElement;
+	const table = row?.parentElement;
+	const span = properties === void 0 ? 1 : intAttr(childrenNamed(properties, "gridSpan")[0], "val") ?? 1;
+	let resolved = width !== void 0 && width > 0 ? width : 0;
+	if (resolved === 0 && table !== null && table !== void 0) {
+		const grid = byTag(table, "gridCol").map((column) => intAttr(column, "w") ?? 0);
+		const start = row === null ? 0 : childrenNamed(row, "tc").indexOf(scope);
+		resolved = grid.slice(start, start + span).reduce((sum, value) => sum + value, 0);
+	}
+	if (resolved === 0) resolved = bodyWidthTwips(doc);
+	const rowProperties = row === null ? void 0 : childrenNamed(row, "trPr")[0];
+	const height = rowProperties === void 0 ? 0 : intAttr(childrenNamed(rowProperties, "trHeight")[0], "val") ?? 0;
+	return {
+		width: resolved,
+		height
+	};
+}
+function nextRelationshipId(pkg) {
+	const text = new TextDecoder().decode(pkg.get(DOCUMENT_RELS) ?? /* @__PURE__ */ new Uint8Array());
+	let max = 0;
+	for (const match of text.matchAll(/Id="rId(\d+)"/g)) max = Math.max(max, Number(match[1]));
+	return `rId${max + 1}`;
+}
+function addImageRelationship(pkg, id, target) {
+	const bytes = pkg.get(DOCUMENT_RELS);
+	if (bytes === void 0) throw new WebSkillError("TEMPLATE_UNSUPPORTED", `The template has no ${DOCUMENT_RELS} part.`);
+	const updated = new TextDecoder().decode(bytes).replace("</Relationships>", `<Relationship Id="${id}" Type="${REL_NS}/image" Target="${target}"/></Relationships>`);
+	pkg.set(DOCUMENT_RELS, new TextEncoder().encode(updated));
+}
+/**
+* 插图（FR-42.18）。用 `<wp:inline>` 而不是 `<wp:anchor>`：
+* inline 参与文档流，跟着单元格走；anchor 是浮动的，分页一变就跑位。
+*/
+function attachImage(pkg, doc, scope, image, index) {
+	const size = readImageSize(image.bytes);
+	if (size === void 0) throw new WebSkillError("TEMPLATE_IMAGE_UNRESOLVED", "The image to insert is not a PNG or JPEG file.");
+	const mediaName = `webskillImage${index + 1}.${image.extension}`;
+	pkg.set(`word/media/${mediaName}`, image.bytes);
+	ensureDefaultExtension(pkg, image.extension, image.contentType);
+	const relId = nextRelationshipId(pkg);
+	addImageRelationship(pkg, relId, `media/${mediaName}`);
+	const box = boxTwipsOf(doc, scope);
+	const fitted = fitWithin({
+		width: size.width * EMU_PER_PIXEL,
+		height: size.height * EMU_PER_PIXEL
+	}, {
+		width: box.width * 635,
+		height: box.height * 635
+	});
+	const id = index + 1;
+	const drawing = `<w:r xmlns:w="${WORD_NS}"><w:drawing><wp:inline distT="0" distB="0" distL="0" distR="0" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"><wp:extent cx="${fitted.width}" cy="${fitted.height}"/><wp:effectExtent l="0" t="0" r="0" b="0"/><wp:docPr id="${1e3 + id}" name="Picture ${id}"/><wp:cNvGraphicFramePr><a:graphicFrameLocks xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" noChangeAspect="1"/></wp:cNvGraphicFramePr><a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"><a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture"><pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture"><pic:nvPicPr><pic:cNvPr id="${1e3 + id}" name="${mediaName}"/><pic:cNvPicPr/></pic:nvPicPr><pic:blipFill><a:blip xmlns:r="${REL_NS}" r:embed="${relId}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill><pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${fitted.width}" cy="${fitted.height}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr></pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing></w:r>`;
+	const parsed = new DOMParser().parseFromString(drawing, "application/xml");
+	if (parsed.getElementsByTagName("parsererror").length > 0) throw new WebSkillError("TOOL_EXECUTION_FAILED", "Failed to build the DrawingML fragment for the image.");
+	const run = doc.importNode(parsed.documentElement, true);
+	const paragraphs = scope.localName === "p" ? [scope] : childrenNamed(scope, "p");
+	const host = paragraphs[paragraphs.length - 1];
+	if (host === void 0) throw new WebSkillError("TEMPLATE_TARGET_MISSING", "The target has no paragraph to place the image in.");
+	host.appendChild(run);
+}
+/**
+* 照模板出新文件。
+*
+* @throws WebSkillError 模板不是 docx、坐标指到不存在的表 / 行 / 列 / 段落、图片认不出来
+*/
+async function fillDocxTemplate(bytes, spec) {
+	const pkg = await readOoxmlPackage(bytes);
+	const { declaration, doc } = parseXmlPart(pkg, DOCUMENT);
+	for (const text of spec.texts ?? []) fillText(doc, locate(doc, text), text.value);
+	(spec.images ?? []).forEach((image, index) => attachImage(pkg, doc, locate(doc, image), image, index));
+	pkg.set(DOCUMENT, serializeXmlPart(declaration, doc));
+	stripMacros(pkg);
+	assertOoxmlPackage(pkg);
+	return writeOoxmlPackage(pkg);
+}
+
 //#endregion
 //#region ../browser/src/viewer/viewerCsp.ts
 /**
@@ -5908,6 +7775,24 @@ const SANDBOX_TOKENS = [
 	"allow-downloads"
 ];
 /**
+* 投放面图片来源的单一事实源（0.22.0 分册 13 FR-13.9）。
+*
+* **不含宿主自身**：两套宿主写法不同——站点写自己的 origin（opaque origin 下 `'self'` 匹配不上），
+* 扩展的 sandbox 页写 `'self'`。能收敛的是**除宿主之外**放行了哪些来源，
+* 而那恰恰是会漂走的部分（扩展的 sandbox CSP 此前整条 `img-src` 都不存在，等于全放）。
+* @experimental
+*/
+const VIEWER_IMG_SRC_BASE = ["data:"];
+/**
+* 降级形态（外链图，FR-13.6）额外需要的来源。
+*
+* ⚠️ 加它进来的代价见 `ViewerCspOptions.imgSrc`：投放面因此多了一条外发信道。
+* `http:` 也在其中，因为需求裁决了「`http` 尽力而为」（分册 13 §2.2）——
+* 抓得到就嵌字节，抓不到才落到这条外链上，此时拦掉它只会让图变成一个破图标。
+* @experimental
+*/
+const VIEWER_IMG_SRC_REMOTE = ["https:", "http:"];
+/**
 * 宿主配置值不得夹带 CSP 分隔符 —— 否则一个来源字符串就能追加任意指令，
 * 白名单形同虚设。这是配置注入，不是理论风险。
 */
@@ -5933,7 +7818,7 @@ function viewerCspHeader(options) {
 		"default-src 'none'",
 		`script-src ${host}`,
 		`style-src ${host} 'unsafe-inline'`,
-		directive("img-src", [host, "data:"], options.imgSrc),
+		directive("img-src", [host, ...VIEWER_IMG_SRC_BASE], options.imgSrc),
 		directive("font-src", [host], options.fontSrc),
 		directive("connect-src", [], options.connectSrc)
 	].join("; ");
@@ -5957,13 +7842,101 @@ function diffSandboxTokens(sdk, host) {
 
 //#endregion
 //#region ../browser/src/viewer/documentSurface.ts
-const DEFAULT_MAX_VIEWER_PAYLOAD_BYTES = 2e6;
+/**
+* 载荷硬兜底（0.22.0 FR-10.1）。
+*
+* 从 0.11.0 的 2 MB 提到这里，是因为那个值从未被论证过，而实测表明它离任何真实边界都很远：
+* 128 MB 的结构化克隆只要 23 ms，V8 的字符串上限在 512 MB 左右才会抛 `RangeError`。
+* 留 4 倍余量是给同一个标签页里的 React、图表库与对话历史用的。
+*/
+const DEFAULT_MAX_VIEWER_PAYLOAD_BYTES = 128e6;
+/** 载荷软阈值：到这里不是「慢」，而是「这份文档异常大」，值得先告诉用户一声 */
+const DEFAULT_SOFT_VIEWER_PAYLOAD_BYTES = 32e6;
+/** 像素硬兜底，约合 1 GB 位图；实测 60 张 4000×3000 达 2.7 GB，那是崩标签页的量级 */
+const DEFAULT_MAX_VIEWER_PAYLOAD_PIXELS = 256e6;
+/** 像素软阈值，约合 256 MB 位图；实测 60 M 像素仍然流畅 */
+const DEFAULT_SOFT_VIEWER_PAYLOAD_PIXELS = 64e6;
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 1e4;
 /** hello 的重发间隔：viewer 脚本加载完之前投出去的消息全部丢失 */
 const HELLO_RETRY_MS = 100;
+/** 拒绝消息里列举的「最大的几张图」条数：两三张巨图撑起整份文档是常态，列太多反而没重点 */
+const LARGEST_IMAGES_IN_MESSAGE = 3;
 /** 审计事件类型（与既有事件同一条链） */
 const DOCUMENT_SURFACE_AUDIT_EVENT = "document.surface.open";
-const payloadBytes = (value) => new TextEncoder().encode(JSON.stringify(value) ?? "").length;
+/**
+* 数载荷有多大，**不物化任何中间副本**（FR-10.3）。
+*
+* 被换掉的写法是 `new TextEncoder().encode(JSON.stringify(value)).length`：
+* 它为了读一个 `.length`，先物化一份与文档等长的字符串、再物化一份等长的字节数组，
+* 峰值内存是文档的三倍。实测 341 MB 的文档上它要 712 ms，
+* 而它保护的那次 `postMessage` 只要 95 ms——度量比传输还慢七倍。
+*
+* 用显式栈而不是递归：投放的是技能生成的数据，嵌套深度不由我们决定。
+*/
+function payloadUnits(value) {
+	let units = 0;
+	const seen = /* @__PURE__ */ new WeakSet();
+	const stack = [value];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (typeof current === "string") {
+			units += current.length;
+			continue;
+		}
+		if (typeof current !== "object" || current === null) continue;
+		if (seen.has(current)) continue;
+		seen.add(current);
+		if (Array.isArray(current)) {
+			for (const item of current) stack.push(item);
+			continue;
+		}
+		if (ArrayBuffer.isView(current)) {
+			units += current.byteLength;
+			continue;
+		}
+		for (const [key, item] of Object.entries(current)) {
+			units += key.length;
+			stack.push(item);
+		}
+	}
+	return units;
+}
+function payloadCost(input) {
+	let pixels = 0;
+	for (const image of input.images ?? []) pixels += image.width * image.height;
+	return {
+		units: payloadUnits(input.document),
+		pixels
+	};
+}
+function limitsOf(options) {
+	return {
+		softUnits: options.softPayloadBytes ?? 32e6,
+		hardUnits: options.maxPayloadBytes ?? 128e6,
+		softPixels: options.softPayloadPixels ?? 64e6,
+		hardPixels: options.maxPayloadPixels ?? 256e6
+	};
+}
+/** 两维取并集：任一维过线即触发，不得加权合并（FR-10.7） */
+function triggeredBy(overUnits, overPixels) {
+	if (overUnits && overPixels) return "both";
+	if (overUnits) return "bytes";
+	if (overPixels) return "pixels";
+}
+/**
+* 拒绝消息必须可执行（FR-10.2）：说清是哪一维超的、超了多少、以及该动哪张图。
+*
+* 「最大的几张图」不是锦上添花——一份超限的文档通常就是两三张巨图撑起来的，
+* 不报出来用户只知道「太大了」，不知道该换掉哪一张。
+*/
+function rejectionMessage(cost, limits, trigger, images) {
+	const parts = [];
+	if (trigger !== "pixels") parts.push(`payload is ${cost.units} units, over the ${limits.hardUnits} unit budget`);
+	if (trigger !== "bytes") parts.push(`images total ${cost.pixels} pixels, over the ${limits.hardPixels} pixel budget`);
+	const largest = [...images].sort(trigger === "bytes" ? (a, b) => b.units - a.units : (a, b) => b.width * b.height - a.width * a.height).slice(0, LARGEST_IMAGES_IN_MESSAGE).map((image) => `${image.ref} (${image.width}x${image.height}, ${image.units} units)`);
+	const advice = largest.length > 0 ? `remove or downscale the largest images before opening the viewer: ${largest.join(", ")}` : "reduce the document content before opening the viewer";
+	return `Document ${parts.join(" and ")} (dimension: ${trigger}); ${advice}`;
+}
 /**
 * 打开一个文档投放面。
 *
@@ -5973,23 +7946,46 @@ const payloadBytes = (value) => new TextEncoder().encode(JSON.stringify(value) ?
 * 无 `allow-top-navigation` 改不了它的地址。
 */
 async function openDocumentSurface(input, options) {
-	const limit = options.maxPayloadBytes ?? 2e6;
-	const size = payloadBytes(input.document);
-	if (size > limit) {
+	const images = input.images ?? [];
+	const omissions = input.omissions ?? [];
+	const limits = limitsOf(options);
+	const cost = payloadCost(input);
+	const facts = {
+		units: cost.units,
+		pixels: cost.pixels,
+		imageCount: images.length,
+		...omissions.length > 0 ? { omissions: [...omissions] } : {}
+	};
+	const rejected = triggeredBy(cost.units > limits.hardUnits, cost.pixels > limits.hardPixels);
+	if (rejected !== void 0) {
 		await audit(options, input, {
 			outcome: "rejected",
 			reason: "payload-too-large",
-			bytes: size
+			...facts,
+			warned: false,
+			trigger: rejected
 		});
-		throw new WebSkillError("VALIDATION_FAILED", `Document payload is ${size} bytes, over the ${limit} byte budget; reduce the data before opening the viewer`);
+		throw new WebSkillError("VALIDATION_FAILED", rejectionMessage(cost, limits, rejected, images));
 	}
+	const warned = triggeredBy(cost.units > limits.softUnits, cost.pixels > limits.softPixels);
+	const sizeNotice = warned === void 0 ? void 0 : {
+		units: cost.units,
+		pixels: cost.pixels,
+		trigger: warned
+	};
+	const audited = {
+		...facts,
+		warned: warned !== void 0,
+		...warned === void 0 ? {} : { trigger: warned }
+	};
 	if (!await options.confirm({
 		skillName: input.skillName,
-		dataSource: input.dataSource
+		dataSource: input.dataSource,
+		...sizeNotice === void 0 ? {} : { sizeNotice }
 	})) {
 		await audit(options, input, {
 			outcome: "cancelled",
-			bytes: size
+			...audited
 		});
 		throw new WebSkillError("DOCUMENT_SURFACE_DECLINED", "The user declined to open the document surface");
 	}
@@ -5998,7 +7994,7 @@ async function openDocumentSurface(input, options) {
 		await audit(options, input, {
 			outcome: "blocked",
 			reason: "popup-blocked",
-			bytes: size
+			...audited
 		});
 		throw new WebSkillError("DOCUMENT_SURFACE_UNAVAILABLE", "The browser blocked the viewer window; open it from a direct user gesture");
 	}
@@ -6009,8 +8005,8 @@ async function openDocumentSurface(input, options) {
 		target.close();
 		await audit(options, input, {
 			outcome: "failed",
-			reason: messageOf(e),
-			bytes: size
+			reason: messageOf$1(e),
+			...audited
 		});
 		throw e;
 	}
@@ -6021,7 +8017,7 @@ async function openDocumentSurface(input, options) {
 	}, viewerOrigin(options));
 	await audit(options, input, {
 		outcome: "opened",
-		bytes: size
+		...audited
 	});
 	return target;
 }
@@ -7279,7 +9275,7 @@ function toolError(e) {
 		content: [],
 		error: {
 			code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
-			message: messageOf(e)
+			message: messageOf$1(e)
 		}
 	};
 }
@@ -7393,4 +9389,4 @@ function readContent(result, images) {
 }
 
 //#endregion
-export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, DEFAULT_CAMERA_MAX_DIMENSION, DEFAULT_FRAME_BUDGET, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_IMAGE_WIDTH_RATIO, DOCX_UNEXTRACTED, HOST_PORT_MATRIX, IframeWorkerLike, LIST_WEBOFFICE_DOCUMENTS_TOOL, OpfsProvider, READ_WEBOFFICE_DOCUMENT_TOOL, SANDBOX_PAGE_SCRIPT_SOURCE, SHARD_SOFT_LIMIT, TsTranspiler, VIEWER_SANDBOX_TOKENS, WEBOFFICE_BUDGET, WEBOFFICE_UNEXTRACTED, WEB_OFFICE_OFFICE_TYPES, WEB_OFFICE_READ_METHODS, WEB_OFFICE_SUPPORTED_TYPES, WORKER_BOOTSTRAP_SOURCE, WebOfficeBudgetGuard, WebOfficePolicy, WorkerRuntimeClient, WorkerUiBridge, XLSX_IMAGE_MIN_COLUMNS, XLSX_IMAGE_MIN_ROWS, XLSX_UNEXTRACTED, assertWebOfficeFingerprint, blockedMessage, bridgeError, callWebOfficeMethod, captureByScrolling, captureElementImage, capturePhoto, checkCameraAvailability, checkDictationAvailability, checkWebOfficeFingerprint, compressImageToBudget, contentKindOf, createBrowserChatbotHost, createDocumentSurfaceHost, createDocxBlockReader, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createRemotePageActionExecutor, createRemotePerceptionReader, createRemoteTargetRegistry, createWebOfficeHandle, createWebOfficeToolSource, createXlsxBlockReader, deleteMemoryEncryptionKey, describeScreenshotOverlap, diffSandboxTokens, documentKey, explainResolution, extractDocxText, extractWebOfficeContent, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, headingLevelOf, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, isWebOfficeReadMethod, missingPorts, openCamera, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, readDocxBlocks, readXlsxBlocks, resolveWebOfficeAuthorization, seedSkillsFromHttp, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources, webOfficeFailure };
+export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, DEFAULT_CAMERA_MAX_DIMENSION, DEFAULT_FRAME_BUDGET, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DEFAULT_MAX_VIEWER_PAYLOAD_PIXELS, DEFAULT_SOFT_VIEWER_PAYLOAD_BYTES, DEFAULT_SOFT_VIEWER_PAYLOAD_PIXELS, DOCUMENT_IMAGE_MIME_TYPES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_IMAGE_WIDTH_RATIO, DOCX_UNEXTRACTED, HOST_PORT_MATRIX, IframeWorkerLike, LIST_WEBOFFICE_DOCUMENTS_TOOL, MAX_REMOTE_IMAGE_BYTES, OpfsProvider, PPTX_UNEXTRACTED, PPTX_UNEXTRACTED_NOTICE, READ_WEBOFFICE_DOCUMENT_TOOL, REMOTE_IMAGE_TIMEOUT_MS, SANDBOX_PAGE_SCRIPT_SOURCE, SHARD_SOFT_LIMIT, TsTranspiler, VIEWER_IMG_SRC_BASE, VIEWER_IMG_SRC_REMOTE, VIEWER_SANDBOX_TOKENS, WEBOFFICE_BUDGET, WEBOFFICE_UNEXTRACTED, WEB_OFFICE_OFFICE_TYPES, WEB_OFFICE_READ_METHODS, WEB_OFFICE_SUPPORTED_TYPES, WORKER_BOOTSTRAP_SOURCE, WebOfficeBudgetGuard, WebOfficePolicy, WorkerRuntimeClient, WorkerUiBridge, XLSX_IMAGE_MIN_COLUMNS, XLSX_IMAGE_MIN_ROWS, XLSX_UNEXTRACTED, assertWebOfficeFingerprint, auditOoxmlPackage, blockedMessage, bridgeError, callWebOfficeMethod, captureByScrolling, captureDocumentImage, captureElementImage, capturePhoto, checkCameraAvailability, checkDictationAvailability, checkWebOfficeFingerprint, classifyFetchFailure, compressImageToBudget, contentKindOf, createBrowserChatbotHost, createDocumentSurfaceHost, createDocxBlockReader, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createPptxBlockReader, createRemoteImageHost, createRemotePageActionExecutor, createRemotePageImageHost, createRemotePerceptionReader, createRemoteTargetRegistry, createWebOfficeHandle, createWebOfficeToolSource, createXlsxBlockReader, deleteMemoryEncryptionKey, describeScreenshotOverlap, diffSandboxTokens, documentKey, explainResolution, extractDocxText, extractPptxText, extractWebOfficeContent, extractXlsxText, extractZipWeb, fetchRemoteImage, fillDocxTemplate, fillXlsxTemplate, generateMemoryEncryptionKey, headingLevelOf, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, isRemoteImageFailure, isWebOfficeReadMethod, missingPorts, openCamera, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, readDocxBlocks, readDocxTemplate, readOoxmlPackage, readPptxBlocks, readXlsxBlocks, readXlsxTemplate, resolveWebOfficeAuthorization, seedSkillsFromHttp, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, toDocumentImage, viewerCspHeader, watchBlockedResources, webOfficeFailure, writeOoxmlPackage };