@godcreator/word-report 0.4.0 → 0.5.0

package/dist/node.d.mts

@@ -1,5 +1,5 @@
-import { n as AssemblyOptions, r as AssemblyResult } from "./types-Bcl48xQN.mjs";
-import { a as ReportCheckDiagnostic, i as reportExport, n as ReportExportResult, o as ReportCheckResult, r as reportEntry, s as checkReports, t as ReportExportOptions } from "./export-DC764Umz.mjs";
+import { n as AssemblyOptions, r as AssemblyResult } from "./types-Ea2OT6Ac.mjs";
+import { a as ReportCheckDiagnostic, i as reportExport, n as ReportExportResult, o as ReportCheckResult, r as reportEntry, s as checkReports, t as ReportExportOptions } from "./export-DMKj4gl2.mjs";
 //#region src/node/read-report.d.ts
 interface SnapshotEntry {
   path: string;
@@ -18,18 +18,24 @@ declare function readReport(entryAbsolute: string, options?: AssemblyOptions & {
 }): Promise<ReadReportResult>;
 //#endregion
 //#region src/node/report-files.d.ts
-/** 站点里的报告：站点根下 reports/<报告 id>/content.json，章节与图片在同一个报告目录里 */
+/** 站点里的报告：站点根下 reports/<报告 id>/，入口是 content.json（JSON 报告）或 index.mdx（MDX 报告），两种只能有一种 */
 declare const reportsDirName = "reports";
+declare const JSON_ENTRY_NAME = "content.json";
 /** 报告 id 就是报告目录名，出现在网址里：小写字母、数字与 -，以字母或数字开头 */
 declare const REPORT_ID_PATTERN: RegExp;
-/** 报告的入口，相对站点目录 */
+/** JSON 报告的入口，相对站点目录；报告是哪种格式要看磁盘，用 reportEntryIn */
 declare function reportEntryOf(reportId: string): string;
-/** 站点里的报告 id：reports/ 下有 content.json 的目录，按名字排；目录名不合 REPORT_ID_PATTERN 的直接报错，不悄悄跳过 */
+declare const isMdxEntry: (entry: string) => boolean;
+/** 一份报告的入口，相对站点目录：reports/<id>/content.json 或 reports/<id>/index.mdx */
+declare function reportEntryIn(siteDir: string, reportId: string): Promise<string>;
+/** 站点里的报告 id：reports/ 下有入口文件的目录，按名字排；目录名不合 REPORT_ID_PATTERN 的直接报错，不悄悄跳过 */
 declare function reportIdsOf(siteDir: string): Promise<string[]>;
 /**
  * 读一份报告组装要的全部 JSON 文件（入口与它 include 到的章节），键是相对站点目录的路径，交给 assembleDocument。
  * 不读图片、不解码：网页显示用；检查与导出用 readReport，它还核对图片与快照
  */
 declare function readReportFiles(siteDir: string, entry: string): Promise<Record<string, string>>;
+/** 读一份 MDX 报告的全部原文：入口、chapters 列的各章、存在时的 references.mdx，键是相对站点目录的路径，交给 assembleMdxReport */
+declare function readMdxReportFiles(siteDir: string, entry: string): Promise<Record<string, string>>;
 //#endregion
-export { REPORT_ID_PATTERN, type ReadReportResult, type ReportCheckDiagnostic, type ReportCheckResult, type ReportExportOptions, type ReportExportResult, type SnapshotEntry, checkReports, readReport, readReportFiles, reportEntry, reportEntryOf, reportExport, reportIdsOf, reportsDirName };
+export { JSON_ENTRY_NAME, REPORT_ID_PATTERN, type ReadReportResult, type ReportCheckDiagnostic, type ReportCheckResult, type ReportExportOptions, type ReportExportResult, type SnapshotEntry, checkReports, isMdxEntry, readMdxReportFiles, readReport, readReportFiles, reportEntry, reportEntryIn, reportEntryOf, reportExport, reportIdsOf, reportsDirName };

package/dist/node.mjs

@@ -1,3 +1,3 @@
-import { i as readReport, n as reportExport, r as checkReports, t as reportEntry } from "./export-DJQiBPPU.mjs";
-import { a as reportsDirName, i as reportIdsOf, n as readReportFiles, r as reportEntryOf, t as REPORT_ID_PATTERN } from "./report-files-CgWzLxH-.mjs";
-export { REPORT_ID_PATTERN, checkReports, readReport, readReportFiles, reportEntry, reportEntryOf, reportExport, reportIdsOf, reportsDirName };
+import { i as readReport, n as reportExport, r as checkReports, t as reportEntry } from "./export-B01-yaAq.mjs";
+import { a as readReportFiles, c as reportIdsOf, i as readMdxReportFiles, l as reportsDirName, n as REPORT_ID_PATTERN, o as reportEntryIn, r as isMdxEntry, s as reportEntryOf, t as JSON_ENTRY_NAME } from "./report-files-Dfr71bRv.mjs";
+export { JSON_ENTRY_NAME, REPORT_ID_PATTERN, checkReports, isMdxEntry, readMdxReportFiles, readReport, readReportFiles, reportEntry, reportEntryIn, reportEntryOf, reportExport, reportIdsOf, reportsDirName };

package/dist/{page-data-CJ6nCBnW.d.mts → page-data-C1veAE55.d.mts}

@@ -1,4 +1,4 @@
-import { r as AssemblyResult } from "./types-Bcl48xQN.mjs";
+import { r as AssemblyResult } from "./types-Ea2OT6Ac.mjs";
 import { CommentsAccess, PageThreadSummary } from "@godcreator/comments/site";
 //#region src/site/page-data.d.ts
 /** 报告列表里的一行：报告读不对时 problem 是原话，标题退回报告 id */

package/dist/report-files-Dfr71bRv.mjs

@@ -0,0 +1,103 @@
+import { i as validateDocument, n as safeRelativePath, o as parseReportJson, s as ReportContentError } from "./assemble-BEt9_xsB.mjs";
+import { a as mdxReportInputsOf, t as MDX_ENTRY_NAME } from "./mdx-C1RVv6E-.mjs";
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+//#region src/node/report-files.ts
+/** 站点里的报告：站点根下 reports/<报告 id>/，入口是 content.json（JSON 报告）或 index.mdx（MDX 报告），两种只能有一种 */
+const reportsDirName = "reports";
+const JSON_ENTRY_NAME = "content.json";
+/** 报告 id 就是报告目录名，出现在网址里：小写字母、数字与 -，以字母或数字开头 */
+const REPORT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** JSON 报告的入口，相对站点目录；报告是哪种格式要看磁盘，用 reportEntryIn */
+function reportEntryOf(reportId) {
+	if (!REPORT_ID_PATTERN.test(reportId)) throw new ReportContentError(`报告 id 只能是小写字母、数字与 -，以字母或数字开头：${JSON.stringify(reportId)}`);
+	return `${reportsDirName}/${reportId}/${JSON_ENTRY_NAME}`;
+}
+const isMdxEntry = (entry) => entry === "index.mdx" || entry.endsWith(`/index.mdx`);
+async function isFile(file) {
+	return stat(file).then((info) => info.isFile(), (error) => {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	});
+}
+/** 报告目录里有哪种入口：两种都有直接报错，都没有回 undefined */
+async function entryNameIn(reportDir, reportId) {
+	const [hasJson, hasMdx] = await Promise.all([isFile(path.join(reportDir, JSON_ENTRY_NAME)), isFile(path.join(reportDir, MDX_ENTRY_NAME))]);
+	if (hasJson && hasMdx) throw new ReportContentError(`报告目录里 ${JSON_ENTRY_NAME} 和 ${MDX_ENTRY_NAME} 只能留一个`, `${reportsDirName}/${reportId}`);
+	return hasJson ? JSON_ENTRY_NAME : hasMdx ? MDX_ENTRY_NAME : void 0;
+}
+/** 一份报告的入口，相对站点目录：reports/<id>/content.json 或 reports/<id>/index.mdx */
+async function reportEntryIn(siteDir, reportId) {
+	const jsonEntry = reportEntryOf(reportId);
+	const name = await entryNameIn(path.join(siteDir, path.dirname(jsonEntry)), reportId);
+	if (name === void 0) throw new ReportContentError(`站点里没有报告 ${reportId}：reports/${reportId}/ 下既没有 ${JSON_ENTRY_NAME} 也没有 ${MDX_ENTRY_NAME}`, siteDir);
+	return `${reportsDirName}/${reportId}/${name}`;
+}
+/** 站点里的报告 id：reports/ 下有入口文件的目录，按名字排；目录名不合 REPORT_ID_PATTERN 的直接报错，不悄悄跳过 */
+async function reportIdsOf(siteDir) {
+	const reportsDir = path.join(siteDir, reportsDirName);
+	let entries;
+	try {
+		entries = await readdir(reportsDir, { withFileTypes: true });
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+	const ids = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		if (await entryNameIn(path.join(reportsDir, entry.name), entry.name) === void 0) continue;
+		reportEntryOf(entry.name);
+		ids.push(entry.name);
+	}
+	return ids.sort();
+}
+/** 读站点目录里的一个文件（相对路径），挡住经符号链接跑出站点目录的 */
+async function readInsideSite(root, relative) {
+	let real;
+	try {
+		real = await realpath(path.join(root, relative));
+	} catch {
+		throw new ReportContentError("Missing or unreadable file", relative);
+	}
+	const inside = path.relative(root, real);
+	if (inside === ".." || inside.startsWith(".." + path.sep) || path.isAbsolute(inside)) throw new ReportContentError("File escapes report root", relative);
+	return readFile(real, "utf8");
+}
+/**
+* 读一份报告组装要的全部 JSON 文件（入口与它 include 到的章节），键是相对站点目录的路径，交给 assembleDocument。
+* 不读图片、不解码：网页显示用；检查与导出用 readReport，它还核对图片与快照
+*/
+async function readReportFiles(siteDir, entry) {
+	const root = await realpath(siteDir);
+	const files = {};
+	const load = async (relative) => {
+		if (Object.hasOwn(files, relative)) return;
+		const text = await readInsideSite(root, relative);
+		files[relative] = text;
+		const document = parseReportJson(text, relative);
+		validateDocument(document, relative);
+		for (const [index, block] of document.blocks.entries()) {
+			if (block.type !== "include") continue;
+			try {
+				safeRelativePath(block.src);
+			} catch (error) {
+				throw new ReportContentError(error.message, relative, `/blocks/${index}/src`);
+			}
+			await load(path.posix.join(path.posix.dirname(relative), block.src));
+		}
+	};
+	await load(entry);
+	return files;
+}
+/** 读一份 MDX 报告的全部原文：入口、chapters 列的各章、存在时的 references.mdx，键是相对站点目录的路径，交给 assembleMdxReport */
+async function readMdxReportFiles(siteDir, entry) {
+	const root = await realpath(siteDir);
+	const files = { [entry]: await readInsideSite(root, entry) };
+	const { chapters, references } = mdxReportInputsOf(files[entry], entry);
+	for (const chapter of chapters) files[chapter] = await readInsideSite(root, chapter);
+	if (await isFile(path.join(root, references))) files[references] = await readInsideSite(root, references);
+	return files;
+}
+//#endregion
+export { readReportFiles as a, reportIdsOf as c, readMdxReportFiles as i, reportsDirName as l, REPORT_ID_PATTERN as n, reportEntryIn as o, isMdxEntry as r, reportEntryOf as s, JSON_ENTRY_NAME as t };

package/dist/site-server.d.mts

@@ -1,4 +1,4 @@
-import { a as ReportTocItem, i as ReportSummary, n as ReportPageComments, r as ReportPageData, t as ReportListData } from "./page-data-CJ6nCBnW.mjs";
+import { a as ReportTocItem, i as ReportSummary, n as ReportPageComments, r as ReportPageData, t as ReportListData } from "./page-data-C1veAE55.mjs";
 //#region src/site/loaders.server.d.ts
 /**
  * 报告功能的站点信息：站点目录（报告在它的 reports/ 下）、站名、报告页的地址前缀，
@@ -10,15 +10,19 @@ type WordReportSite = {
   hrefBase: string;
   pageComments: (page: string) => ReportPageComments;
 };
-/** loader 用到的路由参数：报告页是 :report，图片再加 * */
+/** loader 用到的路由参数：报告页是 :report，图片再加 *；图片的 loader 收到 request 时按 If-None-Match 回 304 */
 type ReportRouteArgs = {
   params: Partial<Record<string, string>>;
+  request?: Request;
 };
 /** 报告列表：站点 reports/ 下的每份报告各一行；读不对的报告也列出来，带上原话 */
 declare function reportListLoader(_args: ReportRouteArgs, site: WordReportSite): Promise<ReportListData>;
 /** 报告页：整份报告组装成一页（各章按 include 的顺序接在一起）；报告读不对直接报错，原话在错误页上 */
 declare function reportPageLoader({ params }: ReportRouteArgs, site: WordReportSite): Promise<ReportPageData>;
-/** 报告里的一张图：地址是组装后的路径 assets/<文档 id>/<文件名>，只给这份报告用到的图 */
-declare function reportAssetLoader({ params }: ReportRouteArgs, site: WordReportSite): Promise<Response>;
+/**
+ * 报告里的一张图：地址是组装后的路径 assets/<文档 id>/<文件名>，只给这份报告用到的图。
+ * 浏览器每次都来问（no-cache），ETag 由文件大小与修改时间算出，没变就回 304、不再传图
+ */
+declare function reportAssetLoader({ params, request }: ReportRouteArgs, site: WordReportSite): Promise<Response>;
 //#endregion
 export { type ReportListData, type ReportPageComments, type ReportPageData, ReportRouteArgs, type ReportSummary, type ReportTocItem, WordReportSite, reportAssetLoader, reportListLoader, reportPageLoader };

package/dist/site-server.mjs

@@ -1,18 +1,85 @@
-import { t as assembleDocument } from "./assemble-D25NLmLx.mjs";
-import { i as reportIdsOf, n as readReportFiles, r as reportEntryOf, t as REPORT_ID_PATTERN } from "./report-files-CgWzLxH-.mjs";
+import { t as assembleDocument } from "./assemble-BEt9_xsB.mjs";
+import { a as mdxReportInputsOf, r as assembleMdxReport, t as MDX_ENTRY_NAME } from "./mdx-C1RVv6E-.mjs";
+import { a as readReportFiles, c as reportIdsOf, i as readMdxReportFiles, n as REPORT_ID_PATTERN, o as reportEntryIn, r as isMdxEntry, t as JSON_ENTRY_NAME } from "./report-files-Dfr71bRv.mjs";
 import { n as reportHrefOf } from "./page-data-DLPoVgXy.mjs";
+import { readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { createReadStream } from "node:fs";
 import { Readable } from "node:stream";
 //#region src/site/loaders.server.ts
 /**
-* `@godcreator/word-report/site/server`：报告列表、报告页与报告里图片的 loader，报告每次从站点 reports/ 现读、现组装。
+* `@godcreator/word-report/site/server`：报告列表、报告页与报告里图片的 loader。报告从站点 reports/ 现读，
+* 原文没变时沿用上一次的组装结果。
 */
 /** 组装结果里有 Object.create(null) 的对象：换成普通对象再交给 React Router 序列化 */
 const plainOf = (result) => JSON.parse(JSON.stringify(result));
+/**
+* 每份报告最近一次组装，键是站点目录加报告 id。一页报告的几十张图同时请求，组装一次要几百毫秒到几秒、
+* 全在一个线程上排队：不共用的话，最后一张图要等几十次组装
+*/
+const latestAssemblies = /* @__PURE__ */ new Map();
+async function assembleFromDisk(siteDir, reportId) {
+	const entry = await reportEntryIn(siteDir, reportId);
+	const reportDir = path.posix.dirname(entry);
+	if (isMdxEntry(entry)) {
+		const files = await readMdxReportFiles(siteDir, entry);
+		const { chapters, references } = mdxReportInputsOf(files[entry], entry);
+		return {
+			files,
+			absentFiles: [`${reportDir}/${JSON_ENTRY_NAME}`, ...Object.hasOwn(files, references) ? [] : [references]],
+			result: assembleMdxReport({
+				reportId,
+				entry,
+				files
+			}, { mode: "complete" }),
+			chapterCount: chapters.length
+		};
+	}
+	const files = await readReportFiles(siteDir, entry);
+	const entryDocument = JSON.parse(files[entry]);
+	const result = assembleDocument(entry, files, { mode: "complete" });
+	return {
+		files,
+		absentFiles: [`${reportDir}/${MDX_ENTRY_NAME}`],
+		result,
+		chapterCount: entryDocument.blocks.filter((block) => block.type === "include").length
+	};
+}
+/** 上次组装读过的每个文件原文都没变、当时不存在的文件仍不存在；读过的文件没了也算变了，交给重新组装去报错 */
+async function unchangedOnDisk(siteDir, assembly) {
+	const root = await realpath(siteDir);
+	const textOrMissing = async (relative) => {
+		try {
+			return await readFile(path.join(root, relative), "utf8");
+		} catch (error) {
+			if (error.code === "ENOENT") return null;
+			throw error;
+		}
+	};
+	const [sameTexts, stillAbsent] = await Promise.all([Promise.all(Object.entries(assembly.files).map(async ([relative, text]) => await textOrMissing(relative) === text)), Promise.all(assembly.absentFiles.map(async (relative) => await textOrMissing(relative) === null))]);
+	return [...sameTexts, ...stillAbsent].every(Boolean);
+}
+/** 报告的整份组装：原文和上次一样就用上次的，同时到的请求共用同一次组装；结果只读，要改先复制 */
+async function latestAssembly(siteDir, reportId) {
+	const key = `${path.resolve(siteDir)}\0${reportId}`;
+	const latest = latestAssemblies.get(key);
+	if (latest !== void 0) {
+		const assembly = await latest;
+		if (await unchangedOnDisk(siteDir, assembly)) return assembly;
+	}
+	const newer = latestAssemblies.get(key);
+	if (newer !== void 0 && newer !== latest) return newer;
+	const fresh = assembleFromDisk(siteDir, reportId);
+	latestAssemblies.set(key, fresh);
+	try {
+		return await fresh;
+	} catch (error) {
+		if (latestAssemblies.get(key) === fresh) latestAssemblies.delete(key);
+		throw error;
+	}
+}
 async function assembledReport(siteDir, reportId) {
-	const entry = reportEntryOf(reportId);
-	return assembleDocument(entry, await readReportFiles(siteDir, entry), { mode: "complete" });
+	return (await latestAssembly(siteDir, reportId)).result;
 }
 /** 地址里的报告 id：形状不对或站点里没有这份报告都是 404 */
 async function reportIdOf(params, siteDir) {
@@ -20,31 +87,26 @@ async function reportIdOf(params, siteDir) {
 	if (!REPORT_ID_PATTERN.test(reportId) || !(await reportIdsOf(siteDir)).includes(reportId)) throw new Response(`站点里没有报告 ${reportId}`, { status: 404 });
 	return reportId;
 }
-function summaryOf(reportId, files, result, problem) {
-	const metadata = result?.document.metadata ?? {};
-	const entryDocument = files === null ? null : JSON.parse(files[reportEntryOf(reportId)]);
+function summaryOf(reportId, read, problem) {
+	const metadata = read?.result.document.metadata ?? {};
 	return {
 		id: reportId,
 		title: metadata.title ?? reportId,
 		revision: metadata.revision ?? null,
 		date: metadata.date ?? null,
 		authors: metadata.authors ?? [],
-		chapterCount: entryDocument?.blocks.filter((block) => block.type === "include").length ?? 0,
-		warningCount: result?.warnings.length ?? 0,
+		chapterCount: read?.chapterCount ?? 0,
+		warningCount: read?.result.warnings.length ?? 0,
 		problem
 	};
 }
 /** 报告列表：站点 reports/ 下的每份报告各一行；读不对的报告也列出来，带上原话 */
 async function reportListLoader(_args, site) {
 	const reports = [];
-	for (const reportId of await reportIdsOf(site.siteDir)) {
-		let files = null;
-		try {
-			files = await readReportFiles(site.siteDir, reportEntryOf(reportId));
-			reports.push(summaryOf(reportId, files, assembleDocument(reportEntryOf(reportId), files, { mode: "complete" }), null));
-		} catch (error) {
-			reports.push(summaryOf(reportId, null, null, error instanceof Error ? error.message : String(error)));
-		}
+	for (const reportId of await reportIdsOf(site.siteDir)) try {
+		reports.push(summaryOf(reportId, await latestAssembly(site.siteDir, reportId), null));
+	} catch (error) {
+		reports.push(summaryOf(reportId, null, error instanceof Error ? error.message : String(error)));
 	}
 	return {
 		siteName: site.siteName,
@@ -88,15 +150,29 @@ const imageContentTypes = {
 	".jpg": "image/jpeg",
 	".jpeg": "image/jpeg"
 };
-/** 报告里的一张图：地址是组装后的路径 assets/<文档 id>/<文件名>，只给这份报告用到的图 */
-async function reportAssetLoader({ params }, site) {
+/**
+* 报告里的一张图：地址是组装后的路径 assets/<文档 id>/<文件名>，只给这份报告用到的图。
+* 浏览器每次都来问（no-cache），ETag 由文件大小与修改时间算出，没变就回 304、不再传图
+*/
+async function reportAssetLoader({ params, request }, site) {
 	const reportId = await reportIdOf(params, site.siteDir);
 	const compiledPath = `assets/${params["*"] ?? ""}`;
 	const source = (await assembledReport(site.siteDir, reportId)).assets[compiledPath];
 	if (source === void 0) return new Response(`报告 ${reportId} 里没有图 ${compiledPath}`, { status: 404 });
 	const contentType = imageContentTypes[path.extname(source).toLowerCase()];
 	if (contentType === void 0) throw new Error(`报告 ${reportId} 的图 ${source} 不是 png 或 jpg`);
-	return new Response(Readable.toWeb(createReadStream(path.join(site.siteDir, source))), { headers: { "content-type": contentType } });
+	const file = path.join(site.siteDir, source);
+	const { size, mtimeMs } = await stat(file);
+	const headers = {
+		"content-type": contentType,
+		"cache-control": "no-cache",
+		etag: `"${size.toString(16)}-${Math.trunc(mtimeMs).toString(16)}"`
+	};
+	if (request?.headers.get("if-none-match") === headers.etag) return new Response(null, {
+		status: 304,
+		headers
+	});
+	return new Response(Readable.toWeb(createReadStream(file)), { headers });
 }
 //#endregion
 export { reportAssetLoader, reportListLoader, reportPageLoader };

package/dist/site.d.mts

@@ -1,5 +1,5 @@
-import { r as AssemblyResult, v as ReportDocument } from "./types-Bcl48xQN.mjs";
-import { a as ReportTocItem, i as ReportSummary, n as ReportPageComments, o as reportAssetHrefOf, r as ReportPageData, s as reportHrefOf, t as ReportListData } from "./page-data-CJ6nCBnW.mjs";
+import { r as AssemblyResult, y as ReportDocument } from "./types-Ea2OT6Ac.mjs";
+import { a as ReportTocItem, i as ReportSummary, n as ReportPageComments, o as reportAssetHrefOf, r as ReportPageData, s as reportHrefOf, t as ReportListData } from "./page-data-C1veAE55.mjs";
 import { CommentAvatar, CommentBodyComponent } from "@godcreator/comments/site";
 //#region src/site/report-pages.d.ts
 declare function ReportListPage(): import("react").JSX.Element;

package/dist/site.mjs

@@ -1,4 +1,4 @@
-import { t as assembleDocument } from "./assemble-D25NLmLx.mjs";
+import { t as assembleDocument } from "./assemble-BEt9_xsB.mjs";
 import { n as reportHrefOf, t as reportAssetHrefOf } from "./page-data-DLPoVgXy.mjs";
 import { Link, useLoaderData } from "react-router";
 import { DocsBody, DocsPage, DocsTitle } from "@fumadocs/base-ui/layouts/docs/page";

package/dist/{types-Bcl48xQN.d.mts → types-Ea2OT6Ac.d.mts}

@@ -7,6 +7,7 @@ type ReportInline = {
   type: 'math';
   id: string;
   latex: string;
+  plainText?: PlainMathRun[];
 } | {
   type: 'ref';
   id: string;
@@ -29,6 +30,11 @@ type ReportInline = {
 } | {
   type: 'break';
 };
+/** 行内公式在 Word 里写成文字时的一段：网页仍按 latex 显示，Word 照这些文字与标记写，不插 MathType */
+interface PlainMathRun {
+  text: string;
+  marks?: ('em' | 'sub' | 'sup')[];
+}
 interface Paragraph {
   type: 'paragraph';
   id: string;
@@ -194,4 +200,4 @@ declare class ReportContentError extends Error {
   constructor(message: string, file?: string, pointer?: string);
 }
 //#endregion
-export { SingleImageFigure as C, TableCell as E, Section as S, Table as T, ReportContentError as _, CellBlock as a, ReportInline as b, ContentWarning as c, FigurePanel as d, Include as f, ReportBlock as g, Paragraph as h, Bibliography as i, Equation as l, MultiImageFigure as m, AssemblyOptions as n, Code as o, IndexEntry as p, AssemblyResult as r, CompiledReport as s, Abstract as t, Figure as u, ReportDocument as v, SourceLocation as w, ReportList as x, ReportIndex as y };
+export { Section as C, TableCell as D, Table as E, ReportList as S, SourceLocation as T, ReportBlock as _, CellBlock as a, ReportIndex as b, ContentWarning as c, FigurePanel as d, Include as f, PlainMathRun as g, Paragraph as h, Bibliography as i, Equation as l, MultiImageFigure as m, AssemblyOptions as n, Code as o, IndexEntry as p, AssemblyResult as r, CompiledReport as s, Abstract as t, Figure as u, ReportContentError as v, SingleImageFigure as w, ReportInline as x, ReportDocument as y };

package/engine/README.md

@@ -1,6 +1,6 @@
 # Word report engine
 
-正式 Word COM / MathType 引擎迁入本仓。来源、提交与每份原始文件的 SHA-256 见 `migration-provenance.json`。仅迁入源仓已提交基线，未迁入源仓未提交代码、probe、旧运行输出或虚拟环境。Python 包版本仍为 0.0.1，依赖版本保持来源固定值。
+正式 Word COM / MathType 引擎迁入本仓。来源、提交与每份原始文件的 SHA-256 见仓根 `probes/2610131513_word-report-migration-baseline/migration-provenance.json`。仅迁入源仓已提交基线，未迁入源仓未提交代码、probe、旧运行输出或虚拟环境。Python 包版本仍为 0.0.1，依赖版本保持来源固定值。
 
 ## 环境
 
@@ -34,8 +34,8 @@
 
 ## 迁入回归
 
-2026-10-13 的证据摘要见 `migration-verification.json`：23 个 Python 单测与依赖检查通过；原 demo 经迁入代码重新生成 12 页 DOCX/PDF，6 个 MathType 保存重开、5 张表、2 张源图片、正文、域引用和临时编号增删检查通过，模板哈希未变。页面显示仍待用户检查。
+2026-10-13 的证据在仓根 `probes/2610131513_word-report-migration-baseline/`，摘要是其中的 `migration-verification.json`：23 个 Python 单测与依赖检查通过；原 demo 经迁入代码重新生成 12 页 DOCX/PDF，6 个 MathType 保存重开、5 张表、2 张源图片、正文、域引用和临时编号增删检查通过，模板哈希未变。页面显示仍待用户检查。
 
-首次运行在 `out/migration-baseline-20261013-01` 留下失败记录：已提交基线的链接锚点保留 `@LINK0@`。迁入包显式替换锚点文字后，在全新目录 `out/migration-baseline-20261013-02` 重新生成并通过自动验收；没有使用源仓未提交的修补代码。
+首次运行（同一目录的 `runs/migration-baseline-20261013-01`）留下失败记录：已提交基线的链接占位文字 `@LINK0@` 没被替换。迁入包显式替换占位文字后，在全新目录（`runs/migration-baseline-20261013-02`）重新生成并通过自动验收；没有使用源仓未提交的修补代码。
 
 独立 CLI 回归时，MathType 将读回文本的外层 `$...$` 换成了 `\[...\]`，旧校验错误地判定公式变化。当前只规范化一对外层数学分隔符，内部 TeX 仍逐字比较；不会改写公式、改 MathType 全局设置或忽略内容差异。对应回归同时检查错误公式与不匹配分隔符仍被拒绝。

package/engine/schemas/report-content.schema.json

@@ -143,6 +143,48 @@
         "latex": {
           "type": "string",
           "minLength": 1
+        },
+        "plainText": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Word writes these runs as text instead of a MathType object; the web view still renders latex.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "text": {
+                "$ref": "#/$defs/line"
+              },
+              "marks": {
+                "type": "array",
+                "items": {
+                  "enum": [
+                    "em",
+                    "sub",
+                    "sup"
+                  ]
+                },
+                "uniqueItems": true,
+                "not": {
+                  "allOf": [
+                    {
+                      "contains": {
+                        "const": "sub"
+                      }
+                    },
+                    {
+                      "contains": {
+                        "const": "sup"
+                      }
+                    }
+                  ]
+                }
+              }
+            },
+            "required": [
+              "text"
+            ],
+            "additionalProperties": false
+          }
         }
       },
       "required": [

package/engine/src/docreport/__main__.py

@@ -16,6 +16,7 @@ from types import SimpleNamespace
 from .content import read_json, validate_content, validate_layout
 from .compose import ContentComposer
 from .mathtype import DEFAULT_DLL, fill_and_reopen, validate_pending
+from .plain_math import clear_east_asian_hints
 from .verify import document_state, package_state, pdf_state, sha, content_state, abstract_state
 from .word import opened_document, refresh, word_application
 
@@ -114,9 +115,18 @@ def build(directory, output, dll=DEFAULT_DLL, *, data_only=False, layout_path=No
     evidence = dict(status="running", startedAt=datetime.now(timezone.utc).isoformat(),
                     report=str(directory), visualReview="pending", events=[])
 
+    # Rewriting the whole record per event is quadratic: a report with 858 equations logs ~3500 events.
+    last_written = [0.0]
+
+    def persist():
+        write_json(output / "verification.json", evidence)
+        last_written[0] = time.perf_counter()
+
     def record(event, **values):
+        values.setdefault('elapsedSeconds', round(time.perf_counter() - started, 3))
         evidence["events"].append(dict(event=event, **values))
-        write_json(output / "verification.json", evidence)
+        if time.perf_counter() - last_written[0] >= 2:
+            persist()
         print(json.dumps(dict(event=event, **values), ensure_ascii=True), flush=True)
 
     manifest = dict(report=str(directory), inputs=inputs,
@@ -142,10 +152,12 @@ def build(directory, output, dll=DEFAULT_DLL, *, data_only=False, layout_path=No
             manifest["environment"]["word"] = dict(version=word.Version, build=word.Build)
             doc = word.Documents.Add(Template=str(template), NewTemplate=False)
             doc.UpdateStylesOnOpen = False
+            record("compose-start")
             pending = module.build(doc, content, output)
             validate_pending(pending)
             doc.SaveAs2(str(draft), 16, AddToRecentFiles=False)
             record("draft-saved", equations=len(pending))
+        record("inline-math-hints-cleared", runs=clear_east_asian_hints(draft))
 
         if pending:
             fill_and_reopen(draft, destination, pending, record, dll.resolve())
@@ -156,16 +168,19 @@ def build(directory, output, dll=DEFAULT_DLL, *, data_only=False, layout_path=No
             with opened_document(word, destination) as doc:
                 refresh(doc)
                 doc.Save()
+            # Checks and the PDF read the field results as saved; refreshing again here would hide a stale save.
             with opened_document(word, destination, True) as doc:
-                refresh(doc)
                 generic = document_state(doc, len(pending))
                 record("document-check", **generic)
                 if content.get('format') == 'docreport':
                     abstracts = abstract_state(doc, content)
                     if abstracts:
                         record('abstract-check', abstracts=abstracts)
+                record("report-check-start")
                 record("report-check", result=module.validate(doc, content))
+                record("pdf-export-start")
                 doc.ExportAsFixedFormat(str(destination.with_suffix(".pdf")), 17)
+                record("pdf-export-finished")
             saved_hash = sha(destination)
             if callable(getattr(module, "validate_editing", None)):
                 with opened_document(word, destination, True) as doc:
@@ -195,6 +210,7 @@ def build(directory, output, dll=DEFAULT_DLL, *, data_only=False, layout_path=No
         record("exception", detail=traceback.format_exc())
         raise
     finally:
+        persist()
         write_json(output / "manifest.json", manifest)