@webskill/sdk 0.15.0 → 0.17.0

package/dist/browser.js

@@ -2,11 +2,11 @@ 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 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-CBPnGPIm.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 frameSteps, i as frameLabel, n as toActionFrameScopes, r as toFrameScopes } from "./types-TUydnxaj.js";
+import { t as createWebSkillApi } from "./webSkillApi-Ce2OO5S5.js";
+import { a as frameLabel, i as toFrameScopes, o as frameSteps, r as toActionFrameScopes } from "./types-BuacBov_.js";
 
 //#region ../browser/src/fs/featureDetection.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -1355,13 +1355,16 @@ var BrowserWorkerScriptExecutor = class {
 	}
 	/** 能力桥宿主侧处理：能力关闭/授权拒绝即 TOOL_UNSUPPORTED；判定逻辑共用 runtime/sandbox/approval */
 	async #handleBridge(request, context) {
-		const gate = async (capability, message, details) => {
+		const gate = async (capability, message, details = {}) => {
 			const decision = await this.#approval.authorize({
 				runId: context.runId,
 				capability,
 				mode: this.#capabilities[capability],
 				message,
-				...details !== void 0 ? { details } : {}
+				details: {
+					skill: context.skillName,
+					...details
+				}
 			});
 			if (decision === "allowed") return void 0;
 			return bridgeError(request.id, "TOOL_UNSUPPORTED", decision === "disabled" ? `Capability "${capability}" is disabled by the sandbox capability settings` : `Capability "${capability}" was denied by the user`);
