@webskill/sdk 0.22.0 → 0.23.0

package/dist/browser.js

@@ -1,14 +1,14 @@
 import { n as messageOf$1, 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 { 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-WSUDp6A1.js";
+import { o as atomicWriteText, r as resolveInsideRoot, s as isAtomicTempPath } from "./pathSecurity-CirkQwWP.js";
 import { t as assertRemoteUrlAllowed } from "./urlSafety-CiSuCJvX.js";
 import { t as ATTACHMENT_TEXT_LIMIT } from "./kind-Dc8x0HWz.js";
-import { _ as FsRunSnapshotStore, a as networkPolicyLibSource, c as bridgeError, ct as ProgressiveRouter, d as FsMemoryStore, l as parseBridgeRequest, m as AgentLoop, r as normalizeToolError, s as UPLOAD_FILES_UNAVAILABLE, t as CapabilityApproval, u as FsArtifactStore } from "./approval-DWQlDPbY.js";
+import { _ as FsRunSnapshotStore, a as networkPolicyLibSource, c as bridgeError, ct as ProgressiveRouter, d as FsMemoryStore, l as parseBridgeRequest, m as AgentLoop, r as normalizeToolError, s as UPLOAD_FILES_UNAVAILABLE, t as CapabilityApproval, u as FsArtifactStore } from "./approval-7CuZS3Z4.js";
 import { a as GoogleGenAiClient, o as AnthropicClient, s as OpenAiCompatibleClient, t as MockLlmClient } from "./llm-eIQNO9tr.js";
-import { c as toBase64$1, f as SPREADSHEET_MIME_TYPE } from "./linkedDocument-CIuh_Yp0.js";
+import { c as toBase64$1, f as SPREADSHEET_MIME_TYPE } from "./linkedDocument-CZZOl9cO.js";
 import { n as normalizeToolContent, t as mergeCatalogEntries } from "./external-_ZRQe-V9.js";
-import { t as createWebSkillApi } from "./webSkillApi-Dy-Zjv0y.js";
-import { D as toFrameScopes, E as toActionFrameScopes, O as frameLabel, _ as defersImage, a as columnWidthToPixels, b as isPdfTextTrustworthy, f as readImageSize, k as frameSteps, l as parseCellAddress, n as EMU_PER_POINT, o as fitWithin, p as PDF_LARGE_IMAGE_RATIO, r as EMU_PER_TWIP$1, s as formatCellAddress, t as EMU_PER_PIXEL, u as parseCellRange, v as takesImage } from "./geometry-wx5ZTYzi.js";
+import { t as createWebSkillApi } from "./webSkillApi-D5VMUnrv.js";
+import { A as frameSteps, D as SCROLL_DIRECTIONS, E as toActionFrameScopes, O as toFrameScopes, _ as defersImage, a as columnWidthToPixels, b as isPdfTextTrustworthy, f as readImageSize, k as frameLabel, l as parseCellAddress, n as EMU_PER_POINT, o as fitWithin, p as PDF_LARGE_IMAGE_RATIO, r as EMU_PER_TWIP$1, s as formatCellAddress, t as EMU_PER_PIXEL, u as parseCellRange, v as takesImage } from "./geometry-CRhuySKV.js";
 import { zipSync } from "fflate";
 
 //#region ../browser/src/fs/featureDetection.ts
@@ -2634,24 +2634,56 @@ const ROUTE_ATTRIBUTES = [
 * 选项往往就是不带 role 的 `<li>`（0.17.0 分册 11）。它与另外三个一样受
 * 「有可操作后代就不提升」约束，所以真正的语义列表不会被误伤。
 *
-* 这张白名单**只约束启发式信号**。宿主探针点名的元素走另一条路（分册 12）。
+* 判据是「条目 / 单元」对「容器」（0.23.0 FR-11.1）：一格、一项、一栏能承载一次点击，
+* `grid` / `menu` / `tablist` 这类容器不能，所以它们不在这里。
+*
+* 0.23.0 补齐了显式 ARIA 写法：过去 `<td>`（隐式 `cell`）能被提升，而
+* `<td role="gridcell">` 不能——把无障碍角色写对反而被降级。自绘日历、菜单、
+* 下拉普遍写显式角色，于是整片点不到（0.23.0 分册 11）。
+*
+* 这张白名单**只约束启发式信号**，放宽的是「够不够格被考察」，不是「够不够格被提升」：
+* 后面三道闸门（自身可操作 / 有可操作后代 / 看起来可交互）一个都没松。
+* 宿主探针点名的元素走另一条路（分册 12）。
 */
 const PROMOTABLE_ROLES = /* @__PURE__ */ new Set([
 	"generic",
 	"img",
 	"cell",
-	"listitem"
+	"listitem",
+	"columnheader",
+	"gridcell",
+	"rowheader",
+	"option",
+	"treeitem",
+	"tab",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio"
 ]);
 /** 合成名的前缀，必须让模型看得出「这不是页面上的字，别拿它去搜」（FR-15.4 第 3 级） */
 const SYNTHETIC_NAME_PREFIX = "unlabeled control";
 /** 往上找具名祖先的层数上限：再往上就是整页容器，拿它当限定语反而更含糊 */
 const SYNTHETIC_NAME_LOOKUP_DEPTH = 5;
 const classAndId = (element) => `${element.getAttribute("class") ?? ""} ${element.getAttribute("id") ?? ""}`;
-/** `cursor: pointer` —— 页面自己声明了可点。`getComputedStyle` 最贵，殿后 */
+/**
+* `cursor: pointer` —— 页面自己声明了可点。`getComputedStyle` 最贵，殿后。
+*
+* 只认元素**自身引入**的那一次声明：`cursor` 是 CSS 继承属性，一句
+* `.card { cursor: pointer }` 会让整张卡片里的每段文字计算值都是 `pointer`。
+* 实测某差旅站点首页 1537 个可见元素里 **1050 个**仅凭继承来的 `cursor`
+* 就被判成可交互，感知里因此冒出 826 个「按钮」（0.23.0 FR-16.1）。
+*
+* 判据是与父元素的计算值**有没有差异**：没有差异就当作继承来的。
+* 父子都显式声明 `pointer` 的情形分辨不了（没有任何 DOM API 能做到），
+* 那类元素由其余四级信号兜底，见 0.23.0 设计 17 §3。
+*/
 function looksClickable(element, view) {
 	if (view === null) return false;
 	try {
-		return view.getComputedStyle(element).cursor === "pointer";
+		if (view.getComputedStyle(element).cursor !== "pointer") return false;
+		const parent = element.parentElement;
+		if (parent === null) return true;
+		return view.getComputedStyle(parent).cursor !== "pointer";
 	} catch {
 		return false;
 	}
@@ -2901,7 +2933,9 @@ function nameOf(element, doc) {
 	}
 	if (FORM_CONTROL_TAGS.has(element.tagName)) return externalNameOf(element);
 	const own = ownText(element);
-	return own === "" ? void 0 : own;
+	if (own !== "") return own;
+	const title = element.getAttribute("title");
+	return title !== null && title.trim() !== "" ? clip(title) : void 0;
 }
 function valueOf(element) {
 	if (element.tagName === "INPUT") {
@@ -2934,6 +2968,35 @@ function hidden$1(element, view) {
 	}
 	return false;
 }
+/**
+* 页面是否有真实布局。jsdom 有 `getComputedStyle` 却没有布局引擎，那里所有元素的
+* rect 都是 0×0，把零尺寸判定套上去会让**全部**控件失去句柄（0.23.0 FR-10.4）。
+*
+* 判据与被判据用**同一种测量手段**：拿根元素的 rect 为下面的 rect 背书。
+* 真实浏览器里根元素必有尺寸，jsdom 里恒为 0×0。
+*
+* 不用 `clientHeight`，更不用 `view.innerHeight`：
+* 前者与 rect 是两套独立机制，测试桩（以及 `overflow` 的各种写法）可以只动其中一套，
+* 用 A 去为 B 背书会得出「有布局」却量不到尺寸的矛盾结论；
+* 后者在 jsdom 里被编了 1024×768，两边根本看不出区别。
+*/
+function hasLayout(doc) {
+	const rect = doc.documentElement.getBoundingClientRect();
+	return rect.width > 0 || rect.height > 0;
+}
+/**
+* 元素在屏幕上不占任何像素（0.23.0 FR-10.1）。人的鼠标点不到它，
+* 用户也无从在逐次确认卡上核对它——`act_on_page` 的安全模型建立在「用户看得懂自己批准了什么」上。
+*
+* 不复用 `measuredSizeOf()`：那个函数在 rect 为 0 时会回退去读 naturalWidth /
+* canvas 属性 / viewBox，为的是「测不到尺寸就别过滤图片」。这里要的恰恰相反：
+* 必须分得清「确实量到了 0」和「没有布局」，一档都不能回退。
+*/
+function occupiesNoSpace(element) {
+	if (!hasLayout(element.ownerDocument)) return false;
+	const rect = element.getBoundingClientRect();
+	return rect.width === 0 || rect.height === 0;
+}
 /** script / style 的正文是代码，不是页面内容 */
 const SKIPPED_TAGS = /* @__PURE__ */ new Set([
 	"SCRIPT",
@@ -2943,6 +3006,33 @@ const SKIPPED_TAGS = /* @__PURE__ */ new Set([
 ]);
 /** 活动模态的三种形态；Radix 之流用 aria-modal，原生用 <dialog open> */
 const MODAL_SELECTOR = "[role=dialog][open], dialog[open], [aria-modal=true]";
+const scrollsOverflow = (overflow) => overflow === "auto" || overflow === "scroll" || overflow === "overlay";
+/**
+* 该元素**自身**还能往哪些方向滚（0.23.0 分册 22 FR-22.1）。
+*
+* 先读布局属性再查计算样式，顺序不能倒：实测某 ERP 页 2488 个元素里只有 18 个
+* 在第一道过筛（1.4ms），对这 18 个查 overflow 只要 0.1ms；对全部 2488 个查要 5.8ms。
+* 这与 `looksClickable` 把 `getComputedStyle` 殿后是同一条原则。
+*
+* 只判元素自身、不上溯，标示因此只落在容器节点上（FR-22.3）。
+* jsdom 没有布局，这些尺寸恒为 0，筛子自然不命中。
+*/
+function scrollableDirectionsOf(element, view) {
+	const overflowsX = element.scrollWidth > element.clientWidth;
+	const overflowsY = element.scrollHeight > element.clientHeight;
+	if (!overflowsX && !overflowsY) return [];
+	const style = view.getComputedStyle(element);
+	const out = [];
+	if (overflowsX && scrollsOverflow(style.overflowX)) {
+		if (element.scrollLeft > 0) out.push("left");
+		if (element.scrollLeft < element.scrollWidth - element.clientWidth - 1) out.push("right");
+	}
+	if (overflowsY && scrollsOverflow(style.overflowY)) {
+		if (element.scrollTop > 0) out.push("up");
+		if (element.scrollTop < element.scrollHeight - element.clientHeight - 1) out.push("down");
+	}
+	return out;
+}
 /** 按尺寸落选取像的说明（FR-20.3）；与「超名额」「取像失败」必须可区分，三者排查方向不同 */
 const ICON_SKIPPED_NOTE = "Not captured: this image is smaller than the icon threshold";
 /**
@@ -2968,6 +3058,8 @@ function describe(element, excluded, doc, view, capture, handles, frame, provena
 	const value = valueOf(element);
 	let role = roleOf$1(element);
 	let promotedHref;
+	let roleBeforePromotion;
+	let nameWasSynthesized = false;
 	if (promotion !== void 0) {
 		const promoted = promoteRole({
 			element,
@@ -2978,14 +3070,37 @@ function describe(element, excluded, doc, view, capture, handles, frame, provena
 			context: promotion
 		});
 		if (promoted !== void 0) {
+			roleBeforePromotion = role;
 			role = promoted.role;
 			promotedHref = promoted.href;
-			if (name === void 0) name = clip(iconHintOf(element) ?? synthesizeName(element, (a) => nameOf(a, doc)));
+			if (name === void 0) {
+				name = clip(iconHintOf(element) ?? synthesizeName(element, (a) => nameOf(a, doc)));
+				nameWasSynthesized = true;
+			}
 		}
 	}
+	let ref = handles?.issue(element, role, frame);
+	if (roleBeforePromotion !== void 0 && ref === void 0) {
+		role = roleBeforePromotion;
+		promotedHref = void 0;
+		if (nameWasSynthesized) name = void 0;
+		ref = handles?.issue(element, role, frame);
+	}
 	const href = promotedHref ?? (role === "link" ? hrefOf(element) : void 0);
-	if (role === "generic" && name === void 0 && value === void 0 && children.length === 0) return void 0;
-	if (promotion !== void 0 && role === "generic" && name === void 0 && value === void 0) {
+	let scrollable;
+	let scrollRef;
+	if (view !== null) {
+		const directions = scrollableDirectionsOf(element, view);
+		if (directions.length > 0) {
+			const issued = ref ?? handles?.issueScrollable(element, frame);
+			if (issued !== void 0) {
+				scrollable = directions;
+				scrollRef = issued;
+			}
+		}
+	}
+	if (role === "generic" && name === void 0 && value === void 0 && children.length === 0 && scrollable === void 0) return;
+	if (promotion !== void 0 && role === "generic" && name === void 0 && value === void 0 && scrollable === void 0) {
 		if (children.length === 1) return children[0];
 	}
 	const node = {
@@ -2997,8 +3112,11 @@ function describe(element, excluded, doc, view, capture, handles, frame, provena
 		...provenance !== void 0 ? { provenance } : {},
 		...children.length > 0 ? { children } : {}
 	};
-	const ref = handles?.issue(element, role, frame);
 	if (ref !== void 0) node.ref = ref;
+	if (scrollable !== void 0) {
+		node.ref = scrollRef;
+		node.scrollable = scrollable;
+	}
 	if (isCapturableElement(element)) {
 		const captureRef = node.ref ?? handles?.issueCapture(element, frame);
 		if (captureRef !== void 0) {
@@ -3116,6 +3234,7 @@ var HandleIssuer = class {
 		if (!this.#actionable.has(element) || this.#excluded.has(element)) return void 0;
 		const kind = ACTIONABLE_ROLES.has(role) ? "action" : ANCHOR_ROLES.has(role) ? "anchor" : void 0;
 		if (kind === void 0) return void 0;
+		if (kind === "action" && occupiesNoSpace(element)) return void 0;
 		const known = this.#refByElement.get(element);
 		if (known !== void 0 && this.#table.has(known)) {
 			this.#table.set(known, {
@@ -3139,6 +3258,19 @@ var HandleIssuer = class {
 		if (known !== void 0 && this.#table.has(known)) return known;
 		return this.#mint(element, "image", frame);
 	}
+	/**
+	* 可滚容器的句柄（0.23.0 分册 22）。角色白名单之外——表格容器往往是个 `generic` div，
+	* 但 `scroll` 确实作用在它身上。不发就成了「标了能滚、模型指认不了」，正是 AC-G8 禁的那种幽灵能力。
+	*
+	* 仍过操作范围与零尺寸两道闸（FR-22.12）；已有句柄就原样复用且**不改 kind**。
+	*/
+	issueScrollable(element, frame) {
+		if (!this.#actionable.has(element) || this.#excluded.has(element)) return void 0;
+		if (occupiesNoSpace(element)) return void 0;
+		const known = this.#refByElement.get(element);
+		if (known !== void 0 && this.#table.has(known)) return known;
+		return this.#mint(element, "action", frame);
+	}
 	#mint(element, kind, frame) {
 		const bytes = /* @__PURE__ */ new Uint8Array(8);
 		crypto.getRandomValues(bytes);
@@ -3612,6 +3744,39 @@ function hidden(element) {
 	}
 	return false;
 }
+/**
+* 「开着的浮层」里必须有可操作的东西。空的定位容器（装饰角标、测量层、定位锚点）
+* 满页都是，只看定位会把它们全当成浮层——实测该页面误伤 337/400（0.23.0 设计 16 §3.1）。
+*/
+const POPOVER_CONTENT_SELECTOR = "a[href],button,input,select,textarea,[role=\"button\"],[role=\"link\"],[role=\"option\"],[role=\"menuitem\"],[role=\"gridcell\"],[role=\"tab\"],[role=\"checkbox\"],[role=\"radio\"]";
+/**
+* 这个元素旁边是不是已经有一个开着的浮层（0.23.0 FR-15.1）。
+*
+* 零 DOM 变更有两种成因：元素真的不响应，和**页面已经处于这个动作要达成的状态**。
+* 后者按分册 12 的原判据会被报成 `noop`，模型于是放弃一条已经走通的路。
+*
+* 只看**父元素这一层**：自绘下拉的写法是触发器与浮层同属一个包装容器，
+* 往上多走一层就开始把无关区块算进来（误伤 3/400 → 31/400）。
+*
+* 用 `hidden()` 而不是尺寸：jsdom 没有布局，`getBoundingClientRect()` 恒为 0，
+* 依赖尺寸这条判据就没法被测试守住（设计 16 §3.2）。
+*/
+function popoverOpenBeside(element) {
+	if (element.getAttribute("aria-expanded") === "true") return true;
+	const parent = element.parentElement;
+	if (parent === null) return false;
+	const view = element.ownerDocument.defaultView;
+	if (view === null) return false;
+	for (const candidate of parent.querySelectorAll("*")) {
+		if (candidate === element || element.contains(candidate) || candidate.contains(element)) continue;
+		const position = view.getComputedStyle(candidate).position;
+		if (position !== "absolute" && position !== "fixed") continue;
+		if (hidden(candidate)) continue;
+		if (candidate.querySelector(POPOVER_CONTENT_SELECTOR) === null) continue;
+		return true;
+	}
+	return false;
+}
 const inputType = (element) => (element.getAttribute("type") ?? "text").toLowerCase();
 const isSecret = (element) => element.tagName === "INPUT" && SECRET_INPUT_TYPES.has(inputType(element));
 const textOf$2 = (element) => element?.textContent?.replace(/\s+/g, " ").trim() ?? "";
@@ -4028,6 +4193,12 @@ function attachFiles(input, files) {
 	input.dispatchEvent(new Event("change", { bubbles: true }));
 }
 const scrolls = (overflow) => overflow === "auto" || overflow === "scroll" || overflow === "overlay";
+const axisOf = (direction) => direction === "left" || direction === "right" ? "x" : "y";
+/** 该元素自身在这条轴上能不能滚。两个条件的合取，见 `scrollTargetOf` 的注释 */
+function scrollsOn(node, axis, view) {
+	const style = view.getComputedStyle(node);
+	return axis === "y" ? scrolls(style.overflowY) && node.scrollHeight > node.clientHeight : scrolls(style.overflowX) && node.scrollWidth > node.clientWidth;
+}
 /**
 * 滚动落点（FR-10.3）：从被指认元素**自身**起沿祖先链上溯，取第一个真正能滚的容器。
 *
@@ -4041,20 +4212,21 @@ const scrolls = (overflow) => overflow === "auto" || overflow === "scroll" || ov
 * 根滚动容器单独兜底而不是靠链上命中：`documentElement` 的 `overflow-y` 计算值
 * 通常是 `visible`（滚动被传播到视口），不会被上面的判据命中，但文档确实可滚。
 * 顺序必须是先链后兜底——嵌套场景下先命中的必须是内层列表。
+*
+* **按轴判（0.23.0 分册 22 FR-22.7）**：同一个容器常常只在一条轴上溢出，
+* 拿纵向判据去找横向落点会整体判成不可滚，那正是横向滚动此前失败的原因。
 */
-function scrollTargetOf(element) {
+function scrollTargetOf(element, axis) {
 	const doc = element.ownerDocument;
 	const view = doc.defaultView;
 	if (view === null) return void 0;
-	for (let node = element; node !== null; node = node.parentElement) {
-		const style = view.getComputedStyle(node);
-		if (scrolls(style.overflowY) && node.scrollHeight > node.clientHeight) return {
-			container: node,
-			isRoot: false
-		};
-	}
+	for (let node = element; node !== null; node = node.parentElement) if (scrollsOn(node, axis, view)) return {
+		container: node,
+		isRoot: false
+	};
 	const root = doc.scrollingElement ?? doc.documentElement;
-	if (root !== null && root.scrollHeight > root.clientHeight) return {
+	const rootOverflows = root !== null && (axis === "y" ? root.scrollHeight > root.clientHeight : root.scrollWidth > root.clientWidth);
+	if (root !== null && rootOverflows) return {
 		container: root,
 		isRoot: true
 	};
@@ -4159,11 +4331,12 @@ function createDomPageActionExecutor(options) {
 	* 稳定化是滚动自己的收尾，见 `watchQuiescence`。
 	*/
 	const scrollRegion = async (element, target, direction) => {
-		const found = scrollTargetOf(element);
+		const axis = axisOf(direction);
+		const found = scrollTargetOf(element, axis);
 		if (found === void 0) return {
 			ok: false,
 			target,
-			reason: "This area cannot be scrolled: nothing around this element has a scrollable region."
+			reason: `This area cannot be scrolled ${direction}: nothing around this element scrolls ${axis === "y" ? "vertically" : "horizontally"}.`
 		};
 		const { container, isRoot } = found;
 		if (!isRoot && !reader.inActionScope(container)) return {
@@ -4171,17 +4344,22 @@ function createDomPageActionExecutor(options) {
 			target,
 			reason: "The scrollable region around this element is outside the actionable scope."
 		};
-		const step = Math.max(container.clientHeight - SCROLL_OVERLAP_PX, Math.round(container.clientHeight / 2), 1);
-		const before = container.scrollTop;
+		const extent = axis === "y" ? container.clientHeight : container.clientWidth;
+		const step = Math.max(extent - SCROLL_OVERLAP_PX, Math.round(extent / 2), 1);
+		const forward = direction === "down" || direction === "right";
+		const before = axis === "y" ? container.scrollTop : container.scrollLeft;
 		const watch = watchQuiescence(container);
-		container.scrollTop = direction === "down" ? before + step : before - step;
+		const next = forward ? before + step : before - step;
+		if (axis === "y") container.scrollTop = next;
+		else container.scrollLeft = next;
 		await watch.settle(clampScrollSettleMs(options.scrollSettleMs?.()));
-		const after = container.scrollTop;
+		const after = axis === "y" ? container.scrollTop : container.scrollLeft;
+		const limit = axis === "y" ? container.scrollHeight - container.clientHeight - 1 : container.scrollWidth - container.clientWidth - 1;
 		return {
 			ok: true,
 			target,
 			scrolled: {
-				atEnd: direction === "down" ? after >= container.scrollHeight - container.clientHeight - 1 : after <= 0,
+				atEnd: forward ? after >= limit : after <= 0,
 				movedBy: Math.abs(after - before)
 			}
 		};
@@ -4205,6 +4383,7 @@ function createDomPageActionExecutor(options) {
 		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 (occupiesNoSpace(element)) return fail("The element takes up no space on screen, so it cannot be clicked or pointed at.");
 		if (element.hasAttribute("disabled")) return fail("The element is disabled.");
 		const modalsBefore = reader.modalSnapshot();
 		const frameView = element.ownerDocument.defaultView;
@@ -4231,15 +4410,22 @@ function createDomPageActionExecutor(options) {
 			};
 		};
 		if (request.action === "click") {
+			const watch = watchMutations(element);
 			press(element);
-			return await done({
+			const outcome = await done({
 				ok: true,
 				target
 			});
+			const changed = watch.changed();
+			watch.stop();
+			return changed || outcome.navigated === true || outcome.elevatedModal !== void 0 || popoverOpenBeside(element) ? outcome : {
+				...outcome,
+				noop: true
+			};
 		}
 		if (request.action === "fill") {
 			if (!FILLABLE_TAGS.has(element.tagName)) return fail("The element is not a text control.");
-			if (element.hasAttribute("readonly")) return fail("The element is read-only.");
+			if (element.hasAttribute("readonly")) return fail("The element is read-only. Read-only text fields often open a picker when clicked, so try the click action on this same element.");
 			fillValue(element, request.value ?? "");
 			return await done({
 				ok: true,
@@ -4258,7 +4444,7 @@ function createDomPageActionExecutor(options) {
 		}
 		if (request.action === "set") return await done(setToggle(element, request.value ?? "", target));
 		if (request.action === "scroll") {
-			if (request.value !== "down" && request.value !== "up") return fail("Use \"down\" or \"up\".");
+			if (!SCROLL_DIRECTIONS.includes(request.value)) return fail(`Use ${SCROLL_DIRECTIONS.map((d) => `"${d}"`).join(" / ")}.`);
 			return await scrollRegion(element, target, request.value);
 		}
 		if (request.action === "hover") {
@@ -4270,7 +4456,7 @@ function createDomPageActionExecutor(options) {
 			return await done({
 				ok: true,
 				target,
-				...changed ? {} : { noop: true }
+				...changed || popoverOpenBeside(element) ? {} : { noop: true }
 			});
 		}
 		if (request.action === "drag") {
@@ -4475,16 +4661,71 @@ async function roundTrip(transport, request, expect, code, timeoutMs) {
 */
 function createRemotePerceptionReader(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, reply.document);
-		if (reply.document !== void 0) onDocument?.(reply.document);
-		return reply.result;
-	} };
+	/**
+	* 上一批写进分片的条目（0.23.0 分册 13 / FR-13.4）。
+	*
+	* `registry.replace` 是**整体替换分片**，而子树读取只回传子树内的条目——
+	* 照搬就等于「读完日期面板，页面别处全部失去句柄」。本地形态没有这个问题：
+	* `HandleIssuer` 的表跨感知保留，子树读取只是少发几个 ref，既有的一个都不丢。
+	* 差值由这里补出来，而不是转嫁给模型。
+	*
+	* 状态留在发起方而不是给 `RemoteTargetRegistry` 加 `merge()`：
+	* 后者对所有实现方都是破坏性变更，需求 §2.2 把它列为禁止项。
+	*/
+	let lastShard;
+	const commit = (entries, document, merge) => {
+		const sameDocument = lastShard !== void 0 && lastShard.key === document?.key;
+		let next = entries;
+		if (merge && sameDocument && lastShard !== void 0) {
+			const byRef = /* @__PURE__ */ new Map();
+			for (const entry of lastShard.entries) byRef.set(entry.ref, entry);
+			for (const entry of entries) byRef.set(entry.ref, entry);
+			next = [...byRef.values()];
+		}
+		targets.replace(next, document);
+		lastShard = {
+			key: document?.key,
+			entries: next
+		};
+		if (document !== void 0) onDocument?.(document);
+	};
+	return {
+		async read(scope, capture) {
+			const reply = await roundTrip(transport, {
+				type: "perceive",
+				scope,
+				...capture !== void 0 ? { capture } : {}
+			}, "perceive-result", "PERCEPTION_FAILED", timeoutMs);
+			commit(reply.targets, reply.document, false);
+			return reply.result;
+		},
+		/**
+		* 子树续读（0.23.0 分册 13 / FR-13.1）。
+		*
+		* 本地形态早就有这个方法，缺的只是这一段跨上下文接线；不实现它，
+		* policy 会直接抛 `PERCEPTION_SUBTREE_UNSUPPORTED`，模型在浏览器扩展这类
+		* 宿主里就永远没有「第一段没找到 → 展开某个子树再看」这条自救路径。
+		*/
+		async readSubtree(scope, ref, capture) {
+			let reply;
+			try {
+				reply = await roundTrip(transport, {
+					type: "perceive",
+					scope,
+					ref,
+					...capture !== void 0 ? { capture } : {}
+				}, "perceive-result", "PERCEPTION_FAILED", timeoutMs);
+			} catch (e) {
+				if (e instanceof WebSkillError) {
+					if (e.code === "PERCEPTION_SUBTREE_OUT_OF_SCOPE") return { rejected: "out-of-scope" };
+					if (e.code === "PERCEPTION_SUBTREE_UNKNOWN_REF") return { rejected: "unknown-ref" };
+				}
+				throw e;
+			}
+			commit(reply.targets, reply.document, true);
+			return reply.result;
+		}
+	};
 }
 
 //#endregion
@@ -4553,6 +4794,24 @@ function collectRefs(nodes, out = []) {
 	return out;
 }
 /**
+* 子树被拒 → 既有的 `error` 应答变体（0.23.0 分册 13 / FR-13.5）。
+* 不新增应答形态，是把本册的契约变更压到「一个可选请求字段」的关键。
+*
+* 这两个错误码本来就在 `WebSkillErrorCode` 里，远程 reader 靠它们还原出
+* `{ rejected }`，policy 那边的 `#recordDenied` 才能照常留痕。
+*/
+function rejectionReply(rejected) {
+	return rejected === "out-of-scope" ? {
+		type: "error",
+		code: "PERCEPTION_SUBTREE_OUT_OF_SCOPE",
+		message: "that reference is outside the perception scope, so its subtree cannot be read"
+	} : {
+		type: "error",
+		code: "PERCEPTION_SUBTREE_UNKNOWN_REF",
+		message: "that reference is not on this page any more; perceive the page again to get a fresh reference"
+	};
+}
+/**
 * 页面侧处理器（分册 13 / FR-13.7）。
 *
 * 必须是工厂而不是裸函数：`DomPerceptionReader` **是有状态的**——
@@ -4596,8 +4855,15 @@ function createPageAgentHandler(options = {}) {
 	return { async handle(request) {
 		try {
 			if (request.type === "perceive") {
-				const raw = request.capture === void 0 ? reader.read(request.scope) : await reader.read(request.scope, request.capture);
-				const result = Array.isArray(raw) ? { nodes: raw } : raw;
+				let result;
+				if (request.ref !== void 0) {
+					const out = request.capture === void 0 ? await reader.readSubtree(request.scope, request.ref) : await reader.readSubtree(request.scope, request.ref, request.capture);
+					if ("rejected" in out) return rejectionReply(out.rejected);
+					result = out;
+				} else {
+					const raw = request.capture === void 0 ? reader.read(request.scope) : await reader.read(request.scope, request.capture);
+					result = Array.isArray(raw) ? { nodes: raw } : raw;
+				}
 				const targets = [];
 				for (const ref of collectRefs(result.nodes)) {
 					const target = executor.describe(ref);
@@ -6579,7 +6845,7 @@ function serializeXmlPart(declaration, doc) {
 /** @throws WebSkillError 归档损坏，或不是 OOXML（缺 `[Content_Types].xml`） */
 async function readOoxmlPackage(bytes) {
 	const entries = await unzipWithLimits(bytes);
-	const pkg = new Map(entries);
+	const pkg = new Map(entries.filter(([path]) => !path.endsWith("/")));
 	if (!pkg.has(CONTENT_TYPES)) throw new WebSkillError("TEMPLATE_UNSUPPORTED", `This file is not an Office Open XML document: it has no ${CONTENT_TYPES} entry.`);
 	return pkg;
 }
@@ -6686,6 +6952,54 @@ function dropPart(pkg, partName, relsPath) {
 		pkg.set(relsPath, new TextEncoder().encode(declaration + stripped));
 	}
 }
+/** VBA 工程部件的 content type 前缀。宏的判据看这个，不看文件路径。 */
+const VBA_CONTENT_TYPE = "application/vnd.ms-office.vbaProject";
+/** macroEnabled 的主部件 content type → 对应的非宏值（0.23.0 分册 25 设计 26 §3.1）。 */
+const NON_MACRO_MAIN_TYPE = /* @__PURE__ */ new Map([
+	["application/vnd.ms-excel.sheet.macroEnabled.main+xml", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"],
+	["application/vnd.ms-excel.template.macroEnabled.main+xml", "application/vnd.openxmlformats-officedocument.spreadsheetml.template.main+xml"],
+	["application/vnd.ms-word.document.macroEnabled.main+xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"],
+	["application/vnd.ms-word.template.macroEnabled.main+xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.template.main+xml"]
+]);
+const attributeOf = (tag, name) => new RegExp(`${name}="([^"]*)"`).exec(tag)?.[1] ?? "";
+/**
+* 把宏痕迹从包里摘干净（0.23.0 分册 25 · FR-25.4）。
+*
+* 我们填完模板交出去的文件叫 `.xlsx` / `.docx`，声明的也是非宏 MIME。如果里面还留着
+* macroEnabled 的 content type 或 `vbaProject.bin`，文件就自相矛盾，Excel 会拒绝打开。
+* 宿主报来的那类文件更极端：`vbaProject.bin` 本身已经损坏或丢失，只剩标记——所以判据是
+* **`[Content_Types].xml` 里的登记**，不是「包里有没有那个部件」。
+*
+* 不是宏包时**一个字节都不改**（FR-25.5）：无条件重写 `[Content_Types].xml` 会动到属性顺序
+* 和空白，非宏模板的产物字节就跟着变了。所以第一件事是判断，不中就原样返回。
+*/
+function stripMacros(pkg) {
+	const typesBytes = pkg.get(CONTENT_TYPES);
+	if (typesBytes === void 0) return;
+	const text = new TextDecoder().decode(typesBytes);
+	if (!text.includes(VBA_CONTENT_TYPE) && !text.includes("macroEnabled.main+xml")) return;
+	const { declaration, body } = splitXmlDeclaration(text);
+	let rewritten = body;
+	for (const match of body.matchAll(/<Override\s[^>]*\/>/g)) {
+		const tag = match[0];
+		const contentType = attributeOf(tag, "ContentType");
+		if (contentType.startsWith(VBA_CONTENT_TYPE)) {
+			pkg.delete(attributeOf(tag, "PartName").replace(/^\//, ""));
+			rewritten = rewritten.replace(tag, "");
+			continue;
+		}
+		const replacement = NON_MACRO_MAIN_TYPE.get(contentType);
+		if (replacement !== void 0) rewritten = rewritten.replace(tag, tag.replace(contentType, replacement));
+	}
+	pkg.set(CONTENT_TYPES, new TextEncoder().encode(declaration + rewritten));
+	for (const [path, bytes] of pkg) {
+		if (!path.endsWith(".rels")) continue;
+		const split = splitXmlDeclaration(new TextDecoder().decode(bytes));
+		let strippedRels = split.body;
+		for (const match of split.body.matchAll(/<Relationship\s[^>]*\/>/g)) if (attributeOf(match[0], "Type").includes("/vbaProject")) strippedRels = strippedRels.replace(match[0], "");
+		if (strippedRels !== split.body) pkg.set(path, new TextEncoder().encode(split.declaration + strippedRels));
+	}
+}
 
 //#endregion
 //#region ../browser/src/document/xlsxTemplate.ts
@@ -7182,6 +7496,7 @@ async function fillXlsxTemplate(bytes, spec) {
 	}
 	if ([...touched.values()].some(({ doc }) => byTag$1(doc, "f").length > 0)) requestFullCalcOnLoad(pkg);
 	for (const [path, { declaration, doc }] of touched) pkg.set(path, serializeXmlPart(declaration, doc));
+	stripMacros(pkg);
 	assertOoxmlPackage(pkg);
 	return writeOoxmlPackage(pkg);
 }
@@ -7421,6 +7736,7 @@ async function fillDocxTemplate(bytes, spec) {
 	for (const text of spec.texts ?? []) fillText(doc, locate(doc, text), text.value);
 	(spec.images ?? []).forEach((image, index) => attachImage(pkg, doc, locate(doc, image), image, index));
 	pkg.set(DOCUMENT, serializeXmlPart(declaration, doc));
+	stripMacros(pkg);
 	assertOoxmlPackage(pkg);
 	return writeOoxmlPackage(pkg);
 }

package/dist/{geometry-wx5ZTYzi.js → geometry-CRhuySKV.js}

@@ -43,6 +43,13 @@ function toFrameScopes(scope) {
 		...scope.exclude ? { exclude: scope.exclude } : {}
 	}];
 }
+/** 四个方向的规范清单；工具层校验与文案生成都从这里取，不各写一份 */
+const SCROLL_DIRECTIONS = [
+	"up",
+	"down",
+	"left",
+	"right"
+];
 
 //#endregion
 //#region ../agent/src/pageAction/types.ts
@@ -712,4 +719,4 @@ function readJpegSize(view, length) {
 }
 
 //#endregion
-export { DOCUMENT_READ_BUDGET as C, toFrameScopes as D, toActionFrameScopes as E, frameLabel as O, sniffDocumentFormat as S, PAGE_DOCUMENT_REF as T, defersImage as _, columnWidthToPixels as a, isPdfTextTrustworthy as b, isRangeTopLeft as c, rangeContains as d, readImageSize as f, asReadMode as g, createDocumentToolSource as h, MAX_DIGIT_WIDTH as i, frameSteps as k, parseCellAddress as l, READ_DOCUMENT_TOOL as m, EMU_PER_POINT as n, fitWithin as o, PDF_LARGE_IMAGE_RATIO as p, EMU_PER_TWIP as r, formatCellAddress as s, EMU_PER_PIXEL as t, parseCellRange as u, takesImage as v, PAGE_ACTION_KINDS as w, measurePdfTextQuality as x, PDF_GARBLED_RATIO as y };
+export { frameSteps as A, DOCUMENT_READ_BUDGET as C, SCROLL_DIRECTIONS as D, toActionFrameScopes as E, toFrameScopes as O, sniffDocumentFormat as S, PAGE_DOCUMENT_REF as T, defersImage as _, columnWidthToPixels as a, isPdfTextTrustworthy as b, isRangeTopLeft as c, rangeContains as d, readImageSize as f, asReadMode as g, createDocumentToolSource as h, MAX_DIGIT_WIDTH as i, frameLabel as k, parseCellAddress as l, READ_DOCUMENT_TOOL as m, EMU_PER_POINT as n, fitWithin as o, PDF_LARGE_IMAGE_RATIO as p, EMU_PER_TWIP as r, formatCellAddress as s, EMU_PER_PIXEL as t, parseCellRange as u, takesImage as v, PAGE_ACTION_KINDS as w, measurePdfTextQuality as x, PDF_GARBLED_RATIO as y };