@webskill/sdk 0.10.0 → 0.11.0

package/dist/browser.js

@@ -1,5 +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 { B as bridgeError, C as ProgressiveRouter, S as OpenAiCompatibleClient, U as createWebSkillApi, a as AgentLoop, b as GoogleGenAiClient, c as CapabilityApproval, dt as parseBridgeRequest, g as FsRunSnapshotStore, h as FsMemoryStore, it as mergeCatalogEntries, lt as normalizeToolContent, m as FsArtifactStore, o as AnthropicClient, ot as networkPolicyLibSource, ut as normalizeToolError } from "./dist-BViUeszk.js";
+import { $ as createWebSkillApi, D as OpenAiCompatibleClient, O as ProgressiveRouter, T as GoogleGenAiClient, X as bridgeError, b as FsMemoryStore, bt as normalizeToolError, c as AnthropicClient, gt as networkPolicyLibSource, mt as mergeCatalogEntries, s as AgentLoop, u as CapabilityApproval, x as FsRunSnapshotStore, xt as parseBridgeRequest, y as FsArtifactStore, yt as normalizeToolContent } from "./dist-B-cOu08W.js";
+import { T as toFrameScopes, w as toActionFrameScopes } from "./dist-qnlI2Iup.js";
 import { n as MockLlmClient } from "./testing-WPTyXQYt.js";
 
 //#region ../browser/dist/index.js