@@ -1419,7 +1422,7 @@ var BrowserWorkerScriptExecutor = class {
 				}
 				case "confirm": {
 					if (!context.confirm) return bridgeError(request.id, "TOOL_UNSUPPORTED", "Capability \"confirm\" is disabled");
-					const denied = await gate("confirm", `Script "${context.skillName}" asks for confirmation: ${request.message}`);
+					const denied = await gate("confirm", `Script "${context.skillName}" asks for confirmation: ${request.message}`, { question: request.message });
 					if (denied) return denied;
 					return {
 						id: request.id,
@@ -1677,7 +1680,7 @@ function checkDictationAvailability() {
 	return { available: true };
 }
 /** 浏览器的 error 码 → 稳定错误码；权限被拒要单独区分，UI 的降级提示不一样（FR-7.6） */
-function toError(code, message) {
+function toError$1(code, message) {
 	if (code === "not-allowed" || code === "service-not-allowed") return new WebSkillError("DICTATION_PERMISSION_DENIED", "Microphone access was denied. Voice input is unavailable until you allow it in the browser.", { reason: code });
 	return new WebSkillError("DICTATION_FAILED", message ?? `Speech recognition failed: ${code}`, { reason: code });
 }
@@ -1713,7 +1716,7 @@ function startDictation(options) {
 	recognition.onerror = (event) => {
 		if (stopped) return;
 		if (event.error === "no-speech" || event.error === "aborted") return;
-		options.onError(toError(event.error, event.message));
+		options.onError(toError$1(event.error, event.message));
 	};
 	try {
 		recognition.start();
@@ -1730,6 +1733,107 @@ function startDictation(options) {
 	} };
 }
 
+//#endregion
+//#region ../browser/src/media/camera.ts
+/**
+* 默认最长边：宿主要「最大分辨率」，给一个远超当前消费级摄像头的 ideal 让浏览器自己贴顶
+* @experimental
+*/
+const DEFAULT_CAMERA_MAX_DIMENSION = 5e3;
+function mediaDevices() {
+	return globalThis.navigator?.mediaDevices;
+}
+/**
+* 渲染期调用（FR-14.2）：不可用时按钮置灰并说明原因。
+*
+* 顺序与语音一致——`getUserMedia` 压根不存在时谈安全上下文没有意义；
+* API 在但站点是 http，取流一定会被浏览器拒绝，这条原因用户能自己解决。
+* @experimental
+*/
+function checkCameraAvailability() {
+	if (typeof mediaDevices()?.getUserMedia !== "function") return {
+		available: false,
+		reason: "api-missing"
+	};
+	if (globalThis.isSecureContext === false) return {
+		available: false,
+		reason: "insecure-context"
+	};
+	return { available: true };
+}
+/** DOMException 的 name → 稳定错误码；权限被拒要单独区分，UI 的降级提示不一样（FR-14.6） */
+function toError(e) {
+	const raw = e?.name;
+	const name = typeof raw === "string" ? raw : "";
+	if (name === "NotAllowedError" || name === "SecurityError") return new WebSkillError("CAMERA_PERMISSION_DENIED", "Camera access was denied. Photo capture is unavailable until you allow it in the browser.", { reason: name });
+	const message = e?.message;
+	return new WebSkillError("CAMERA_UNAVAILABLE", `The camera could not be opened: ${typeof message === "string" && message !== "" ? message : String(e)}`, { ...name !== "" ? { reason: name } : {} });
+}
+/**
+* 打开摄像头取景（FR-14.1）。
+*
+* **只能由用户手势调用**（FR-14.4）。设计上的保证是它不进工具列表：
+* agent 拿不到「打开摄像头」这个动作，因此不存在自主开摄像头的路径。
+* @experimental
+*/
+async function openCamera(options = {}) {
+	const devices = mediaDevices();
+	if (typeof devices?.getUserMedia !== "function") throw new WebSkillError("CAMERA_UNAVAILABLE", "Camera capture is not available in this browser.");
+	const max = options.maxDimension ?? 5e3;
+	let stream;
+	try {
+		stream = await devices.getUserMedia({
+			video: {
+				width: { ideal: max },
+				height: { ideal: max },
+				...options.facingMode !== void 0 ? { facingMode: options.facingMode } : {}
+			},
+			audio: false
+		});
+	} catch (e) {
+		throw toError(e);
+	}
+	return {
+		stream,
+		resolution() {
+			const settings = stream.getVideoTracks()[0]?.getSettings();
+			return {
+				width: settings?.width ?? 0,
+				height: settings?.height ?? 0
+			};
+		},
+		close() {
+			for (const track of stream.getTracks()) track.stop();
+		}
+	};
+}
+/**
+* 把取景元素的**当前一帧**编码成文件（FR-14.5）。
+*
+* 尺寸取 `videoWidth`/`videoHeight`（轨道原生分辨率），不取 CSS 尺寸——
+* 预览区被布局缩到 320px 宽，照着画出来的就是 320px 的照片。
+* 编码交给平台的 canvas，不手写编码器（AGENTS.md §6）。
+* @experimental
+*/
+async function capturePhoto(video, options = {}) {
+	const width = video.videoWidth;
+	const height = video.videoHeight;
+	if (width === 0 || height === 0) throw new WebSkillError("CAMERA_CAPTURE_FAILED", "The camera has not produced a frame yet.");
+	const type = options.type ?? "image/jpeg";
+	const canvas = document.createElement("canvas");
+	canvas.width = width;
+	canvas.height = height;
+	const context = canvas.getContext("2d");
+	if (context === null) throw new WebSkillError("CAMERA_CAPTURE_FAILED", "This browser did not provide a 2D canvas context.");
+	context.drawImage(video, 0, 0, width, height);
+	const blob = await new Promise((resolve) => {
+		canvas.toBlob(resolve, type, options.quality ?? .92);
+	});
+	if (blob === null) throw new WebSkillError("CAMERA_CAPTURE_FAILED", `The captured frame could not be encoded as ${type}.`);
+	const name = options.fileName ?? `photo-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.jpg`;
+	return new File([blob], name, { type: blob.type === "" ? type : blob.type });
+}
+
 //#endregion
 //#region ../browser/src/media/compressImage.ts
 /** 动图无法在不丢帧的前提下走单帧编码管线，超限直接拒绝（裁决 D-2） */
@@ -2013,6 +2117,17 @@ function isAnimatedWebp(bytes) {
 	].every((byte, index) => bytes[12 + index] === byte) && ((bytes[20] ?? 0) & 2) !== 0;
 }
 /**
+* APNG：`acTL` 块。规范要求它排在第一个 `IDAT` 之前，所以嗅探头部就够。
+* 魔数与静态 PNG 完全相同，只看魔数会让加载动画这类素材当作静态图原样发出去。
+*/
+function isAnimatedPng(bytes) {
+	for (let i = 8; i + 4 <= bytes.length; i += 1) {
+		if (bytes[i] === 73 && bytes[i + 1] === 68 && bytes[i + 2] === 65 && bytes[i + 3] === 84) return false;
+		if (bytes[i] === 97 && bytes[i + 1] === 99 && bytes[i + 2] === 84 && bytes[i + 3] === 76) return true;
+	}
+	return false;
+}
+/**
 * 按魔数认图片类型（服务端声明只作兜底）。
 *
 * 图片接口常年是「无扩展名 + `application/octet-stream`」这种组合（查询串带 file id 的尤其多），
@@ -2065,7 +2180,7 @@ async function rasterizeToPng(blob) {
 * 照抄声明会让端点解码失败并连累整次请求（一张图 400，37 张全废）。
 *
 * 魔数对得上也不等于发得出去，还有两类会被端点整次拒收，必须重编码成单帧位图：
-* - **动图**（GIF 天然多帧，WebP 看 `VP8X` 的动画位）：图片通道普遍只收静态图；
+* - **动图**（GIF 天然多帧，WebP 看 `VP8X` 的动画位，PNG 看 `acTL` 块）：图片通道普遍只收静态图；
 * - **超长边**：横幅类素材常见 7680×120 这种尺寸，字节数却很小，
 *   纯按字节压缩的预算根本不会触发，原样发出去就撞上端点的边长上限。
 *
@@ -2077,7 +2192,7 @@ async function toDeliverableBlob(blob, oversized = false) {
 	const sniffed = sniffImageMime(head);
 	if (sniffed !== void 0 && DELIVERABLE_IMAGE_MIME_TYPES.has(sniffed)) {
 		const typed = sniffed === declared ? blob : new Blob([blob], { type: sniffed });
-		const animated = sniffed === "image/gif" || sniffed === "image/webp" && isAnimatedWebp(head);
+		const animated = sniffed === "image/gif" || sniffed === "image/webp" && isAnimatedWebp(head) || sniffed === "image/png" && isAnimatedPng(head);
 		return oversized || animated ? await rasterizeToPng(typed) : typed;
 	}
 	const mimeType = sniffed ?? (declared.startsWith("image/") ? declared : void 0);
@@ -2158,11 +2273,20 @@ const ROUTE_ATTRIBUTES = [
 	"data-href",
 	"data-url"
 ];
-/** 只有这三种角色会被提升：其余角色要么本就能发句柄，要么带着不该被覆盖的语义（D-15-3） */
+/**
+* 可被启发式信号提升的角色：其余角色要么本就能发句柄，要么带着不该被覆盖的语义（D-15-3）。
+*
+* `listitem` 在列表里本该只是结构，但 `<ul><li>` 是自绘下拉 / 菜单的主流写法，
+* 选项往往就是不带 role 的 `<li>`（0.17.0 分册 11）。它与另外三个一样受
+* 「有可操作后代就不提升」约束，所以真正的语义列表不会被误伤。
+*
+* 这张白名单**只约束启发式信号**。宿主探针点名的元素走另一条路（分册 12）。
+*/
 const PROMOTABLE_ROLES = /* @__PURE__ */ new Set([
 	"generic",
 	"img",
-	"cell"
+	"cell",
+	"listitem"
 ]);
 /** 合成名的前缀，必须让模型看得出「这不是页面上的字，别拿它去搜」（FR-15.4 第 3 级） */
 const SYNTHETIC_NAME_PREFIX = "unlabeled control";
@@ -2264,10 +2388,11 @@ function synthesizeName(element, nameOf) {
 }
 /** 提升后的角色与导航目标；未提升时返回 undefined */
 function promoteRole(input) {
-	const { element, role, doc, hasActionableDescendant, context } = input;
+	const { element, role, doc, hasActionableDescendant, selfActionable, context } = input;
 	const hinted = hintedRoleOf(element, context.roleHints);
 	if (hinted !== void 0) return { role: hinted };
-	if (!PROMOTABLE_ROLES.has(role)) return void 0;
+	if (selfActionable) return void 0;
+	if (!(context.interactiveHint?.(element) === true) && !PROMOTABLE_ROLES.has(role)) return void 0;
 	if (hasActionableDescendant && role !== "img") return void 0;
 	if (!looksInteractive(element, context)) return void 0;
 	const href = navigationTargetOf(element, doc);
@@ -2281,7 +2406,7 @@ function promoteRole(input) {
 //#region ../browser/src/dom/perception.ts
 /** 值可能是凭据的输入类型：即便宿主忘了写进 exclude 也不读值。操作侧复用同一份，不另写 */
 const SECRET_INPUT_TYPES = /* @__PURE__ */ new Set(["password", "hidden"]);
-/** 可被操作的角色：只给这些节点发句柄，其余节点模型连提都提不出来 */
+/** 可被操作的角色：只有这些节点的句柄能拿去写页面 */
 const ACTIONABLE_ROLES = /* @__PURE__ */ new Set([
 	"button",
 	"checkbox",
@@ -2293,9 +2418,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",
@@ -2469,7 +2619,8 @@ 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),
+			selfActionable: ACTIONABLE_ROLES.has(role),
 			context: promotion
 		});
 		if (promoted !== void 0) {
@@ -2602,11 +2753,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;
@@ -2616,11 +2769,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;
 	}
@@ -2721,12 +2879,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();
@@ -2818,6 +2984,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;
@@ -2825,14 +2992,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"));
@@ -2852,15 +3032,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;
@@ -2888,6 +3069,7 @@ function createDomPerceptionReader(options = {}) {
 			images,
 			imagesOmitted: targets.length - selected.length,
 			imageFailures,
+			anchored,
 			...frameNotes.length > 0 ? { frameNotes } : {},
 			...nestedFrames.length > 0 ? { nestedFrames } : {}
 		};
@@ -2904,6 +3086,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();
@@ -2916,7 +3120,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) => {
@@ -2960,6 +3166,35 @@ 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"]);
@@ -3044,6 +3279,67 @@ function fillValue(element, value) {
 	element.dispatchEvent(new Event("change", { bubbles: true }));
 }
 const norm = (text) => (text ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+/**
+* 激活一个元素。
+*
+* `click()` 只定义在 `HTMLElement` 上：内联 `<svg>`（以及其它外来命名空间的元素）
+* 拿到的是 `undefined`，直接调会抛 `TypeError`，整次操作倒在最后一步。
+* 图标把监听器挂在 `<svg>` 本体上是常见写法，所以这条路径必须通。
+* 退路是派发一个真正的 `click` 事件：它照样冒泡，祖先 `<a>` 的激活行为也照样跑。
+*/
+function activate(element, init) {
+	const native = element.click;
+	if (typeof native === "function") native.call(element);
+	else element.dispatchEvent(new MouseEvent("click", init));
+}
+/**
+* 一次「像人一样」的点击。
+*
+* `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
+	}));
+	activate(element, base);
+}
 /** 轮询等待，上限固定：等不到就失败，不能无限挂着一次工具调用 */
 async function waitFor(probe, timeoutMs = 2e3) {
 	const deadline = Date.now() + timeoutMs;
@@ -3082,12 +3378,18 @@ 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));
 	if (option === void 0) return fail(`No option named "${value}" is available.`);
-	option.click();
+	activate(option, {
+		bubbles: true,
+		cancelable: true,
+		composed: true,
+		detail: 1,
+		button: 0
+	});
 	return await waitFor(() => {
 		const shown = `${accessibleName(element) ?? ""} ${element.value ?? ""}`;
 		return norm(shown).includes(norm(value)) ? true : void 0;
@@ -3120,7 +3422,7 @@ function setToggle(element, value, target) {
 		target,
 		noop: true
 	};
-	element.click();
+	press(element);
 	return {
 		ok: true,
 		target
@@ -3163,7 +3465,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,
@@ -3176,36 +3515,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 that carries its own reference. If nothing inside it has one, this part of the page offers no action and retrying here will not help.");
 		if (reader.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
@@ -3262,35 +3602,114 @@ function createDomPageActionExecutor(options) {
 
 //#endregion
 //#region ../browser/src/remote/registry.ts
+/**
+* 分片数的防泄漏软上限（分册 11 / DV-2）。
+*
+* 它**不是** FR-11.5 那个容量闸门：那一条管的是「同时有几个**标签页**可操作」，
+* 触顶硬拒绝，落在 `TabWorksetPolicy`。这里管的是同一个标签页里连续跳页攒下的历史分片，
+* 那些本来就该失效，按最久未使用逐出即可，逐出不构成对模型的拒绝。
+* 软上限必须宽于 `TAB_WORKSET_MAX_MAX`（分册 18），否则工作集里**还活着**的页
+* 会因为别的页新发分片而被逐出；64 = 天花板 32 × 每页两代历史。
+*/
+const SHARD_SOFT_LIMIT = 64;
+/** 不给 `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 ?? 64));
+	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;
 		}
 	};
 }
@@ -3338,14 +3757,15 @@ 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;
 	} };
 }
@@ -3416,8 +3836,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") {
@@ -3431,10 +3868,12 @@ function createPageAgentHandler(options = {}) {
 						...target
 					});
 				}
+				const identity = describeDocument();
 				return {
 					type: "perceive-result",
 					result,
-					targets
+					targets,
+					...identity !== void 0 ? { document: identity } : {}
 				};
 			}
 			return {
@@ -3634,7 +4073,8 @@ function createFrameRouter(options) {
 				...imageFailures > 0 ? { imageFailures } : {},
 				...frameNotes.length > 0 ? { frameNotes } : {}
 			},
-			targets
+			targets,
+			...main.reply.document !== void 0 ? { document: main.reply.document } : {}
 		};
 	}
 	async function execute(request) {
@@ -5151,4 +5591,4 @@ function originOf(blockedURI) {
 }
 
 //#endregion
-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, 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, 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_CAMERA_MAX_DIMENSION, 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, capturePhoto, checkCameraAvailability, 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, openCamera, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };