@webskill/sdk 0.20.0 → 0.22.0

package/dist/geometry-wx5ZTYzi.js

@@ -0,0 +1,715 @@
+import { n as messageOf, t as WebSkillError } from "./errors-BDZNpC13.js";
+
+//#region ../agent/src/frame.ts
+/**
+* 帧指称的展示形式（分册 18 FR-18.2）。
+*
+* 感知与操作两侧各自声明自己的 scope 类型（那是刻意的，见各自 types.ts），
+* 但「一条帧路径写成给人看的字符串」只能有一份实现——
+* 两处各写一遍，审计里的帧名和确认卡里的帧名就会慢慢对不上。
+*/
+/**
+* 帧路径的稳定展示串：`'self'` / `'#a'` / `'#a >>> #b'`。
+*
+* `>>>` **只是展示分隔符**：CSS 选择器里可以合法出现任意字符，
+* 反向解析这个串取回路径是不成立的，实现层一律传原始形状（D-18-1）。
+* @experimental
+*/
+function frameLabel(frame) {
+	if (typeof frame === "string") return frame;
+	if (frame.length === 0) return "self";
+	return frame.join(" >>> ");
+}
+/** 把两种形状归一成逐层选择器数组；`'self'` 与空数组都归一成空数组 @experimental */
+function frameSteps(frame) {
+	if (typeof frame === "string") return frame === "self" ? [] : [frame];
+	return frame;
+}
+
+//#endregion
+//#region ../agent/src/perception/types.ts
+/**
+* 两种形状归一成帧列表；旧形状等价于一条 `frame:'self'`（FR-24.1）。
+*
+* **这是判别的单一来源。** 散在各处写 `'frames' in scope` 会让
+* 「旧配置还等价吗」这个问题没有唯一答案。
+* @experimental
+*/
+function toFrameScopes(scope) {
+	if ("frames" in scope) return scope.frames;
+	return [{
+		frame: "self",
+		include: scope.include,
+		...scope.exclude ? { exclude: scope.exclude } : {}
+	}];
+}
+
+//#endregion
+//#region ../agent/src/pageAction/types.ts
+/**
+* 两种形状归一成帧列表；旧形状等价于一条 `frame:'self'`。
+* 与感知侧的 `toFrameScopes` 一样，是本侧判别的**单一来源**。
+* @experimental
+*/
+function toActionFrameScopes(scope) {
+	if ("frames" in scope) return scope.frames;
+	return [{
+		frame: "self",
+		include: scope.include,
+		...scope.exclude ? { exclude: scope.exclude } : {}
+	}];
+}
+/**
+* 本版的操作集（FR-25.1 / 0.16.0 FR-13.6 / 0.18.0 FR-10.1 / 0.22.0 FR-17.1）。
+* 导航只有 `back` 一个，且它**不接受地址**——可达面被浏览器历史封死（SC-1）。
+*
+* `drag` 只表达**起点与终点**，没有中途轨迹（0.22.0 FR-17.6 裁定，D64 就此撤销）：
+* 轨迹是实现细节不是意图，能画任意路径等于架空 AC-23.2，而且滑块验证码要的正是轨迹——
+* 表达不了轨迹，这个动作就天然做不了人机验证绕过。
+*
+* 这些动作与既有几个走**同一条** policy 路径，
+* 范围白名单、逐次确认、审计三条硬约束因此天然覆盖到它们——
+* 前提是新动作不绕过 policy 直调执行器（AC-25.4 守这一点）。
+* @experimental
+*/
+const PAGE_ACTION_KINDS = [
+	"click",
+	"fill",
+	"submit",
+	"select",
+	"set",
+	"attach",
+	"scroll",
+	"hover",
+	"drag",
+	"back"
+];
+/**
+* `back` 的目标占位（0.16.0 分册 13 §4.1）。
+*
+* **模型不能表达它**：工具源在 `action === 'back'` 时拒绝任何 `ref` 入参。
+* 它存在只为了让 `back` 不必改 `PageActionRequest.ref` 的类型——
+* 改它会波及所有实现过 executor 的宓主。
+* @experimental
+*/
+const PAGE_DOCUMENT_REF = "@document";
+
+//#endregion
+//#region ../agent/src/document/budget.ts
+/** @experimental */
+const DOCUMENT_READ_BUDGET = {
+	textChars: 96e3,
+	visionImages: 8
+};
+
+//#endregion
+//#region ../agent/src/document/format.ts
+const PDF_MAGIC = [
+	37,
+	80,
+	68,
+	70,
+	45
+];
+const ZIP_MAGIC = [
+	80,
+	75,
+	3,
+	4
+];
+function startsWith(bytes, magic) {
+	return magic.every((b, i) => bytes[i] === b);
+}
+/** zip 的本地文件头把条目名以明文 ASCII 存着，扫一遍即可，不必解压 */
+function containsEntry(bytes, name) {
+	const needle = new TextEncoder().encode(name);
+	const find = (from, to) => {
+		outer: for (let i = from; i + needle.length <= to; i += 1) {
+			for (let j = 0; j < needle.length; j += 1) if (bytes[i + j] !== needle[j]) continue outer;
+			return true;
+		}
+		return false;
+	};
+	const WINDOW = 64 * 1024;
+	if (find(0, Math.min(bytes.length, WINDOW))) return true;
+	return find(Math.max(0, bytes.length - WINDOW * 2), bytes.length);
+}
+/**
+* 格式以字节为准，文件名只作次要线索：改扩展名不该改变我们如何解析它。
+* 认不出返回 `undefined`，由调用方归因。
+* @experimental
+*/
+function sniffDocumentFormat(bytes, name) {
+	if (startsWith(bytes, PDF_MAGIC)) return "pdf";
+	if (!startsWith(bytes, ZIP_MAGIC)) return void 0;
+	const lower = (name ?? "").toLowerCase();
+	if (lower.endsWith(".docx")) return "docx";
+	if (lower.endsWith(".xlsx")) return "xlsx";
+	if (lower.endsWith(".pptx")) return "pptx";
+	if (containsEntry(bytes, "word/document.xml")) return "docx";
+	if (containsEntry(bytes, "xl/workbook.xml")) return "xlsx";
+	if (containsEntry(bytes, "ppt/presentation.xml")) return "pptx";
+}
+
+//#endregion
+//#region ../agent/src/document/pdfQuality.ts
+/**
+* 「这一页抽出来的是不是乱码」的判定（0.21.0 分册 22 · FR-22.2）。
+*
+* 判定必须是纯函数：它决定一页走文本还是走渲染，而渲染要烧一次多模态请求。
+* 靠人眼看一遍不叫判据。
+*/
+/** 坏字符占可打印字符的比例超过它即判文本层不可信 @experimental */
+const PDF_GARBLED_RATIO = .2;
+/** 短于它的页不参与比例判定：三五个字符里有一个私用区字符说明不了任何事 */
+const MIN_SAMPLE = 16;
+/**
+* 坏字符有三类，来源各不相同：
+* - 私用区 U+E000–U+F8FF：字体子集没有 `ToUnicode` 时，pdfjs 把 CID 原样落在这里
+* - U+FFFD：解码失败的替换字符
+* - C0/C1 控制字符：把二进制当文本读出来的残留
+*/
+function isGarbledChar(code) {
+	if (code >= 57344 && code <= 63743) return true;
+	if (code === 65533) return true;
+	if (code < 32 && code !== 9 && code !== 10 && code !== 13) return true;
+	return code >= 127 && code <= 159;
+}
+/**
+* 空白页一律判不可信：它要么是扫描页、要么什么都没有，
+* 两种情况都该让模型自己看一眼，而不是把一页空气交上去。
+* @experimental
+*/
+function measurePdfTextQuality(text) {
+	let printable = 0;
+	let garbled = 0;
+	for (const ch of text) {
+		const code = ch.codePointAt(0) ?? 0;
+		if (/\s/u.test(ch)) continue;
+		printable += 1;
+		if (isGarbledChar(code)) garbled += 1;
+	}
+	if (printable === 0) return {
+		printable,
+		garbled,
+		trustworthy: false
+	};
+	if (printable < MIN_SAMPLE) return {
+		printable,
+		garbled,
+		trustworthy: garbled === 0
+	};
+	return {
+		printable,
+		garbled,
+		trustworthy: garbled / printable <= PDF_GARBLED_RATIO
+	};
+}
+/** `measurePdfTextQuality(text).trustworthy` 的简写 @experimental */
+function isPdfTextTrustworthy(text) {
+	return measurePdfTextQuality(text).trustworthy;
+}
+
+//#endregion
+//#region ../agent/src/document/deferral.ts
+/** @experimental */
+function takesImage(mode, role) {
+	if (mode === "vision") return true;
+	if (mode === "images") return role === "illustration";
+	return role === "content";
+}
+/** 本次没取、但回头取得到的图（进返回值的 `deferred`） @experimental */
+function defersImage(mode, role) {
+	return mode === "auto" && role === "illustration";
+}
+/** 入参里的 `mode` 只认这三个字面量，其余一律当 `auto` @experimental */
+function asReadMode(raw) {
+	return raw === "vision" || raw === "images" ? raw : "auto";
+}
+
+//#endregion
+//#region ../agent/src/document/toolSource.ts
+/** @experimental */
+const READ_DOCUMENT_TOOL = "read_document";
+/** 大图的门槛：低于它的是页眉 logo、印章、项目符号，投它们等于白烧一次多模态请求 @experimental */
+const PDF_LARGE_IMAGE_RATIO = .15;
+const DESCRIPTION = "Read a PDF, Word (.docx), Excel (.xlsx) or PowerPoint (.pptx) document the user attached or downloaded, one batch of units at a time. Pages that have no usable text layer (scans) are rendered as images, so their content is never lost. Pictures on pages whose text is readable are listed under \"deferred\" instead of being returned, because reading them costs an extra round trip; call again with mode=\"images\" to fetch those.";
+const INPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		id: {
+			type: "string",
+			description: "The attachment id, or the id from list_downloaded_files."
+		},
+		from: {
+			type: "object",
+			description: "Where to continue. Omit to start at the beginning; otherwise pass the \"next\" of the previous call.",
+			properties: {
+				page: {
+					type: "number",
+					description: "PDF only: 0-based page index."
+				},
+				block: {
+					type: "number",
+					description: "Word and PowerPoint: 0-based block index."
+				},
+				sheet: {
+					type: "number",
+					description: "Excel only: 0-based sheet index."
+				},
+				row: {
+					type: "number",
+					description: "Excel only: 0-based row index within the sheet."
+				},
+				slide: {
+					type: "number",
+					description: "PowerPoint only: 0-based slide index."
+				}
+			},
+			additionalProperties: false
+		},
+		mode: {
+			type: "string",
+			enum: [
+				"auto",
+				"images",
+				"vision"
+			],
+			description: "\"auto\" (default) returns text plus the pictures that cannot be replaced by text, and lists the rest under \"deferred\". \"images\" returns only those deferred pictures and no text. \"vision\" (PDF only) renders every page as an image and ignores the text layer."
+		}
+	},
+	required: ["id"],
+	additionalProperties: false
+};
+const SYSTEM_PROMPT = "read_document reads an attached or downloaded PDF/Word/Excel/PowerPoint document in batches. It returns a \"next\" cursor whenever the document is not finished: keep calling read_document with that cursor until the result has no \"next\", otherwise you have only seen part of the document. Read the text first and answer from it; a result that carries \"deferred\" means those units hold pictures that were not read yet. Fetch them with mode=\"images\" only when the answer depends on what they show, and tell the user the pictures have not been looked at when you answer without them. Never guess an id, and never claim you read a document you only read part of.";
+function toolError(e) {
+	return {
+		ok: false,
+		content: [],
+		error: {
+			code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
+			message: messageOf(e)
+		}
+	};
+}
+/** 包一层：直写 `signal?.aborted` 会被 TS 按第一次检查永久收窄成 false */
+function aborted(signal) {
+	return signal !== void 0 && signal.aborted;
+}
+/**
+* 逐单元读文档，读不出字的地方出图（0.21.0 分册 22）。
+*
+* 四个端口一个都没接时 `listToolSpecs()` 返回空——模型连这个工具的存在都看不到，
+* 而不是看得到再被拒（AC-22.2）。
+* @experimental
+*/
+function createDocumentToolSource(options) {
+	const { files } = options;
+	const available = () => options.pdf !== void 0 || options.docx !== void 0 || options.xlsx !== void 0 || options.pptx !== void 0;
+	const budgetOf = () => options.budget?.() ?? DOCUMENT_READ_BUDGET;
+	return {
+		kind: "document-reader",
+		listToolSpecs: () => Promise.resolve(available() ? [{
+			name: READ_DOCUMENT_TOOL,
+			description: DESCRIPTION,
+			inputSchema: INPUT_SCHEMA
+		}] : []),
+		systemPrompt: () => Promise.resolve(available() ? SYSTEM_PROMPT : void 0),
+		canHandle: (name) => name === READ_DOCUMENT_TOOL,
+		argCaptureTrust: (name) => name === "read_document" ? { tier: "reviewed" } : void 0,
+		call: async (name, args, context) => {
+			try {
+				if (name !== "read_document") throw new WebSkillError("TOOL_NOT_FOUND", `Unknown tool ${name}.`);
+				return await read(args, context?.signal);
+			} catch (e) {
+				return toolError(e);
+			}
+		}
+	};
+	async function read(args, signal) {
+		const id = args["id"];
+		if (typeof id !== "string" || id === "") throw new WebSkillError("TOOL_UNSUPPORTED", "read_document requires the \"id\" of an attachment or download.");
+		const file = await files.read(id);
+		if (file === void 0) throw new WebSkillError("TOOL_UNSUPPORTED", `No readable document with id "${id}". It is either not an attachment of the current message, or a download id that has since expired — list the downloads again to get a fresh one.`);
+		const format = sniffDocumentFormat(file.bytes, file.name);
+		if (format === void 0) throw new WebSkillError("TOOL_UNSUPPORTED", `"${file.name}" is not a PDF, Word (.docx), Excel (.xlsx) or PowerPoint (.pptx) document, so read_document cannot read it.`);
+		const reader = readerFor(format);
+		if (reader === void 0) throw new WebSkillError("TOOL_UNSUPPORTED", `This environment cannot read ${format.toUpperCase()} documents.`);
+		const from = asCursor(args["from"]);
+		const mode = asReadMode(args["mode"]);
+		const budget = budgetOf();
+		const batch = format === "pdf" ? await readPdf(reader, file.bytes, from, mode, budget, signal) : format === "docx" ? await readDocx(reader, file.bytes, from, mode, budget, signal) : format === "pptx" ? await readPptx(reader, file.bytes, from, mode, budget, signal) : await readXlsx(reader, file.bytes, from, mode, budget, signal);
+		return {
+			ok: true,
+			content: describe(file.name, format, batch, aborted(signal))
+		};
+	}
+	function readerFor(format) {
+		if (format === "pdf") return options.pdf;
+		if (format === "docx") return options.docx;
+		if (format === "pptx") return options.pptx;
+		return options.xlsx;
+	}
+}
+function asCursor(raw) {
+	if (typeof raw !== "object" || raw === null) return {};
+	const out = {};
+	for (const key of [
+		"page",
+		"block",
+		"sheet",
+		"row",
+		"slide"
+	]) {
+		const value = raw[key];
+		if (typeof value === "number" && Number.isInteger(value) && value >= 0) out[key] = value;
+	}
+	return out;
+}
+/**
+* 预算是「加上这一个还超不超」，不是「已经超了没有」：
+* 后者会把一个超大单元整个吞下去再喊停，等于预算形同虚设。
+* 但**至少读一个单元**，否则一个超预算的单元会让续读原地打转。
+*/
+function wouldExceed(budget, taken, chars, images) {
+	if (taken === 0) return false;
+	return chars > budget.textChars || images > budget.visionImages;
+}
+async function readPdf(reader, bytes, from, mode, budget, signal) {
+	const handle = await reader.open(bytes);
+	try {
+		const start = from["page"] ?? 0;
+		const units = [];
+		const deferred = [];
+		let chars = 0;
+		let images = 0;
+		let page = start;
+		for (; page < handle.pageCount; page += 1) {
+			if (aborted(signal)) break;
+			const text = mode === "vision" ? "" : await handle.text(page);
+			const trustworthy = mode !== "vision" && isPdfTextTrustworthy(text);
+			const role = trustworthy ? "illustration" : "content";
+			const hasImage = role === "content" || await hasLargeImage(handle, page);
+			const needsImage = hasImage && takesImage(mode, role);
+			if (mode === "images" && !needsImage) continue;
+			const withText = trustworthy && mode !== "images";
+			const nextChars = chars + (withText ? text.length : 0);
+			const nextImages = images + (needsImage ? 1 : 0);
+			if (wouldExceed(budget, units.length, nextChars, nextImages)) break;
+			if (aborted(signal)) break;
+			const rendered = needsImage ? await handle.render(page) : void 0;
+			if (hasImage && defersImage(mode, role)) deferred.push({ page });
+			units.push({
+				unit: { page },
+				...withText ? { text } : {},
+				...rendered ? { image: rendered } : {}
+			});
+			chars = nextChars;
+			images = nextImages;
+		}
+		return {
+			units,
+			total: handle.pageCount,
+			done: page,
+			skippedImages: 0,
+			deferred,
+			...page < handle.pageCount ? { next: { page } } : {}
+		};
+	} finally {
+		await handle.close();
+	}
+}
+async function hasLargeImage(handle, page) {
+	return (await handle.images(page)).some((image) => image.areaRatio >= PDF_LARGE_IMAGE_RATIO);
+}
+async function readDocx(reader, bytes, from, mode, budget, signal) {
+	const { blocks } = await reader.read(bytes);
+	const taken = takeBlocks(blocks, from["block"] ?? 0, mode, budget, signal, (index) => ({ block: index }));
+	return {
+		units: taken.units,
+		total: blocks.length,
+		done: taken.stopped,
+		skippedImages: taken.skippedImages,
+		deferred: taken.deferred,
+		...taken.stopped < blocks.length ? { next: { block: taken.stopped } } : {}
+	};
+}
+async function readXlsx(reader, bytes, from, mode, budget, signal) {
+	const { sheets } = await reader.read(bytes);
+	const flat = [];
+	sheets.forEach((sheet, sheetIndex) => {
+		sheet.rows.forEach((block, rowIndex) => {
+			flat.push({
+				sheet: sheetIndex,
+				sheetName: sheet.name,
+				row: rowIndex,
+				block
+			});
+		});
+	});
+	const startSheet = from["sheet"] ?? 0;
+	const startRow = from["row"] ?? 0;
+	const found = flat.findIndex((entry) => entry.sheet > startSheet || entry.sheet === startSheet && entry.row >= startRow);
+	const start = found === -1 ? flat.length : found;
+	const taken = takeBlocks(flat.map((entry) => entry.block), start, mode, budget, signal, (index) => ({
+		sheet: flat[index].sheet,
+		sheetName: flat[index].sheetName,
+		row: flat[index].row
+	}));
+	const stop = flat[taken.stopped];
+	return {
+		units: taken.units,
+		total: flat.length,
+		done: taken.stopped,
+		skippedImages: taken.skippedImages,
+		deferred: taken.deferred,
+		...stop ? { next: {
+			sheet: stop.sheet,
+			row: stop.row
+		} } : {}
+	};
+}
+/**
+* pptx 摊平成「第几页第几块」的一条序列，与 xlsx 的表×行同构。
+* 幻灯片真有页，所以坐标保留页号——模型报「第 7 页那张图」时对得上用户看到的东西。
+*/
+async function readPptx(reader, bytes, from, mode, budget, signal) {
+	const { slides } = await reader.read(bytes);
+	const flat = [];
+	slides.forEach((slide, slideIndex) => {
+		slide.blocks.forEach((content, blockIndex) => {
+			flat.push({
+				slide: slideIndex,
+				block: blockIndex,
+				content
+			});
+		});
+	});
+	const startSlide = from["slide"] ?? 0;
+	const startBlock = from["block"] ?? 0;
+	const found = flat.findIndex((entry) => entry.slide > startSlide || entry.slide === startSlide && entry.block >= startBlock);
+	const start = found === -1 ? flat.length : found;
+	const taken = takeBlocks(flat.map((entry) => entry.content), start, mode, budget, signal, (index) => ({
+		slide: flat[index].slide,
+		block: flat[index].block
+	}));
+	const stop = flat[taken.stopped];
+	return {
+		units: taken.units,
+		total: flat.length,
+		done: taken.stopped,
+		skippedImages: taken.skippedImages,
+		deferred: taken.deferred,
+		...stop ? { next: {
+			slide: stop.slide,
+			block: stop.block
+		} } : {}
+	};
+}
+function takeBlocks(blocks, start, mode, budget, signal, locate) {
+	const units = [];
+	const deferred = [];
+	let chars = 0;
+	let images = 0;
+	let skippedImages = 0;
+	let index = start;
+	for (; index < blocks.length; index += 1) {
+		if (aborted(signal)) break;
+		const block = blocks[index];
+		if (block.kind === "skipped") {
+			skippedImages += 1;
+			continue;
+		}
+		if (!(block.kind === "text" ? mode !== "images" : takesImage(mode, "illustration"))) {
+			if (block.kind === "image" && defersImage(mode, "illustration")) deferred.push(locate(index));
+			continue;
+		}
+		const nextChars = chars + (block.kind === "text" ? block.text.length : 0);
+		const nextImages = images + (block.kind === "image" ? 1 : 0);
+		if (wouldExceed(budget, units.length, nextChars, nextImages)) break;
+		units.push({
+			unit: locate(index),
+			...block.kind === "text" ? { text: block.text } : {},
+			...block.kind === "image" ? { image: {
+				mimeType: block.mimeType,
+				data: block.data
+			} } : {}
+		});
+		chars = nextChars;
+		images = nextImages;
+	}
+	return {
+		units,
+		stopped: index,
+		skippedImages,
+		deferred
+	};
+}
+/**
+* 图只能走 user 消息，出处只能随同一结果里的 json 分片走——
+* 与下载工具源同款（引擎把图转成 carried 时会丢掉 id 与文件名）。
+*/
+function describe(name, format, batch, cancelled) {
+	const images = [];
+	const units = batch.units.map((entry) => {
+		const located = {
+			...entry.unit,
+			...entry.text === void 0 ? {} : { text: entry.text }
+		};
+		if (entry.image === void 0) return located;
+		const imageId = imageIdOf(entry.unit);
+		images.push({
+			type: "image",
+			id: imageId,
+			mimeType: entry.image.mimeType,
+			data: entry.image.data
+		});
+		return {
+			...located,
+			imageId
+		};
+	});
+	const withText = batch.units.filter((entry) => entry.text !== void 0).length;
+	const withImage = images.length;
+	const remaining = Math.max(0, batch.total - batch.done);
+	const json = {
+		file: name,
+		format,
+		source: withImage === 0 ? "text" : withText === 0 ? "vision" : "mixed",
+		total: batch.total,
+		units,
+		remaining,
+		note: continuationNote(format, batch, remaining, cancelled)
+	};
+	if (batch.next !== void 0) {
+		json["next"] = batch.next;
+		json["truncated"] = true;
+	}
+	if (batch.skippedImages > 0) json["skipped"] = {
+		images: batch.skippedImages,
+		reason: "EMF/WMF images cannot be decoded in a browser and were left out."
+	};
+	if (batch.deferred.length > 0) json["deferred"] = {
+		images: batch.deferred.length,
+		units: batch.deferred,
+		note: `${batch.deferred.length} unit(s) above hold pictures that were not read, because their text is readable on its own. Answer from the text when you can. If the answer depends on what a picture shows, call read_document again with mode="images" and from = ${JSON.stringify(batch.deferred[0])}, and say so if you answer without looking at them.`
+	};
+	return [{
+		type: "json",
+		data: json
+	}, ...images];
+}
+function continuationNote(format, batch, remaining, cancelled) {
+	const noun = format === "pdf" ? "page" : format === "xlsx" ? "row" : "block";
+	if (batch.next === void 0) return `Reached the end of the document; all ${batch.total} ${noun}s have been read.`;
+	const cursor = JSON.stringify(batch.next);
+	return `${cancelled ? "Stopped because the user cancelled the run" : `${remaining} ${noun}(s) still unread`}. Call read_document again with from = ${cursor} to continue.`;
+}
+/** 由单元坐标推出，因此与 `units[].imageId` 天然对得上，不依赖批次内的序号 */
+function imageIdOf(unit) {
+	if (typeof unit["page"] === "number") return `doc-p${unit["page"]}`;
+	if (typeof unit["block"] === "number") return `doc-b${unit["block"]}`;
+	return `doc-s${unit["sheet"]}r${unit["row"]}`;
+}
+
+//#endregion
+//#region ../agent/src/template/geometry.ts
+/**
+* A1 地址与 OOXML 几何换算（0.22.0 分册 42 · 设计 43 §1.6）。
+*
+* 环境无关，`@webskill/agent` 里可直接单测——几何算错的后果是图溢出单元格，
+* 而那只有人肉打开文件才看得见，所以这一层的覆盖要密。
+*/
+/** 1 px 的 EMU 数（96 DPI） */
+const EMU_PER_PIXEL = 9525;
+/** 1 磅的 EMU 数 */
+const EMU_PER_POINT = 12700;
+/** 1 twip 的 EMU 数 */
+const EMU_PER_TWIP = 635;
+/** 默认字体的最大数字宽度，Excel 列宽换算基准 */
+const MAX_DIGIT_WIDTH = 7;
+const ADDRESS = /^([A-Z]+)([1-9][0-9]*)$/;
+/** @throws WebSkillError 语法不合法 */
+function parseCellAddress(address) {
+	const match = ADDRESS.exec(address.trim().toUpperCase());
+	if (match === null) throw new WebSkillError("TEMPLATE_ADDRESS_INVALID", `"${address}" is not a valid cell address. Use A1 notation such as B3.`);
+	let column = 0;
+	for (const letter of match[1] ?? "") column = column * 26 + (letter.charCodeAt(0) - 64);
+	return {
+		column: column - 1,
+		row: Number(match[2]) - 1
+	};
+}
+function formatCellAddress({ column, row }) {
+	let letters = "";
+	for (let rest = column + 1; rest > 0; rest = Math.floor((rest - 1) / 26)) letters = String.fromCharCode(65 + (rest - 1) % 26) + letters;
+	return `${letters}${row + 1}`;
+}
+/** @throws WebSkillError 语法不合法 */
+function parseCellRange(range) {
+	const [from = "", to] = range.split(":");
+	if (to === void 0) {
+		const single = parseCellAddress(from);
+		return {
+			start: single,
+			end: single
+		};
+	}
+	return {
+		start: parseCellAddress(from),
+		end: parseCellAddress(to)
+	};
+}
+function isRangeTopLeft(range, address) {
+	return range.start.column === address.column && range.start.row === address.row;
+}
+function rangeContains(range, address) {
+	return address.column >= range.start.column && address.column <= range.end.column && address.row >= range.start.row && address.row <= range.end.row;
+}
+/** Excel 的列宽单位是字符数，换算成像素（设计 43 §1.6 实测 MDW=7） */
+function columnWidthToPixels(width) {
+	return Math.round(width * 7 + 5);
+}
+/**
+* 等比缩放进框：宽高同时约束、**取两个比例里的小者**。
+*
+* FR-42.11 与 FR-42.19 是同一条口径——xlsx 的合并区和 docx 声明了 `trHeight` 的
+* 表格行都这么算。框的某一边为 0（未声明高度）时那一边不参与约束。
+*/
+function fitWithin(natural, box) {
+	const widthRatio = box.width > 0 ? box.width / natural.width : Number.POSITIVE_INFINITY;
+	const heightRatio = box.height > 0 ? box.height / natural.height : Number.POSITIVE_INFINITY;
+	const ratio = Math.min(widthRatio, heightRatio, 1);
+	if (!Number.isFinite(ratio)) return natural;
+	return {
+		width: Math.floor(natural.width * ratio),
+		height: Math.floor(natural.height * ratio)
+	};
+}
+/** PNG / JPEG 的像素尺寸。读文件头，不解码整张图。 */
+function readImageSize(bytes) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	if (bytes.length > 24 && view.getUint32(0) === 2303741511) return {
+		width: view.getUint32(16),
+		height: view.getUint32(20)
+	};
+	if (bytes.length > 4 && view.getUint16(0) === 65496) return readJpegSize(view, bytes.length);
+}
+function readJpegSize(view, length) {
+	let offset = 2;
+	while (offset + 9 < length) {
+		if (view.getUint8(offset) !== 255) {
+			offset += 1;
+			continue;
+		}
+		const marker = view.getUint8(offset + 1);
+		if (marker >= 192 && marker <= 207 && marker !== 196 && marker !== 200 && marker !== 204) return {
+			width: view.getUint16(offset + 7),
+			height: view.getUint16(offset + 5)
+		};
+		offset += 2 + view.getUint16(offset + 2);
+	}
+}
+
+//#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 };