@@ -304,6 +305,18 @@ function makeContext(msg) {
     readReference: function (path) {
       return callCapability('readReference', { path: path });
     },
+    readAsset: function (path) {
+      return callCapability('readAsset', { path: path });
+    },
+    fetchData: function (sourceId, params) {
+      return callCapability('fetchData', { sourceId: sourceId, params: params });
+    },
+    readAssetBinary: function (path) {
+      // 线上是 number[]（与 writeArtifact 同口径），还给脚本的必须是 Uint8Array
+      return callCapability('readAssetBinary', { path: path }).then(function (bytes) {
+        return new Uint8Array(bytes);
+      });
+    },
     writeArtifact: function (path, content, options) {
       return callCapability('writeArtifact', {
         path: path,
@@ -1018,8 +1031,10 @@ var BrowserWorkerScriptExecutor = class {
 		}) : void 0;
 		this.#capabilities = {
 			readReference: deps.capabilities?.readReference ?? true,
+			readAsset: deps.capabilities?.readAsset ?? true,
 			writeArtifact: deps.capabilities?.writeArtifact ?? true,
-			confirm: deps.capabilities?.confirm ?? true
+			confirm: deps.capabilities?.confirm ?? true,
+			fetchData: deps.capabilities?.fetchData ?? false
 		};
 		this.#networkPolicy = deps.networkPolicy ?? "deny-all";
 		this.#approval = new CapabilityApproval({
@@ -1192,6 +1207,29 @@ var BrowserWorkerScriptExecutor = class {
 						value: await context.readReference(request.path)
 					};
 				}
+				case "readAsset":
+				case "readAssetBinary": {
+					const read = request.kind === "readAsset" ? context.readAsset : context.readAssetBinary;
+					if (!read) return bridgeError(request.id, "TOOL_UNSUPPORTED", "Capability \"readAsset\" is disabled");
+					const denied = await gate("readAsset", `Script "${context.skillName}" wants to read asset "${request.path}"`, { path: request.path });
+					if (denied) return denied;
+					const value = await read(request.path);
+					return {
+						id: request.id,
+						ok: true,
+						value: typeof value === "string" ? value : Array.from(value)
+					};
+				}
+				case "fetchData": {
+					if (!context.fetchData) return bridgeError(request.id, "TOOL_UNSUPPORTED", "Capability \"fetchData\" is disabled");
+					const denied = await gate("fetchData", `Script "${context.skillName}" wants to fetch data source "${request.sourceId}"`, { sourceId: request.sourceId });
+					if (denied) return denied;
+					return {
+						id: request.id,
+						ok: true,
+						value: await context.fetchData(request.sourceId, request.params)
+					};
+				}
 				case "writeArtifact": {
 					const denied = await gate("writeArtifact", `Script "${context.skillName}" wants to write artifact "${request.path}"`, {
 						path: request.path,
@@ -1282,10 +1320,10 @@ async function probeChromeBuiltinAvailability() {
 		};
 	}
 }
-const textOf = (message) => message.content.map((part) => part.type === "text" ? part.text : `[${part.type}]`).join("").trim();
+const textOf$1 = (message) => message.content.map((part) => part.type === "text" ? part.text : `[${part.type}]`).join("").trim();
 /** tool 角色 Prompt API 不认识，降级成 user 文本——内置模型本来就不做工具调用 */
 function toInitialPrompt(message) {
-	const text = textOf(message);
+	const text = textOf$1(message);
 	if (message.role === "assistant") return {
 		role: "assistant",
 		content: text
@@ -1296,7 +1334,7 @@ function toInitialPrompt(message) {
 	};
 }
 function splitInput(input) {
-	const system = input.messages.filter((m) => m.role === "system").map(textOf).filter((text) => text !== "");
+	const system = input.messages.filter((m) => m.role === "system").map(textOf$1).filter((text) => text !== "");
 	const rest = input.messages.filter((m) => m.role !== "system");
 	const last = rest.at(-1);
 	return {
@@ -1736,6 +1774,17 @@ const clip = (text) => {
 	const normalized = text.replace(/\s+/g, " ").trim();
 	return normalized.length > MAX_TEXT ? `${normalized.slice(0, MAX_TEXT)}…` : normalized;
 };
+/**
+* 链接目标，已按文档基准解析成绝对 URL。
+*
+* `<a>` / `<area>` 的 `.href` 属性天然是解析过的；`role="link"` 的其它元素没有这个属性，
+* 只能退回原始属性值——那种情况下 URL 是否可用由取数侧的准入判定说了算。
+*/
+function hrefOf(element) {
+	const anchor = element;
+	if (typeof anchor.href === "string" && anchor.href !== "") return anchor.href;
+	return element.getAttribute("href") ?? void 0;
+}
 function roleOf$1(element) {
 	const explicit = element.getAttribute("role");
 	if (explicit !== null && explicit.trim() !== "") return explicit.trim();
@@ -1804,26 +1853,32 @@ const SKIPPED_TAGS = /* @__PURE__ */ new Set([
 	"NOSCRIPT",
 	"TEMPLATE"
 ]);
-function describe(element, excluded, doc, view, targets, handles) {
+/** 活动模态的三种形态；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) {
 	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);
+		const node = describe(child, excluded, doc, view, targets, handles, frame, provenance);
 		if (node !== void 0) children.push(node);
 	}
 	const name = nameOf(element, doc);
 	const value = valueOf(element);
 	const role = roleOf$1(element);
+	const href = role === "link" ? hrefOf(element) : void 0;
 	if (role === "generic" && name === void 0 && value === void 0 && children.length === 0) return void 0;
 	const node = {
 		role,
 		...name !== void 0 ? { name } : {},
 		...value !== void 0 ? { value } : {},
+		...frame !== void 0 ? { frame } : {},
+		...href !== void 0 ? { href } : {},
+		...provenance !== void 0 ? { provenance } : {},
 		...children.length > 0 ? { children } : {}
 	};
-	const ref = handles?.issue(element, role);
+	const ref = handles?.issue(element, role, frame);
 	if (ref !== void 0) node.ref = ref;
 	if (targets !== void 0 && isCapturableElement(element)) targets.push({
 		element,
@@ -1843,13 +1898,21 @@ var HandleIssuer = class {
 		this.#actionable = actionable;
 		this.#excluded = excluded;
 	}
-	issue(element, role) {
+	/** 每帧一份可操作集合；发句柄时按帧替换，避免 A 帧的集合拿去判 B 帧的元素 */
+	useSets(actionable, excluded) {
+		this.#actionable = actionable;
+		this.#excluded = excluded;
+	}
+	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 bytes = /* @__PURE__ */ new Uint8Array(8);
 		crypto.getRandomValues(bytes);
 		const ref = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
-		this.#table.set(ref, element);
+		this.#table.set(ref, {
+			element,
+			...frame !== void 0 ? { frame } : {}
+		});
 		return ref;
 	}
 	get table() {
@@ -1866,12 +1929,54 @@ var HandleIssuer = class {
 */
 function createDomPerceptionReader(options = {}) {
 	let handles;
-	const resolveDocument = () => options.document ?? globalThis.document;
+	/** 授权生效时记下各帧的 origin，之后每次感知比对（FR-24.3） */
+	const frameOrigins = /* @__PURE__ */ new Map();
+	/**
+	* 被提升的模态（FR-25.6）：**只装由已授权操作打开的那些**。
+	* 用户自己点开的对话框不在里面——它在操作前的快照里，差集会把它排除。
+	*/
+	const elevatedModals = /* @__PURE__ */ new Set();
+	const rootDocument = () => options.document ?? globalThis.document;
+	/**
+	* 把一条帧授权解析成 Document。
+	*
+	* 跨源时 `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 };
+	}
 	/** 按当前 DOM 重算一次可操作集合；发句柄与执行前各算一次 */
-	const actionSets = (doc) => {
+	const actionSets = (doc, scope) => {
 		const actionable = /* @__PURE__ */ new Set();
 		const excluded = /* @__PURE__ */ new Set();
-		const scope = options.actionScope;
 		if (scope === void 0 || scope.include.length === 0) return {
 			actionable,
 			excluded
@@ -1889,26 +1994,67 @@ 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) {
-		const doc = resolveDocument();
-		if (doc === void 0 || scope.include.length === 0) return [];
-		const view = doc.defaultView;
-		const sets = actionSets(doc);
-		handles = new HandleIssuer(sets.actionable, sets.excluded);
-		const excluded = /* @__PURE__ */ new Set();
-		for (const selector of scope.exclude ?? []) for (const element of doc.querySelectorAll(selector)) excluded.add(element);
-		const roots = [];
-		for (const selector of scope.include) for (const element of doc.querySelectorAll(selector)) if (!roots.includes(element)) roots.push(element);
+		const root = rootDocument();
+		if (root === void 0) return {
+			nodes: [],
+			frameNotes: []
+		};
+		handles = new HandleIssuer(/* @__PURE__ */ new Set(), /* @__PURE__ */ new Set());
 		const nodes = [];
-		for (const root of roots) {
-			const node = describe(root, excluded, doc, view, targets, handles);
+		const frameNotes = [];
+		for (const frameScope of toFrameScopes(scope)) {
+			if (frameScope.include.length === 0) continue;
+			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
+				});
+				continue;
+			}
+			const doc = resolved.doc;
+			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 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);
+				if (node !== void 0) nodes.push(node);
+			}
+		}
+		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");
 			if (node !== void 0) nodes.push(node);
 		}
-		return nodes;
+		for (const modal of root.querySelectorAll(MODAL_SELECTOR)) {
+			if (elevatedModals.has(modal)) continue;
+			const name = nameOf(modal, root) ?? "dialog";
+			nodes.push({
+				role: "note",
+				name: `The dialog "${name}" is open but outside the authorized scope because it was opened manually. Ask the user to let you open it instead.`
+			});
+		}
+		return {
+			nodes,
+			frameNotes
+		};
 	}
 	async function readWithImages(scope, capture) {
 		const targets = [];
-		const nodes = collect(scope, targets);
+		const { nodes, frameNotes } = collect(scope, targets);
 		const selected = targets.slice(0, capture.maxImages);
 		const images = [];
 		let imageFailures = 0;
@@ -1935,24 +2081,68 @@ function createDomPerceptionReader(options = {}) {
 			nodes,
 			images,
 			imagesOmitted: targets.length - selected.length,
-			imageFailures
+			imageFailures,
+			...frameNotes.length > 0 ? { frameNotes } : {}
 		};
 	}
 	function read(scope, capture) {
-		if (capture === void 0) return collect(scope, void 0);
-		if (!capture.images || capture.maxImages <= 0) return Promise.resolve({ nodes: collect(scope, void 0) });
+		if (capture === void 0) return collect(scope, void 0).nodes;
+		if (!capture.images || capture.maxImages <= 0) {
+			const { nodes, frameNotes } = collect(scope, void 0);
+			return Promise.resolve({
+				nodes,
+				...frameNotes.length > 0 ? { frameNotes } : {}
+			});
+		}
 		return readWithImages(scope, capture);
 	}
+	/** 当前活动模态；跨帧不适用（模态提升只在主文档语义下成立） */
+	function modalSnapshot() {
+		const root = rootDocument();
+		if (root === void 0) return /* @__PURE__ */ new Set();
+		return new Set(root.querySelectorAll(MODAL_SELECTOR));
+	}
+	/** 关掉或已从文档移除的模态立刻失去提升：授权不得跨对话框生命周期存活 */
+	function pruneElevated() {
+		for (const modal of elevatedModals) if (!(modal.isConnected && modal.matches(MODAL_SELECTOR))) elevatedModals.delete(modal);
+	}
 	return {
 		read,
-		resolve: (ref) => handles?.table.get(ref),
+		resolve: (ref) => handles?.table.get(ref)?.element,
+		frameOf: (ref) => handles?.table.get(ref)?.frame,
+		modalSnapshot,
+		elevateNewModals: (before) => {
+			pruneElevated();
+			for (const modal of modalSnapshot()) {
+				if (before.has(modal)) continue;
+				elevatedModals.add(modal);
+				return modal;
+			}
+		},
+		modalStateOf: (element) => {
+			pruneElevated();
+			const modal = element.closest(MODAL_SELECTOR);
+			if (modal === null) return "none";
+			return elevatedModals.has(modal) ? "elevated" : "unelevated";
+		},
 		inActionScope: (element) => {
-			const doc = resolveDocument();
-			if (doc === void 0) return false;
-			const sets = actionSets(doc);
+			const doc = element.ownerDocument;
+			const frame = frameOfDocument(doc);
+			if (frame === void 0) return false;
+			const sets = actionSets(doc, actionScopeFor(frame));
 			return sets.actionable.has(element) && !sets.excluded.has(element);
 		}
 	};
+	/** 反查一个 Document 属于哪条帧授权；不在授权列表里的帧一律判不可操作 */
+	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;
+		}
+	}
 }
 const FILLABLE_TAGS = /* @__PURE__ */ new Set(["INPUT", "TEXTAREA"]);
 /** 只看显式声明，不看尺寸：jsdom 有 getComputedStyle 但没有布局 */
@@ -1970,13 +2160,36 @@ function hidden(element) {
 }
 const inputType = (element) => (element.getAttribute("type") ?? "text").toLowerCase();
 const isSecret = (element) => element.tagName === "INPUT" && SECRET_INPUT_TYPES.has(inputType(element));
+const textOf = (element) => element?.textContent?.replace(/\s+/g, " ").trim() ?? "";
+/**
+* 可访问名称，按 accname 的优先级取。
+*
+* `aria-labelledby` 与关联 `<label>` 这两级不能省：`<input type="radio">`
+* 自己既没有 textContent 也没有 placeholder，少了它们审计里只剩 role + frame，
+* 事后看不出用户批准的到底是哪个单选组（UI-UX8 UX-08）。
+*/
 function accessibleName(element) {
+	const labelledBy = element.getAttribute("aria-labelledby");
+	if (labelledBy !== null && labelledBy.trim() !== "") {
+		const doc = element.ownerDocument;
+		const joined = labelledBy.split(/\s+/).map((id) => textOf(doc.getElementById(id))).filter((part) => part !== "").join(" ");
+		if (joined !== "") return joined;
+	}
 	const label = element.getAttribute("aria-label");
 	if (label !== null && label.trim() !== "") return label.trim();
-	const text = element.textContent?.replace(/\s+/g, " ").trim() ?? "";
-	if (text !== "") return text;
+	const labels = element.labels;
+	if (labels && labels.length > 0) {
+		const joined = [...labels].map((node) => textOf(node)).filter((part) => part !== "").join(" ");
+		if (joined !== "") return joined;
+	}
+	const own = textOf(element);
+	if (own !== "") return own;
+	const wrapping = textOf(element.closest("label"));
+	if (wrapping !== "") return wrapping;
 	const placeholder = element.getAttribute("placeholder");
-	return placeholder !== null && placeholder.trim() !== "" ? placeholder.trim() : void 0;
+	if (placeholder !== null && placeholder.trim() !== "") return placeholder.trim();
+	const title = element.getAttribute("title");
+	return title !== null && title.trim() !== "" ? title.trim() : void 0;
 }
 function roleOf(element) {
 	const explicit = element.getAttribute("role");
@@ -2012,52 +2225,202 @@ function fillValue(element, value) {
 	element.dispatchEvent(new Event("input", { bubbles: true }));
 	element.dispatchEvent(new Event("change", { bubbles: true }));
 }
+const norm = (text) => (text ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+/** 轮询等待，上限固定：等不到就失败，不能无限挂着一次工具调用 */
+async function waitFor(probe, timeoutMs = 2e3) {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		const hit = probe();
+		if (hit !== void 0) return hit;
+		if (Date.now() >= deadline) return void 0;
+		await new Promise((resolve) => setTimeout(resolve, 25));
+	}
+}
+/**
+* 一个动作覆盖三种选择控件（FR-25.2）：原生 select 直接设值，
+* ARIA 组合与日期格点走「点开 → 等浮层 → 按可访问名匹配 → 点中」。
+*
+* **收尾一定要回读确认**：浮层里点了不等于选上了（受控组件可能拒绝、
+* 也可能匹配到了另一个同名项）。少了这一步就会向模型报假成功。
+*/
+async function selectOption(element, value) {
+	const target = describeElement(element);
+	const fail = (reason) => ({
+		ok: false,
+		target,
+		reason
+	});
+	if (value === "") return fail("The select action needs a value.");
+	if (element.tagName === "SELECT") {
+		const select = element;
+		const option = [...select.options].find((candidate) => norm(candidate.label) === norm(value) || norm(candidate.value) === norm(value));
+		if (option === void 0) return fail(`No option named "${value}" is available.`);
+		select.value = option.value;
+		select.dispatchEvent(new Event("input", { bubbles: true }));
+		select.dispatchEvent(new Event("change", { bubbles: true }));
+		return norm(select.selectedOptions[0]?.label) === norm(option.label) ? {
+			ok: true,
+			target
+		} : fail(`The control did not accept "${value}".`);
+	}
+	const doc = element.ownerDocument;
+	element.click();
+	const listbox = await waitFor(() => doc.querySelector("[role=listbox], [role=grid], [role=menu]") ?? void 0);
+	if (listbox === null || listbox === void 0) return fail("The options panel did not open.");
+	const option = [...listbox.querySelectorAll("[role=option], [role=gridcell], [role=menuitem], option")].find((candidate) => norm(accessibleName(candidate)) === norm(value));
+	if (option === void 0) return fail(`No option named "${value}" is available.`);
+	option.click();
+	return await waitFor(() => {
+		const shown = `${accessibleName(element) ?? ""} ${element.value ?? ""}`;
+		return norm(shown).includes(norm(value)) ? true : void 0;
+	}) === true ? {
+		ok: true,
+		target
+	} : fail(`The control did not settle on "${value}".`);
+}
+/**
+* 幂等置值（FR-25.4）：当前态已是目标态就**不点**，避免「点一下反而关掉」。
+* 未操作时仍返回 ok —— 返回失败模型会重试，假装点了审计会失真。
+*/
+function setToggle(element, value, target) {
+	const wanted = norm(value);
+	if (wanted !== "true" && wanted !== "false") return {
+		ok: false,
+		target,
+		reason: "Use \"true\" or \"false\"."
+	};
+	const desired = wanted === "true";
+	const aria = element.getAttribute("aria-checked") ?? element.getAttribute("aria-pressed");
+	const current = aria !== null ? aria === "true" : element.tagName === "INPUT" ? element.checked : void 0;
+	if (current === void 0) return {
+		ok: false,
+		target,
+		reason: "The element is not a toggle."
+	};
+	if (current === desired) return {
+		ok: true,
+		target,
+		noop: true
+	};
+	element.click();
+	return {
+		ok: true,
+		target
+	};
+}
+/**
+* 用户选中的文件写进目标 input；`DataTransfer` 是唯一能构造 `FileList` 的途径。
+*
+* 失败要**返回**而不是抛：执行器的契约是「一律给出结构化结果」，
+* 抛出去会连带跳过策略层的审计，那比操作失败本身更糟。
+*/
+function attachFiles(input, files) {
+	try {
+		const transfer = new DataTransfer();
+		for (const file of files) transfer.items.add(file);
+		input.files = transfer.files;
+	} catch (e) {
+		return `This browser cannot attach files programmatically: ${e instanceof Error ? e.message : String(e)}`;
+	}
+	input.dispatchEvent(new Event("input", { bubbles: true }));
+	input.dispatchEvent(new Event("change", { bubbles: true }));
+}
 /** @experimental */
 function createDomPageActionExecutor(options) {
 	const { reader } = options;
+	/** 帧标识从 reader 的句柄表取，不另存一份：两张表会有两套过期时机 */
+	const withFrame = (ref, described) => {
+		const frame = reader.frameOf(ref);
+		return {
+			...described,
+			...frame !== void 0 ? { frame } : {}
+		};
+	};
 	const describe = (ref) => {
 		const element = reader.resolve(ref);
-		return element === void 0 ? void 0 : describeElement(element);
+		if (element === void 0) return void 0;
+		const described = withFrame(ref, describeElement(element));
+		return reader.modalStateOf(element) === "elevated" ? {
+			...described,
+			elevated: true
+		} : described;
 	};
-	const execute = (request) => {
+	const execute = async (request) => {
 		const element = reader.resolve(request.ref);
 		if (element === void 0) return {
 			ok: false,
 			target: { role: "generic" },
 			reason: "The element reference is unknown or expired."
 		};
-		const target = describeElement(element);
+		const target = withFrame(request.ref, describeElement(element));
 		const fail = (reason) => ({
 			ok: false,
 			target,
 			reason
 		});
-		if (!reader.inActionScope(element)) return fail("The element is no longer inside the actionable scope.");
+		if (reader.modalStateOf(element) === "unelevated") return fail("That dialog is not in the authorized scope because it was opened manually. Ask me to open it, or add it to the host allowlist.");
+		if (reader.modalStateOf(element) !== "elevated" && !reader.inActionScope(element)) return fail("The element is no longer inside the actionable scope.");
 		if (hidden(element)) return fail("The element is not visible.");
 		if (element.hasAttribute("disabled")) return fail("The element is disabled.");
+		const modalsBefore = reader.modalSnapshot();
+		const done = async (outcome) => {
+			if (!outcome.ok) return outcome;
+			const elevated = await waitFor(() => reader.elevateNewModals(modalsBefore), 500) ?? reader.elevateNewModals(modalsBefore);
+			const name = elevated === void 0 ? void 0 : accessibleName(elevated) ?? "dialog";
+			return name === void 0 ? outcome : {
+				...outcome,
+				elevatedModal: name
+			};
+		};
 		if (request.action === "click") {
 			element.click();
-			return {
+			return await done({
 				ok: true,
 				target
-			};
+			});
 		}
 		if (request.action === "fill") {
 			if (!FILLABLE_TAGS.has(element.tagName)) return fail("The element is not a text control.");
 			if (element.hasAttribute("readonly")) return fail("The element is read-only.");
 			fillValue(element, request.value ?? "");
-			return {
+			return await done({
 				ok: true,
 				target
+			});
+		}
+		if (request.action === "select") {
+			const outcome = await selectOption(element, request.value ?? "");
+			return outcome.ok ? await done({
+				...outcome,
+				target
+			}) : {
+				...outcome,
+				target
 			};
 		}
+		if (request.action === "set") return await done(setToggle(element, request.value ?? "", target));
+		if (request.action === "attach") {
+			const files = await options.pickFiles?.();
+			if (files === void 0 || files.length === 0) return {
+				ok: false,
+				target,
+				reason: "The user cancelled the file selection."
+			};
+			if (element.tagName !== "INPUT" || element.type !== "file") return fail("The element is not a file input.");
+			const failure = attachFiles(element, files);
+			if (failure !== void 0) return fail(failure);
+			return await done({
+				ok: true,
+				target
+			});
+		}
 		const form = element.tagName === "FORM" ? element : element.form;
 		if (!form) return fail("The element does not belong to a form.");
 		form.requestSubmit();
-		return {
+		return await done({
 			ok: true,
 			target
-		};
+		});
 	};
 	return {
 		execute,
@@ -2917,6 +3280,355 @@ function createBrowserChatbotHost(options) {
 		connectFacade: overrides?.connectFacade ?? connectFacade
 	};
 }
+const DEFAULT_TIMEOUT_MS = 3e4;
+/**
+* 默认的链接文档读取实现（分册 22 §2.2）。
+*
+* 出站准入（scheme / 私有地址）与同源判定都在**引擎侧**完成，这里只负责取字节：
+* 把判定散到实现里，宿主换一个 reader 就能绕过整套闸门。
+* @experimental
+*/
+function createFetchLinkedDocumentReader(options = {}) {
+	const origin = "origin" in options ? options.origin : globalThis.location?.origin;
+	const doFetch = options.fetch ?? globalThis.fetch;
+	return {
+		...origin !== void 0 ? { origin } : {},
+		async read(url) {
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+			try {
+				const response = await doFetch(url, { signal: controller.signal });
+				if (!response.ok) throw new WebSkillError("TOOL_EXECUTION_FAILED", `The document responded with HTTP ${response.status}.`);
+				const buffer = await response.arrayBuffer();
+				return {
+					mimeType: response.headers.get("content-type") ?? "application/octet-stream",
+					bytes: new Uint8Array(buffer)
+				};
+			} finally {
+				clearTimeout(timer);
+			}
+		}
+	};
+}
+/**
+* docx 正文抽取（分册 22 §2.4 / FR-23.7）。
+*
+* **零新增依赖**：zip 用仓内既有的 `unzipWithLimits`（自带解压体积上限，
+* 顺带挡住 zip 炸弹），XML 用浏览器原生 `DOMParser`。
+*
+* ⚠️ `DOMParser` 是浏览器 API，Node 没有 —— 所以这个模块只在 `@webskill/browser`。
+* Node 宿主没有 docx 能力，这是**显式声明**的限制（AC-G15），不是静默降级；
+* 收紧到 Node 侧的备案是 D55。
+*/
+/**
+* **不抽取**的内容，逐条写明而不是笼统说「尽力而为」：
+* 样式、标题层级、图片、批注、修订、页眉页脚、脚注。
+*
+* 模型拿到的是纯正文文本流。把「这是 H1」这类信息也抽出来需要解析
+* `styles.xml` 的样式继承链，那是另一个量级的工作，本版不做。
+*/
+const DOCX_UNEXTRACTED = [
+	"styles",
+	"heading levels",
+	"images",
+	"comments",
+	"tracked changes",
+	"headers and footers",
+	"footnotes"
+];
+const DOCX_ENTRY = "word/document.xml";
+/** 段落内的行内元素：文本、软换行、制表符 */
+function inlineText(node) {
+	let out = "";
+	for (const child of node.children) {
+		const tag = child.tagName.replace(/^w:/, "");
+		if (tag === "t") out += child.textContent ?? "";
+		else if (tag === "br") out += "\n";
+		else if (tag === "tab") out += "	";
+		else out += inlineText(child);
+	}
+	return out;
+}
+/**
+* 表格按「行一行、单元格用制表符分隔」展开。
+* 不还原合并单元格——还原它需要读 gridSpan/vMerge，且模型多半用不上。
+*/
+function tableText(table, paragraphOf) {
+	const rows = [];
+	for (const row of table.getElementsByTagName("w:tr")) {
+		const cells = [];
+		for (const cell of row.getElementsByTagName("w:tc")) {
+			const paragraphs = [...cell.getElementsByTagName("w:p")].map(paragraphOf);
+			cells.push(paragraphs.join(" ").trim());
+		}
+		rows.push(cells.join("	"));
+	}
+	return rows.join("\n");
+}
+/**
+* 从 docx 字节里抽出正文文本。
+*
+* @throws WebSkillError 归档损坏、缺 `word/document.xml`、XML 解析失败
+*/
+async function extractDocxText(bytes) {
+	const entry = (await unzipWithLimits(bytes)).find(([path]) => path === DOCX_ENTRY);
+	if (entry === void 0) throw new WebSkillError("TOOL_EXECUTION_FAILED", `This file is not a Word document: it has no ${DOCX_ENTRY} entry.`);
+	const xml = new TextDecoder().decode(entry[1]);
+	const doc = new DOMParser().parseFromString(xml, "application/xml");
+	if (doc.getElementsByTagName("parsererror").length > 0) throw new WebSkillError("TOOL_EXECUTION_FAILED", "The Word document body could not be parsed as XML.");
+	const body = doc.getElementsByTagName("w:body")[0];
+	if (body === void 0) return "";
+	const paragraphOf = (paragraph) => inlineText(paragraph);
+	const blocks = [];
+	for (const child of body.children) {
+		const tag = child.tagName.replace(/^w:/, "");
+		if (tag === "p") blocks.push(paragraphOf(child));
+		else if (tag === "tbl") blocks.push(tableText(child, paragraphOf));
+	}
+	return blocks.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+/**
+* 文档投放面的 CSP 单一来源（0.11.0 分册 18 FR-18.3 / AC-G21）。
+*
+* ⚠️ 策略**只能**由 viewer 路由的响应头下发。
+* 实测：`<meta http-equiv="Content-Security-Policy" content="sandbox …">` 里的
+* `sandbox` 指令**完全无效**——同一份文档，`<meta>` 下 `localStorage` 写入成功，
+* 换成响应头才抛 `SecurityError`。规范规定 `sandbox` / `frame-ancestors` /
+* `report-uri` 在 `<meta>` 里被忽略。
+* 不要试图用 `<meta>` 省掉那条 HTTP 路由。
+*/
+/**
+* 固定的 sandbox token，**不接受宿主配置**。
+*
+* `allow-same-origin` 给了就等于隔离归零（文档能读主应用存储、经 opener 反控），
+* 所以它连「可配置」都不该是。`allow-downloads` 本版不给：没有消费场景。
+*/
+const SANDBOX_TOKENS = ["allow-scripts", "allow-modals"];
+/**
+* 宿主配置值不得夹带 CSP 分隔符 —— 否则一个来源字符串就能追加任意指令，
+* 白名单形同虚设。这是配置注入，不是理论风险。
+*/
+function assertSource(value, directive) {
+	if (value.trim() === "" || /[;,'"\s]/.test(value)) throw new WebSkillError("VALIDATION_FAILED", `Invalid ${directive} source ${JSON.stringify(value)}: sources must be a single token without whitespace, quotes, ";" or ","`);
+}
+function directive(name, defaults, extra) {
+	for (const value of extra ?? []) assertSource(value, name);
+	const sources = [...defaults, ...extra ?? []];
+	return `${name} ${sources.length > 0 ? sources.join(" ") : "'none'"}`;
+}
+/**
+* 生成 viewer 路由的 `Content-Security-Policy` 响应头值。
+*
+* 宿主只能**加白名单来源**，加不了 sandbox token —— 隔离边界的策略不由被隔离方
+* 也不由宿主的白名单配置决定。
+*/
+function viewerCspHeader(options) {
+	const host = options.hostOrigin;
+	assertSource(host, "host-origin");
+	return [
+		`sandbox ${SANDBOX_TOKENS.join(" ")}`,
+		"default-src 'none'",
+		`script-src ${host}`,
+		`style-src ${host} 'unsafe-inline'`,
+		directive("img-src", [host, "data:"], options.imgSrc),
+		directive("font-src", [host], options.fontSrc),
+		directive("connect-src", [], options.connectSrc)
+	].join("; ");
+}
+/** 本版固定的 sandbox token（供判据与装配文档引用，避免第二份清单） */
+const VIEWER_SANDBOX_TOKENS = SANDBOX_TOKENS;
+const DEFAULT_MAX_VIEWER_PAYLOAD_BYTES = 2e6;
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 1e4;
+/** hello 的重发间隔：viewer 脚本加载完之前投出去的消息全部丢失 */
+const HELLO_RETRY_MS = 100;
+/** 审计事件类型（与既有事件同一条链） */
+const DOCUMENT_SURFACE_AUDIT_EVENT = "document.surface.open";
+const payloadBytes = (value) => new TextEncoder().encode(JSON.stringify(value) ?? "").length;
+/**
+* 打开一个文档投放面。
+*
+* `window.open` **必须在用户手势里调**，否则被浏览器拦截；不能在 run 收尾时自动开。
+* 也**不加 `noopener`** —— 需要句柄才能把内容 post 进去。反控面不靠 `noopener` 封，
+* 靠沙箱本身：无 `allow-same-origin` 读不到 opener 的任何东西，
+* 无 `allow-top-navigation` 改不了它的地址。
+*/
+async function openDocumentSurface(input, options) {
+	const limit = options.maxPayloadBytes ?? 2e6;
+	const size = payloadBytes(input.document);
+	if (size > limit) {
+		await audit(options, input, {
+			outcome: "rejected",
+			reason: "payload-too-large",
+			bytes: size
+		});
+		throw new WebSkillError("VALIDATION_FAILED", `Document payload is ${size} bytes, over the ${limit} byte budget; reduce the data before opening the viewer`);
+	}
+	if (!await options.confirm({
+		skillName: input.skillName,
+		dataSource: input.dataSource
+	})) {
+		await audit(options, input, {
+			outcome: "cancelled",
+			bytes: size
+		});
+		throw new WebSkillError("DOCUMENT_SURFACE_DECLINED", "The user declined to open the document surface");
+	}
+	const target = (options.open ?? defaultOpen)(options.viewerUrl, "_blank");
+	if (!target) {
+		await audit(options, input, {
+			outcome: "blocked",
+			reason: "popup-blocked",
+			bytes: size
+		});
+		throw new WebSkillError("DOCUMENT_SURFACE_UNAVAILABLE", "The browser blocked the viewer window; open it from a direct user gesture");
+	}
+	const channelId = newChannelId();
+	try {
+		await handshake(target, channelId, options);
+	} catch (e) {
+		target.close();
+		await audit(options, input, {
+			outcome: "failed",
+			reason: messageOf(e),
+			bytes: size
+		});
+		throw e;
+	}
+	target.postMessage({
+		channelId,
+		type: "webskill:viewer-document",
+		document: input.document
+	}, viewerOrigin(options));
+	await audit(options, input, {
+		outcome: "opened",
+		bytes: size
+	});
+	return target;
+}
+function defaultOpen(url, target) {
+	return globalThis.open?.(url, target) ?? null;
+}
+/** viewer 是 opaque origin，`postMessage` 的 targetOrigin 只能是 `*` —— 用 channelId 做配对校验 */
+function viewerOrigin(_options) {
+	return "*";
+}
+function newChannelId() {
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	globalThis.crypto?.getRandomValues(bytes);
+	return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* 等 viewer 外壳回报就绪。
+*
+* hello 必须**重发**：`window.open` 一返回就 post 的那一条，viewer 的脚本还没加载，
+* 消息直接丢掉（`postMessage` 不排队等监听器）。只发一次的写法在本机偶尔能过——
+* 那是缓存命中让文档加载快过第一条消息，换台机器就必然超时。
+*
+* 必须同时校验 `event.source === target` 与 `channelId`：
+* 只看 origin 不行（opaque origin 的 `event.origin` 是 `"null"`，任何沙箱页面都一样）。
+*/
+function handshake(target, channelId, options) {
+	const timeoutMs = options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+	const scope = globalThis;
+	return new Promise((resolve, reject) => {
+		const done = (fn) => {
+			clearTimeout(timer);
+			clearInterval(retry);
+			scope.removeEventListener("message", onMessage);
+			fn();
+		};
+		const timer = setTimeout(() => {
+			done(() => reject(new WebSkillError("DOCUMENT_SURFACE_UNAVAILABLE", `The viewer did not report ready within ${timeoutMs}ms`)));
+		}, timeoutMs);
+		const onMessage = (event) => {
+			if (event.source !== target) return;
+			const data = event.data;
+			if (data?.type !== "webskill:viewer-ready" || data.channelId !== channelId) return;
+			done(resolve);
+		};
+		scope.addEventListener("message", onMessage);
+		const hello = () => target.postMessage({
+			channelId,
+			type: "webskill:viewer-hello"
+		}, "*");
+		const retry = setInterval(hello, HELLO_RETRY_MS);
+		hello();
+	});
+}
+async function audit(options, input, data) {
+	await options.audit?.append({
+		type: DOCUMENT_SURFACE_AUDIT_EVENT,
+		target: input.skillName,
+		data: {
+			skillName: input.skillName,
+			dataSource: input.dataSource,
+			...data
+		}
+	}).catch(() => void 0);
+}
+/**
+* 启动外壳：等主应用的 hello → 回报 ready → 收文档 → 写进 DOM。
+*
+* `channelId` 必须由**主应用**在 hello 里给定并全程比对。opaque origin 下
+* `event.origin` 恒为 `"null"`，任何沙箱页面都一样，靠 origin 分辨不了来源；
+* 而 `event.source` 在这一侧只能确认「来自 opener」，确认不了是哪一次投放。
+*/
+function startViewerShell(host, mount, onData) {
+	let channelId;
+	const onMessage = (event) => {
+		const data = event.data;
+		if (typeof data?.channelId !== "string" || data.channelId === "") return;
+		if (data.type === "webskill:viewer-hello") {
+			channelId = data.channelId;
+			host.opener?.postMessage({
+				type: "webskill:viewer-ready",
+				channelId
+			}, "*");
+			return;
+		}
+		if (data.type !== "webskill:viewer-document" || channelId === void 0 || data.channelId !== channelId) return;
+		const doc = data.document;
+		if (!doc) return;
+		mount.style.textContent = doc.css ?? "";
+		mount.content.innerHTML = doc.html;
+		onData?.(doc.data);
+	};
+	host.addEventListener("message", onMessage);
+	return { dispose: () => {
+		host.removeEventListener("message", onMessage);
+	} };
+}
+/**
+* 监听 CSP 违规并把被拦资源汇总成一句话。
+*
+* 必须在**文档写入之前**挂上：违规事件不补发，晚一步就永远收不到。
+* 同一个来源只报一次——一份文档引十个图标会刷出十条同样的提示。
+*/
+function watchBlockedResources(host, notice) {
+	const origins = /* @__PURE__ */ new Set();
+	const onViolation = (event) => {
+		const origin = originOf(event.blockedURI);
+		if (origin === "" || origins.has(origin)) return;
+		origins.add(origin);
+		notice.textContent = blockedMessage([...origins]);
+	};
+	host.addEventListener("securitypolicyviolation", onViolation);
+	return { dispose: () => {
+		host.removeEventListener("securitypolicyviolation", onViolation);
+	} };
+}
+/** 提示文案的单一来源；判据直接引用，不各写一份字面量 */
+function blockedMessage(origins) {
+	return `Blocked by this page's content policy: ${origins.join(", ")}. The document fell back to locally available resources, so printed output may differ from the author's intent.`;
+}
+/** 只留 origin：完整 URL 里的路径对用户没有信息量，还会把提示撑得很长 */
+function originOf(blockedURI) {
+	try {
+		return new URL(blockedURI).origin;
+	} catch {
+		return blockedURI;
+	}
+}
 
 //#endregion
-export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, HOST_PORT_MATRIX, IframeWorkerLike, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };
+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 };