@webskill/sdk 0.26.0 → 0.27.0

package/dist/browser.js

@@ -3,12 +3,12 @@ import { A as SKILL_MANIFEST_FILE, D as verifySkillSignature, M as buildManifest
 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-7CuZS3Z4.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-BSwffz8P.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-CZZOl9cO.js";
+import { c as toBase64$1, f as SPREADSHEET_MIME_TYPE } from "./linkedDocument-0iiVPd5t.js";
 import { n as normalizeToolContent, t as mergeCatalogEntries } from "./external-_ZRQe-V9.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, c as isRangeTopLeft, d as rangeContains, 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 { t as createWebSkillApi } from "./webSkillApi-C_7CTwtB.js";
+import { A as frameSteps, D as SCROLL_DIRECTIONS, E as toActionFrameScopes, O as toFrameScopes, _ as defersImage, a as columnWidthToPixels, b as isPdfTextTrustworthy, c as isRangeTopLeft, d as rangeContains, 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-BXMPNuM6.js";
 import { zipSync } from "fflate";
 
 //#region ../browser/src/fs/featureDetection.ts
@@ -20,6 +20,8 @@ function isOpfsAvailable(globalScope) {
 //#endregion
 //#region ../browser/src/fs/opfsProvider.ts
 const isDomException = (e, name) => e instanceof DOMException && e.name === name;
+/** move 的两种原生签名形状不匹配时，浏览器抛的是这两类；权限/找不到等真实失败不重试。 */
+const isWrongMoveSignature = (e) => e instanceof TypeError || typeof DOMException !== "undefined" && e instanceof DOMException && e.name === "NotSupportedError";
 const mapError = (e, path) => {
 	if (isDomException(e, "NotFoundError")) return new WebSkillError("FS_NOT_FOUND", `Path not found: ${path}`);
 	if (isDomException(e, "NotAllowedError")) return new WebSkillError("FS_PERMISSION_DENIED", `Permission denied: ${path}`, e);
@@ -224,11 +226,21 @@ var OpfsProvider = class {
 		const toSegments = this.#segments(to);
 		const toName = toSegments.pop();
 		if (!toName) throw new WebSkillError("FS_NOT_FOUND", `Invalid path: ${to}`);
-		const file = await (await this.#walkDir(`/${fromSegments.join("/")}`, false)).getFileHandle(fromName);
+		const fromDir = await this.#walkDir(`/${fromSegments.join("/")}`, false);
+		const file = await fromDir.getFileHandle(fromName);
 		const mover = file.move;
 		if (`/${fromSegments.join("/")}` === `/${toSegments.join("/")}` && typeof mover === "function") {
 			await this.#wrap(from, async () => {
-				await mover.call(file, toName);
+				const attempts = mover.length >= 2 ? [[fromDir, toName], [toName]] : [[toName], [fromDir, toName]];
+				let last;
+				for (const args of attempts) try {
+					await mover.call(file, ...args);
+					return;
+				} catch (e) {
+					if (!isWrongMoveSignature(e)) throw e;
+					last = e;
+				}
+				throw new WebSkillError("FS_PERMISSION_DENIED", `OPFS atomic rename is not supported by this browser's FileSystemFileHandle.move()`, last);
 			});
 			return;
 		}
@@ -2792,6 +2804,14 @@ function promoteRole(input) {
 //#region ../browser/src/dom/perception.ts
 /** 值可能是凭据的输入类型：即便宿主忘了写进 exclude 也不读值。操作侧复用同一份，不另写 */
 const SECRET_INPUT_TYPES = /* @__PURE__ */ new Set(["password", "hidden"]);
+/**
+* 当前页地址的长度上限（0.27.0 分册 22 FR-22.4）。
+*
+* 地址是给人看的一串字，不是可解析的契约：超长时截断并标记，比让它把整次感知
+* 的预算吃掉要好。`…[truncated]` 与其它截断标记同源写法。
+*/
+const PAGE_URL_LIMIT = 2048;
+const PAGE_URL_TRUNCATED = "…[truncated]";
 /** 可被操作的角色：只有这些节点的句柄能拿去写页面 */
 const ACTIONABLE_ROLES = /* @__PURE__ */ new Set([
 	"button",
@@ -2937,6 +2957,34 @@ function nameOf(element, doc) {
 	const title = element.getAttribute("title");
 	return title !== null && title.trim() !== "" ? clip(title) : void 0;
 }
+/**
+* 稳定化签名（0.27.0 分册 17）。它是**恢复用的保守指纹**，不是选择器：
+* 角色/名称/链接/表单名/文档内路径/最近行上下文任一不同都不匹配。
+* 列表重排后同路径可能指向另一行，因此上下文缺失时调用方必须拒绝恢复。
+*/
+function handleSignatureOf(element, role) {
+	const doc = element.ownerDocument;
+	const segments = [];
+	let node = element;
+	while (node !== null) {
+		const parent = node.parentElement;
+		const index = parent === null ? 0 : [...parent.children].indexOf(node);
+		segments.unshift(`${node.tagName.toLowerCase()}[${index}]`);
+		node = parent;
+	}
+	const ancestor = element.parentElement?.closest("tr, [role=\"row\"], li, [role=\"listitem\"], article, [role=\"article\"], [role=\"feed\"]");
+	const context = ancestor === null || ancestor === void 0 ? void 0 : nameOf(ancestor, doc) ?? hrefOf(ancestor);
+	const form = element.closest("form");
+	const formName = element.getAttribute("name") ?? form?.getAttribute("name") ?? form?.getAttribute("aria-label") ?? void 0;
+	return JSON.stringify({
+		role,
+		...nameOf(element, doc) !== void 0 ? { name: nameOf(element, doc) } : {},
+		...hrefOf(element) !== void 0 ? { href: hrefOf(element) } : {},
+		...formName !== void 0 ? { formName } : {},
+		path: segments.join("/"),
+		...context !== void 0 ? { context } : {}
+	});
+}
 function valueOf(element) {
 	if (element.tagName === "INPUT") {
 		const type = (element.getAttribute("type") ?? "text").toLowerCase();
@@ -3208,10 +3256,16 @@ function sameOriginDocumentOf(iframe) {
 * 而安全性本就不由句柄寿命承担——执行前的 `modalStateOf` / `inActionScope` /
 * 可见性 / 可用性四道校验才是闸门，它们按**执行那一刻**的 DOM 实时判定。
 */
-var HandleIssuer = class {
+var HandleIssuer = class HandleIssuer {
 	#table = /* @__PURE__ */ new Map();
 	/** 同一元素复用同一个 ref：模型重读页面后手里的句柄仍然指向同一个东西 */
 	#refByElement = /* @__PURE__ */ new WeakMap();
+	/**
+	* 失效 ref 的签名（0.27.0 分册 17）。不随 `#table` 删除：重渲染替换实例后，
+	* 旧 ref 仍要能按签名找回来；上限 4096，文档 WeakRef 销毁即视为失效。
+	*/
+	#signatures = /* @__PURE__ */ new Map();
+	static #MAX_SIGNATURES = 4096;
 	#actionable;
 	#excluded;
 	constructor(actionable, excluded) {
@@ -3229,22 +3283,59 @@ var HandleIssuer = class {
 	*/
 	prune() {
 		for (const [ref, entry] of this.#table) if (!entry.element.isConnected) this.#table.delete(ref);
+		for (const [ref, record] of this.#signatures) if (record.document.deref() === void 0) this.#signatures.delete(ref);
+		this.#trimSignatures();
+	}
+	#trimSignatures() {
+		while (this.#signatures.size > HandleIssuer.#MAX_SIGNATURES) {
+			const oldest = this.#signatures.keys().next().value;
+			if (oldest === void 0) return;
+			this.#signatures.delete(oldest);
+		}
+	}
+	#remember(ref, element, signature) {
+		this.#signatures.delete(ref);
+		this.#signatures.set(ref, {
+			signature,
+			document: new WeakRef(element.ownerDocument)
+		});
+		this.#trimSignatures();
+	}
+	signatureOf(ref) {
+		return this.#signatures.get(ref)?.signature ?? this.#table.get(ref)?.signature;
+	}
+	documentOf(ref) {
+		return this.#signatures.get(ref)?.document.deref();
+	}
+	/** 动作恢复：把旧 ref 重新指向实际元素；四道闸仍由执行器在 execute 时判。 */
+	restore(ref, element, kind, frame, signature) {
+		this.#table.set(ref, {
+			element,
+			kind,
+			...frame !== void 0 ? { frame } : {},
+			signature
+		});
+		this.#refByElement.set(element, ref);
+		this.#remember(ref, element, signature);
 	}
 	issue(element, role, frame) {
 		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 signature = handleSignatureOf(element, role);
 		const known = this.#refByElement.get(element);
 		if (known !== void 0 && this.#table.has(known)) {
 			this.#table.set(known, {
 				element,
 				kind,
-				...frame !== void 0 ? { frame } : {}
+				...frame !== void 0 ? { frame } : {},
+				signature
 			});
+			this.#remember(known, element, signature);
 			return known;
 		}
-		return this.#mint(element, kind, frame);
+		return this.#mint(element, kind, frame, signature);
 	}
 	/**
 	* 取像句柄（0.22.0 FR-12.1）。**不过操作范围那道闸**：取像是读，而该元素已经在
@@ -3256,7 +3347,7 @@ var HandleIssuer = class {
 		if (this.#excluded.has(element)) return void 0;
 		const known = this.#refByElement.get(element);
 		if (known !== void 0 && this.#table.has(known)) return known;
-		return this.#mint(element, "image", frame);
+		return this.#mint(element, "image", frame, handleSignatureOf(element, roleOf$1(element)));
 	}
 	/**
 	* 可滚容器的句柄（0.23.0 分册 22）。角色白名单之外——表格容器往往是个 `generic` div，
@@ -3269,18 +3360,20 @@ var HandleIssuer = class {
 		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);
+		return this.#mint(element, "action", frame, handleSignatureOf(element, roleOf$1(element)));
 	}
-	#mint(element, kind, frame) {
+	#mint(element, kind, frame, signature) {
 		const bytes = /* @__PURE__ */ new Uint8Array(8);
 		crypto.getRandomValues(bytes);
 		const ref = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
 		this.#table.set(ref, {
 			element,
 			kind,
-			...frame !== void 0 ? { frame } : {}
+			...frame !== void 0 ? { frame } : {},
+			signature
 		});
 		this.#refByElement.set(element, ref);
+		this.#remember(ref, element, signature);
 		return ref;
 	}
 	/** 角色提升要的是「有可操作后代」，容器锚点不算；混进来会把可点容器判成已有出口 */
@@ -3301,6 +3394,8 @@ var HandleIssuer = class {
 */
 function createDomPerceptionReader(options = {}) {
 	let handles;
+	/** 最近一次 read/readSubtree 的范围；只给内部 actionChildRefs 用，不进公开接口 */
+	let lastScope;
 	/** 授权生效时记下各帧的 origin，之后每次感知比对（FR-24.3） */
 	const frameOrigins = /* @__PURE__ */ new Map();
 	/**
@@ -3309,6 +3404,22 @@ function createDomPerceptionReader(options = {}) {
 	*/
 	const elevatedModals = /* @__PURE__ */ new Set();
 	const rootDocument = () => options.document ?? globalThis.document;
+	/**
+	* 当前文档的地址与标题（0.27.0 分册 22 FR-22.1）。
+	*
+	* 只回答「你在哪一页」，不是导航入口：没有任何入参能选目的地。
+	* 拿不到（无文档、`about:blank`、`srcdoc`）时返回 `undefined`——结果里就不带这个键，
+	* 而不是塞一个空串让模型以为拿到了地址（FR-22.8）。
+	*/
+	const pageOf = (doc) => {
+		const href = (doc?.defaultView)?.location?.href;
+		if (typeof href !== "string" || href === "" || href === "about:blank") return void 0;
+		const title = typeof doc?.title === "string" ? doc.title.trim() : "";
+		return {
+			url: href.length > PAGE_URL_LIMIT ? `${href.slice(0, PAGE_URL_LIMIT)}${PAGE_URL_TRUNCATED}` : href,
+			...title === "" ? {} : { title }
+		};
+	};
 	/** 提升未开启时返回 undefined，遍历侧据此整段跳过（AC-G10） */
 	const promotionOf = (view) => options.promoteRoles === true ? {
 		view,
@@ -3402,6 +3513,7 @@ function createDomPerceptionReader(options = {}) {
 			nestedFrames: [],
 			anchored: false
 		};
+		const page = pageOf(root);
 		handles ??= new HandleIssuer(/* @__PURE__ */ new Set(), /* @__PURE__ */ new Set());
 		handles.prune();
 		const issuer = handles;
@@ -3519,7 +3631,8 @@ function createDomPerceptionReader(options = {}) {
 			nodes,
 			frameNotes,
 			nestedFrames,
-			anchored
+			anchored,
+			...page === void 0 ? {} : { page }
 		};
 		pruneElevated();
 		const view = root.defaultView;
@@ -3541,12 +3654,13 @@ function createDomPerceptionReader(options = {}) {
 			nodes,
 			frameNotes,
 			nestedFrames,
-			anchored
+			anchored,
+			...page === void 0 ? {} : { page }
 		};
 	}
 	async function readWithImages(scope, capture, subtree) {
 		const targets = [];
-		const { nodes, frameNotes, nestedFrames, anchored } = collect(scope, {
+		const { nodes, frameNotes, nestedFrames, anchored, page } = collect(scope, {
 			targets,
 			minImageArea: capture.minImageArea ?? 0
 		}, subtree);
@@ -3578,16 +3692,19 @@ function createDomPerceptionReader(options = {}) {
 			imagesOmitted: targets.length - selected.length,
 			imageFailures,
 			anchored,
+			...page === void 0 ? {} : { page },
 			...frameNotes.length > 0 ? { frameNotes } : {},
 			...nestedFrames.length > 0 ? { nestedFrames } : {}
 		};
 	}
 	function read(scope, capture) {
+		lastScope = scope;
 		if (capture === void 0) return collect(scope, void 0).nodes;
 		if (!capture.images || capture.maxImages <= 0) {
-			const { nodes, frameNotes, nestedFrames } = collect(scope, void 0);
+			const { nodes, frameNotes, nestedFrames, page } = collect(scope, void 0);
 			return Promise.resolve({
 				nodes,
+				...page === void 0 ? {} : { page },
 				...frameNotes.length > 0 ? { frameNotes } : {},
 				...nestedFrames.length > 0 ? { nestedFrames } : {}
 			});
@@ -3602,20 +3719,113 @@ function createDomPerceptionReader(options = {}) {
 	* 拒绝走返回值而不是抛错：跨上下文的 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" };
+		lastScope = scope;
+		let element = handles?.table.get(ref)?.element;
+		if (element === void 0 || !element.isConnected) element = recoverElement(ref, "perceive");
+		if (element === void 0) 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);
+		const { nodes, frameNotes, nestedFrames, anchored, page } = collect(scope, void 0, element);
 		if (!anchored) return { rejected: "out-of-scope" };
 		return {
 			nodes,
+			...page === void 0 ? {} : { page },
 			...frameNotes.length > 0 ? { frameNotes } : {},
 			...nestedFrames.length > 0 ? { nestedFrames } : {}
 		};
 	}
+	/**
+	* 内部能力（分册 16）：容器 ref 被拒时，给出当前已持有/读一次子树后的可操作子 ref。
+	* 不导出到 `DomPerceptionReader`：公开接口加方法会改 d.ts 与 API 快照。
+	* 返回 `known:false` 表示无法判断，调用方必须退回旧文案，不能声称“没有子节点”。
+	*/
+	async function actionChildRefs(ref, limit) {
+		const entry = handles?.table.get(ref);
+		if (entry === void 0 || entry.kind !== "anchor" || !entry.element.isConnected) return void 0;
+		const container = entry.element;
+		const doc = container.ownerDocument;
+		const collectActionRefs = () => {
+			const out = [];
+			for (const [childRef, child] of handles?.table ?? []) {
+				if (child.kind !== "action" || !child.element.isConnected) continue;
+				if (child.element === container || !container.contains(child.element)) continue;
+				if (child.element.ownerDocument !== doc) continue;
+				out.push({
+					ref: childRef,
+					element: child.element
+				});
+			}
+			out.sort((a, b) => {
+				const position = a.element.compareDocumentPosition(b.element);
+				if (position & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+				if (position & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+				return 0;
+			});
+			return [...new Set(out.map((item) => item.ref))];
+		};
+		let refs = collectActionRefs();
+		if (refs.length === 0) {
+			if (lastScope === void 0) return {
+				refs: [],
+				known: false,
+				more: 0
+			};
+			if ("rejected" in await readSubtree(lastScope, ref)) return {
+				refs: [],
+				known: false,
+				more: 0
+			};
+			refs = collectActionRefs();
+		}
+		const unique = [...new Set(refs)];
+		return {
+			refs: unique.slice(0, limit),
+			known: true,
+			more: Math.max(0, unique.length - limit)
+		};
+	}
+	/**
+	* 内部恢复（0.27.0 分册 17）：旧 ref 的元素断开后，按签名在**当前主文档**内找唯一元素。
+	* `action` 模式会恢复句柄表，`perceive` 只返回元素供本次子树读，不把旧 ref 写回。
+	* 跨帧不恢复：这里只处理主文档，iframe 旧 ref 仍走既有失效路径。
+	*/
+	function recoverElement(ref, mode) {
+		const doc = rootDocument();
+		const signature = handles?.signatureOf(ref);
+		const oldDoc = handles?.documentOf(ref);
+		if (doc === void 0 || signature === void 0 || oldDoc !== doc) return void 0;
+		const scope = lastScope;
+		if (scope === void 0) return void 0;
+		const view = doc.defaultView;
+		const candidates = [...doc.querySelectorAll("*")].filter((element) => {
+			if (!element.isConnected) return false;
+			if (handleSignatureOf(element, roleOf$1(element)) !== signature) return false;
+			if (mode === "action") {
+				const sets = actionSets(doc, actionScopeFor("self"));
+				if (!sets.actionable.has(element) || sets.excluded.has(element)) return false;
+				const modal = element.closest(MODAL_SELECTOR);
+				if (modal !== null && !elevatedModals.has(modal)) return false;
+				if (hidden$1(element, view)) return false;
+				if (occupiesNoSpace(element)) return false;
+				if (element.hasAttribute("disabled")) return false;
+				return true;
+			}
+			const frameScope = "frames" in scope ? scope.frames.find((entry) => frameSteps(entry.frame).length === 0) : scope;
+			if (frameScope === void 0) return false;
+			const sets = actionSets(doc, frameScope);
+			return sets.actionable.has(element) && !sets.excluded.has(element);
+		});
+		if (candidates.length !== 1) return void 0;
+		const [element] = candidates;
+		if (element === void 0) return void 0;
+		if (mode === "action") {
+			const frame = handles?.table.get(ref)?.frame;
+			handles?.restore(ref, element, "action", frame, signature);
+		}
+		return element;
+	}
 	/** 当前活动模态；跨帧不适用（模态提升只在主文档语义下成立） */
 	function modalSnapshot() {
 		const root = rootDocument();
@@ -3629,6 +3839,8 @@ function createDomPerceptionReader(options = {}) {
 	return {
 		read,
 		readSubtree,
+		actionChildRefs,
+		recoverElement,
 		resolve: (ref) => handles?.table.get(ref)?.element,
 		handleKindOf: (ref) => handles?.table.get(ref)?.kind,
 		frameOf: (ref) => handles?.table.get(ref)?.frame,
@@ -3824,6 +4036,26 @@ function roleOf(element) {
 	if (element.tagName === "FORM") return "form";
 	return "generic";
 }
+const containerActionText = (reader, inside) => {
+	const base = "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 (inside === void 0 || !inside.known) return base;
+	const usable = [];
+	for (const ref of inside.refs) {
+		const element = reader.resolve(ref);
+		if (element === void 0) continue;
+		if (reader.modalStateOf(element) === "unelevated") continue;
+		if (reader.modalStateOf(element) !== "elevated" && !reader.inActionScope(element)) continue;
+		if (hidden(element)) continue;
+		if (occupiesNoSpace(element)) continue;
+		if (element.hasAttribute("disabled")) continue;
+		const target = describeElement(element);
+		usable.push(`[${ref}] ${target.role}${target.name !== void 0 ? ` "${target.name}"` : ""}`);
+	}
+	if (usable.length === 0) return `${base} This container has no actionable elements; retrying here will not help. Perceive the container again after a row or panel has changed.`;
+	const shown = usable.slice(0, 5);
+	const more = Math.max(inside.more, usable.length - shown.length);
+	return `${base} Actionable references inside: ${shown.join("; ")}${more > 0 ? `; and ${more} more` : ""}.`;
+};
 const describeElement = (element) => {
 	const name = accessibleName(element);
 	return {
@@ -3971,24 +4203,28 @@ function hoverOver(element) {
 	}));
 	element.dispatchEvent(new MouseEvent("mousemove", base));
 }
-/**
-* 悬停之后页面有没有动（FR-17.3）。
-*
-* 用 `MutationObserver` 而不是比对快照：浮层可能挂到 `document.body` 末尾、
-* 也可能只是把某个节点的 `hidden` 去掉，逐一枚举会漏，而漏判的代价是向模型报假成功。
-* 观察器在派发**之前**挂上——晚一步就会错过同步执行的那批监听器。
-*/
 function watchMutations(element) {
 	const doc = element.ownerDocument;
 	const Observer = doc.defaultView?.MutationObserver;
 	if (Observer === void 0) return {
-		changed: () => true,
+		take: () => ({
+			added: 0,
+			removed: 0,
+			changed: true
+		}),
 		stop: () => void 0
 	};
+	let added = 0;
+	let removed = 0;
 	let seen = false;
-	const observer = new Observer(() => {
-		seen = true;
-	});
+	const absorb = (records) => {
+		for (const record of records) {
+			seen = true;
+			added += record.addedNodes.length;
+			removed += record.removedNodes.length;
+		}
+	};
+	const observer = new Observer(absorb);
 	observer.observe(doc, {
 		subtree: true,
 		childList: true,
@@ -3996,13 +4232,50 @@ function watchMutations(element) {
 		characterData: true
 	});
 	return {
-		changed: () => {
-			if (observer.takeRecords().length > 0) seen = true;
-			return seen;
+		take: () => {
+			absorb(observer.takeRecords());
+			return {
+				added,
+				removed,
+				changed: seen
+			};
 		},
 		stop: () => observer.disconnect()
 	};
 }
+const STATUS_SELECTORS = [
+	"[role=\"status\"]",
+	"[role=\"alert\"]",
+	".messages .message",
+	".messages li"
+];
+const compactText = (element) => {
+	const text = element.textContent?.replace(/\s+/g, " ").trim();
+	return text === void 0 || text === "" ? void 0 : text;
+};
+/** 状态文本只在固定状态区取；不读整页、不读 `.messages` 容器，避免把多条消息/正文带进模型上下文。 */
+function statusTextOf(element, request, target) {
+	if (target.secret === true) return void 0;
+	let text = [...element.ownerDocument.querySelectorAll(STATUS_SELECTORS.join(","))].filter((node) => !hidden(node)).map((node) => compactText(node)).filter((text) => text !== void 0).at(-1);
+	if (text === void 0) return void 0;
+	const value = request.value;
+	if (value !== void 0 && value.length > 0) text = text.split(value).join("[redacted]");
+	return text.length > 200 ? `${text.slice(0, 197)}...` : text;
+}
+function withChanges(outcome, mutations, element, request) {
+	if (!outcome.ok || outcome.noop === true || outcome.navigated === true) return outcome;
+	const snapshot = mutations.take();
+	const status = statusTextOf(element, request, outcome.target);
+	if (snapshot.added === 0 && snapshot.removed === 0 && status === void 0) return outcome;
+	return {
+		...outcome,
+		changes: {
+			added: snapshot.added,
+			removed: snapshot.removed,
+			...status !== void 0 ? { status } : {}
+		}
+	};
+}
 /**
 * 一次拖拽（FR-17.5）。真实页面有两套互不相通的机制，按起点自动选：
 *
@@ -4279,9 +4552,23 @@ function createDomPageActionExecutor(options) {
 			...frame !== void 0 ? { frame } : {}
 		};
 	};
+	const recoveredRefs = /* @__PURE__ */ new Map();
+	const rememberRecovered = (ref, element) => {
+		recoveredRefs.delete(ref);
+		recoveredRefs.set(ref, element);
+		while (recoveredRefs.size > 32) {
+			const oldest = recoveredRefs.keys().next().value;
+			if (oldest === void 0) break;
+			recoveredRefs.delete(oldest);
+		}
+	};
+	const recoverAction = (ref) => reader.recoverElement?.(ref, "action");
 	const describe = (ref) => {
-		const element = reader.resolve(ref);
+		const resolved = reader.resolve(ref);
+		const live = resolved?.isConnected === true ? resolved : void 0;
+		const element = live ?? recoverAction(ref);
 		if (element === void 0) return void 0;
+		if (live === void 0) rememberRecovered(ref, element);
 		const described = withFrame(ref, describeElement(element));
 		return reader.modalStateOf(element) === "elevated" ? {
 			...described,
@@ -4366,7 +4653,15 @@ function createDomPageActionExecutor(options) {
 	};
 	const execute = async (request) => {
 		if (request.action === "back") return await goBack();
-		const element = reader.resolve(request.ref);
+		const cached = recoveredRefs.get(request.ref);
+		const liveResolved = reader.resolve(request.ref);
+		let element = cached ?? (liveResolved?.isConnected === true ? liveResolved : void 0);
+		let recovered = cached !== void 0;
+		if (element === void 0) {
+			element = recoverAction(request.ref);
+			recovered = element !== void 0;
+			if (element !== void 0) rememberRecovered(request.ref, element);
+		}
 		if (element === void 0) return {
 			ok: false,
 			target: { role: "generic" },
@@ -4378,7 +4673,15 @@ 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.handleKindOf(request.ref) === "anchor") {
+			let inside;
+			try {
+				inside = await reader.actionChildRefs?.(request.ref, 5);
+			} catch {
+				inside = void 0;
+			}
+			return fail(containerActionText(reader, inside));
+		}
 		if (reader.handleKindOf(request.ref) === "image") return fail("That reference points at an image, which cannot be acted on. Use it with capture_page_image to read the picture itself.");
 		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.");
@@ -4402,6 +4705,7 @@ function createDomPageActionExecutor(options) {
 			const navigated = keyAfter !== void 0 && keyBefore !== void 0 && keyAfter !== keyBefore;
 			return {
 				...outcome,
+				...recovered ? { recovered: true } : {},
 				...name !== void 0 ? { elevatedModal: name } : {},
 				...navigated ? {
 					navigated: true,
@@ -4409,93 +4713,96 @@ function createDomPageActionExecutor(options) {
 				} : {}
 			};
 		};
-		if (request.action === "click") {
-			const watch = watchMutations(element);
-			press(element);
-			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. 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,
-				target
-			});
-		}
-		if (request.action === "select") {
-			const outcome = await selectOption(element, request.value ?? "");
-			return outcome.ok ? await done({
-				...outcome,
-				target
-			}) : {
-				...outcome,
-				target
-			};
-		}
-		if (request.action === "set") return await done(setToggle(element, request.value ?? "", target));
-		if (request.action === "scroll") {
-			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") {
-			const watch = watchMutations(element);
-			hoverOver(element);
-			await waitFor(() => watch.changed() ? true : void 0, 500);
-			const changed = watch.changed();
-			watch.stop();
-			return await done({
-				ok: true,
-				target,
-				...changed || popoverOpenBeside(element) ? {} : { noop: true }
-			});
-		}
-		if (request.action === "drag") {
-			const destination = request.value ?? "";
-			if (destination === "") return fail("The drag action needs a value holding the destination ref.");
-			const dropTarget = reader.resolve(destination);
-			if (dropTarget === void 0) return fail("The destination reference is unknown or expired.");
-			if (reader.handleKindOf(destination) === "image") return fail("The destination reference points at an image, which cannot receive a drop.");
-			if (reader.modalStateOf(dropTarget) !== "elevated" && !reader.inActionScope(dropTarget)) return fail("The destination is no longer inside the actionable scope.");
-			if (hidden(dropTarget)) return fail("The destination is not visible.");
-			const refused = dragBetween(element, dropTarget);
-			if (refused !== void 0) return fail(refused);
-			return await done({
-				ok: true,
-				target
-			});
-		}
-		if (request.action === "attach") {
-			const files = await options.pickFiles?.();
-			if (files === void 0 || files.length === 0) return {
-				ok: false,
-				target,
-				reason: "The user cancelled the file selection."
-			};
-			if (element.tagName !== "INPUT" || element.type !== "file") return fail("The element is not a file input.");
-			const failure = attachFiles(element, files);
-			if (failure !== void 0) return fail(failure);
-			return await done({
+		const mutations = watchMutations(element);
+		try {
+			if (request.action === "click") {
+				press(element);
+				const outcome = await done({
+					ok: true,
+					target
+				});
+				return mutations.take().changed || outcome.navigated === true || outcome.elevatedModal !== void 0 || popoverOpenBeside(element) ? withChanges(outcome, mutations, element, request) : {
+					...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. Read-only text fields often open a picker when clicked, so try the click action on this same element.");
+				fillValue(element, request.value ?? "");
+				return withChanges(await done({
+					ok: true,
+					target
+				}), mutations, element, request);
+			}
+			if (request.action === "select") {
+				const outcome = await selectOption(element, request.value ?? "");
+				return outcome.ok ? withChanges(await done({
+					...outcome,
+					target
+				}), mutations, element, request) : {
+					...outcome,
+					target
+				};
+			}
+			if (request.action === "set") return withChanges(await done(setToggle(element, request.value ?? "", target)), mutations, element, request);
+			if (request.action === "scroll") {
+				if (!SCROLL_DIRECTIONS.includes(request.value)) return fail(`Use ${SCROLL_DIRECTIONS.map((d) => `"${d}"`).join(" / ")}.`);
+				const scrolled = withChanges(await scrollRegion(element, target, request.value), mutations, element, request);
+				return recovered && scrolled.ok ? {
+					...scrolled,
+					recovered: true
+				} : scrolled;
+			}
+			if (request.action === "hover") {
+				hoverOver(element);
+				await waitFor(() => mutations.take().changed ? true : void 0, 500);
+				return withChanges(await done({
+					ok: true,
+					target,
+					...mutations.take().changed || popoverOpenBeside(element) ? {} : { noop: true }
+				}), mutations, element, request);
+			}
+			if (request.action === "drag") {
+				const destination = request.value ?? "";
+				if (destination === "") return fail("The drag action needs a value holding the destination ref.");
+				const dropTarget = reader.resolve(destination);
+				if (dropTarget === void 0) return fail("The destination reference is unknown or expired.");
+				if (reader.handleKindOf(destination) === "image") return fail("The destination reference points at an image, which cannot receive a drop.");
+				if (reader.modalStateOf(dropTarget) !== "elevated" && !reader.inActionScope(dropTarget)) return fail("The destination is no longer inside the actionable scope.");
+				if (hidden(dropTarget)) return fail("The destination is not visible.");
+				const refused = dragBetween(element, dropTarget);
+				if (refused !== void 0) return fail(refused);
+				return withChanges(await done({
+					ok: true,
+					target
+				}), mutations, element, request);
+			}
+			if (request.action === "attach") {
+				const files = await options.pickFiles?.();
+				if (files === void 0 || files.length === 0) return {
+					ok: false,
+					target,
+					reason: "The user cancelled the file selection."
+				};
+				if (element.tagName !== "INPUT" || element.type !== "file") return fail("The element is not a file input.");
+				const failure = attachFiles(element, files);
+				if (failure !== void 0) return fail(failure);
+				return withChanges(await done({
+					ok: true,
+					target
+				}), mutations, element, request);
+			}
+			const form = element.tagName === "FORM" ? element : element.form;
+			if (!form) return fail("The element does not belong to a form.");
+			form.requestSubmit();
+			return withChanges(await done({
 				ok: true,
 				target
-			});
+			}), mutations, element, request);
+		} finally {
+			mutations.stop();
 		}
-		const form = element.tagName === "FORM" ? element : element.form;
-		if (!form) return fail("The element does not belong to a form.");
-		form.requestSubmit();
-		return await done({
-			ok: true,
-			target
-		});
 	};
 	return {
 		execute,
@@ -6534,10 +6841,17 @@ async function readDocxBlocks(bytes) {
 * 图不是浮在表外的附件，它压着某几行几列——按锚点插回行流里，
 * 模型才知道「这张图说的是上面那几行」。
 */
-/** 值得单独烧一次多模态的图：至少跨 2 列、3 行（FR-22.11） @experimental */
+/** @experimental @deprecated 0.27.0 起不再按跨度过滤图片；保留导出仅为兼容既有调用。 */
 const XLSX_IMAGE_MIN_COLUMNS = 2;
-/** @experimental */
+/** @experimental @deprecated 0.27.0 起不再按跨度过滤图片；保留导出仅为兼容既有调用。 */
 const XLSX_IMAGE_MIN_ROWS = 3;
+const ANCHOR_TAGS = /* @__PURE__ */ new Set([
+	"twoCellAnchor",
+	"oneCellAnchor",
+	"absoluteAnchor"
+]);
+/** 绝对锚点没有行号；放在表尾，保证图片不丢。 */
+const AFTER_LAST_ROW = Number.MAX_SAFE_INTEGER;
 const RELATIONSHIPS_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
 const byTag$2 = (scope, name) => [...scope.getElementsByTagNameNS("*", name)];
 function parseXml$1(bytes) {
@@ -6575,7 +6889,13 @@ const anchorNumber = (anchor, name) => {
 	const value = Number(node?.textContent ?? NaN);
 	return Number.isInteger(value) && value >= 0 ? value : 0;
 };
-/** 一张表上的图：行号（0 基）→ 该行下面要插的图块 */
+/**
+* 一张表上的图：行号（0 基）→ 该行下面要插的图块。
+*
+* 0.27.0 起读所有 DrawingML 锚点、所有尺寸：`twoCellAnchor`、`oneCellAnchor` 都按
+* `from` 行插回；`absoluteAnchor` 没有单元格坐标，补在表尾。旧版按跨列/跨行阈值过滤，
+* 会把小图标、单元格小图、以及本仓 `fill_template` 自己写的 `oneCellAnchor` 全部丢掉。
+*/
 function imagesOf(parts, sheetPath) {
 	const placed = /* @__PURE__ */ new Map();
 	const sheetRels = readRels(parts, sheetPath);
@@ -6585,21 +6905,18 @@ function imagesOf(parts, sheetPath) {
 		const drawing = drawingBytes === void 0 ? void 0 : parseXml$1(drawingBytes);
 		if (drawing === void 0) continue;
 		const drawingRels = readRels(parts, target);
-		for (const anchor of byTag$2(drawing, "twoCellAnchor")) {
+		const anchors = [...drawing.documentElement?.children ?? []].filter((element) => ANCHOR_TAGS.has(element.localName));
+		for (const anchor of anchors) {
 			const from = byTag$2(anchor, "from")[0];
-			const to = byTag$2(anchor, "to")[0];
-			const fromRow = anchorNumber(from, "row");
-			const columns = anchorNumber(to, "col") - anchorNumber(from, "col");
-			const rows = anchorNumber(to, "row") - fromRow;
-			if (columns < 2 || rows < 3) continue;
+			const row = anchor.localName === "absoluteAnchor" || from === void 0 ? AFTER_LAST_ROW : anchorNumber(from, "row");
 			const blip = byTag$2(anchor, "blip")[0];
 			const relId = blip?.getAttributeNS(RELATIONSHIPS_NS, "embed") ?? blip?.getAttribute("r:embed");
 			const path = relId === null || relId === void 0 ? void 0 : drawingRels.get(relId);
 			const data = path === void 0 ? void 0 : parts.get(path);
 			if (path === void 0 || data === void 0) continue;
-			const list = placed.get(fromRow) ?? [];
+			const list = placed.get(row) ?? [];
 			list.push(imageBlockOf(path, () => toBase64$1(data)));
-			placed.set(fromRow, list);
+			placed.set(row, list);
 		}
 	}
 	return placed;
@@ -6897,6 +7214,14 @@ const extensionOf = (path) => {
 	const dot = path.lastIndexOf(".");
 	return dot < 0 ? "" : path.slice(dot + 1).toLowerCase();
 };
+/** 用 DOM 读登记项，不能按属性顺序写正则：有的写库（write-excel-file）把 ContentType 排在 Extension 前面 */
+function declaredTypes(text) {
+	const doc = new DOMParser().parseFromString(splitXmlDeclaration(text).body, "application/xml");
+	return {
+		defaults: new Set(Array.from(doc.getElementsByTagName("Default"), (el) => (el.getAttribute("Extension") ?? "").toLowerCase())),
+		overrides: new Set(Array.from(doc.getElementsByTagName("Override"), (el) => el.getAttribute("PartName") ?? ""))
+	};
+}
 /**
 * 结构自检（AC-42.27）。
 *
@@ -6910,9 +7235,7 @@ function auditOoxmlPackage(pkg) {
 	const problems = [];
 	const contentTypes = pkg.get(CONTENT_TYPES);
 	if (contentTypes === void 0) return [`missing ${CONTENT_TYPES}`];
-	const types = new TextDecoder().decode(contentTypes);
-	const defaults = new Set([...types.matchAll(/<Default\s+Extension="([^"]+)"/g)].map((match) => (match[1] ?? "").toLowerCase()));
-	const overrides = new Set([...types.matchAll(/<Override\s+PartName="([^"]+)"/g)].map((match) => match[1]));
+	const { defaults, overrides } = declaredTypes(new TextDecoder().decode(contentTypes));
 	for (const path of pkg.keys()) {
 		if (path === CONTENT_TYPES) continue;
 		if (!defaults.has(extensionOf(path)) && !overrides.has(`/${path}`)) problems.push(`part is not covered by [Content_Types].xml: ${path}`);
@@ -6950,7 +7273,7 @@ function ensureDefaultExtension(pkg, extension, contentType) {
 	const bytes = pkg.get(CONTENT_TYPES);
 	if (bytes === void 0) return;
 	const text = new TextDecoder().decode(bytes);
-	if (new RegExp(`<Default\\s+Extension="${extension}"`, "i").test(text)) return;
+	if (declaredTypes(text).defaults.has(extension.toLowerCase())) return;
 	const { declaration, body } = splitXmlDeclaration(text);
 	const inserted = body.replace("<Default", `<Default Extension="${extension}" ContentType="${contentType}"/><Default`);
 	pkg.set(CONTENT_TYPES, new TextEncoder().encode(declaration + inserted));
@@ -7326,6 +7649,25 @@ function rowsOf(doc) {
 	const sheetData = byTag$1(doc, "sheetData")[0];
 	return sheetData === void 0 ? [] : [...sheetData.children].filter((node) => node.localName === "row");
 }
+const rowIndexes = /* @__PURE__ */ new WeakMap();
+/** 逐格写入时每次线性扫全表是 O(格数×行数)：2 万行的表加一列实测 160 s。只在插行之后建 */
+function rowIndexOf(doc) {
+	let index = rowIndexes.get(doc);
+	if (index === void 0) {
+		index = {
+			rows: /* @__PURE__ */ new Map(),
+			last: 0
+		};
+		for (const row of rowsOf(doc)) {
+			const number = rowNumberOf(row);
+			if (Number.isNaN(number)) continue;
+			if (!index.rows.has(number)) index.rows.set(number, row);
+			index.last = Math.max(index.last, number);
+		}
+		rowIndexes.set(doc, index);
+	}
+	return index;
+}
 /** 把一个元素上的行号整体平移：`<row r>` 与其中每个 `<c r>` */
 function shiftRow(row, delta) {
 	const next = rowNumberOf(row) + delta;
@@ -7498,7 +7840,7 @@ function fillCell(doc, address, value, guards) {
 		code: "TEMPLATE_CELL_IS_COVERED",
 		reason: `Cell ${normalized} is covered by the merged region ${rangeLabel(covering.start, covering.end)}, so anything written there is never displayed. Write ${formatCellAddress(covering.start)} instead.`
 	};
-	const row = rowsOf(doc).find((candidate) => rowNumberOf(candidate) === parsed.row + 1) ?? createRow(doc, parsed.row + 1);
+	const row = rowIndexOf(doc).rows.get(parsed.row + 1) ?? createRow(doc, parsed.row + 1);
 	let cell = byTag$1(row, "c").find((candidate) => candidate.getAttribute("r") === normalized);
 	if (cell === void 0) cell = createCell(doc, row, parsed.column, normalized);
 	const formula = [...cell.children].find((child) => child.localName === "f");
@@ -7558,8 +7900,11 @@ function createRow(doc, rowNumber) {
 	if (sheetData === void 0) throw new WebSkillError("TEMPLATE_UNSUPPORTED", "The worksheet part has no sheetData element.");
 	const row = doc.createElementNS(MAIN_NS, "row");
 	row.setAttribute("r", String(rowNumber));
-	const anchor = rowsOf(doc).find((candidate) => rowNumberOf(candidate) > rowNumber) ?? null;
+	const index = rowIndexOf(doc);
+	const anchor = rowNumber > index.last ? null : rowsOf(doc).find((candidate) => rowNumberOf(candidate) > rowNumber) ?? null;
 	sheetData.insertBefore(row, anchor);
+	index.rows.set(rowNumber, row);
+	index.last = Math.max(index.last, rowNumber);
 	return row;
 }
 function createCell(doc, row, column, address) {