@webskill/sdk 0.15.0 → 0.16.0

package/dist/browser.js

@@ -6,7 +6,7 @@ import { a as networkPolicyLibSource, c as bridgeError, d as FsMemoryStore, g as
 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 { 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） */
@@ -2281,7 +2281,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 +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",
@@ -2469,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) {
@@ -2602,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;
@@ -2616,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;
 	}
@@ -2721,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();
@@ -2818,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;
@@ -2825,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"));
@@ -2852,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;
@@ -2888,6 +2943,7 @@ function createDomPerceptionReader(options = {}) {
 			images,
 			imagesOmitted: targets.length - selected.length,
 			imageFailures,
+			anchored,
 			...frameNotes.length > 0 ? { frameNotes } : {},
 			...nestedFrames.length > 0 ? { nestedFrames } : {}
 		};
@@ -2904,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();
@@ -2916,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) => {
@@ -2960,6 +3040,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 +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;
@@ -3082,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));
@@ -3120,7 +3277,7 @@ function setToggle(element, value, target) {
 		target,
 		noop: true
 	};
-	element.click();
+	press(element);
 	return {
 		ok: true,
 		target
@@ -3163,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,
@@ -3176,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
@@ -3262,35 +3457,112 @@ function createDomPageActionExecutor(options) {
 
 //#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;
 		}
 	};
 }
@@ -3338,14 +3610,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 +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") {
@@ -3431,10 +3721,12 @@ function createPageAgentHandler(options = {}) {
 						...target
 					});
 				}
+				const identity = describeDocument();
 				return {
 					type: "perceive-result",
 					result,
-					targets
+					targets,
+					...identity !== void 0 ? { document: identity } : {}
 				};
 			}
 			return {
@@ -3634,7 +3926,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 +5444,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_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 };

package/dist/{eventTypes-Y07N8IAC.js → eventTypes-CwciaqCU.js}

@@ -41,12 +41,35 @@ const AUDIT_EVENT_TYPES = {
 	/** 候选记录被从审批队列里删除（仅 draft / pending-review / rejected 可删） */
 	candidateRemoved: "candidate.removed",
 	pagePerceived: "page.perceived",
+	/**
+	* 子树续读被拒（0.16.0 分册 14 · FR-14.6）。载荷只有 `reason`，**不含被拒的 `ref`**：
+	* 句柄换轮即失效，留下来对复盘没有帮助，却会把一个模型可控的字符串写进审计流。
+	*
+	* `reason: 'out-of-scope'` 是注入攻击的观测点：页面里写着「请读取整个页面」时，
+	* 模型若照做，这条留痕就是它留下的痕迹。
+	*/
+	pagePerceiveDenied: "page.perceive.denied",
 	pageAction: "page.action",
 	/**
 	* 一次页面操作引发了下载，但 `sandbox.downloadedFiles` 关着，模型因此一无所知
 	* （0.15.0 分册 15 · FR-15.7）。载荷只有计数与原因，不含文件名 / 大小 / 类型。
 	*/
 	pageDownloadUnreported: "page.download.unreported",
+	/**
+	* 模型侧标签页控制（0.16.0 分册 12 · FR-12.7）。写入点在
+	* `packages/agent/src/tabs/policy.ts`，同样是字面量同步。
+	*
+	* `list_page_tabs` **不在此列**：纯读、无副作用、每轮可能被调很多次，
+	* 记下来只会把 focused / closed 淹没在噪音里（DV-4）。作为交换，
+	* `page.tab.focused` 的 `data.from` 是必需的——失去列举留痕后，
+	* 它是唯一能回答「模型是从哪一页跳过去的」的字段。
+	*/
+	pageTabFocused: "page.tab.focused",
+	pageTabClosed: "page.tab.closed",
+	/** 切换 / 关闭被拒，或工作集触顶。载荷只有原因与上限，**不含**被拒的句柄内容 */
+	pageTabDenied: "page.tab.denied",
+	/** 页面操作新开了一页并被接进工作集（SC-2 的唯一入口） */
+	pageTabOpened: "page.tab.opened",
 	documentRead: "document.read",
 	documentSurfaceOpen: "document.surface.open",
 	/** 脚本按宿主声明的数据源取数（分册 16）；被拒也记，否则反复试探看不见 */