@webskill/sdk 0.14.0 → 0.16.0

package/dist/browser.js

@@ -1,13 +1,21 @@
-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";
+import { n as messageOf, t as WebSkillError } from "./errors-BDZNpC13.js";
+import { A as SKILL_MANIFEST_FILE, D as verifySkillSignature, M as buildManifest, O as MANIFEST_EXCLUDED_FILES, P as verifyManifest, b as parseSkillMarkdown, c as unzipWithLimits, f as SKILL_PACK_FILE, i as buildCatalog, k as SKILLS_LOCKFILE, m as parseSkillPackManifest, n as SkillDiscovery, o as readResponseWithLimit, p as exportSkills, t as validateSkills, u as detectSkillArchiveShapeFromFs, w as readSkillSignature, y as isValidSkillName } from "./skill-CAJMsLod.js";
+import { a as atomicWriteText, o as isAtomicTempPath, r as resolveInsideRoot } from "./pathSecurity-B1owvJAF.js";
+import { t as assertRemoteUrlAllowed } from "./urlSafety-CiSuCJvX.js";
+import { a as networkPolicyLibSource, c as bridgeError, d as FsMemoryStore, g as FsRunSnapshotStore, l as parseBridgeRequest, nt as ProgressiveRouter, p as AgentLoop, r as normalizeToolError, s as UPLOAD_FILES_UNAVAILABLE, t as CapabilityApproval, u as FsArtifactStore } from "./approval-BnLLCOG0.js";
+import { a as GoogleGenAiClient, o as AnthropicClient, s as OpenAiCompatibleClient, t as MockLlmClient } from "./llm-B7lLH0ZI.js";
+import { n as normalizeToolContent, t as mergeCatalogEntries } from "./external-_ZRQe-V9.js";
+import { t as createWebSkillApi } from "./webSkillApi-DOOyz2G5.js";
+import { a as frameLabel, i as toFrameScopes, o as frameSteps, r as toActionFrameScopes } from "./types-BuacBov_.js";
 
-//#region ../browser/dist/index.js
+//#region ../browser/src/fs/featureDetection.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
 function isOpfsAvailable(globalScope) {
 	return typeof (globalScope ?? globalThis).navigator?.storage?.getDirectory === "function";
 }
+
+//#endregion
+//#region ../browser/src/fs/opfsProvider.ts
 const isDomException = (e, name) => e instanceof DOMException && e.name === name;
 const mapError = (e, path) => {
 	if (isDomException(e, "NotFoundError")) return new WebSkillError("FS_NOT_FOUND", `Path not found: ${path}`);
@@ -174,6 +182,9 @@ var OpfsProvider = class {
 		await this.remove(from);
 	}
 };
+
+//#endregion
+//#region ../browser/src/executor/workerBootstrap.ts
 /**
 * Worker 引导源码（字符串 → Blob URL → new Worker(url, {type:'module'})）。
 * 注意：内容为纯 JS，不能含反引号与 ${ 占位（外层用模板字符串内嵌）；
@@ -183,7 +194,7 @@ var OpfsProvider = class {
 *
 * 协议（宿主 ↔ Worker）：
 * - 宿主 → Worker：{type:'load', id, source, networkPolicy?} 请求加载脚本定义
-* - 宿主 → Worker：{type:'execute', id, skillName, runId, source, args, networkPolicy?} 请求执行
+* - 宿主 → Worker：{type:'execute', id, skillName, runId, source, args, networkPolicy?, documentSurface?} 请求执行
 * - Worker → 宿主：{type:'load-result', id, ok, definition?, error?}
 * - Worker → 宿主：{type:'execute-result', id, ok, value?, stdout, stderr, error?}
 * - Worker → 宿主：{type:'bridge', request} 能力桥 RPC（readReference/writeArtifact/confirm）
@@ -299,7 +310,7 @@ function callCapability(kind, payload) {
 }
 
 function makeContext(msg) {
-  return {
+  var ctx = {
     skillName: msg.skillName,
     runId: msg.runId,
     readReference: function (path) {
@@ -329,6 +340,21 @@ function makeContext(msg) {
       return callCapability('confirm', { message: message });
     },
   };
+  // 能力位而非能力函数：其余能力无条件挂上去（拿不到时桥对面报错），
+  // documentSurface 是个供探测的布尔值，无条件挂上去就变成恒真谎言。
+  if (msg.documentSurface) ctx.documentSurface = true;
+  // 上传文件同理：宿主没接就不能给出「存在但必然失败」的假出口（分册 17 FR-17.1）
+  if (msg.uploadFiles) {
+    ctx.listUploadFiles = function () {
+      return callCapability('listUploadFiles', {});
+    };
+    ctx.readUploadFile = function (fileId) {
+      return callCapability('readUploadFile', { fileId: fileId }).then(function (bytes) {
+        return new Uint8Array(bytes);
+      });
+    };
+  }
+  return ctx;
 }
 
 self.onmessage = async function (event) {
@@ -404,6 +430,9 @@ self.onmessage = async function (event) {
   }
 };
 `;
+
+//#endregion
+//#region ../browser/src/executor/tsTranspiler.ts
 /** 按资源地址缓存，而不是全局单例：不同地址必须各自加载，否则先到的实例会顶替后来的配置 */
 const esbuildCache = /* @__PURE__ */ new Map();
 async function loadEsbuild(options) {
@@ -466,12 +495,18 @@ var TsTranspiler = class {
 		return code;
 	}
 };
+
+//#endregion
+//#region ../browser/src/skillManagement/checksumWeb.ts
 /** WebCrypto sha256（浏览器/Worker 通用；Node 20+ 全局 crypto 同样可用） */
 async function sha256HexWeb(data) {
 	const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
 	const digest = await crypto.subtle.digest("SHA-256", bytes);
 	return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+
+//#endregion
+//#region ../browser/src/skillManagement/fsUtils.ts
 /** 递归拷贝目录（含子目录与二进制文件；原子写中断残留的 `.tmp-*` 不拷贝） */
 async function copyDir(fs, from, to) {
 	await fs.mkdir(to);
@@ -498,6 +533,9 @@ async function removeDirQuiet(fs, dir) {
 		if (await fs.exists(dir)) await fs.remove(dir, { recursive: true });
 	} catch {}
 }
+
+//#endregion
+//#region ../browser/src/skillManagement/zipExtract.ts
 /**
 * zip 解包（fflate 流式，单条目/总解压体积上限，浏览器无依赖）。
 * 每个条目路径过 resolveInsideRoot：拒绝 `..` 段、绝对路径、反斜杠穿越（与 node 规则一致）。
@@ -509,6 +547,9 @@ async function extractZipWeb(fs, data, destRoot, limits) {
 		else await fs.writeBinary(target, content);
 	}
 }
+
+//#endregion
+//#region ../browser/src/skillManagement/browserSkillManager.ts
 /**
 * 验签失败不能被折叠成 INSTALL_FAILED：四种失败的宿主处置完全不同
 * （引导选策略 / 提示重下 / 引导添加密钥 / 安全事件），与 Node 侧同口径。
@@ -885,6 +926,9 @@ var BrowserSkillManager = class {
 		await atomicWriteText(this.#fs, lockfilePath(this.#managedRoot), JSON.stringify(lockfile, null, 2));
 	}
 };
+
+//#endregion
+//#region ../browser/src/executor/iframeSandbox.ts
 const ENVELOPE = "__webskill_sandbox__";
 let channelSeq = 0;
 /** 每实例 channelId（防同页伪造消息注入；crypto.randomUUID 优先，无则随机回退） */
@@ -1098,8 +1142,9 @@ function createIframeWorker(bootstrapSource, options = {}) {
 		doc.body.appendChild(iframe);
 		return worker;
 	}
+	const readyTimeoutMs = resolved.readyTimeoutMs ?? 1e4;
 	const worker = new IframeWorkerLike(iframe, hostWindow, channelId, {
-		ms: resolved.readyTimeoutMs ?? 1e4,
+		ms: readyTimeoutMs,
 		documentUrl
 	});
 	iframe.addEventListener("load", () => {
@@ -1116,6 +1161,9 @@ function createIframeWorker(bootstrapSource, options = {}) {
 	doc.body.appendChild(iframe);
 	return worker;
 }
+
+//#endregion
+//#region ../browser/src/executor/workerScriptExecutor.ts
 const blobWorkerFactory = () => {
 	const blob = new Blob([WORKER_BOOTSTRAP_SOURCE], { type: "text/javascript" });
 	const url = URL.createObjectURL(blob);
@@ -1228,7 +1276,9 @@ var BrowserWorkerScriptExecutor = class {
 				runId: context.runId,
 				source: script.source,
 				args,
-				networkPolicy: this.#networkPolicy
+				networkPolicy: this.#networkPolicy,
+				...context.documentSurface ? { documentSurface: true } : {},
+				...context.readUploadFile ? { uploadFiles: true } : {}
 			}, timeoutMs, (bridgeRequest) => this.#handleBridge(bridgeRequest, context), (host) => context.onWarning?.(`Network request blocked by sandbox network policy: ${host}`));
 			if (!response.ok) {
 				const stderrSummary = response.stderr?.length ? ` | stderr: ${response.stderr.join(" | ").slice(0, 500)}` : "";
@@ -1377,12 +1427,29 @@ var BrowserWorkerScriptExecutor = class {
 						value: await context.confirm(request.message)
 					};
 				}
+				case "listUploadFiles":
+					if (!context.listUploadFiles) return bridgeError(request.id, "TOOL_UNSUPPORTED", UPLOAD_FILES_UNAVAILABLE);
+					return {
+						id: request.id,
+						ok: true,
+						value: await context.listUploadFiles()
+					};
+				case "readUploadFile":
+					if (!context.readUploadFile) return bridgeError(request.id, "TOOL_UNSUPPORTED", UPLOAD_FILES_UNAVAILABLE);
+					return {
+						id: request.id,
+						ok: true,
+						value: Array.from(await context.readUploadFile(request.fileId))
+					};
 			}
 		} catch (e) {
 			return bridgeError(request.id, e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", messageOf(e));
 		}
 	}
 };
+
+//#endregion
+//#region ../browser/src/navigator.ts
 /**
 * navigator.webskill 显式装配：OPFS 默认存储 + BrowserWorkerScriptExecutor +
 * BrowserSkillManager → createWebSkillApi；target 提供时挂 target.navigator
@@ -1412,6 +1479,9 @@ function installWebSkillNavigator(config) {
 	nav["webskill"] = api;
 	return api;
 }
+
+//#endregion
+//#region ../browser/src/llm/chromeBuiltinClient.ts
 function languageModel() {
 	const candidate = globalThis.LanguageModel;
 	return typeof candidate?.availability === "function" && typeof candidate.create === "function" ? candidate : void 0;
@@ -1547,6 +1617,9 @@ var ChromeBuiltinLlmClient = class {
 		return (await probeChromeBuiltinAvailability()).available;
 	}
 };
+
+//#endregion
+//#region ../browser/src/llm/createLlmClient.ts
 /**
 * 配置 → `LlmClient`。收在 SDK 里是为了让下游只跟 `RuntimeConfigStore` 打交道，
 * 不必自己维护「provider → client 类」的映射（设计 04 §5）。
@@ -1578,6 +1651,9 @@ function createLlmClient(config) {
 		model: config.model
 	});
 }
+
+//#endregion
+//#region ../browser/src/media/dictation.ts
 function recognitionCtor() {
 	const scope = globalThis;
 	return scope.SpeechRecognition ?? scope.webkitSpeechRecognition;
@@ -1653,6 +1729,9 @@ function startDictation(options) {
 		recognition.stop();
 	} };
 }
+
+//#endregion
+//#region ../browser/src/media/compressImage.ts
 /** 动图无法在不丢帧的前提下走单帧编码管线，超限直接拒绝（裁决 D-2） */
 const UNCOMPRESSABLE_MIME_TYPES = /* @__PURE__ */ new Set(["image/gif"]);
 const QUALITY_STEPS = [
@@ -1720,6 +1799,9 @@ async function encode(bitmap, width, height, quality) {
 function formatBytes(bytes) {
 	return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 }
+
+//#endregion
+//#region ../browser/src/dom/imageCapture.ts
 /** @experimental */
 function isCaptureFailure(result) {
 	return "reason" in result;
@@ -2049,6 +2131,9 @@ function describeError(e) {
 	if (e instanceof TypeError) return "the request was blocked, most likely by CORS";
 	return e instanceof Error ? e.message : String(e);
 }
+
+//#endregion
+//#region ../browser/src/dom/promotion.ts
 /**
 * 非标可交互元素的识别与角色提升（0.14.0 分册 15）。
 *
@@ -2191,9 +2276,12 @@ function promoteRole(input) {
 		href
 	} : { role: "button" };
 }
+
+//#endregion
+//#region ../browser/src/dom/perception.ts
 /** 值可能是凭据的输入类型：即便宿主忘了写进 exclude 也不读值。操作侧复用同一份，不另写 */
 const SECRET_INPUT_TYPES = /* @__PURE__ */ new Set(["password", "hidden"]);
-/** 可被操作的角色：只给这些节点发句柄，其余节点模型连提都提不出来 */
+/** 可被操作的角色：只有这些节点的句柄能拿去写页面 */
 const ACTIONABLE_ROLES = /* @__PURE__ */ new Set([
 	"button",
 	"checkbox",
@@ -2205,9 +2293,34 @@ const ACTIONABLE_ROLES = /* @__PURE__ */ new Set([
 	"switch",
 	"textbox"
 ]);
+/**
+* 只能做子树锚点的容器角色（分册 14 §6.1）。
+*
+* 这些节点拿到的是“读”句柄：`perceive_page(ref)` 能以它为根续读，
+* `act_on_page` 拿到它则一律被拒。不取 generic：那等于给每个 div 发句柄。
+*/
+const ANCHOR_ROLES = /* @__PURE__ */ new Set([
+	"article",
+	"dialog",
+	"feed",
+	"grid",
+	"group",
+	"list",
+	"listitem",
+	"main",
+	"navigation",
+	"region",
+	"row",
+	"rowgroup",
+	"table",
+	"tabpanel",
+	"tree",
+	"treeitem"
+]);
 /** tag → 可访问性角色的最小映射；命中不了就退到 generic，不猜 */
 const ROLE_BY_TAG = {
 	A: "link",
+	ARTICLE: "article",
 	BUTTON: "button",
 	CANVAS: "img",
 	H1: "heading",
@@ -2381,7 +2494,7 @@ function describe(element, excluded, doc, view, capture, handles, frame, provena
 			element,
 			role,
 			doc,
-			hasActionableDescendant: children.some((child) => child.ref !== void 0),
+			hasActionableDescendant: children.some((child) => child.ref !== void 0 && handles?.isAction(child.ref) === true),
 			context: promotion
 		});
 		if (promoted !== void 0) {
@@ -2514,11 +2627,13 @@ var HandleIssuer = class {
 	}
 	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 kind = ACTIONABLE_ROLES.has(role) ? "action" : ANCHOR_ROLES.has(role) ? "anchor" : void 0;
+		if (kind === void 0) return void 0;
 		const known = this.#refByElement.get(element);
 		if (known !== void 0 && this.#table.has(known)) {
 			this.#table.set(known, {
 				element,
+				kind,
 				...frame !== void 0 ? { frame } : {}
 			});
 			return known;
@@ -2528,11 +2643,16 @@ var HandleIssuer = class {
 		const ref = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
 		this.#table.set(ref, {
 			element,
+			kind,
 			...frame !== void 0 ? { frame } : {}
 		});
 		this.#refByElement.set(element, ref);
 		return ref;
 	}
+	/** 角色提升要的是「有可操作后代」，容器锚点不算；混进来会把可点容器判成已有出口 */
+	isAction(ref) {
+		return this.#table.get(ref)?.kind === "action";
+	}
 	get table() {
 		return this.#table;
 	}
@@ -2633,12 +2753,20 @@ function createDomPerceptionReader(options = {}) {
 	};
 	/** 该帧的操作范围；没有对应条目就是「这个帧只可读不可操作」。按展示串匹配（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) {
+	/**
+	* @param subtree 不为 `undefined` 时只读这一棵子树（分册 14）。
+	* 它**不是一个新的范围来源**：子树必须先落在某条帧授权的 include 根下、
+	* 且未被 exclude 命中，否则遍历**根本不开始**（`anchored: false`）。
+	* 命中时也只是把那一帧的 `roots` 换成这一个元素，遍历器与 exclude 判定一字未改——
+	* 「带 `ref` 的结果是不带它时的子集」因此是个结构事实（FR-14.2）。
+	*/
+	function collect(scope, capture, subtree) {
 		const root = rootDocument();
 		if (root === void 0) return {
 			nodes: [],
 			frameNotes: [],
-			nestedFrames: []
+			nestedFrames: [],
+			anchored: false
 		};
 		handles ??= new HandleIssuer(/* @__PURE__ */ new Set(), /* @__PURE__ */ new Set());
 		handles.prune();
@@ -2730,6 +2858,7 @@ function createDomPerceptionReader(options = {}) {
 			issuer.useSets(actionable, actionExcluded);
 			return node !== void 0;
 		}
+		let anchored = subtree === void 0;
 		for (const { scope: frameScope, label, doc } of resolvedScopes) {
 			const view = doc.defaultView;
 			const tag = label === "self" ? void 0 : label;
@@ -2737,14 +2866,27 @@ function createDomPerceptionReader(options = {}) {
 			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 = [];
+			let roots = [];
 			for (const selector of frameScope.include) for (const element of doc.querySelectorAll(selector)) if (!roots.includes(element)) roots.push(element);
+			if (subtree !== void 0) {
+				const inScope = roots.some((element) => element === subtree || element.contains(subtree));
+				const cut = [...excluded].some((element) => element === subtree || element.contains(subtree));
+				if (!inScope || cut) continue;
+				roots = [subtree];
+				anchored = true;
+			}
 			for (const element of roots) {
 				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);
 		}
+		if (subtree !== void 0) return {
+			nodes,
+			frameNotes,
+			nestedFrames,
+			anchored
+		};
 		pruneElevated();
 		const view = root.defaultView;
 		const sets = actionSets(root, actionScopeFor("self"));
@@ -2764,15 +2906,16 @@ function createDomPerceptionReader(options = {}) {
 		return {
 			nodes,
 			frameNotes,
-			nestedFrames
+			nestedFrames,
+			anchored
 		};
 	}
-	async function readWithImages(scope, capture) {
+	async function readWithImages(scope, capture, subtree) {
 		const targets = [];
-		const { nodes, frameNotes, nestedFrames } = collect(scope, {
+		const { nodes, frameNotes, nestedFrames, anchored } = collect(scope, {
 			targets,
 			minImageArea: capture.minImageArea ?? 0
-		});
+		}, subtree);
 		const selected = targets.slice(0, capture.maxImages);
 		const images = [];
 		let imageFailures = 0;
@@ -2800,6 +2943,7 @@ function createDomPerceptionReader(options = {}) {
 			images,
 			imagesOmitted: targets.length - selected.length,
 			imageFailures,
+			anchored,
 			...frameNotes.length > 0 ? { frameNotes } : {},
 			...nestedFrames.length > 0 ? { nestedFrames } : {}
 		};
@@ -2816,6 +2960,28 @@ function createDomPerceptionReader(options = {}) {
 		}
 		return readWithImages(scope, capture);
 	}
+	/**
+	* 子树续读（分册 14 FR-14.1）。三条判定全在遍历开始**之前**：
+	* 句柄不认识 → `unknown-ref`；解析得到的元素已离开文档、
+	* 或不在任何一条帧授权的 include 根下、或被 exclude 连根剪掉 → `out-of-scope`。
+	*
+	* 拒绝走返回值而不是抛错：跨上下文的 reject 到本地就是一个没有错误码的 `Error`。
+	*/
+	async function readSubtree(scope, ref, capture) {
+		const element = handles?.table.get(ref)?.element;
+		if (element === void 0 || !element.isConnected) return { rejected: "unknown-ref" };
+		if (capture?.images === true && capture.maxImages > 0) {
+			const { anchored, ...result } = await readWithImages(scope, capture, element);
+			return anchored ? result : { rejected: "out-of-scope" };
+		}
+		const { nodes, frameNotes, nestedFrames, anchored } = collect(scope, void 0, element);
+		if (!anchored) return { rejected: "out-of-scope" };
+		return {
+			nodes,
+			...frameNotes.length > 0 ? { frameNotes } : {},
+			...nestedFrames.length > 0 ? { nestedFrames } : {}
+		};
+	}
 	/** 当前活动模态；跨帧不适用（模态提升只在主文档语义下成立） */
 	function modalSnapshot() {
 		const root = rootDocument();
@@ -2828,7 +2994,9 @@ function createDomPerceptionReader(options = {}) {
 	}
 	return {
 		read,
+		readSubtree,
 		resolve: (ref) => handles?.table.get(ref)?.element,
+		handleKindOf: (ref) => handles?.table.get(ref)?.kind,
 		frameOf: (ref) => handles?.table.get(ref)?.frame,
 		modalSnapshot,
 		elevateNewModals: (before) => {
@@ -2871,6 +3039,38 @@ function createDomPerceptionReader(options = {}) {
 		}
 	}
 }
+
+//#endregion
+//#region ../browser/src/remote/documentIdentity.ts
+/**
+* 文档标识（0.16.0 分册 11 · FR-11.1）。
+*
+* 它有且只有两个消费者，且**必须是同一个函数**：
+* ① 感知回复里的 `document.key`，决定这批句柄进哪个分片；
+* ② `PageActionOutcome.navigated`，执行前后各取一次。
+* 两处各写一套判定，就会出现「操作说导航了、分片说没换」的不一致（AC-11.4 / AC-13.4 验的就是这个）。
+*/
+/** 每个文档实例一次。页面重载即换，因此真导航天然换 key */
+const instance = (() => {
+	const bytes = /* @__PURE__ */ new Uint8Array(8);
+	crypto.getRandomValues(bytes);
+	return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+})();
+/**
+* `instance` + 当前地址。真导航换 `instance`，帧内路由（SPA）换 `href`，
+* 两类都被这一个串覆盖——靠 origin 比对识别不出后者。
+*
+* `href` 含 hash 是有意的：纯 hash 跳转在很多站点上会换掉整块内容，
+* 判成换文档是安全侧的选择（代价是多感知一次；漏判没有便宜的补救）。
+* @experimental
+*/
+function documentKey(view) {
+	const href = view?.location.href;
+	return href === void 0 ? void 0 : `${instance}\u0000${href}`;
+}
+
+//#endregion
+//#region ../browser/src/dom/pageAction.ts
 const FILLABLE_TAGS = /* @__PURE__ */ new Set(["INPUT", "TEXTAREA"]);
 /** 只看显式声明，不看尺寸：jsdom 有 getComputedStyle 但没有布局 */
 function hidden(element) {
@@ -2953,6 +3153,54 @@ function fillValue(element, value) {
 	element.dispatchEvent(new Event("change", { bubbles: true }));
 }
 const norm = (text) => (text ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+/**
+* 一次「像人一样」的点击。
+*
+* `HTMLElement.click()` **只**派发 `click`，不派发指针/鼠标序列，也不移动焦点。
+* 大量自研下拉、弹层、菜单是在 `pointerdown` / `mousedown` 上开的（这样拖拽和
+* 「点外面关闭」才好写），于是模型「点了但什么都没发生」，人手点却正常——
+* 差别不在权限，在事件序列。真实用户点击本来就会先后产生 down 与 click 两拨事件，
+* 因此补齐序列不会造成「点两下」。
+*
+* 激活行为仍交给 `.click()`：链接跳转、复选框翻转这些默认动作由它保证。
+*/
+function press(element) {
+	const view = element.ownerDocument.defaultView;
+	const rect = element.getBoundingClientRect();
+	const base = {
+		bubbles: true,
+		cancelable: true,
+		composed: true,
+		detail: 1,
+		button: 0,
+		clientX: rect.left + rect.width / 2,
+		clientY: rect.top + rect.height / 2
+	};
+	const pointer = {
+		...base,
+		pointerId: 1,
+		pointerType: "mouse",
+		isPrimary: true
+	};
+	const Pointer = view?.PointerEvent;
+	if (Pointer !== void 0) element.dispatchEvent(new Pointer("pointerdown", {
+		...pointer,
+		buttons: 1
+	}));
+	if (element.dispatchEvent(new MouseEvent("mousedown", {
+		...base,
+		buttons: 1
+	}))) element.focus?.();
+	if (Pointer !== void 0) element.dispatchEvent(new Pointer("pointerup", {
+		...pointer,
+		buttons: 0
+	}));
+	element.dispatchEvent(new MouseEvent("mouseup", {
+		...base,
+		buttons: 0
+	}));
+	element.click();
+}
 /** 轮询等待，上限固定：等不到就失败，不能无限挂着一次工具调用 */
 async function waitFor(probe, timeoutMs = 2e3) {
 	const deadline = Date.now() + timeoutMs;
@@ -2991,7 +3239,7 @@ async function selectOption(element, value) {
 		} : fail(`The control did not accept "${value}".`);
 	}
 	const doc = element.ownerDocument;
-	element.click();
+	press(element);
 	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));
@@ -3029,7 +3277,7 @@ function setToggle(element, value, target) {
 		target,
 		noop: true
 	};
-	element.click();
+	press(element);
 	return {
 		ok: true,
 		target
@@ -3072,7 +3320,44 @@ function createDomPageActionExecutor(options) {
 			elevated: true
 		} : described;
 	};
+	/**
+	* 后退（0.16.0 分册 13 / FR-13.6）。
+	*
+	* 两种「没退成」都返回 `ok: true, noop: true` 而不是失败：
+	* 返回失败模型会重试，而重试同样退不动——它需要的是「这条路走不通」的事实，
+	* 不是一个可以再试一次的错误（与 `set` 的 noop 同惯例）。
+	*/
+	const goBack = async () => {
+		const view = (options.document ?? globalThis.document)?.defaultView;
+		const target = { role: "document" };
+		if (view === void 0 || view === null) return {
+			ok: false,
+			target,
+			reason: "No browsing context is available."
+		};
+		if (view.history.length <= 1) return {
+			ok: true,
+			target,
+			noop: true
+		};
+		const keyBefore = documentKey(view);
+		view.history.back();
+		return await waitFor(() => {
+			const key = documentKey(view);
+			return key !== void 0 && key !== keyBefore ? key : void 0;
+		}, 500) === void 0 ? {
+			ok: true,
+			target,
+			noop: true
+		} : {
+			ok: true,
+			target,
+			navigated: true,
+			documentUrl: view.location.href
+		};
+	};
 	const execute = async (request) => {
+		if (request.action === "back") return await goBack();
 		const element = reader.resolve(request.ref);
 		if (element === void 0) return {
 			ok: false,
@@ -3085,36 +3370,37 @@ function createDomPageActionExecutor(options) {
 			target,
 			reason
 		});
+		if (reader.handleKindOf(request.ref) === "anchor") return fail("That reference points at a container, which cannot be acted on. Use it with perceive_page to read inside it, then act on an element found there.");
 		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 frameView = element.ownerDocument.defaultView;
-		const urlBefore = frameView?.location.href;
+		const keyBefore = documentKey(frameView);
 		const done = async (outcome) => {
 			if (!outcome.ok) return outcome;
 			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;
+				const key = documentKey(frameView);
+				return key !== void 0 && key !== keyBefore ? { key } : 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";
-			const urlAfter = frameView?.location.href;
-			const navigated = urlAfter !== void 0 && urlBefore !== void 0 && urlAfter !== urlBefore;
+			const keyAfter = documentKey(frameView);
+			const navigated = keyAfter !== void 0 && keyBefore !== void 0 && keyAfter !== keyBefore;
 			return {
 				...outcome,
 				...name !== void 0 ? { elevatedModal: name } : {},
 				...navigated ? {
 					navigated: true,
-					documentUrl: urlAfter
+					documentUrl: frameView?.location.href
 				} : {}
 			};
 		};
 		if (request.action === "click") {
-			element.click();
+			press(element);
 			return await done({
 				ok: true,
 				target
@@ -3168,38 +3454,121 @@ function createDomPageActionExecutor(options) {
 		describe
 	};
 }
+
+//#endregion
+//#region ../browser/src/remote/registry.ts
+/**
+* 分片数的防泄漏软上限（分册 11 / DV-2）。
+*
+* 它**不是** FR-11.5 那个容量闸门：那一条管的是「同时有几个**标签页**可操作」，
+* 触顶硬拒绝，落在 `TabWorksetPolicy`。这里管的是同一个标签页里连续跳页攒下的历史分片，
+* 那些本来就该失效，按最久未使用逐出即可，逐出不构成对模型的拒绝。
+*/
+const SHARD_SOFT_LIMIT = 24;
+/** 不给 `shard` 时用的分片键；单分片宿主全程待在这一个分片里 */
+const DEFAULT_SHARD = "";
+/**
+* 把解析结果翻译成给模型看的补充说明（分册 11 / FR-11.6）；
+* 接到 `PageActionPolicyOptions.diagnose` 上即可：
+*
+* ```ts
+* diagnose: (ref) => explainResolution(targets.resolve(ref))
+* ```
+*
+* `unknown` 返回 `undefined` 而不是自己拼一句：让 policy 落回它的缺省文案，
+* 于是 AC-11.3 要求的「与 0.15.0 逐字相同」是**构造性**成立的，
+* 而不是靠两个文件里的字符串抄得一样。
+* @experimental
+*/
+function explainResolution(resolution) {
+	if (resolution.status === "unfocused") return "This reference belongs to a different page. Switch to that page first, then retry.";
+	if (resolution.status === "expired") return "The page this reference belongs to has changed or was closed. Perceive the page again and retry.";
+}
 /** @experimental */
-function createRemoteTargetRegistry() {
-	let table = /* @__PURE__ */ new Map();
+function createRemoteTargetRegistry(options = {}) {
+	const maxShards = Math.max(1, Math.trunc(options.maxShards ?? 24));
+	let shards = /* @__PURE__ */ new Map();
+	let refIndex = /* @__PURE__ */ new Map();
+	let focused = DEFAULT_SHARD;
+	const touch = (key, shard) => {
+		shards.delete(key);
+		shards.set(key, shard);
+		while (shards.size > maxShards) {
+			const oldest = shards.keys().next();
+			if (oldest.done === true) break;
+			shards.delete(oldest.value);
+		}
+	};
 	return {
 		/**
 		* 整表替换而非合并（FR-13.2）：合并会让上一次感知的 ref 在本次感知后仍然可执行——
 		* 那正是 `PAGE_ACTION_STALE_REF` 要拦的东西。本地形态里旧 ref 天然失效
 		* （DOM 重新遍历、句柄表 prune 掉离开文档的条目），远端必须手动复现这个失效语义，
 		* 否则远端比本地更松。
+		*
+		* 0.16.0 起替换的是**该分片**的表，别的分片不受影响——这是相对 0.15.0 的唯一语义变化。
 		*/
-		replace(entries) {
-			const next = /* @__PURE__ */ new Map();
+		replace(entries, document) {
+			const shard = document?.key ?? DEFAULT_SHARD;
+			const table = /* @__PURE__ */ new Map();
 			for (const entry of entries) {
 				const { ref, role, name, secret, frame, elevated } = entry;
-				next.set(ref, {
+				table.set(ref, {
 					role,
 					...name !== void 0 ? { name } : {},
 					...secret === true ? { secret: true } : {},
 					...frame !== void 0 ? { frame } : {},
 					...elevated === true ? { elevated: true } : {}
 				});
+				refIndex.set(ref, shard);
 			}
-			table = next;
+			touch(shard, {
+				table,
+				...document !== void 0 ? { document } : {}
+			});
+			focused = shard;
 		},
 		get(ref) {
-			return table.get(ref);
+			return shards.get(focused)?.table.get(ref);
+		},
+		resolve(ref) {
+			const target = shards.get(focused)?.table.get(ref);
+			if (target !== void 0) return {
+				status: "ok",
+				target
+			};
+			const owner = refIndex.get(ref);
+			if (owner === void 0) return { status: "unknown" };
+			return shards.get(owner)?.table.has(ref) === true ? { status: "unfocused" } : { status: "expired" };
+		},
+		focus(shard) {
+			focused = shard;
+		},
+		get focused() {
+			return focused === DEFAULT_SHARD ? void 0 : focused;
+		},
+		describePage() {
+			return shards.get(focused)?.document;
+		},
+		drop(shard) {
+			shards.delete(shard);
+		},
+		clear() {
+			shards = /* @__PURE__ */ new Map();
+			refIndex = /* @__PURE__ */ new Map();
+			focused = DEFAULT_SHARD;
 		},
 		get size() {
-			return table.size;
+			return shards.get(focused)?.table.size ?? 0;
+		},
+		get shardCount() {
+			return shards.size;
 		}
 	};
 }
+
+//#endregion
+//#region ../browser/src/remote/transport.ts
 /** 缺省单次往返上限（FR-13.2 / FR-13.3） */
 const DEFAULT_PAGE_AGENT_TIMEOUT_MS = 1e4;
 /**
@@ -3230,6 +3599,9 @@ async function roundTrip(transport, request, expect, code, timeoutMs) {
 	if (reply.type !== expect) throw new WebSkillError(code, `Page agent replied with "${reply.type}" to a "${request.type}" request; expected "${expect}".`);
 	return reply;
 }
+
+//#endregion
+//#region ../browser/src/remote/reader.ts
 /**
 * 跨上下文的页面感知（分册 13 / FR-13.2）。
 *
@@ -3238,17 +3610,21 @@ async function roundTrip(transport, request, expect, code, timeoutMs) {
 * @experimental
 */
 function createRemotePerceptionReader(options) {
-	const { transport, targets, timeoutMs = DEFAULT_PAGE_AGENT_TIMEOUT_MS } = options;
+	const { transport, targets, timeoutMs = DEFAULT_PAGE_AGENT_TIMEOUT_MS, onDocument } = options;
 	return { async read(scope, capture) {
 		const reply = await roundTrip(transport, {
 			type: "perceive",
 			scope,
 			...capture !== void 0 ? { capture } : {}
 		}, "perceive-result", "PERCEPTION_FAILED", timeoutMs);
-		targets.replace(reply.targets);
+		targets.replace(reply.targets, reply.document);
+		if (reply.document !== void 0) onDocument?.(reply.document);
 		return reply.result;
 	} };
 }
+
+//#endregion
+//#region ../browser/src/remote/executor.ts
 /**
 * 跨上下文的页面操作执行器（分册 13 / FR-13.3）。
 * @experimental
@@ -3280,6 +3656,9 @@ function createRemotePageActionExecutor(options) {
 		}
 	};
 }
+
+//#endregion
+//#region ../browser/src/remote/handler.ts
 /** 深度收集句柄；顺序即遍历序，便于与本地形态逐条比对 */
 function collectRefs(nodes, out = []) {
 	for (const node of nodes) {
@@ -3310,8 +3689,25 @@ function createPageAgentHandler(options = {}) {
 	});
 	const executor = createDomPageActionExecutor({
 		reader,
+		...options.document !== void 0 ? { document: options.document } : {},
 		...options.pickFiles !== void 0 ? { pickFiles: options.pickFiles } : {}
 	});
+	/**
+	* 这批句柄属于哪个文档（FR-11.1）。`key` 与 `PageActionOutcome.navigated`
+	* 出自同一个 `documentKey()` —— 这是「操作说导航了、分片说没换」不可能发生的构造性保证。
+	*/
+	const describeDocument = () => {
+		const doc = options.document ?? globalThis.document;
+		const key = documentKey(doc?.defaultView);
+		if (key === void 0) return void 0;
+		const url = doc.defaultView?.location.href;
+		const title = doc.title;
+		return {
+			key,
+			...url !== void 0 ? { url } : {},
+			...title !== void 0 && title !== "" ? { title } : {}
+		};
+	};
 	return { async handle(request) {
 		try {
 			if (request.type === "perceive") {
@@ -3325,10 +3721,12 @@ function createPageAgentHandler(options = {}) {
 						...target
 					});
 				}
+				const identity = describeDocument();
 				return {
 					type: "perceive-result",
 					result,
-					targets
+					targets,
+					...identity !== void 0 ? { document: identity } : {}
 				};
 			}
 			return {
@@ -3344,6 +3742,206 @@ function createPageAgentHandler(options = {}) {
 		}
 	} };
 }
+
+//#endregion
+//#region ../browser/src/remote/frameRouter.ts
+/** @experimental */
+const DEFAULT_FRAME_BUDGET = {
+	maxFrames: 12,
+	maxNodes: 1500
+};
+function countNodes(nodes) {
+	let total = 0;
+	for (const node of nodes) total += 1 + countNodes(node.children ?? []);
+	return total;
+}
+function note(name) {
+	return {
+		role: "note",
+		name
+	};
+}
+/**
+* 地址归一化：只比较 origin + path。
+*
+* 父页面写的 `src` 常带 `?t=123` 之类的缓存参数，甚至被框架改写过 hash。
+* 带上 query/hash 比对会把明明是同一帧的判成换了页，
+* 于是本该读到的内容变成一句「导航走了」——宁可粗一点也不能漏。
+*/
+function frameKey(url) {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.origin}${parsed.pathname}`;
+	} catch {
+		return;
+	}
+}
+/**
+* 确认卡与模型上下文里指称一帧的说法（分册 16 FR-16.6）。
+*
+* 带上 host 而不只用父页面写的 `hint`：用户要能一眼分清「页面主体里的那个按钮」
+* 和「某个第三方 iframe 里的按钮」，而 `hint` 来自被嵌一方决定不了、
+* 嵌入方随便写的属性——`title="账户设置"` 的 iframe 完全可以指向别人的域。
+*/
+function frameLabelOf(nested) {
+	try {
+		return `${nested.hint} (${new URL(nested.url).host})`;
+	} catch {
+		return nested.hint;
+	}
+}
+/** 与 SDK 单帧取像超限时的文案同源；两边改要一起改 */
+const IMAGE_LIMIT_NOTE = "Not captured: the per-message image limit was reached";
+/**
+* 深度重写节点：打帧标签，并把 `imageId` 换成汇总后的全局 id。
+*
+* 每帧的取像 id 都是自己从 `img-1` 数起的，直接合并会让不同帧的图撞成同一个 id。
+* 落选（超整页预算）的图必须**同时**抹掉节点上的 `imageId`，否则节点指向一张
+* 根本没下发的图，模型会以为自己看过了。
+*/
+function relabel(nodes, frame, imageIds) {
+	return nodes.map((node) => {
+		const next = { ...node };
+		if (frame !== void 0) next.frame = node.frame ?? frame;
+		if (node.imageId !== void 0) {
+			const mapped = imageIds.get(node.imageId);
+			if (mapped === void 0) {
+				delete next.imageId;
+				next.imageNote = node.imageNote ?? IMAGE_LIMIT_NOTE;
+			} else next.imageId = mapped;
+		}
+		if (node.children !== void 0) next.children = relabel(node.children, frame, imageIds);
+		return next;
+	});
+}
+/**
+* 逐帧下钻并汇总（分册 16 FR-16.2 / FR-16.3 / FR-16.4，分册 11 FR-11.2）。
+*
+* 编排本身与浏览器 API 无关：它只认 `PageAgentRequest` / `PageAgentReply`，
+* 寻址全压在宿主实现的 `FrameDispatcher` 里。因此这个模块可以在 Service Worker
+* 里实例化，也可以服务不按帧号寻址的宿主。
+* @experimental
+*/
+function createFrameRouter(options) {
+	const budget = {
+		...DEFAULT_FRAME_BUDGET,
+		...options.budget
+	};
+	/** ref → 发放它的那一帧。`execute` 必须投回原帧，投给别的帧要么查无此 ref 要么误点同名控件 */
+	const refFrames = /* @__PURE__ */ new Map();
+	async function perceive(request) {
+		const mainAddress = await options.dispatcher.mainFrame();
+		const nodes = [];
+		const targets = [];
+		const frameNotes = [];
+		const main = await options.dispatcher.send(mainAddress, request);
+		if (main.reply.type !== "perceive-result") return main.reply;
+		const images = [];
+		let imagesOmitted = 0;
+		let imageFailures = 0;
+		const imageBudget = request.capture?.images === true ? request.capture.maxImages : 0;
+		const queue = [];
+		const visited = [mainAddress];
+		let nodeCount = 0;
+		let framesRead = 0;
+		let descended = 0;
+		const skipped = [];
+		const absorb = (reply, address, frame, imagePrefix) => {
+			framesRead += 1;
+			nodeCount += countNodes(reply.result.nodes);
+			const imageIds = /* @__PURE__ */ new Map();
+			for (const image of reply.result.images ?? []) {
+				if (images.length >= imageBudget) {
+					imagesOmitted += 1;
+					continue;
+				}
+				const id = `${imagePrefix}${image.id}`;
+				imageIds.set(image.id, id);
+				images.push({
+					...image,
+					id
+				});
+			}
+			imagesOmitted += reply.result.imagesOmitted ?? 0;
+			imageFailures += reply.result.imageFailures ?? 0;
+			nodes.push(...relabel(reply.result.nodes, frame, imageIds));
+			for (const target of reply.targets) {
+				targets.push(frame === void 0 ? target : {
+					...target,
+					frame: target.frame ?? frame
+				});
+				refFrames.set(target.ref, address);
+			}
+			if (reply.result.frameNotes !== void 0) frameNotes.push(...reply.result.frameNotes);
+			for (const nested of reply.result.nestedFrames ?? []) queue.push({
+				...nested,
+				parent: address
+			});
+		};
+		absorb(main.reply, mainAddress, options.mainFrameLabel, "");
+		while (queue.length > 0) {
+			const next = queue.shift();
+			if (framesRead >= budget.maxFrames || nodeCount >= budget.maxNodes) {
+				skipped.push(next.hint);
+				continue;
+			}
+			const address = await options.dispatcher.resolveNestedFrame(next, {
+				parent: next.parent,
+				visited
+			});
+			if (address === void 0) {
+				nodes.push(note(`A nested frame "${next.hint}" (${next.url}) could not be addressed and was not read. It may have been removed, replaced, or it is out of reach for this host.`));
+				continue;
+			}
+			visited.push(address);
+			const answer = await options.dispatcher.send(address, request).catch((e) => {
+				return {
+					reply: {
+						type: "error",
+						code: "TOOL_EXECUTION_FAILED",
+						message: e instanceof Error ? e.message : String(e)
+					},
+					documentUrl: ""
+				};
+			});
+			if (answer.reply.type !== "perceive-result") {
+				const reason = answer.reply.type === "error" ? answer.reply.message : "it returned an unexpected reply";
+				nodes.push(note(`A nested frame "${next.hint}" (${next.url}) was not read: ${reason}`));
+				continue;
+			}
+			if (frameKey(answer.documentUrl) !== frameKey(next.url)) {
+				nodes.push(note(`A nested frame "${next.hint}" (${next.url}) navigated away while it was being read (it answered from ${answer.documentUrl}); its content was discarded.`));
+				continue;
+			}
+			descended += 1;
+			absorb(answer.reply, address, frameLabelOf(next), `f${descended}-`);
+		}
+		if (skipped.length > 0) nodes.push(note(`${skipped.length} nested frame(s) were not read because this page exceeds the per-perception budget (${budget.maxFrames} frames / ${budget.maxNodes} nodes): ${skipped.join(", ")}. The content above is complete for the frames that were read.`));
+		return {
+			type: "perceive-result",
+			result: {
+				nodes,
+				...images.length > 0 ? { images } : {},
+				...imagesOmitted > 0 ? { imagesOmitted } : {},
+				...imageFailures > 0 ? { imageFailures } : {},
+				...frameNotes.length > 0 ? { frameNotes } : {}
+			},
+			targets,
+			...main.reply.document !== void 0 ? { document: main.reply.document } : {}
+		};
+	}
+	async function execute(request) {
+		const address = refFrames.get(request.request.ref) ?? await options.dispatcher.mainFrame();
+		return (await options.dispatcher.send(address, request)).reply;
+	}
+	return {
+		perceive,
+		execute
+	};
+}
+
+//#endregion
+//#region ../browser/src/host/protocol.ts
 const isRecord = (v) => typeof v === "object" && v !== null;
 const isNonEmptyString = (v) => typeof v === "string" && v !== "";
 /** Worker 侧入站校验：非法消息返回 undefined（忽略） */
@@ -3431,6 +4029,9 @@ function parseWorkerEvent(data) {
 		default: return;
 	}
 }
+
+//#endregion
+//#region ../browser/src/ui/workerUiBridge.ts
 /**
 * Worker 内 UiBridge：request → 'interaction' 消息到主线程，
 * 挂起等待 'interaction-response' → resolve（行内 await 跨线程成立）。
@@ -3485,6 +4086,9 @@ var WorkerUiBridge = class {
 		});
 	}
 };
+
+//#endregion
+//#region ../browser/src/host/workerRuntimeHost.ts
 const serializeError = (e) => ({
 	code: e instanceof WebSkillError ? e.code : "RUN_FAILED",
 	message: e instanceof Error ? e.message : String(e)
@@ -3712,6 +4316,9 @@ function startWorkerRuntimeHost(scope, overrides = {}) {
 		}
 	});
 }
+
+//#endregion
+//#region ../browser/src/host/workerClient.ts
 /** 主线程客户端：init/run/cancel/status/dispose 的 Promise API + 交互转发 */
 var WorkerRuntimeClient = class {
 	#worker;
@@ -3857,6 +4464,9 @@ var WorkerRuntimeClient = class {
 		}
 	}
 };
+
+//#endregion
+//#region ../browser/src/memory/encryptedMemoryStore.ts
 /**
 * 静态加密的 MemoryStore 包装（FR-19.5）。落盘形态：
 * `{ v: 1, iv: base64, ct: base64 }`；每次写入生成新的 12 字节随机 IV
@@ -4024,6 +4634,9 @@ async function deleteMemoryEncryptionKey(name = "user-profile") {
 		db.close();
 	}
 }
+
+//#endregion
+//#region ../browser/src/host/portMatrix.ts
 /**
 * 端口 × 宿主类型的**唯一定义**（AC-17.4）。
 * About 页与装配工厂都读这一份；护栏 `port-matrix-single-source` 盯着不许再抄。
@@ -4173,6 +4786,9 @@ function inspectHostWiring(input) {
 function missingPorts(reports) {
 	return reports.filter((report) => report.status === "missing");
 }
+
+//#endregion
+//#region ../browser/src/host/createBrowserChatbotHost.ts
 function createBrowserChatbotHost(options) {
 	const { fs, managedRoot, skillRoots, navigation, overrides } = options;
 	const chatbotAdapter = {
@@ -4197,6 +4813,9 @@ function createBrowserChatbotHost(options) {
 		connectFacade: overrides?.connectFacade ?? connectFacade
 	};
 }
+
+//#endregion
+//#region ../browser/src/net/fetchLinkedDocument.ts
 const DEFAULT_TIMEOUT_MS = 3e4;
 /**
 * 默认的链接文档读取实现（分册 22 §2.2）。
@@ -4227,6 +4846,9 @@ function createFetchLinkedDocumentReader(options = {}) {
 		}
 	};
 }
+
+//#endregion
+//#region ../browser/src/document/docx.ts
 /**
 * docx 正文抽取（分册 22 §2.4 / FR-23.7）。
 *
@@ -4304,6 +4926,9 @@ async function extractDocxText(bytes) {
 	}
 	return blocks.join("\n").replace(/\n{3,}/g, "\n\n").trim();
 }
+
+//#endregion
+//#region ../browser/src/document/xlsx.ts
 /**
 * xlsx 文本抽取（0.13.0 分册 12）。
 *
@@ -4553,6 +5178,9 @@ async function extractXlsxText(bytes) {
 	}
 	return sections.join("\n\n");
 }
+
+//#endregion
+//#region ../browser/src/viewer/viewerCsp.ts
 /**
 * 文档投放面的 CSP 单一来源（0.11.0 分册 18 FR-18.3 / AC-G21）。
 *
@@ -4603,6 +5231,9 @@ function viewerCspHeader(options) {
 }
 /** 本版固定的 sandbox token（供判据与装配文档引用，避免第二份清单） */
 const VIEWER_SANDBOX_TOKENS = SANDBOX_TOKENS;
+
+//#endregion
+//#region ../browser/src/viewer/documentSurface.ts
 const DEFAULT_MAX_VIEWER_PAYLOAD_BYTES = 2e6;
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 1e4;
 /** hello 的重发间隔：viewer 脚本加载完之前投出去的消息全部丢失 */
@@ -4674,6 +5305,16 @@ async function openDocumentSurface(input, options) {
 function defaultOpen(url, target) {
 	return globalThis.open?.(url, target) ?? null;
 }
+/**
+* 把 `openDocumentSurface` 柯里化成 `DocumentSurfaceHost`（0.15.0 分册 13 FR-13.3）。
+*
+* **只绑定选项，不新增任何逻辑**：体积上限、握手超时、`DOCUMENT_SURFACE_DECLINED`
+* 与审计事件全部沿用上面那一份实现（FR-13.5「逐条不变」的实现基础）。
+* @experimental
+*/
+function createDocumentSurfaceHost(options) {
+	return { open: async (input) => void await openDocumentSurface(input, options) };
+}
 /** viewer 是 opaque origin，`postMessage` 的 targetOrigin 只能是 `*` —— 用 channelId 做配对校验 */
 function viewerOrigin(_options) {
 	return "*";
@@ -4732,6 +5373,9 @@ async function audit(options, input, data) {
 		}
 	}).catch(() => void 0);
 }
+
+//#endregion
+//#region ../browser/src/viewer/shell.ts
 /**
 * 启动外壳：等主应用的 hello → 回报 ready → 收文档 → 写进 DOM。
 *
@@ -4764,6 +5408,9 @@ function startViewerShell(host, mount, onData) {
 		host.removeEventListener("message", onMessage);
 	} };
 }
+
+//#endregion
+//#region ../browser/src/viewer/blockedResources.ts
 /**
 * 监听 CSP 违规并把被拦资源汇总成一句话。
 *
@@ -4797,4 +5444,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, 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 };
+export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, DEFAULT_FRAME_BUDGET, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_UNEXTRACTED, HOST_PORT_MATRIX, IframeWorkerLike, OpfsProvider, SANDBOX_PAGE_SCRIPT_SOURCE, SHARD_SOFT_LIMIT, TsTranspiler, VIEWER_SANDBOX_TOKENS, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, XLSX_UNEXTRACTED, blockedMessage, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDocumentSurfaceHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createRemotePageActionExecutor, createRemotePerceptionReader, createRemoteTargetRegistry, deleteMemoryEncryptionKey, documentKey, explainResolution, extractDocxText, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };