@webskill/sdk 0.12.0 → 0.14.0

package/dist/browser.js

@@ -1,7 +1,7 @@
-import { D as exportSkills, F as parseSkillPackManifest, G as unzipWithLimits, I as readResponseWithLimit, J as verifySkillSignature, K as validateSkills, L as readSkillSignature, M as messageOf, O as isAtomicTempPath, P as parseSkillMarkdown, T as detectSkillArchiveShapeFromFs, V as resolveInsideRoot, b as buildManifest, c as SKILL_MANIFEST_FILE, d as SKILL_PACK_FILE, g as assertRemoteUrlAllowed, h as WebSkillError, i as MANIFEST_EXCLUDED_FILES, k as isValidSkillName, p as SkillDiscovery, q as verifyManifest, s as SKILLS_LOCKFILE, v as atomicWriteText, y as buildCatalog } from "./dist-Bev6i6Ip.js";
-import { $ as bridgeError, A as ProgressiveRouter, Ct as normalizeToolError, E as GoogleGenAiClient, St as normalizeToolContent, _t as mergeCatalogEntries, b as FsMemoryStore, c as AnthropicClient, k as OpenAiCompatibleClient, nt as createWebSkillApi, s as AgentLoop, u as CapabilityApproval, wt as parseBridgeRequest, x as FsRunSnapshotStore, y as FsArtifactStore, yt as networkPolicyLibSource } from "./dist-sdKFgERo.js";
-import { T as toFrameScopes, w as toActionFrameScopes } from "./dist-DU9KDAuR.js";
-import { n as MockLlmClient } from "./testing-WPTyXQYt.js";
+import { $ as unzipWithLimits, B as messageOf, E as buildManifest, G as readSkillSignature, H as parseSkillMarkdown, I as isAtomicTempPath, L as isValidSkillName, M as detectSkillArchiveShapeFromFs, P as exportSkills, S as assertRemoteUrlAllowed, T as buildCatalog, U as parseSkillPackManifest, W as readResponseWithLimit, Y as resolveInsideRoot, _ as SkillDiscovery, b as WebSkillError, c as MANIFEST_EXCLUDED_FILES, d as SKILLS_LOCKFILE, et as validateSkills, f as SKILL_MANIFEST_FILE, h as SKILL_PACK_FILE, nt as verifySkillSignature, tt as verifyManifest, w as atomicWriteText } from "./dist-D5YhlCdY.js";
+import { $ as bridgeError, A as ProgressiveRouter, Ct as normalizeToolError, E as GoogleGenAiClient, St as normalizeToolContent, _t as mergeCatalogEntries, b as FsMemoryStore, c as AnthropicClient, k as OpenAiCompatibleClient, nt as createWebSkillApi, s as AgentLoop, u as CapabilityApproval, wt as parseBridgeRequest, x as FsRunSnapshotStore, y as FsArtifactStore, yt as networkPolicyLibSource } from "./dist-Bfga1TmS.js";
+import { A as frameLabel, M as toActionFrameScopes, N as toFrameScopes, j as frameSteps } from "./dist-BnqAkSS6.js";
+import { n as MockLlmClient } from "./testing-Cm8MseLF.js";
 
 //#region ../browser/dist/index.js
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -905,12 +905,16 @@ var IframeWorkerLike = class {
 	#channelId;
 	#hostWindow;
 	#hostListener;
-	constructor(iframe, hostWindow, channelId) {
+	#readyTimer;
+	constructor(iframe, hostWindow, channelId, readyTimeout) {
 		this.#iframe = iframe;
 		this.#hostWindow = hostWindow;
 		this.#channelId = channelId;
 		this.#hostListener = (event) => this.#onMessage(event);
 		this.#hostWindow.addEventListener("message", this.#hostListener);
+		if (readyTimeout) this.#readyTimer = setTimeout(() => {
+			this.#failQueue(`Sandbox document did not become ready within ${readyTimeout.ms}ms: ${readyTimeout.documentUrl}. Ensure it is listed in both manifest sandbox.pages and web_accessible_resources.`);
+		}, readyTimeout.ms);
 	}
 	get ready() {
 		return this.#ready;
@@ -919,10 +923,38 @@ var IframeWorkerLike = class {
 		return this.#channelId;
 	}
 	markReady() {
+		this.#clearReadyTimer();
 		this.#ready = true;
 		for (const payload of this.#queue) this.#post(payload);
 		this.#queue = [];
 	}
+	#clearReadyTimer() {
+		if (this.#readyTimer !== void 0) {
+			clearTimeout(this.#readyTimer);
+			this.#readyTimer = void 0;
+		}
+	}
+	/**
+	* 就绪超时（FR-12.4）：`createIframeWorker` 同步返回，超时无处可抛，只能走回包通道。
+	* 而 `#request` 按 `data.id` 匹配回包，id 对不上的消息被静默丢弃——
+	* 所以必须**逐条**回复队列里每一条消息的 id，否则调用方一直挂着。
+	*/
+	#failQueue(message) {
+		const queued = this.#queue;
+		this.#queue = [];
+		for (const payload of queued) {
+			const id = payload.id;
+			if (typeof id === "string") this.emit({
+				id,
+				ok: false,
+				error: {
+					code: "TOOL_EXECUTION_FAILED",
+					message
+				}
+			});
+		}
+		this.terminate();
+	}
 	#post(payload) {
 		this.#iframe.contentWindow?.postMessage({
 			[ENVELOPE]: true,
@@ -953,11 +985,18 @@ var IframeWorkerLike = class {
 		for (const listener of this.#listeners) listener({ data });
 	}
 	terminate() {
+		this.#clearReadyTimer();
 		this.#hostWindow.removeEventListener("message", this.#hostListener);
 		this.#iframe.remove();
 	}
 };
-/** srcdoc 文档：内嵌 Worker 引导源码 + 双向中继（BOOTSTRAP 经 JSON 字符串注入，防 <\/script> 截断） */
+/**
+* srcdoc 文档：内嵌 Worker 引导源码 + 双向中继（BOOTSTRAP 经 JSON 字符串注入，防 <\/script> 截断）。
+*
+* **这段文本被 FR-12.5 / AC-12.1 冻结在 0.13.0 基线上**：既有网页宿主不给 `documentUrl`，
+* 必须逐字节拿到与升级前相同的沙箱文档。因此它不与 `SANDBOX_PAGE_SCRIPT_SOURCE` 共用模板——
+* 抽模板必然改动生成文本。两份中继的一致性改由行为对拍守卫（见 `sandboxRelayParity` 用例）。
+*/
 function sandboxDocument(bootstrapSource, channelId) {
 	const bootstrapJson = JSON.stringify(bootstrapSource).replace(/<\//g, "<\\/");
 	return `<!doctype html>
@@ -984,16 +1023,96 @@ parent.postMessage({ [ENVELOPE]: true, channelId: CHANNEL_ID, payload: { type: '
 <\/script></body></html>`;
 }
 /**
-* 创建 opaque iframe 沙箱 Worker：sandbox="allow-scripts" srcdoc iframe 承载 classic Worker。
+* 静态沙箱页的中继脚本源码（分册 12 / FR-12.3）。
+*
+* 宿主把它落成一个独立文件并用 `<script src>` 引入——**不得内联**：
+* sandbox 页虽允许 `unsafe-inline`，但外链能让「沙箱页脚本 = SDK 原样产物」在审计时可核对。
+*
+* 与 srcdoc 形态的两点区别，都源于「静态页在加载完时还不知道要跑什么」：
+* - **引导源码**随宿主的 `sandbox-init` 消息到达，而不是内嵌在文档里；
+* - **channelId** 由第一条来自 `parent` 的消息 latch。SDK 导出的是一份与宿主无关的源码，
+*   不可能预知宿主这次生成的 id。latch 前先认 `event.source === parent`：少了这句，
+*   任何把本页嵌进去的第三方 frame 都能抢先 latch 一个自己的 id，
+*   让真正的宿主消息全部被丢弃——一个纯粹的拒绝服务面。
+*
+* 本源码不含任何扩展 API：sandbox 页拿不到它们（实证）。
+* `ENVELOPE` 与宿主侧同源（同一个模块常量），两边各写一份字面量会在改名时静默失配。
+* @experimental
+*/
+const SANDBOX_PAGE_SCRIPT_SOURCE = `const ENVELOPE = ${JSON.stringify(ENVELOPE)};
+let CHANNEL_ID = null;
+let worker = null;
+function post(payload) {
+  parent.postMessage({ [ENVELOPE]: true, channelId: CHANNEL_ID, payload }, '*');
+}
+function startWorker(bootstrapSource) {
+  if (worker || typeof bootstrapSource !== 'string') return;
+  const blob = new Blob([bootstrapSource], { type: 'text/javascript' });
+  const url = URL.createObjectURL(blob);
+  // 注意：opaque origin 下 module Worker 无法加载（实证），classic Worker + data: URL 动态导入可用
+  worker = new Worker(url);
+  URL.revokeObjectURL(url);
+  worker.addEventListener('message', (event) => post(event.data));
+  worker.addEventListener('error', (event) => post({ type: 'sandbox-worker-error', message: event.message }));
+  post({ type: 'sandbox-ready' });
+}
+window.addEventListener('message', (event) => {
+  const data = event.data;
+  if (!data || data[ENVELOPE] !== true) return;
+  if (event.source !== parent) return;
+  if (CHANNEL_ID === null) {
+    if (typeof data.channelId !== 'string') return;
+    CHANNEL_ID = data.channelId;
+  } else if (data.channelId !== CHANNEL_ID) return;
+  const payload = data.payload;
+  if (payload && payload.type === 'sandbox-init') {
+    startWorker(payload.bootstrapSource);
+    return;
+  }
+  if (worker) worker.postMessage(payload);
+});
+`;
+/**
+* `Document` 判别式。不用 `'documentUrl' in v`：`Document` 上没有该属性，
+* 但一个只给了 `doc` 的选项对象上也没有，两者会被判到同一侧。
+*/
+function isDocument(value) {
+	return value.nodeType === 9;
+}
+/**
+* 创建 opaque iframe 沙箱 Worker：srcdoc（默认）或宿主指定的静态沙箱页承载 classic Worker。
 * 返回 IframeWorkerLike（协议与 blob Worker 完全一致：load/execute/bridge/network-blocked）。
 */
-function createIframeWorker(bootstrapSource, doc = document) {
+function createIframeWorker(bootstrapSource, options = {}) {
+	const resolved = isDocument(options) ? { doc: options } : options;
+	const doc = resolved.doc ?? document;
 	const channelId = nextChannelId();
 	const iframe = doc.createElement("iframe");
-	iframe.setAttribute("sandbox", "allow-scripts");
 	iframe.style.display = "none";
-	iframe.srcdoc = sandboxDocument(bootstrapSource, channelId);
-	const worker = new IframeWorkerLike(iframe, doc.defaultView ?? window, channelId);
+	const hostWindow = doc.defaultView ?? window;
+	const { documentUrl } = resolved;
+	if (documentUrl === void 0) {
+		iframe.setAttribute("sandbox", "allow-scripts");
+		iframe.srcdoc = sandboxDocument(bootstrapSource, channelId);
+		const worker = new IframeWorkerLike(iframe, hostWindow, channelId);
+		doc.body.appendChild(iframe);
+		return worker;
+	}
+	const worker = new IframeWorkerLike(iframe, hostWindow, channelId, {
+		ms: resolved.readyTimeoutMs ?? 1e4,
+		documentUrl
+	});
+	iframe.addEventListener("load", () => {
+		iframe.contentWindow?.postMessage({
+			[ENVELOPE]: true,
+			channelId,
+			payload: {
+				type: "sandbox-init",
+				bootstrapSource
+			}
+		}, "*");
+	});
+	iframe.src = documentUrl;
 	doc.body.appendChild(iframe);
 	return worker;
 }
@@ -1195,7 +1314,7 @@ var BrowserWorkerScriptExecutor = class {
 				...details !== void 0 ? { details } : {}
 			});
 			if (decision === "allowed") return void 0;
-			return bridgeError(request.id, "TOOL_UNSUPPORTED", decision === "disabled" ? `Capability "${capability}" is disabled` : `Capability "${capability}" was denied by the user`);
+			return bridgeError(request.id, "TOOL_UNSUPPORTED", decision === "disabled" ? `Capability "${capability}" is disabled by the sandbox capability settings` : `Capability "${capability}" was denied by the user`);
 		};
 		try {
 			switch (request.kind) {
@@ -1222,7 +1341,7 @@ var BrowserWorkerScriptExecutor = class {
 					};
 				}
 				case "fetchData": {
-					if (!context.fetchData) return bridgeError(request.id, "TOOL_UNSUPPORTED", "Capability \"fetchData\" is disabled");
+					if (!context.fetchData) return bridgeError(request.id, "TOOL_UNSUPPORTED", "Capability \"fetchData\" is unavailable: this host wired no data source access at all. This is not the capability switch being off — a data source has to be declared in the host settings first.");
 					const denied = await gate("fetchData", `Script "${context.skillName}" wants to fetch data source "${request.sourceId}"`, { sourceId: request.sourceId });
 					if (denied) return denied;
 					return {
@@ -1633,10 +1752,12 @@ function splitDataUrl(dataUrl) {
 /** 压到预算内；压不下去时把失败原因原样上抛给调用方转成 `CaptureFailure` */
 async function toBudget(id, level, blob, maxBytes) {
 	const compressed = await compressImageToBudget(blob, maxBytes);
+	const mimeType = compressed.blob.type.split(";")[0]?.trim().toLowerCase() ?? "";
+	if (!DELIVERABLE_IMAGE_MIME_TYPES.has(mimeType)) throw new Error(`the bytes normalized to "${mimeType === "" ? "no content type" : mimeType}", which is not one of ${[...DELIVERABLE_IMAGE_MIME_TYPES].join(", ")}`);
 	const buffer = await compressed.blob.arrayBuffer();
 	return {
 		id,
-		mimeType: compressed.blob.type === "" ? "application/octet-stream" : compressed.blob.type,
+		mimeType,
 		data: base64Of(new Uint8Array(buffer)),
 		level,
 		originalBytes: compressed.originalBytes,
@@ -1647,15 +1768,16 @@ async function toBudget(id, level, blob, maxBytes) {
 async function captureImg(element, id, maxBytes) {
 	const src = element.currentSrc !== "" ? element.currentSrc : element.src;
 	if (src === "") throw new Error("the <img> element has no resolved source");
+	const oversized = Math.max(element.naturalWidth, element.naturalHeight) > MAX_RASTER_EDGE;
 	const inline = splitDataUrl(src);
 	if (inline) {
 		const bytes = Uint8Array.from(atob(inline.data), (char) => char.charCodeAt(0));
-		return toBudget(id, "src", new Blob([bytes], { type: inline.mimeType }), maxBytes);
+		return toBudget(id, "src", await toDeliverableBlob(new Blob([bytes], { type: inline.mimeType }), oversized), 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 response.blob(), maxBytes);
+	return toBudget(id, "src", await toDeliverableBlob(await response.blob(), oversized), maxBytes);
 }
 /** L2：`<canvas>` 读回。画布被跨域内容污染时 `toDataURL` 抛 SecurityError，不再兜底（裁决 D-3） */
 async function captureCanvas(element, id, maxBytes) {
@@ -1664,29 +1786,229 @@ async function captureCanvas(element, id, maxBytes) {
 	const bytes = Uint8Array.from(atob(parsed.data), (char) => char.charCodeAt(0));
 	return toBudget(id, "canvas", new Blob([bytes], { type: parsed.mimeType }), maxBytes);
 }
-/** L2：内联 `<svg>` 序列化。SVG 是文本，不进压缩管线——重编码成位图反而丢信息 */
-function captureSvg(element, id, maxBytes) {
-	const markup = new XMLSerializer().serializeToString(element);
-	const data = base64Of(new TextEncoder().encode(markup));
-	const bytes = data.length;
-	if (bytes > maxBytes) throw new Error(`the serialized SVG is ${bytes} bytes, which exceeds the budget`);
+const SVG_NS = "http://www.w3.org/2000/svg";
+/** 无固有尺寸的 SVG 在浏览器里的默认渲染尺寸，照抄规范而不是自创 */
+const SVG_FALLBACK_SIZE = {
+	width: 300,
+	height: 150
+};
+/** 栅格画布的长边上限；再大也会被 `compressImageToBudget` 缩回去，只是白占内存 */
+const MAX_RASTER_EDGE = 2048;
+function numberAttr(element, name) {
+	const raw = element.getAttribute?.(name);
+	if (raw === null || raw === void 0) return void 0;
+	const value = Number.parseFloat(raw);
+	return Number.isFinite(value) && value > 0 ? value : void 0;
+}
+/**
+* 元素的显示尺寸，取不到返回 `undefined`（0.13.0 FR-20.3）。
+*
+* 逐级回退而不是只看 `getBoundingClientRect()`：没有布局的环境里它恒为 0，
+* 只认它会把所有图都判成 0 面积。**取不到就是取不到**，由调用方决定不过滤，
+* 不在这里编一个尺寸出来。
+*/
+function measuredSizeOf(element) {
+	const rect = element.getBoundingClientRect?.();
+	if (rect !== void 0 && rect.width > 0 && rect.height > 0) return {
+		width: rect.width,
+		height: rect.height
+	};
+	const { naturalWidth, naturalHeight } = element;
+	if (typeof naturalWidth === "number" && typeof naturalHeight === "number" && naturalWidth > 0 && naturalHeight > 0) return {
+		width: naturalWidth,
+		height: naturalHeight
+	};
+	const { width: propWidth, height: propHeight } = element;
+	if (typeof propWidth === "number" && typeof propHeight === "number" && propWidth > 0 && propHeight > 0) return {
+		width: propWidth,
+		height: propHeight
+	};
+	const attrWidth = numberAttr(element, "width");
+	const attrHeight = numberAttr(element, "height");
+	if (attrWidth !== void 0 && attrHeight !== void 0) return {
+		width: attrWidth,
+		height: attrHeight
+	};
+	const box = element.getAttribute?.("viewBox")?.trim().split(/[\s,]+/);
+	if (box?.length === 4) {
+		const width = Number.parseFloat(box[2] ?? "");
+		const height = Number.parseFloat(box[3] ?? "");
+		if (Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0) return {
+			width,
+			height
+		};
+	}
+}
+function rasterSizeOf(element) {
+	const measured = measuredSizeOf(element) ?? SVG_FALLBACK_SIZE;
+	const scale = Math.min(1, MAX_RASTER_EDGE / Math.max(measured.width, measured.height));
 	return {
-		id,
-		mimeType: "image/svg+xml",
-		data,
-		level: "canvas",
-		originalBytes: bytes,
-		bytes
+		width: Math.max(1, Math.round(measured.width * scale)),
+		height: Math.max(1, Math.round(measured.height * scale))
 	};
 }
 /**
+* 解码超时。真实浏览器里 data URL 的 SVG 解码是瞬时的（不加载任何外部资源），
+* 但环境不支持图像管线时 load / error 可能一个都不来——没有这道闸门整次感知会永远挂着。
+*/
+const DECODE_TIMEOUT_MS = 2e3;
+async function loadImage(url) {
+	const image = new Image();
+	image.src = url;
+	const decoded = typeof image.decode === "function" ? image.decode() : new Promise((resolve, reject) => {
+		image.onload = () => resolve();
+		image.onerror = () => reject(/* @__PURE__ */ new Error("the browser could not decode the serialized SVG"));
+	});
+	let timer;
+	try {
+		await Promise.race([decoded, new Promise((_, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error("decoding the serialized SVG timed out")), DECODE_TIMEOUT_MS);
+		})]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+	return image;
+}
+/** 逐像素查 alpha，命中一个不透明点立刻返回；只有真正的空图才会扫完全图 */
+function isFullyTransparent(ctx, width, height) {
+	const { data } = ctx.getImageData(0, 0, width, height);
+	for (let i = 3; i < data.length; i += 4) if (data[i] !== 0) return false;
+	return true;
+}
+async function toPngBlob(canvas) {
+	return await new Promise((resolve, reject) => {
+		canvas.toBlob((blob) => {
+			if (blob === null) reject(/* @__PURE__ */ new Error("the canvas could not be encoded as PNG"));
+			else resolve(blob);
+		}, "image/png");
+	});
+}
+/**
+* L2：内联 `<svg>` 栅格化成 PNG（0.13.0 FR-20.1）。
+*
+* 三家提供方的图片通道都不收 `image/svg+xml`（分册 20 §0.1），原样序列化下发等于取不到图。
+* 经 `<img>` 加载的 SVG 被浏览器强制资源隔离：不执行脚本，不加载外部图片 / 样式 / 字体。
+* 因此这里不做污染处理**不是漏了**——画布根本不会被跨源内容污染，也不会因为取像发起外部请求。
+* 代价是页面 CSS 类与外部字体不生效，由下面的空图检测兜底（FR-20.2）。
+*/
+async function captureSvg(element, id, maxBytes) {
+	if (typeof Image !== "function" || typeof document === "undefined") throw new Error("this environment has no DOM image pipeline, so SVG cannot be rasterized");
+	const { width, height } = rasterSizeOf(element);
+	const clone = element.cloneNode(true);
+	clone.setAttribute("xmlns", SVG_NS);
+	clone.setAttribute("width", String(width));
+	clone.setAttribute("height", String(height));
+	const markup = new XMLSerializer().serializeToString(clone);
+	const image = await loadImage(`data:image/svg+xml;base64,${base64Of(new TextEncoder().encode(markup))}`);
+	const canvas = document.createElement("canvas");
+	canvas.width = width;
+	canvas.height = height;
+	const ctx = canvas.getContext("2d");
+	if (ctx === null) throw new Error("a 2D canvas context is unavailable");
+	ctx.drawImage(image, 0, 0, width, height);
+	if (isFullyTransparent(ctx, width, height)) throw new Error("the SVG rendered blank once detached from the page, so its appearance most likely comes from page CSS or external assets that do not apply inside an <img>");
+	return toBudget(id, "canvas", await toPngBlob(canvas), maxBytes);
+}
+/** 模型图片通道只收这几种位图（与 runtime 的 `MODEL_IMAGE_MIME_TYPES` 同一组） */
+const DELIVERABLE_IMAGE_MIME_TYPES = /* @__PURE__ */ new Set([
+	"image/png",
+	"image/jpeg",
+	"image/gif",
+	"image/webp"
+]);
+/** 用于认出 SVG 正文的前缀嗅探长度：`<?xml`、注释、DOCTYPE 都可能排在 `<svg` 之前 */
+const SVG_SNIFF_BYTES = 1024;
+/**
+* WebP 动图：扩展头 `VP8X` 的 flags 字节第 1 位。位置固定在文件前 24 字节内，
+* 不必解码整图就能判出来。
+*/
+function isAnimatedWebp(bytes) {
+	return [
+		86,
+		80,
+		56,
+		88
+	].every((byte, index) => bytes[12 + index] === byte) && ((bytes[20] ?? 0) & 2) !== 0;
+}
+/**
+* 按魔数认图片类型（服务端声明只作兜底）。
+*
+* 图片接口常年是「无扩展名 + `application/octet-stream`」这种组合（查询串带 file id 的尤其多），
+* 而模型侧只按 MIME 判能不能投递——照抄服务端的声明，整张图会在最后一步被丢掉，
+* 模型只收到一句「这个格式发不了」。
+*/
+function sniffImageMime(bytes) {
+	const at = (offset, ...signature) => signature.every((byte, index) => bytes[offset + index] === byte);
+	if (at(0, 137, 80, 78, 71, 13, 10, 26, 10)) return "image/png";
+	if (at(0, 255, 216, 255)) return "image/jpeg";
+	if (at(0, 71, 73, 70, 56)) return "image/gif";
+	if (at(0, 82, 73, 70, 70) && at(8, 87, 69, 66, 80)) return "image/webp";
+	if (at(0, 66, 77)) return "image/bmp";
+	const head = new TextDecoder("utf-8", { fatal: false }).decode(bytes.subarray(0, SVG_SNIFF_BYTES));
+	if (/<svg[\s>]/i.test(head)) return "image/svg+xml";
+}
+/** 把任意 blob 重新编码成 PNG：先让浏览器解码，再画进画布 */
+async function rasterizeToPng(blob) {
+	if (typeof document === "undefined" || typeof Image !== "function" || typeof URL?.createObjectURL !== "function") throw new Error("this environment has no DOM image pipeline, so the image cannot be re-encoded");
+	const url = URL.createObjectURL(blob);
+	try {
+		const image = await loadImage(url);
+		const natural = {
+			width: image.naturalWidth,
+			height: image.naturalHeight
+		};
+		const measured = natural.width > 0 && natural.height > 0 ? natural : SVG_FALLBACK_SIZE;
+		const scale = Math.min(1, MAX_RASTER_EDGE / Math.max(measured.width, measured.height));
+		const width = Math.max(1, Math.round(measured.width * scale));
+		const height = Math.max(1, Math.round(measured.height * scale));
+		const canvas = document.createElement("canvas");
+		canvas.width = width;
+		canvas.height = height;
+		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);
+	} finally {
+		URL.revokeObjectURL(url);
+	}
+}
+/**
+* 把取到的字节归一成模型收得下的位图（0.13.0）。
+*
+* 两类真实站点上很常见的图会在最后一步被模型侧丢掉：服务端把图报成 `application/octet-stream`，
+* 以及矢量图（三家提供方的图片通道都不收 `image/svg+xml`，分册 20 §0.1）。
+* 前者只是声明错了，按魔数改回来即可；后者必须就地栅格化，否则等于没取到图。
+*
+* **声明一律不采信**：大站 CDN 会按 `Accept` 头改发 AVIF 却仍旧报 `image/webp`，
+* 照抄声明会让端点解码失败并连累整次请求（一张图 400，37 张全废）。
+*
+* 魔数对得上也不等于发得出去，还有两类会被端点整次拒收，必须重编码成单帧位图：
+* - **动图**（GIF 天然多帧，WebP 看 `VP8X` 的动画位）：图片通道普遍只收静态图；
+* - **超长边**：横幅类素材常见 7680×120 这种尺寸，字节数却很小，
+*   纯按字节压缩的预算根本不会触发，原样发出去就撞上端点的边长上限。
+*
+* @param oversized 调用方已知原图长边超限（`<img>` 能直接读到 `naturalWidth`，不必为此解码）
+*/
+async function toDeliverableBlob(blob, oversized = false) {
+	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)) {
+		const typed = sniffed === declared ? blob : new Blob([blob], { type: sniffed });
+		const animated = sniffed === "image/gif" || sniffed === "image/webp" && isAnimatedWebp(head);
+		return oversized || animated ? await rasterizeToPng(typed) : 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 }));
+}
+/**
 * 取一个元素的图像（0.6.0 FR-12.1）。
 *
 * 按元素类型分派，不做无意义的尝试：`<img>` 只走 L1，`<canvas>` / `<svg>` 只走 L2，
 * 两者互不兜底。失败返回 `CaptureFailure` 而不是抛错——一张图抓不到不该让整次感知失败。
 * @experimental
-*/
-async function captureElementImage(element, options) {
+*/ async function captureElementImage(element, options) {
 	const { id, maxBytes } = options;
 	const tag = element.tagName.toUpperCase();
 	if (tag === "IMG") try {
@@ -1708,11 +2030,11 @@ async function captureElementImage(element, options) {
 		};
 	}
 	if (tag === "SVG") try {
-		return captureSvg(element, id, maxBytes);
+		return await captureSvg(element, id, maxBytes);
 	} catch (e) {
 		return {
 			id,
-			reason: `L2 could not serialize the SVG: ${describeError(e)}`,
+			reason: `L2 could not rasterize the SVG: ${describeError(e)}`,
 			triedLevels: ["canvas"]
 		};
 	}
@@ -1727,6 +2049,148 @@ function describeError(e) {
 	if (e instanceof TypeError) return "the request was blocked, most likely by CORS";
 	return e instanceof Error ? e.message : String(e);
 }
+/**
+* 非标可交互元素的识别与角色提升（0.14.0 分册 15）。
+*
+* 现代前端用 `div` / `span` 做按钮是常态，它们在无障碍树里全落到 `generic`，
+* 于是拿不到句柄——模型读得到那几个字，却点不动。本模块补的就是这一段判定。
+*
+* 整套逻辑默认关闭，由 `createDomPerceptionReader` 的 `promoteRoles` 开启（D-15-1）。
+*/
+/**
+* class / id 里的交互语义词根（FR-15.2）。
+*
+* 带词边界匹配：`table` 含 `tab`、`container` 含 `nav`，子串匹配会把它们全误伤（D-15-8）。
+* 图标类单列一支：`icon-view` / `el-icon-download` / `anticon-*` 这类命名带着具体动作语义。
+*/
+const INTERACTIVE_TOKEN = /(?:^|[^a-z])(btn|button|actions?|click(?:able)?|link|menu|nav|tabs?|trigger|operate|operations?|handle|entry|toolbar|[a-z]*icons?(?:[-_][a-z0-9]+)?)(?:[^a-z]|$)/i;
+/** 从图标类名反推语义：`el-icon-view` → `view`、`icon-download` → `download`（FR-15.4 第 2 级） */
+const ICON_CLASS = /[a-z]*icons?[-_]([a-z0-9][a-z0-9-_]*)$/i;
+/** 框架路由属性：值非空即视为确凿的导航线索（FR-15.3 第 2 条） */
+const ROUTE_ATTRIBUTES = [
+	"to",
+	"routerlink",
+	"data-href",
+	"data-url"
+];
+/** 只有这三种角色会被提升：其余角色要么本就能发句柄，要么带着不该被覆盖的语义（D-15-3） */
+const PROMOTABLE_ROLES = /* @__PURE__ */ new Set([
+	"generic",
+	"img",
+	"cell"
+]);
+/** 合成名的前缀，必须让模型看得出「这不是页面上的字，别拿它去搜」（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` 最贵，殿后 */
+function looksClickable(element, view) {
+	if (view === null) return false;
+	try {
+		return view.getComputedStyle(element).cursor === "pointer";
+	} catch {
+		return false;
+	}
+}
+/**
+* 五级信号，命中任一即为真（FR-15.1）。
+*
+* 求值顺序按**成本**排而不是按强度排：前面的廉价信号命中就短路，
+* 把 `getComputedStyle` 这条唯一会触发样式重算的路径留到最后。
+*/
+function looksInteractive(element, context) {
+	if (context.interactiveHint?.(element) === true) return true;
+	const tabindex = element.getAttribute("tabindex");
+	if (tabindex !== null && tabindex.trim() !== "" && tabindex.trim() !== "-1") return true;
+	const title = element.getAttribute("title");
+	if (title !== null && title.trim() !== "") return true;
+	if (INTERACTIVE_TOKEN.test(classAndId(element))) return true;
+	return looksClickable(element, context.view);
+}
+/** 图标类名反推出的语义词；没有图标类则 undefined */
+function iconHintOf(element) {
+	for (const cls of (element.getAttribute("class") ?? "").split(/\s+/)) {
+		const match = ICON_CLASS.exec(cls);
+		if (match === null) continue;
+		const semantic = match[1]?.split("__")[0];
+		if (semantic !== void 0 && semantic !== "") return semantic;
+	}
+}
+/** 宿主逃生舱的角色；命中即无条件提升成声明的角色（FR-15.6） */
+function hintedRoleOf(element, hints) {
+	if (hints === void 0) return void 0;
+	for (const hint of hints) for (const selector of hint.selectors) try {
+		if (element.matches(selector)) return hint.role;
+	} catch {}
+}
+/**
+* 确凿的导航线索（FR-15.3）：拿得到就判 `link`，拿不到一律 `button`。
+*
+* **不看** `cursor` / class 词根 / `onclick` 这类间接迹象——猜错会让模型以为「点了会跳走」
+* 而放弃先把页内信息读完，代价比多标一个 `button` 大。
+*/
+function navigationTargetOf(element, doc) {
+	const own = resolvedHref(element, doc);
+	if (own !== void 0) return own;
+	for (const attribute of ROUTE_ATTRIBUTES) {
+		const value = element.getAttribute(attribute);
+		if (value !== null && value.trim() !== "") return value.trim();
+	}
+	const anchor = element.closest("a[href]");
+	if (anchor !== null && anchor.getAttribute("role") === null) return resolvedHref(anchor, doc);
+}
+/** `href` 解析成绝对地址；不导航的形态（`#`、`javascript:`、空值）一律不算线索 */
+function resolvedHref(element, doc) {
+	const raw = element.getAttribute("href") ?? element.getAttribute("xlink:href");
+	if (raw === null) return void 0;
+	const trimmed = raw.trim();
+	if (trimmed === "" || trimmed === "#" || /^javascript:/i.test(trimmed)) return void 0;
+	try {
+		const url = new URL(trimmed, doc.baseURI);
+		return url.protocol === "http:" || url.protocol === "https:" ? url.href : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* 算不出名字时合成一个可指称的称呼（FR-15.4 第 3 级）。
+*
+* 用「最近具名祖先 + 同级序位」而不是坐标：坐标随滚动和窗口尺寸变，
+* 用户在屏幕上对不上号，模型跨两次感知也认不出是同一个东西。
+*/
+function synthesizeName(element, nameOf) {
+	const siblings = element.parentElement?.children;
+	let position = 0;
+	if (siblings !== void 0) {
+		for (const [index, sibling] of [...siblings].entries()) if (sibling === element) {
+			position = index + 1;
+			break;
+		}
+	}
+	const ordinal = position > 0 ? `${SYNTHETIC_NAME_PREFIX} #${position}` : SYNTHETIC_NAME_PREFIX;
+	let ancestor = element.parentElement;
+	for (let depth = 0; depth < SYNTHETIC_NAME_LOOKUP_DEPTH && ancestor !== null; depth += 1) {
+		const label = nameOf(ancestor);
+		if (label !== void 0 && label !== "") return `${ordinal} in "${label}"`;
+		ancestor = ancestor.parentElement;
+	}
+	return ordinal;
+}
+/** 提升后的角色与导航目标；未提升时返回 undefined */
+function promoteRole(input) {
+	const { element, role, doc, hasActionableDescendant, context } = input;
+	const hinted = hintedRoleOf(element, context.roleHints);
+	if (hinted !== void 0) return { role: hinted };
+	if (!PROMOTABLE_ROLES.has(role)) return void 0;
+	if (hasActionableDescendant && role !== "img") return void 0;
+	if (!looksInteractive(element, context)) return void 0;
+	const href = navigationTargetOf(element, doc);
+	return href !== void 0 ? {
+		role: "link",
+		href
+	} : { role: "button" };
+}
 /** 值可能是凭据的输入类型：即便宿主忘了写进 exclude 也不读值。操作侧复用同一份，不另写 */
 const SECRET_INPUT_TYPES = /* @__PURE__ */ new Set(["password", "hidden"]);
 /** 可被操作的角色：只给这些节点发句柄，其余节点模型连提都提不出来 */
@@ -1804,6 +2268,33 @@ function ownText(element) {
 	for (const node of element.childNodes) if (node.nodeType === 3) text += node.nodeValue ?? "";
 	return clip(text);
 }
+/** 名字全在元素外面的那几种控件 */
+const FORM_CONTROL_TAGS = /* @__PURE__ */ new Set([
+	"INPUT",
+	"TEXTAREA",
+	"SELECT"
+]);
+/**
+* 表单控件的名字来源：`<label>`（关联式与包裹式）、`placeholder`、`title`。
+*
+* 缺了这几级，一个填着「基小建」的输入框在模型眼里就是无名的 textbox——
+* 旁边的 `<label>` 文字它读得到，却接不到这个框上，于是「值明明在结果里，
+* 模型却说不出这是谁」。操作侧的 `accessibleName` 一直取这几级，两边不一致
+* 还会让「感知时叫不出名字、点下去审计里却有名字」。
+*/
+function externalNameOf(element) {
+	const labels = element.labels;
+	if (labels && labels.length > 0) {
+		const joined = [...labels].map((node) => node.textContent ?? "").filter((part) => part.trim() !== "").join(" ");
+		if (joined.trim() !== "") return clip(joined);
+	}
+	const wrapping = element.closest("label")?.textContent ?? "";
+	if (wrapping.trim() !== "") return clip(wrapping);
+	for (const attribute of ["placeholder", "title"]) {
+		const value = element.getAttribute(attribute);
+		if (value !== null && value.trim() !== "") return clip(value);
+	}
+}
 function nameOf(element, doc) {
 	const label = element.getAttribute("aria-label");
 	if (label !== null && label.trim() !== "") return clip(label);
@@ -1816,6 +2307,7 @@ function nameOf(element, doc) {
 		const alt = element.getAttribute("alt");
 		if (alt !== null && alt.trim() !== "") return clip(alt);
 	}
+	if (FORM_CONTROL_TAGS.has(element.tagName)) return externalNameOf(element);
 	const own = ownText(element);
 	return own === "" ? void 0 : own;
 }
@@ -1859,20 +2351,50 @@ const SKIPPED_TAGS = /* @__PURE__ */ new Set([
 ]);
 /** 活动模态的三种形态；Radix 之流用 aria-modal，原生用 <dialog open> */
 const MODAL_SELECTOR = "[role=dialog][open], dialog[open], [aria-modal=true]";
-function describe(element, excluded, doc, view, targets, handles, frame, provenance) {
+/** 按尺寸落选取像的说明（FR-20.3）；与「超名额」「取像失败」必须可区分，三者排查方向不同 */
+const ICON_SKIPPED_NOTE = "Not captured: this image is smaller than the icon threshold";
+/**
+* 元素是否小到该当图标看待（FR-20.3）。
+* 测不到尺寸就**不过滤**：没有布局的环境里宁可多取一张，也不能把图全吞了。
+*/
+function isBelowMinArea(element, minImageArea) {
+	if (minImageArea <= 0) return false;
+	const size = measuredSizeOf(element);
+	if (size === void 0) return false;
+	return size.width * size.height < minImageArea;
+}
+function describe(element, excluded, doc, view, capture, handles, frame, provenance, promotion) {
 	if (excluded.has(element)) return void 0;
 	if (SKIPPED_TAGS.has(element.tagName)) return void 0;
 	if (hidden$1(element, view)) return void 0;
 	const children = [];
 	for (const child of element.children) {
-		const node = describe(child, excluded, doc, view, targets, handles, frame, provenance);
+		const node = describe(child, excluded, doc, view, capture, handles, frame, provenance, promotion);
 		if (node !== void 0) children.push(node);
 	}
-	const name = nameOf(element, doc);
+	let name = nameOf(element, doc);
 	const value = valueOf(element);
-	const role = roleOf$1(element);
-	const href = role === "link" ? hrefOf(element) : void 0;
+	let role = roleOf$1(element);
+	let promotedHref;
+	if (promotion !== void 0) {
+		const promoted = promoteRole({
+			element,
+			role,
+			doc,
+			hasActionableDescendant: children.some((child) => child.ref !== void 0),
+			context: promotion
+		});
+		if (promoted !== void 0) {
+			role = promoted.role;
+			promotedHref = promoted.href;
+			if (name === void 0) name = clip(iconHintOf(element) ?? synthesizeName(element, (a) => nameOf(a, doc)));
+		}
+	}
+	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) {
+		if (children.length === 1) return children[0];
+	}
 	const node = {
 		role,
 		...name !== void 0 ? { name } : {},
@@ -1884,18 +2406,94 @@ function describe(element, excluded, doc, view, targets, handles, frame, provena
 	};
 	const ref = handles?.issue(element, role, frame);
 	if (ref !== void 0) node.ref = ref;
-	if (targets !== void 0 && isCapturableElement(element)) targets.push({
+	if (capture !== void 0 && isCapturableElement(element)) if (isBelowMinArea(element, capture.minImageArea)) node.imageNote = ICON_SKIPPED_NOTE;
+	else capture.targets.push({
 		element,
 		node
 	});
 	return node;
 }
 /**
-* 句柄发放与解析。表在 reader 实例内、每次 `read()` 整体替换：
-* 全局表是第二套状态且会跨会话泄漏；不替换则页面变了还能用旧句柄点到别的东西。
+* 子树里的 `<iframe>`（含根自身），跳过 exclude 命中的整棵子树。
+* 供 FR-18.4 判断「范围里有帧但没被授权」；本函数**不读**这些帧的内容。
+*/
+function nestedFramesIn(root, excluded) {
+	const inExcluded = (element) => {
+		for (let node = element; node !== null; node = node.parentElement) if (excluded.has(node)) return true;
+		return false;
+	};
+	const found = [];
+	if (root.tagName === "IFRAME" && !inExcluded(root)) found.push(root);
+	for (const iframe of root.querySelectorAll("iframe")) if (!inExcluded(iframe)) found.push(iframe);
+	return found;
+}
+/**
+* 未授权嵌套帧的指称。`<iframe>` 的可访问名来自 `title`，而 `nameOf` 走的是
+* aria/文本那一套（帧没有自身文本），所以这里单独取——**只用于说明文本**，
+* 不进任何可操作路径。
+*/
+function frameHint(iframe) {
+	for (const attribute of [
+		"aria-label",
+		"title",
+		"name",
+		"id"
+	]) {
+		const value = iframe.getAttribute(attribute);
+		if (value !== null && value.trim() !== "") return clip(value);
+	}
+	return "unnamed";
+}
+/**
+* 可路由的绝对地址（分册 16 FR-16.1）。
+*
+* 只认 http(s)：`about:blank` / `srcdoc` / `data:` 这些外壳寻不到址，
+* 交出去只会让它拿一个匹配不上任何 frameId 的字符串去猜。
+*/
+function httpUrlOf(value, base) {
+	try {
+		const url = new URL(value, base);
+		return url.protocol === "http:" || url.protocol === "https:" ? url.href : void 0;
+	} catch {
+		return;
+	}
+}
+function routableUrlOf(iframe, doc) {
+	try {
+		const live = iframe.contentWindow?.location?.href;
+		if (live !== void 0 && live !== "about:blank") {
+			const routable = httpUrlOf(live, doc.baseURI);
+			if (routable !== void 0) return routable;
+		}
+	} catch {}
+	const src = iframe.getAttribute("src");
+	if (src === null || src.trim() === "") return void 0;
+	return httpUrlOf(src, doc.baseURI);
+}
+/**
+* 同源嵌套帧的文档；跨源与尚未就绪时返回 `undefined`。
+*
+* 跨源时 `contentDocument` 返回 `null` 而**不抛异常**，某些引擎在别的属性上才抛——
+* 两种形态都要接住，只写 try/catch 会漏掉前一种。
+*/
+function sameOriginDocumentOf(iframe) {
+	try {
+		const inner = iframe.contentDocument;
+		return inner === null || inner.body === null ? void 0 : inner;
+	} catch {
+		return;
+	}
+}
+/**
+* 句柄发放与解析。表在 reader 实例内、**跨感知保留**（分册 18 FR-18.5）：
+* 每次 read() 作废全部旧句柄会让多步任务陷入「读—点—失效—再读」的空转，
+* 而安全性本就不由句柄寿命承担——执行前的 `modalStateOf` / `inActionScope` /
+* 可见性 / 可用性四道校验才是闸门，它们按**执行那一刻**的 DOM 实时判定。
 */
 var HandleIssuer = class {
 	#table = /* @__PURE__ */ new Map();
+	/** 同一元素复用同一个 ref：模型重读页面后手里的句柄仍然指向同一个东西 */
+	#refByElement = /* @__PURE__ */ new WeakMap();
 	#actionable;
 	#excluded;
 	constructor(actionable, excluded) {
@@ -1907,9 +2505,24 @@ var HandleIssuer = class {
 		this.#actionable = actionable;
 		this.#excluded = excluded;
 	}
+	/**
+	* 丢弃已离开文档的条目。**只防表随长会话无限膨胀，不是安全判据**——
+	* 「元素还在但已挪出授权范围」这一类由执行前的第二道闸门拦（FR-18.5）。
+	*/
+	prune() {
+		for (const [ref, entry] of this.#table) if (!entry.element.isConnected) this.#table.delete(ref);
+	}
 	issue(element, role, frame) {
 		if (!this.#actionable.has(element) || this.#excluded.has(element)) return void 0;
 		if (!ACTIONABLE_ROLES.has(role)) return void 0;
+		const known = this.#refByElement.get(element);
+		if (known !== void 0 && this.#table.has(known)) {
+			this.#table.set(known, {
+				element,
+				...frame !== void 0 ? { frame } : {}
+			});
+			return known;
+		}
 		const bytes = /* @__PURE__ */ new Uint8Array(8);
 		crypto.getRandomValues(bytes);
 		const ref = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -1917,6 +2530,7 @@ var HandleIssuer = class {
 			element,
 			...frame !== void 0 ? { frame } : {}
 		});
+		this.#refByElement.set(element, ref);
 		return ref;
 	}
 	get table() {
@@ -1941,41 +2555,60 @@ function createDomPerceptionReader(options = {}) {
 	*/
 	const elevatedModals = /* @__PURE__ */ new Set();
 	const rootDocument = () => options.document ?? globalThis.document;
+	/** 提升未开启时返回 undefined，遍历侧据此整段跳过（AC-G10） */
+	const promotionOf = (view) => options.promoteRoles === true ? {
+		view,
+		...options.interactiveHint !== void 0 ? { interactiveHint: options.interactiveHint } : {},
+		...options.roleHints !== void 0 ? { roleHints: options.roleHints } : {}
+	} : void 0;
 	/**
-	* 把一条帧授权解析成 Document。
+	* 把一条帧授权解析成 Document，逐层下钻（分册 18 FR-18.3）。
 	*
 	* 跨源时 `contentDocument` 在多数浏览器返回 `null` 而**不抛异常**，
 	* 只有部分属性访问才抛 —— 所以两种形态都要处理，只写 try/catch 会漏。
 	*/
 	function resolveFrame(frame, root) {
-		if (frame === "self") return { doc: root };
-		const element = root.querySelector(frame);
-		if (element === null || element.tagName !== "IFRAME") return { note: {
-			frame,
-			reason: "not-found",
-			message: `Frame "${frame}" was not found in the page.`
-		} };
-		let doc;
-		let origin;
-		try {
-			doc = element.contentDocument;
-			origin = element.contentWindow?.location.origin;
-		} catch {
-			doc = null;
-		}
-		if (doc === null || origin === void 0) return { note: {
-			frame,
-			reason: "cross-origin",
-			message: `Frame "${frame}" is cross-origin and was not read.`
-		} };
-		const known = frameOrigins.get(frame);
-		if (known === void 0) frameOrigins.set(frame, origin);
-		else if (known !== origin) return { note: {
-			frame,
-			reason: "origin-changed",
-			message: `Frame "${frame}" now points at ${origin} instead of the authorized ${known}; the grant was revoked.`
-		} };
-		return { doc };
+		const steps = frameSteps(frame);
+		const label = frameLabel(frame);
+		let doc = root;
+		const frames = [];
+		for (const [index, selector] of steps.entries()) {
+			const hop = `step ${index + 1} ("${selector}") of frame path "${label}"`;
+			const element = doc.querySelector(selector);
+			if (element === null || element.tagName !== "IFRAME") return { note: {
+				frame: label,
+				reason: "not-found",
+				message: `Frame ${hop} was not found in the page.`
+			} };
+			const iframe = element;
+			let next;
+			let origin;
+			try {
+				next = iframe.contentDocument;
+				origin = iframe.contentWindow?.location.origin;
+			} catch {
+				next = null;
+			}
+			if (next === null || origin === void 0) return { note: {
+				frame: label,
+				reason: "cross-origin",
+				message: `Frame ${hop} is cross-origin and was not read.`
+			} };
+			const key = frameLabel(steps.slice(0, index + 1));
+			const known = frameOrigins.get(key);
+			if (known === void 0) frameOrigins.set(key, origin);
+			else if (known !== origin) return { note: {
+				frame: label,
+				reason: "origin-changed",
+				message: `Frame ${hop} now points at ${origin} instead of the authorized ${known}; the grant was revoked.`
+			} };
+			doc = next;
+			frames.push(iframe);
+		}
+		return {
+			doc,
+			frames
+		};
 	}
 	/** 按当前 DOM 重算一次可操作集合；发句柄与执行前各算一次 */
 	const actionSets = (doc, scope) => {
@@ -1998,49 +2631,126 @@ function createDomPerceptionReader(options = {}) {
 			excluded
 		};
 	};
-	/** 该帧的操作范围；没有对应条目就是「这个帧只可读不可操作」 */
-	const actionScopeFor = (frame) => options.actionScope === void 0 ? void 0 : toActionFrameScopes(options.actionScope).find((entry) => entry.frame === frame);
-	function collect(scope, targets) {
+	/** 该帧的操作范围；没有对应条目就是「这个帧只可读不可操作」。按展示串匹配（FR-18.2） */
+	const actionScopeFor = (label) => options.actionScope === void 0 ? void 0 : toActionFrameScopes(options.actionScope).find((entry) => frameLabel(entry.frame) === label);
+	function collect(scope, capture) {
 		const root = rootDocument();
 		if (root === void 0) return {
 			nodes: [],
-			frameNotes: []
+			frameNotes: [],
+			nestedFrames: []
 		};
-		handles = new HandleIssuer(/* @__PURE__ */ new Set(), /* @__PURE__ */ new Set());
+		handles ??= new HandleIssuer(/* @__PURE__ */ new Set(), /* @__PURE__ */ new Set());
+		handles.prune();
+		const issuer = handles;
 		const nodes = [];
 		const frameNotes = [];
+		const nestedFrames = [];
+		/** 同一个未授权 iframe 至多报一次（它可能同时落在多个 include 根的子树里） */
+		const reportedUnauthorized = /* @__PURE__ */ new Set();
+		const resolvedScopes = [];
+		const authorizedFrames = /* @__PURE__ */ new Set();
 		for (const frameScope of toFrameScopes(scope)) {
 			if (frameScope.include.length === 0) continue;
+			const label = frameLabel(frameScope.frame);
 			const resolved = resolveFrame(frameScope.frame, root);
 			if ("note" in resolved) {
 				frameNotes.push(resolved.note);
 				nodes.push({
 					role: "note",
 					name: resolved.note.message,
-					frame: frameScope.frame
+					frame: label
 				});
 				continue;
 			}
-			const doc = resolved.doc;
+			for (const iframe of resolved.frames) authorizedFrames.add(iframe);
+			resolvedScopes.push({
+				scope: frameScope,
+				label,
+				doc: resolved.doc
+			});
+		}
+		/**
+		* 范围内未授权嵌套帧的处置（分册 16 FR-16.1）。
+		*
+		* 递归而不是循环固定层数：0.13.0 D-18-8 用「路径是宿主写死的数组」论证深度上限，
+		* 自动发现一进来这个前提就没了。兜底改由**帧数与节点总预算**承担，
+		* 层数是错的度量（见分册 16 §0.2）。
+		*/
+		function descendFrames(roots, doc, excluded, frameScope, label, tag, actionable, actionExcluded) {
+			for (const element of roots) for (const iframe of nestedFramesIn(element, excluded)) {
+				if (authorizedFrames.has(iframe)) continue;
+				if (reportedUnauthorized.has(iframe)) continue;
+				reportedUnauthorized.add(iframe);
+				const hint = frameHint(iframe);
+				if (options.discoverNestedFrames === true) {
+					const url = routableUrlOf(iframe, doc);
+					if (url !== void 0) {
+						nestedFrames.push({
+							url,
+							hint,
+							...tag !== void 0 ? { frame: tag } : {}
+						});
+						continue;
+					}
+					const inner = sameOriginDocumentOf(iframe);
+					if (inner !== void 0 && inlineFrame(inner, iframe, frameScope, label, tag, actionable, actionExcluded)) continue;
+				}
+				nodes.push({
+					role: "note",
+					name: `A nested frame "${hint}" inside "${label}" is not part of the authorized scope and was not read. Ask the user to authorize it if its content is needed.`,
+					...tag !== void 0 ? { frame: tag } : {}
+				});
+			}
+		}
+		/**
+		* 无地址同源帧的就地内联；成功返回 `true`。
+		*
+		* `srcdoc` / `about:blank` 没有可路由地址，外壳寻不到址，只能由父帧代读。
+		*
+		* 可操作性**继承自那个 `<iframe>` 元素本身**：它由父页面写入内容，视觉上就是父页面的一部分，
+		* 父帧的 action scope 把它圈进来了就等于圈进了它的内容；没圈进来则帧内一个句柄都不发。
+		* exclude 在子文档里重新求值——敏感控件在每一层都要剪掉，不因为它在帧里就放宽（§0.1 边界 3）。
+		*/
+		function inlineFrame(inner, iframe, frameScope, label, tag, actionable, actionExcluded) {
+			const innerExcluded = /* @__PURE__ */ new Set();
+			for (const selector of frameScope.exclude ?? []) for (const target of inner.querySelectorAll(selector)) innerExcluded.add(target);
+			const innerActionable = /* @__PURE__ */ new Set();
+			const innerActionExcluded = /* @__PURE__ */ new Set();
+			if (actionable.has(iframe)) {
+				innerActionable.add(inner.body);
+				for (const descendant of inner.body.querySelectorAll("*")) innerActionable.add(descendant);
+				for (const selector of actionScopeFor(label)?.exclude ?? []) for (const target of inner.querySelectorAll(selector)) innerActionExcluded.add(target);
+			}
+			issuer.useSets(innerActionable, innerActionExcluded);
+			const innerView = inner.defaultView;
+			const node = describe(inner.body, innerExcluded, inner, innerView, capture, issuer, tag, "inline-frame", promotionOf(innerView));
+			if (node !== void 0) nodes.push(node);
+			descendFrames([inner.body], inner, innerExcluded, frameScope, label, tag, innerActionable, innerActionExcluded);
+			issuer.useSets(actionable, actionExcluded);
+			return node !== void 0;
+		}
+		for (const { scope: frameScope, label, doc } of resolvedScopes) {
 			const view = doc.defaultView;
-			const tag = frameScope.frame === "self" ? void 0 : frameScope.frame;
-			const sets = actionSets(doc, actionScopeFor(frameScope.frame));
-			handles.useSets(sets.actionable, sets.excluded);
+			const tag = label === "self" ? void 0 : label;
+			const sets = actionSets(doc, actionScopeFor(label));
+			issuer.useSets(sets.actionable, sets.excluded);
 			const excluded = /* @__PURE__ */ new Set();
 			for (const selector of frameScope.exclude ?? []) for (const element of doc.querySelectorAll(selector)) excluded.add(element);
 			const roots = [];
 			for (const selector of frameScope.include) for (const element of doc.querySelectorAll(selector)) if (!roots.includes(element)) roots.push(element);
 			for (const element of roots) {
-				const node = describe(element, excluded, doc, view, targets, handles, tag, void 0);
+				const node = describe(element, excluded, doc, view, capture, issuer, tag, void 0, promotionOf(view));
 				if (node !== void 0) nodes.push(node);
 			}
+			descendFrames(roots, doc, excluded, frameScope, label, tag, sets.actionable, sets.excluded);
 		}
 		pruneElevated();
 		const view = root.defaultView;
 		const sets = actionSets(root, actionScopeFor("self"));
 		for (const modal of elevatedModals) {
-			handles.useSets(/* @__PURE__ */ new Set([modal, ...modal.querySelectorAll("*")]), sets.excluded);
-			const node = describe(modal, /* @__PURE__ */ new Set(), root, view, targets, handles, void 0, "modal-elevated");
+			issuer.useSets(/* @__PURE__ */ new Set([modal, ...modal.querySelectorAll("*")]), sets.excluded);
+			const node = describe(modal, /* @__PURE__ */ new Set(), root, view, capture, issuer, void 0, "modal-elevated", promotionOf(view));
 			if (node !== void 0) nodes.push(node);
 		}
 		for (const modal of root.querySelectorAll(MODAL_SELECTOR)) {
@@ -2053,12 +2763,16 @@ function createDomPerceptionReader(options = {}) {
 		}
 		return {
 			nodes,
-			frameNotes
+			frameNotes,
+			nestedFrames
 		};
 	}
 	async function readWithImages(scope, capture) {
 		const targets = [];
-		const { nodes, frameNotes } = collect(scope, targets);
+		const { nodes, frameNotes, nestedFrames } = collect(scope, {
+			targets,
+			minImageArea: capture.minImageArea ?? 0
+		});
 		const selected = targets.slice(0, capture.maxImages);
 		const images = [];
 		let imageFailures = 0;
@@ -2086,16 +2800,18 @@ function createDomPerceptionReader(options = {}) {
 			images,
 			imagesOmitted: targets.length - selected.length,
 			imageFailures,
-			...frameNotes.length > 0 ? { frameNotes } : {}
+			...frameNotes.length > 0 ? { frameNotes } : {},
+			...nestedFrames.length > 0 ? { nestedFrames } : {}
 		};
 	}
 	function read(scope, capture) {
 		if (capture === void 0) return collect(scope, void 0).nodes;
 		if (!capture.images || capture.maxImages <= 0) {
-			const { nodes, frameNotes } = collect(scope, void 0);
+			const { nodes, frameNotes, nestedFrames } = collect(scope, void 0);
 			return Promise.resolve({
 				nodes,
-				...frameNotes.length > 0 ? { frameNotes } : {}
+				...frameNotes.length > 0 ? { frameNotes } : {},
+				...nestedFrames.length > 0 ? { nestedFrames } : {}
 			});
 		}
 		return readWithImages(scope, capture);
@@ -2137,14 +2853,21 @@ function createDomPerceptionReader(options = {}) {
 			return sets.actionable.has(element) && !sets.excluded.has(element);
 		}
 	};
-	/** 反查一个 Document 属于哪条帧授权；不在授权列表里的帧一律判不可操作 */
+	/**
+	* 反查一个 Document 属于哪条帧授权，返回它的展示串；不在授权列表里的帧一律判不可操作。
+	* 没有反向解析展示串（那是不成立的，D-18-1），而是把每条授权路径重新走一遍后比对
+	* 文档对象：路径中任一层被换掉 / origin 变了，这里就对不上，旧句柄因此失效。
+	*/
 	function frameOfDocument(doc) {
 		const root = rootDocument();
 		if (root === void 0) return void 0;
 		if (doc === root) return "self";
-		for (const frame of frameOrigins.keys()) {
-			const element = root.querySelector(frame);
-			if (element?.tagName === "IFRAME" && element.contentDocument === doc) return frame;
+		if (options.actionScope === void 0) return void 0;
+		for (const entry of toActionFrameScopes(options.actionScope)) {
+			if (frameSteps(entry.frame).length === 0) continue;
+			const resolved = resolveFrame(entry.frame, root);
+			if ("note" in resolved) continue;
+			if (resolved.doc === doc) return frameLabel(entry.frame);
 		}
 	}
 }
@@ -2367,13 +3090,27 @@ function createDomPageActionExecutor(options) {
 		if (hidden(element)) return fail("The element is not visible.");
 		if (element.hasAttribute("disabled")) return fail("The element is disabled.");
 		const modalsBefore = reader.modalSnapshot();
+		const frameView = element.ownerDocument.defaultView;
+		const urlBefore = frameView?.location.href;
 		const done = async (outcome) => {
 			if (!outcome.ok) return outcome;
-			const elevated = await waitFor(() => reader.elevateNewModals(modalsBefore), 500) ?? reader.elevateNewModals(modalsBefore);
+			const settled = await waitFor(() => {
+				const modal = reader.elevateNewModals(modalsBefore);
+				if (modal !== void 0) return { modal };
+				const url = frameView?.location.href;
+				return url !== void 0 && url !== urlBefore ? { url } : void 0;
+			}, 500);
+			const elevated = settled !== void 0 && "modal" in settled ? settled.modal : reader.elevateNewModals(modalsBefore);
 			const name = elevated === void 0 ? void 0 : accessibleName(elevated) ?? "dialog";
-			return name === void 0 ? outcome : {
+			const urlAfter = frameView?.location.href;
+			const navigated = urlAfter !== void 0 && urlBefore !== void 0 && urlAfter !== urlBefore;
+			return {
 				...outcome,
-				elevatedModal: name
+				...name !== void 0 ? { elevatedModal: name } : {},
+				...navigated ? {
+					navigated: true,
+					documentUrl: urlAfter
+				} : {}
 			};
 		};
 		if (request.action === "click") {
@@ -2431,6 +3168,182 @@ function createDomPageActionExecutor(options) {
 		describe
 	};
 }
+/** @experimental */
+function createRemoteTargetRegistry() {
+	let table = /* @__PURE__ */ new Map();
+	return {
+		/**
+		* 整表替换而非合并（FR-13.2）：合并会让上一次感知的 ref 在本次感知后仍然可执行——
+		* 那正是 `PAGE_ACTION_STALE_REF` 要拦的东西。本地形态里旧 ref 天然失效
+		* （DOM 重新遍历、句柄表 prune 掉离开文档的条目），远端必须手动复现这个失效语义，
+		* 否则远端比本地更松。
+		*/
+		replace(entries) {
+			const next = /* @__PURE__ */ new Map();
+			for (const entry of entries) {
+				const { ref, role, name, secret, frame, elevated } = entry;
+				next.set(ref, {
+					role,
+					...name !== void 0 ? { name } : {},
+					...secret === true ? { secret: true } : {},
+					...frame !== void 0 ? { frame } : {},
+					...elevated === true ? { elevated: true } : {}
+				});
+			}
+			table = next;
+		},
+		get(ref) {
+			return table.get(ref);
+		},
+		get size() {
+			return table.size;
+		}
+	};
+}
+/** 缺省单次往返上限（FR-13.2 / FR-13.3） */
+const DEFAULT_PAGE_AGENT_TIMEOUT_MS = 1e4;
+/**
+* 一次带超时的往返，并把三类失败统一成 `WebSkillError`（FR-13.6）。
+*
+* 三类都必须显式失败，**绝不降级成空结果**：
+* 空节点数组的含义是「页面上什么都没有」，模型收到它会据此作答，
+* 比报错危险得多——报错至少不会产出一个自信的错误回答。
+*
+* @param expect 期望的应答类型；对不上通常意味着装错了 agent 版本，
+*   静默容忍会把问题推到很远的地方才暴露。
+*/
+async function roundTrip(transport, request, expect, code, timeoutMs) {
+	let timer;
+	let reply;
+	try {
+		reply = await Promise.race([transport.send(request), new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(new WebSkillError(code, `Page agent request "${request.type}" timed out after ${timeoutMs}ms with no reply from the page.`)), timeoutMs);
+		})]);
+	} catch (e) {
+		if (e instanceof WebSkillError) throw e;
+		const message = e instanceof Error ? e.message : String(e);
+		throw new WebSkillError(code, `Page agent request "${request.type}" failed: ${message}`);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+	if (reply.type === "error") throw new WebSkillError(reply.code, reply.message);
+	if (reply.type !== expect) throw new WebSkillError(code, `Page agent replied with "${reply.type}" to a "${request.type}" request; expected "${expect}".`);
+	return reply;
+}
+/**
+* 跨上下文的页面感知（分册 13 / FR-13.2）。
+*
+* 把句柄描述表写进 registry，**只把 `result` 返回给调用方**——
+* 返回值就是标准 `PerceptionResult`，不夹带任何新字段（AC-13.2）。
+* @experimental
+*/
+function createRemotePerceptionReader(options) {
+	const { transport, targets, timeoutMs = DEFAULT_PAGE_AGENT_TIMEOUT_MS } = 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);
+		return reply.result;
+	} };
+}
+/**
+* 跨上下文的页面操作执行器（分册 13 / FR-13.3）。
+* @experimental
+*/
+function createRemotePageActionExecutor(options) {
+	const { transport, targets, timeoutMs = DEFAULT_PAGE_AGENT_TIMEOUT_MS } = options;
+	return {
+		/**
+		* **同步**查表。`PageActionPolicy.act()` 在弹确认卡之前调它，
+		* 拿到的 target 决定卡上写什么、是否 `secret`、是否 `elevated`——
+		* 改成异步就是改 `@webskill/agent` 的公开契约。
+		*
+		* 表里没有即 `undefined`，于是 `act()` 抛 `PAGE_ACTION_STALE_REF`：
+		* 没感知过就执行 = 拒绝，宁可让模型多感知一次（fail-closed）。
+		*/
+		describe(ref) {
+			return targets.get(ref);
+		},
+		/**
+		* 原样返回远端**执行那一刻**回填的 outcome（FR-13.5）：
+		* 不用 registry 里的快照拼装，也不补默认值——
+		* 补出来的 `false` 与「远端没报」在审计上不是一回事。
+		*/
+		async execute(request) {
+			return (await roundTrip(transport, {
+				type: "execute",
+				request
+			}, "execute-result", "TOOL_EXECUTION_FAILED", timeoutMs)).outcome;
+		}
+	};
+}
+/** 深度收集句柄；顺序即遍历序，便于与本地形态逐条比对 */
+function collectRefs(nodes, out = []) {
+	for (const node of nodes) {
+		if (node.ref !== void 0) out.push(node.ref);
+		if (node.children !== void 0) collectRefs(node.children, out);
+	}
+	return out;
+}
+/**
+* 页面侧处理器（分册 13 / FR-13.7）。
+*
+* 必须是工厂而不是裸函数：`DomPerceptionReader` **是有状态的**——
+* `resolve(ref)` 依赖上一次感知发出的句柄表，模态提升状态也跨调用累积。
+* 每次请求新建 reader，`execute` 就永远 resolve 不到 `perceive` 发出的 ref。
+*
+* 它**不自己收发消息**：只做「请求进、应答出」。监听消息通道、判断消息是不是给自己的、
+* 回不回 `true`——那些全是宿主的事，本包不得出现任何扩展 API。
+* @experimental
+*/
+function createPageAgentHandler(options = {}) {
+	const reader = createDomPerceptionReader({
+		...options.document !== void 0 ? { document: options.document } : {},
+		...options.actionScope !== void 0 ? { actionScope: options.actionScope } : {},
+		...options.promoteRoles !== void 0 ? { promoteRoles: options.promoteRoles } : {},
+		...options.interactiveHint !== void 0 ? { interactiveHint: options.interactiveHint } : {},
+		...options.roleHints !== void 0 ? { roleHints: options.roleHints } : {},
+		...options.discoverNestedFrames !== void 0 ? { discoverNestedFrames: options.discoverNestedFrames } : {}
+	});
+	const executor = createDomPageActionExecutor({
+		reader,
+		...options.pickFiles !== void 0 ? { pickFiles: options.pickFiles } : {}
+	});
+	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;
+				const targets = [];
+				for (const ref of collectRefs(result.nodes)) {
+					const target = executor.describe(ref);
+					if (target !== void 0) targets.push({
+						ref,
+						...target
+					});
+				}
+				return {
+					type: "perceive-result",
+					result,
+					targets
+				};
+			}
+			return {
+				type: "execute-result",
+				outcome: await executor.execute(request.request)
+			};
+		} catch (e) {
+			return {
+				type: "error",
+				code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
+				message: e instanceof Error ? e.message : String(e)
+			};
+		}
+	} };
+}
 const isRecord = (v) => typeof v === "object" && v !== null;
 const isNonEmptyString = (v) => typeof v === "string" && v !== "";
 /** Worker 侧入站校验：非法消息返回 undefined（忽略） */
@@ -3392,6 +4305,255 @@ async function extractDocxText(bytes) {
 	return blocks.join("\n").replace(/\n{3,}/g, "\n\n").trim();
 }
 /**
+* xlsx 文本抽取（0.13.0 分册 12）。
+*
+* **零新增依赖**：xlsx 和 docx 是同一种容器（OPC = zip + XML），
+* 所以沿用 docx 那条路 —— zip 走仓内既有的 `unzipWithLimits`（fflate，
+* 自带解压体积上限，顺带挡住 zip 炸弹），XML 走浏览器原生 `DOMParser`。
+*
+* ⚠️ `DOMParser` 是浏览器 API，Node 没有 —— 所以这个模块只在 `@webskill/browser`。
+* Node 宿主没有 xlsx 能力，与 docx 同一条**显式声明**的限制，不是静默降级（备案 D55）。
+*/
+/**
+* **不抽取**的内容，逐条写明而不是笼统说「尽力而为」（FR-12.4）。
+*
+* 公式只取 Excel 自己写进文件的缓存值：零依赖求值等于自写一个表达式引擎。
+*/
+const XLSX_UNEXTRACTED = [
+	"styles",
+	"conditional formatting",
+	"merged cell reconstruction",
+	"charts",
+	"images",
+	"comments",
+	"pivot tables",
+	"macros",
+	"hidden row and column marking",
+	"formula expressions (only cached values are read)"
+];
+const WORKBOOK = "xl/workbook.xml";
+const WORKBOOK_RELS = "xl/_rels/workbook.xml.rels";
+const SHARED_STRINGS = "xl/sharedStrings.xml";
+const STYLES = "xl/styles.xml";
+/** OLE2 复合文档签名：旧版 .xls 的开头，它不是 zip，走不到解压那一步 */
+const OLE2_SIGNATURE = [
+	208,
+	207,
+	17,
+	224,
+	161,
+	177,
+	26,
+	225
+];
+/** 内建的日期/时间数字格式 id（ECMA-376 §18.8.30） */
+const BUILTIN_DATE_FORMATS = /* @__PURE__ */ new Set([
+	14,
+	15,
+	16,
+	17,
+	18,
+	19,
+	20,
+	21,
+	22,
+	45,
+	46,
+	47
+]);
+function fail(message) {
+	throw new WebSkillError("TOOL_EXECUTION_FAILED", message);
+}
+/** 按 localName 取子孙元素，忽略命名空间前缀：不同生成器的前缀写法并不统一 */
+const byTag = (scope, name) => [...scope.getElementsByTagNameNS("*", name)];
+function parseXml(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;
+}
+/** `B` → 1、`AA` → 26；拿不到列号时返回 undefined，由调用方顺位补上 */
+function columnIndex(ref) {
+	if (ref === null) return void 0;
+	let index = 0;
+	let seen = false;
+	for (const ch of ref) {
+		const code = ch.charCodeAt(0);
+		if (code < 65 || code > 90) break;
+		index = index * 26 + (code - 64);
+		seen = true;
+	}
+	return seen ? index - 1 : void 0;
+}
+/**
+* 一个 `<si>` 的文本。富文本会被切成多个 `<r>`，须拼接；
+* `<rPh>` 是日文注音，拼进去会在正文里插入读音噪声，跳过。
+*/
+function sharedStringText(si) {
+	let out = "";
+	for (const child of si.children) {
+		const tag = child.localName;
+		if (tag === "t") out += child.textContent ?? "";
+		else if (tag === "r") {
+			for (const run of child.children) if (run.localName === "t") out += run.textContent ?? "";
+		}
+	}
+	return out;
+}
+/**
+* 数字格式是否表示日期/时间。
+*
+* `[h]:mm:ss` 这类方括号包住时分秒的是**经过时长**（可以是 25:30），不是时刻，
+* 按日期换算会得出荒谬结果，先排掉。
+*/
+function isDateFormatCode(code) {
+	if (/\[[hms]+\]/i.test(code)) return false;
+	const stripped = code.replace(/"[^"]*"/g, "").replace(/\[[^\]]*\]/g, "").replace(/\\./g, "");
+	return /[ymdhs]/i.test(stripped);
+}
+/** 单元格样式索引 → 是否日期格式 */
+function readDateStyles(bytes) {
+	if (bytes === void 0) return [];
+	const doc = parseXml(bytes, "styles");
+	const custom = /* @__PURE__ */ new Map();
+	for (const fmt of byTag(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(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");
+		if (!Number.isFinite(id)) return false;
+		const code = custom.get(id);
+		return code !== void 0 ? isDateFormatCode(code) : BUILTIN_DATE_FORMATS.has(id);
+	});
+}
+const pad = (n, width = 2) => String(n).padStart(width, "0");
+/**
+* Excel 日期序列号 → ISO 8601。
+*
+* 1900 历制里序列号 60 是**不存在的 1900-02-29**：Excel 为兼容 Lotus 1-2-3
+* 保留了这个错误。不特判它，1900-03-01 之后的全部日期都会差一天。
+*/
+function serialToIso(serial, date1904) {
+	const whole = Math.floor(serial);
+	const fraction = serial - whole;
+	let seconds = Math.round(fraction * 86400);
+	let days = whole;
+	if (seconds >= 86400) {
+		seconds -= 86400;
+		days += 1;
+	}
+	let iso;
+	if (!date1904 && days === 60) iso = "1900-02-29";
+	else {
+		const at = new Date((date1904 ? Date.UTC(1904, 0, 1) : days < 60 ? Date.UTC(1899, 11, 31) : Date.UTC(1899, 11, 30)) + days * 864e5);
+		iso = `${pad(at.getUTCFullYear(), 4)}-${pad(at.getUTCMonth() + 1)}-${pad(at.getUTCDate())}`;
+	}
+	if (seconds === 0) return iso;
+	const h = Math.floor(seconds / 3600);
+	const m = Math.floor(seconds % 3600 / 60);
+	const s = seconds % 60;
+	return `${iso}T${pad(h)}:${pad(m)}:${pad(s)}`;
+}
+/** 一个 `<c>` 的呈现文本（FR-12.3） */
+function cellText(cell, shared, dateStyles, date1904) {
+	const type = cell.getAttribute("t");
+	if (type === "inlineStr") {
+		const is = [...cell.children].find((child) => child.localName === "is");
+		return is !== void 0 ? sharedStringText(is) : "";
+	}
+	const raw = [...cell.children].find((child) => child.localName === "v")?.textContent ?? "";
+	if (raw === "") return "";
+	if (type === "s") {
+		const index = Number(raw);
+		return Number.isInteger(index) ? shared[index] ?? "" : "";
+	}
+	if (type === "str" || type === "e") return raw;
+	if (type === "b") return raw === "1" ? "TRUE" : "FALSE";
+	const numeric = Number(raw);
+	if (!Number.isFinite(numeric)) return raw;
+	const styleIndex = Number(cell.getAttribute("s") ?? "0");
+	if (Number.isInteger(styleIndex) && dateStyles[styleIndex] === true) return serialToIso(numeric, date1904);
+	return raw;
+}
+/**
+* 一张工作表的文本：一行一行，单元格用制表符分隔（与 docx 的表格同口径）。
+* 空行与空列**照原样留着** —— 位置本身是语义，压掉之后「第 3 列」就对不上了。
+*/
+function sheetText(doc, shared, dateStyles, date1904) {
+	const lines = [];
+	let previousRow = 0;
+	for (const row of byTag(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("");
+		previousRow = rowNumber;
+		const cells = [];
+		let nextColumn = 0;
+		for (const cell of row.children) {
+			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);
+			if (cells.length > column) cells[column] = text;
+			else cells.push(text);
+			nextColumn = column + 1;
+		}
+		lines.push(cells.join("	").replace(/\t+$/, ""));
+	}
+	while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines.join("\n");
+}
+const looksLikeOle2 = (bytes) => bytes.length >= OLE2_SIGNATURE.length && OLE2_SIGNATURE.every((byte, i) => bytes[i] === byte);
+/** rels 里的 Target 可能是相对 `xl/` 的，也可能是包根绝对路径 */
+function resolveSheetPath(target) {
+	const clean = target.replace(/^\.\//, "");
+	return clean.startsWith("/") ? clean.slice(1) : `xl/${clean}`;
+}
+/**
+* 从 xlsx 字节里抽出文本，每个工作表一段、段首是表名。
+*
+* @throws WebSkillError 归档损坏、旧版 `.xls`、缺 `xl/workbook.xml`、工作表关系解不开、XML 解析失败
+*/
+async function extractXlsxText(bytes) {
+	if (looksLikeOle2(bytes)) fail("This is a legacy .xls workbook, which is not supported. Save it as .xlsx and try again.");
+	let entries;
+	try {
+		entries = await unzipWithLimits(bytes);
+	} catch {
+		fail("This file could not be read as an Excel workbook: the archive is damaged or not a .xlsx file.");
+	}
+	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(workbookBytes, "index");
+	const workbookPr = byTag(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(parseXml(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(parseXml(sharedBytes, "shared strings"), "si").map(sharedStringText);
+	const dateStyles = readDateStyles(parts.get(STYLES));
+	const sections = [];
+	for (const [ordinal, sheet] of byTag(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;
+		const sheetBytes = path !== void 0 ? parts.get(path) : void 0;
+		if (sheetBytes === void 0) fail(`The worksheet "${name}" could not be located inside the workbook.`);
+		const body = sheetText(parseXml(sheetBytes, `worksheet "${name}"`), shared, dateStyles, date1904);
+		sections.push(body === "" ? `Sheet: ${name}` : `Sheet: ${name}\n${body}`);
+	}
+	return sections.join("\n\n");
+}
+/**
 * 文档投放面的 CSP 单一来源（0.11.0 分册 18 FR-18.3 / AC-G21）。
 *
 * ⚠️ 策略**只能**由 viewer 路由的响应头下发。
@@ -3635,4 +4797,4 @@ function originOf(blockedURI) {
 }
 
 //#endregion
-export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_UNEXTRACTED, HOST_PORT_MATRIX, IframeWorkerLike, OpfsProvider, TsTranspiler, VIEWER_SANDBOX_TOKENS, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, blockedMessage, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractDocxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };
+export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_UNEXTRACTED, HOST_PORT_MATRIX, IframeWorkerLike, OpfsProvider, SANDBOX_PAGE_SCRIPT_SOURCE, TsTranspiler, VIEWER_SANDBOX_TOKENS, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, XLSX_UNEXTRACTED, blockedMessage, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createIframeWorker, createLlmClient, createPageAgentHandler, createRemotePageActionExecutor, createRemotePerceptionReader, createRemoteTargetRegistry, deleteMemoryEncryptionKey, extractDocxText, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };