@webskill/sdk 0.12.0 → 0.13.0

package/dist/browser.js

@@ -1,6 +1,6 @@
 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 { $ 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-ExSQky4C.js";
+import { D as toFrameScopes, E as toActionFrameScopes, T as frameSteps, w as frameLabel } from "./dist-GK6dtjRv.js";
 import { n as MockLlmClient } from "./testing-WPTyXQYt.js";
 
 //#region ../browser/dist/index.js
@@ -1650,12 +1650,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", new Blob([bytes], { type: inline.mimeType }), maxBytes);
+		return toBudget(id, "src", await toDeliverableBlob(new Blob([bytes], { type: inline.mimeType })), 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()), maxBytes);
 }
 /** L2：`<canvas>` 读回。画布被跨域内容污染时 `toDataURL` 抛 SecurityError，不再兜底（裁决 D-3） */
 async function captureCanvas(element, id, maxBytes) {
@@ -1664,29 +1664,204 @@ 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;
+/**
+* 按魔数认图片类型（服务端声明只作兜底）。
+*
+* 图片接口常年是「无扩展名 + `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）。
+* 前者只是声明错了，按魔数改回来即可；后者必须就地栅格化，否则等于没取到图。
+*/
+async function toDeliverableBlob(blob) {
+	const declared = blob.type.split(";")[0]?.trim().toLowerCase() ?? "";
+	if (DELIVERABLE_IMAGE_MIME_TYPES.has(declared)) return blob;
+	const bytes = new Uint8Array(await blob.arrayBuffer());
+	const sniffed = sniffImageMime(bytes);
+	if (sniffed !== void 0 && DELIVERABLE_IMAGE_MIME_TYPES.has(sniffed)) return new Blob([bytes], { type: sniffed });
+	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([bytes], { 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 +1883,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"]
 		};
 	}
@@ -1859,13 +2034,25 @@ 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) {
 	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);
 		if (node !== void 0) children.push(node);
 	}
 	const name = nameOf(element, doc);
@@ -1884,18 +2071,54 @@ 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";
+}
+/**
+* 句柄发放与解析。表在 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 +2130,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 +2155,7 @@ var HandleIssuer = class {
 			element,
 			...frame !== void 0 ? { frame } : {}
 		});
+		this.#refByElement.set(element, ref);
 		return ref;
 	}
 	get table() {
@@ -1942,40 +2181,53 @@ function createDomPerceptionReader(options = {}) {
 	const elevatedModals = /* @__PURE__ */ new Set();
 	const rootDocument = () => options.document ?? globalThis.document;
 	/**
-	* 把一条帧授权解析成 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;
+		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);
 		}
-		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 };
+		return {
+			doc,
+			frames
+		};
 	}
 	/** 按当前 DOM 重算一次可操作集合；发句柄与执行前各算一次 */
 	const actionSets = (doc, scope) => {
@@ -1998,49 +2250,74 @@ 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: []
 		};
-		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 = [];
+		/** 同一个未授权 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
+			});
+		}
+		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);
 				if (node !== void 0) nodes.push(node);
 			}
+			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);
+				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 } : {}
+				});
+			}
 		}
 		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");
 			if (node !== void 0) nodes.push(node);
 		}
 		for (const modal of root.querySelectorAll(MODAL_SELECTOR)) {
@@ -2058,7 +2335,10 @@ function createDomPerceptionReader(options = {}) {
 	}
 	async function readWithImages(scope, capture) {
 		const targets = [];
-		const { nodes, frameNotes } = collect(scope, targets);
+		const { nodes, frameNotes } = collect(scope, {
+			targets,
+			minImageArea: capture.minImageArea ?? 0
+		});
 		const selected = targets.slice(0, capture.maxImages);
 		const images = [];
 		let imageFailures = 0;
@@ -2137,14 +2417,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 +2654,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") {
@@ -3392,6 +3693,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 +4185,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, TsTranspiler, VIEWER_SANDBOX_TOKENS, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, XLSX_UNEXTRACTED, blockedMessage, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractDocxText, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };