@godcreator/word-report 0.1.0 → 0.3.1

package/README.md

@@ -4,7 +4,6 @@
 
 文档站平台、按功能划分的功能包，以及两个 gwb 工作台插件。任何站点都是「fumadocs 官方 React Router 模板 + 挑选的功能包」：
 平台包 `@godcreator/god-docsite` 带唯一的站点模板与建站器，功能包各自经 fumadocs 与 React Router 原生的扩展点接入站点。
-仓正在重构，设计未定，以代码和 `AGENTS.md` 为准。
 
 | 包（`packages/`） | 做什么 |
 | --- | --- |
@@ -46,7 +45,7 @@ pnpm doc:render                                # 只重新生成生成物
 
 ## 文档在哪
 
-`docs-site/` 是全仓唯一的文档站：总览、fumadocs 原理、写页面、Gitea 与 NAS、维护。轨迹卡在 `docs-site/trajectory/`。
+`docs-site/` 是全仓唯一的文档站：总览、建站与写页面、包（一个包一页）、插件、Gitea 与 NAS、维护、背景（fumadocs 原理）。轨迹卡在 `docs-site/trajectory/`。
 随插件发布的说明书正本在 `docs-site/content/docs/outputs/skills/`，生成到 `plugins/docsite/skills/` 与 `plugins/collab/skills/`。
 
 **这份 README 与仓根 `CLAUDE.md` 是生成物**（正本在 `docs-site/content/docs/outputs/`），`AGENTS.md` 手写；改 mdx 正本再在 `docs-site/` 里 `pnpm doc:render`。
@@ -59,8 +58,8 @@ pnpm build          # 按依赖序构建全部包、两个插件与各站
 pnpm check          # 逐个包跑 check（typecheck、快的一级测试，有 lint 的再 lint），一分钟左右
 pnpm test:slow      # 慢的一级测试（各包的 *.slow.test.ts：真建站、大量调 git 的），只在显式要求时跑，近三分钟
 pnpm test:deps      # 包之间的依赖方向、包内分层、模块之间不许有环（规则在 tests/dependency-rules.cjs，要先 pnpm build）
-pnpm verify         # 最终交付之前（推送、交给人验收、发版前）：build → check → test:slow → test:deps → test:scaffold → test:e2e
-pnpm test:pack      # 发版前再跑：把包打成 tarball 装进测试站的副本，跑同样的端到端检查
+pnpm verify         # 全量：build → check → test:slow → test:deps → test:scaffold → test:e2e；只在升共用依赖时跑，平时看改到了什么只跑相关的几项（见 AGENTS.md）
+pnpm test:pack      # 把包打成 tarball 装进测试站的副本，跑同样的端到端检查；改了包的 exports、files、依赖时跑
 
 cd docs-site
 pnpm doc

package/dist/{assemble-Czu-J7tB.mjs → assemble-3cx8L2vo.mjs}

@@ -371,13 +371,90 @@ const schema = {
 					"$ref": "#/$defs/inlines",
 					"minItems": 1
 				},
-				"alt": { "$ref": "#/$defs/line" }
+				"alt": { "$ref": "#/$defs/line" },
+				"rows": {
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 6
+				},
+				"columns": {
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 6
+				},
+				"panels": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/figurePanel" },
+					"minItems": 2,
+					"maxItems": 36
+				}
 			},
 			"required": [
 				"type",
 				"id",
+				"caption"
+			],
+			"additionalProperties": false,
+			"allOf": [
+				{
+					"if": { "required": ["panels"] },
+					"then": { "required": ["rows", "columns"] }
+				},
+				{
+					"if": { "required": ["panels"] },
+					"then": { "not": { "required": ["src"] } }
+				},
+				{
+					"if": { "required": ["panels"] },
+					"then": { "not": { "required": ["alt"] } }
+				},
+				{
+					"if": { "not": { "required": ["panels"] } },
+					"then": { "required": ["src", "alt"] }
+				},
+				{
+					"if": { "not": { "required": ["panels"] } },
+					"then": { "not": { "required": ["rows"] } }
+				},
+				{
+					"if": { "not": { "required": ["panels"] } },
+					"then": { "not": { "required": ["columns"] } }
+				}
+			],
+			"description": "A single image (src, alt) or several images under one figure number (rows, columns, panels). Each panel names its own grid cell and label; cells nobody names stay empty. Cells inside the grid, one panel per cell and unique labels are semantic checks."
+		},
+		"figurePanel": {
+			"type": "object",
+			"properties": {
+				"id": { "$ref": "#/$defs/id" },
+				"row": {
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 6
+				},
+				"column": {
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 6
+				},
+				"label": {
+					"type": "string",
+					"pattern": "^[^\\s()（）]{1,8}$",
+					"description": "Shown under the image as (label) and in references as figure number + (label); written without parentheses."
+				},
+				"src": { "$ref": "#/$defs/assetPath" },
+				"alt": { "$ref": "#/$defs/line" },
+				"caption": {
+					"$ref": "#/$defs/inlines",
+					"minItems": 1
+				}
+			},
+			"required": [
+				"id",
+				"row",
+				"column",
+				"label",
 				"src",
-				"caption",
 				"alt"
 			],
 			"additionalProperties": false
@@ -675,8 +752,10 @@ function shape(value, rule, pointer, file) {
 		if (rule.format === "date" && (Number.isNaN(Date.parse(value)) || new Date(value).toISOString().slice(0, 10) !== value)) fail("Invalid calendar date");
 	}
 	if (typeof value === "number" && rule.minimum !== void 0 && value < rule.minimum) fail(`Minimum is ${rule.minimum}`);
+	if (typeof value === "number" && rule.maximum !== void 0 && value > rule.maximum) fail(`Maximum is ${rule.maximum}`);
 	if (Array.isArray(value)) {
-		if (rule.minItems && value.length < rule.minItems) fail("Array must not be empty");
+		if (rule.minItems && value.length < rule.minItems) fail(rule.minItems === 1 ? "Array must not be empty" : `At least ${rule.minItems} items`);
+		if (rule.maxItems && value.length > rule.maxItems) fail(`At most ${rule.maxItems} items`);
 		if (rule.uniqueItems && new Set(value.map(stableValue)).size !== value.length) fail("Duplicate array values");
 		if (rule.items) value.forEach((v, i) => shape(v, rule.items, `${pointer}/${i}`, file));
 		if (rule.contains && !value.some((v) => {
@@ -767,6 +846,23 @@ function assembleDocument(entry, files, options = {}) {
 	const pending = /* @__PURE__ */ new Map();
 	const resourceNames = /* @__PURE__ */ new Map();
 	let rootBibliography;
+	/** 图片路径改成按文档 id 分开的 assets/<文档 id>/…，同名的章节图片不互相覆盖 */
+	function registerAsset(image, file, srcPointer) {
+		try {
+			safeRelativePath(image.src, true);
+		} catch (e) {
+			throw new ReportContentError(e.message, file, srcPointer);
+		}
+		const original = join(file, image.src);
+		const output = `assets/${documents.get(file).id}/${image.src.slice(7)}`;
+		for (const resource of [original, output]) {
+			const key = resource.normalize("NFC").toLowerCase(), previous = resourceNames.get(key);
+			if (previous && previous !== resource) throw new ReportContentError("Asset names collide on Windows", file, srcPointer);
+			resourceNames.set(key, resource);
+		}
+		assets[output] = original;
+		image.src = output;
+	}
 	function register(value, file, prefix) {
 		for (const { node, pointer } of walk(value, prefix)) {
 			if (node.id !== void 0) {
@@ -778,20 +874,8 @@ function assembleDocument(entry, files, options = {}) {
 				};
 			}
 			if (node.type === "figure") {
-				try {
-					safeRelativePath(node.src, true);
-				} catch (e) {
-					throw new ReportContentError(e.message, file, pointer + "/src");
-				}
-				const original = join(file, node.src);
-				const output = `assets/${documents.get(file).id}/${node.src.slice(7)}`;
-				for (const resource of [original, output]) {
-					const key = resource.normalize("NFC").toLowerCase(), previous = resourceNames.get(key);
-					if (previous && previous !== resource) throw new ReportContentError("Asset names collide on Windows", file, pointer + "/src");
-					resourceNames.set(key, resource);
-				}
-				assets[output] = original;
-				node.src = output;
+				const images = node.panels ? node.panels.map((panel, k) => [panel, `${pointer}/panels/${k}/src`]) : [[node, `${pointer}/src`]];
+				for (const [image, srcPointer] of images) registerAsset(image, file, srcPointer);
 			}
 		}
 	}
@@ -892,6 +976,7 @@ function assembleDocument(entry, files, options = {}) {
 			const source = sources[node.id];
 			validateTable(node, source.file, source.pointer);
 		}
+		if (node.type === "figure" && node.panels) validatePanelGrid(node, fail);
 		if (node.type === "math" || node.type === "equation") {
 			const latex = node.latex.trim();
 			if (!latex || /[^\x00-\x7f]/.test(latex) || /^(\$|\\\(|\\\[)/.test(latex) || /\\(?:tag|label|documentclass)\b|\\begin\s*\{document\}/.test(latex)) fail(node, "MathType requires nonempty ASCII TeX without delimiters or manual numbering");
@@ -964,6 +1049,15 @@ function assembleDocument(entry, files, options = {}) {
 				label,
 				title
 			};
+			if (node.type === "figure" && node.panels) for (const panel of node.panels) {
+				const panelNumber = `${number}(${panel.label})`;
+				index[panel.id] = {
+					type: "figure-panel",
+					number: panelNumber,
+					label: `图 ${panelNumber}`,
+					title: plain(panel.caption)
+				};
+			}
 			if (node.type === "table") {
 				if (tables >= 6) fail(node, "At most six table levels");
 				for (const row of node.rows) for (const cell of row.cells) blockNumbers(cell.blocks, depth, chapter, parentNumber, parentMode, tables + 1);
@@ -1033,6 +1127,11 @@ function assembleDocument(entry, files, options = {}) {
 					}
 					fail(node, `Unknown reference target: ${node.target}`);
 				}
+				if (index[node.target]?.type === "figure-panel") {
+					if (node.display === "title" && (!target.caption?.length || target.caption.some((x) => !["text", "break"].includes(x.type)))) fail(node, "Title reference requires plain caption");
+					delete node.externalLabel;
+					continue;
+				}
 				if (![
 					"section",
 					"figure",
@@ -1065,6 +1164,18 @@ function assembleDocument(entry, files, options = {}) {
 		warnings
 	};
 }
+/** 多图的每张都要在 rows × columns 的网格里、一格只放一张、编号不重复 */
+function validatePanelGrid(figure, fail) {
+	const occupied = /* @__PURE__ */ new Map(), labels = /* @__PURE__ */ new Map();
+	for (const panel of figure.panels) {
+		if (panel.row > figure.rows || panel.column > figure.columns) fail(panel, `Panel cell row ${panel.row}, column ${panel.column} is outside the ${figure.rows} x ${figure.columns} grid of ${figure.id}`);
+		const cell = `${panel.row},${panel.column}`;
+		if (occupied.has(cell)) fail(panel, `Panel shares row ${panel.row}, column ${panel.column} with ${occupied.get(cell)}`);
+		if (labels.has(panel.label)) fail(panel, `Panel label (${panel.label}) is also used by ${labels.get(panel.label)}`);
+		occupied.set(cell, panel.id);
+		labels.set(panel.label, panel.id);
+	}
+}
 function alphabet(n) {
 	let s = "";
 	while (n > 0) {
@@ -1075,4 +1186,4 @@ function alphabet(n) {
 	return s;
 }
 //#endregion
-export { ReportContentError as a, parseReportJson as i, safeRelativePath as n, validateDocument as r, assembleDocument as t };
+export { parseReportJson as a, walk as i, safeRelativePath as n, ReportContentError as o, validateDocument as r, assembleDocument as t };

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { n as ReportExportResult, o as ReportCheckResult, t as ReportExportOptions } from "./export-Bi5yS3GW.mjs";
+import { n as ReportExportResult, o as ReportCheckResult, t as ReportExportOptions } from "./export-DC764Umz.mjs";
 //#region src/node/cli.d.ts
 type CliCommand = {
   command: 'export' | 'status';

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { n as reportExport, r as checkReports } from "./export-BdwmhUIp.mjs";
-import { r as reportEntryOf } from "./report-files-DwLdh0QQ.mjs";
+import { n as reportExport, r as checkReports } from "./export-TbclsIsE.mjs";
+import { r as reportEntryOf } from "./report-files-DM9Ea6yK.mjs";
 import path from "node:path";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";

package/dist/core.d.mts

@@ -1,4 +1,4 @@
-import { C as TableCell, S as Table, _ as ReportIndex, a as CellBlock, b as Section, c as ContentWarning, d as Include, f as IndexEntry, g as ReportDocument, h as ReportContentError, i as Bibliography, l as Equation, m as ReportBlock, n as AssemblyOptions, o as Code, p as Paragraph, r as AssemblyResult, s as CompiledReport, t as Abstract, u as Figure, v as ReportInline, x as SourceLocation, y as ReportList } from "./types-BYcLlSjZ.mjs";
+import { C as SingleImageFigure, E as TableCell, S as Section, T as Table, _ as ReportContentError, a as CellBlock, b as ReportInline, c as ContentWarning, d as FigurePanel, f as Include, g as ReportBlock, h as Paragraph, i as Bibliography, l as Equation, m as MultiImageFigure, n as AssemblyOptions, o as Code, p as IndexEntry, r as AssemblyResult, s as CompiledReport, t as Abstract, u as Figure, v as ReportDocument, w as SourceLocation, x as ReportList, y as ReportIndex } from "./types-Bcl48xQN.mjs";
 //#region src/core/assemble.d.ts
 declare function assembleDocument(entry: string, files: Record<string, string | ReportDocument>, options?: AssemblyOptions): AssemblyResult;
 //#endregion
@@ -10,4 +10,4 @@ declare function parseReportJson(text: string, file?: string): unknown;
 declare function validateDocument(value: unknown, file?: string): asserts value is ReportDocument;
 declare function safeRelativePath(raw: string, asset?: boolean): string;
 //#endregion
-export { Abstract, AssemblyOptions, AssemblyResult, Bibliography, CellBlock, Code, CompiledReport, ContentWarning, Equation, Figure, Include, IndexEntry, Paragraph, ReportBlock, ReportContentError, ReportDocument, ReportIndex, ReportInline, ReportList, Section, SourceLocation, Table, TableCell, assembleDocument, parseReportJson, safeRelativePath, validateDocument };
+export { Abstract, AssemblyOptions, AssemblyResult, Bibliography, CellBlock, Code, CompiledReport, ContentWarning, Equation, Figure, FigurePanel, Include, IndexEntry, MultiImageFigure, Paragraph, ReportBlock, ReportContentError, ReportDocument, ReportIndex, ReportInline, ReportList, Section, SingleImageFigure, SourceLocation, Table, TableCell, assembleDocument, parseReportJson, safeRelativePath, validateDocument };

package/dist/core.mjs

@@ -1 +1 @@
-export { a as ReportContentError, t as assembleDocument, i as parseReportJson, n as safeRelativePath, r as validateDocument } from "./assemble-Czu-J7tB.mjs";
+export { o as ReportContentError, t as assembleDocument, a as parseReportJson, n as safeRelativePath, r as validateDocument } from "./assemble-3cx8L2vo.mjs";

package/dist/{export-Bi5yS3GW.d.mts → export-DC764Umz.d.mts}

@@ -1,4 +1,4 @@
-import { c as ContentWarning } from "./types-BYcLlSjZ.mjs";
+import { c as ContentWarning } from "./types-Bcl48xQN.mjs";
 //#region src/node/check.d.ts
 interface ReportCheckDiagnostic {
   file: string;

package/dist/{export-BdwmhUIp.mjs → export-TbclsIsE.mjs}

@@ -1,5 +1,5 @@
-import { a as ReportContentError, i as parseReportJson, n as safeRelativePath, r as validateDocument, t as assembleDocument } from "./assemble-Czu-J7tB.mjs";
-import { a as reportsDirName } from "./report-files-DwLdh0QQ.mjs";
+import { a as parseReportJson, i as walk, n as safeRelativePath, o as ReportContentError, r as validateDocument, t as assembleDocument } from "./assemble-3cx8L2vo.mjs";
+import { a as reportsDirName } from "./report-files-DM9Ea6yK.mjs";
 import { access, mkdir, open, readFile, readdir, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -283,12 +283,17 @@ async function layoutOf(root, entry) {
 		value: JSON.parse(bytes.toString("utf8"))
 	};
 }
+/** Word 引擎还不会排一个图号下的多张图：报告里有多图就在启动 Word 之前拒绝 */
+function rejectMultiImageFigures(document) {
+	for (const { node } of walk(document)) if (node.type === "figure" && node.panels) throw new Error(`图 ${node.id} 是多图（panels），导出 Word 还不支持多图；网页上照常显示`);
+}
 async function capture(site, engine, compiler, entry, mode) {
 	const root = site;
 	const report = await readReport(path.join(root, entry), {
 		root,
 		mode
 	});
+	rejectMultiImageFigures(report.document);
 	const layout = await layoutOf(root, entry);
 	const engineHash = await engineFingerprint(engine, compiler);
 	return {

package/dist/node.d.mts

@@ -1,5 +1,5 @@
-import { n as AssemblyOptions, r as AssemblyResult } from "./types-BYcLlSjZ.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-Bi5yS3GW.mjs";
+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";
 //#region src/node/read-report.d.ts
 interface SnapshotEntry {
   path: string;

package/dist/node.mjs

@@ -1,3 +1,3 @@
-import { i as readReport, n as reportExport, r as checkReports, t as reportEntry } from "./export-BdwmhUIp.mjs";
-import { a as reportsDirName, i as reportIdsOf, n as readReportFiles, r as reportEntryOf, t as REPORT_ID_PATTERN } from "./report-files-DwLdh0QQ.mjs";
+import { i as readReport, n as reportExport, r as checkReports, t as reportEntry } from "./export-TbclsIsE.mjs";
+import { a as reportsDirName, i as reportIdsOf, n as readReportFiles, r as reportEntryOf, t as REPORT_ID_PATTERN } from "./report-files-DM9Ea6yK.mjs";
 export { REPORT_ID_PATTERN, checkReports, readReport, readReportFiles, reportEntry, reportEntryOf, reportExport, reportIdsOf, reportsDirName };

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

@@ -1,4 +1,5 @@
-import { r as AssemblyResult } from "./types-BYcLlSjZ.mjs";
+import { r as AssemblyResult } from "./types-Bcl48xQN.mjs";
+import { CommentsAccess, PageThreadSummary } from "@godcreator/comments/site";
 //#region src/site/page-data.d.ts
 /** 报告列表里的一行：报告读不对时 problem 是原话，标题退回报告 id */
 type ReportSummary = {
@@ -24,16 +25,22 @@ type ReportTocItem = {
   url: string;
   depth: number;
 };
+/** 报告页上的评论：归属这一页的评论串，以及本机身份能不能写 */
+type ReportPageComments = {
+  threads: PageThreadSummary[];
+  access: CommentsAccess;
+};
 type ReportPageData = {
   siteName: string;
   hrefBase: string;
   reportId: string;
   report: AssemblyResult;
   toc: ReportTocItem[];
+  comments: ReportPageComments;
 };
 /** 报告页地址 */
 declare const reportHrefOf: (hrefBase: string, reportId: string) => string;
 /** 报告里一张图的地址：组装后图的路径是 assets/<文档 id>/<文件名>，挂在报告页地址下面 */
 declare const reportAssetHrefOf: (hrefBase: string, reportId: string, compiledPath: string) => string;
 //#endregion
-export { reportAssetHrefOf as a, ReportTocItem as i, ReportPageData as n, reportHrefOf as o, ReportSummary as r, ReportListData as t };
+export { ReportTocItem as a, ReportSummary as i, ReportPageComments as n, reportAssetHrefOf as o, ReportPageData as r, reportHrefOf as s, ReportListData as t };

package/dist/page-data-DLPoVgXy.mjs

@@ -0,0 +1,7 @@
+//#region src/site/page-data.ts
+/** 报告页地址 */
+const reportHrefOf = (hrefBase, reportId) => `${hrefBase}/${reportId}`;
+/** 报告里一张图的地址：组装后图的路径是 assets/<文档 id>/<文件名>，挂在报告页地址下面 */
+const reportAssetHrefOf = (hrefBase, reportId, compiledPath) => `${reportHrefOf(hrefBase, reportId)}/${compiledPath}`;
+//#endregion
+export { reportHrefOf as n, reportAssetHrefOf as t };

package/dist/{report-files-DwLdh0QQ.mjs → report-files-DM9Ea6yK.mjs}

@@ -1,4 +1,4 @@
-import { a as ReportContentError, i as parseReportJson, n as safeRelativePath, r as validateDocument } from "./assemble-Czu-J7tB.mjs";
+import { a as parseReportJson, n as safeRelativePath, o as ReportContentError, r as validateDocument } from "./assemble-3cx8L2vo.mjs";
 import { readFile, readdir, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 //#region src/node/report-files.ts

package/dist/site-server.d.mts

@@ -1,20 +1,28 @@
-import { i as ReportTocItem, n as ReportPageData, r as ReportSummary, t as ReportListData } from "./page-data-UaiHPCZA.mjs";
+import { a as ReportTocItem, i as ReportSummary, n as ReportPageComments, r as ReportPageData, t as ReportListData } from "./page-data-CJ6nCBnW.mjs";
 //#region src/site/loaders.server.d.ts
-/** 报告功能的站点信息：站点目录（报告在它的 reports/ 下）、站名、报告页的地址前缀 */
+/**
+ * 报告功能的站点信息：站点目录（报告在它的 reports/ 下）、站名、报告页的地址前缀，
+ * 以及按评论归属键取一页评论的函数（报告页的归属键是它的地址，如 /reports/sample）
+ */
 type WordReportSite = {
   siteDir: string;
   siteName: string;
   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 ReportPageData, ReportRouteArgs, type ReportSummary, type ReportTocItem, WordReportSite, reportAssetLoader, reportListLoader, reportPageLoader };
+export { type ReportListData, type ReportPageComments, type ReportPageData, ReportRouteArgs, type ReportSummary, type ReportTocItem, WordReportSite, reportAssetLoader, reportListLoader, reportPageLoader };

package/dist/site-server.mjs

@@ -1,17 +1,60 @@
-import { t as assembleDocument } from "./assemble-Czu-J7tB.mjs";
-import { i as reportIdsOf, n as readReportFiles, r as reportEntryOf, t as REPORT_ID_PATTERN } from "./report-files-DwLdh0QQ.mjs";
+import { t as assembleDocument } from "./assemble-3cx8L2vo.mjs";
+import { i as reportIdsOf, n as readReportFiles, r as reportEntryOf, t as REPORT_ID_PATTERN } from "./report-files-DM9Ea6yK.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/ 现读，
+* 报告页与图片在 JSON 原文没变时沿用上一次的组装结果。
 */
 /** 组装结果里有 Object.create(null) 的对象：换成普通对象再交给 React Router 序列化 */
 const plainOf = (result) => JSON.parse(JSON.stringify(result));
-async function assembledReport(siteDir, reportId) {
+/**
+* 每份报告最近一次组装，键是站点目录加报告 id。一页报告的几十张图同时请求，组装一次要几百毫秒到几秒、
+* 全在一个线程上排队：不共用的话，最后一张图要等几十次组装
+*/
+const latestAssemblies = /* @__PURE__ */ new Map();
+async function assembleFromDisk(siteDir, reportId) {
 	const entry = reportEntryOf(reportId);
-	return assembleDocument(entry, await readReportFiles(siteDir, entry), { mode: "complete" });
+	const files = await readReportFiles(siteDir, entry);
+	return {
+		files,
+		result: assembleDocument(entry, files, { mode: "complete" })
+	};
+}
+/** 上次组装读过的每个 JSON 文件原文都没变；文件没了也算变了，交给重新组装去报错 */
+async function sameFilesOnDisk(siteDir, files) {
+	const root = await realpath(siteDir);
+	return (await Promise.all(Object.entries(files).map(async ([relative, text]) => {
+		try {
+			return await readFile(path.join(root, relative), "utf8") === text;
+		} catch (error) {
+			if (error.code === "ENOENT") return false;
+			throw error;
+		}
+	}))).every(Boolean);
+}
+/** 报告的整份组装结果：JSON 原文和上次一样就用上次的，同时到的请求共用同一次组装；结果只读，要改先复制 */
+async function assembledReport(siteDir, reportId) {
+	const key = `${path.resolve(siteDir)}\0${reportId}`;
+	const latest = latestAssemblies.get(key);
+	if (latest !== void 0) {
+		const assembly = await latest;
+		if (await sameFilesOnDisk(siteDir, assembly.files)) return assembly.result;
+	}
+	const newer = latestAssemblies.get(key);
+	if (newer !== void 0 && newer !== latest) return (await newer).result;
+	const fresh = assembleFromDisk(siteDir, reportId);
+	latestAssemblies.set(key, fresh);
+	try {
+		return (await fresh).result;
+	} catch (error) {
+		if (latestAssemblies.get(key) === fresh) latestAssemblies.delete(key);
+		throw error;
+	}
 }
 /** 地址里的报告 id：形状不对或站点里没有这份报告都是 404 */
 async function reportIdOf(params, siteDir) {
@@ -78,7 +121,8 @@ async function reportPageLoader({ params }, site) {
 		hrefBase: site.hrefBase,
 		reportId,
 		report: result,
-		toc: tocOf(result)
+		toc: tocOf(result),
+		comments: site.pageComments(reportHrefOf(site.hrefBase, reportId))
 	};
 }
 const imageContentTypes = {
@@ -86,15 +130,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,8 +1,17 @@
-import { g as ReportDocument, r as AssemblyResult } from "./types-BYcLlSjZ.mjs";
-import { a as reportAssetHrefOf, i as ReportTocItem, n as ReportPageData, o as reportHrefOf, r as ReportSummary, t as ReportListData } from "./page-data-UaiHPCZA.mjs";
+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 { CommentAvatar, CommentBodyComponent } from "@godcreator/comments/site";
 //#region src/site/report-pages.d.ts
 declare function ReportListPage(): import("react").JSX.Element;
-declare function ReportDocumentPage(): import("react").JSX.Element;
+interface ReportDocumentPageProps {
+  /** 评论表单提交到的地址：站点的评论写入路由（comments 功能的 /comments） */
+  commentAction: string;
+  /** 站点的评论正文组件与头像组件（站点 app/lib/content 里的 CommentBody、commentAvatar） */
+  CommentBody: CommentBodyComponent;
+  AvatarComponent?: CommentAvatar;
+}
+/** 报告页：正文是评论范围，右下角是本页评论；评论归属键是报告页的地址 */
+declare function ReportDocumentPage({ commentAction, CommentBody, AvatarComponent }: ReportDocumentPageProps): import("react").JSX.Element;
 //#endregion
 //#region src/site/report-view.d.ts
 type AssetUrl = (sourcePath: string, compiledPath: string) => string;
@@ -29,4 +38,4 @@ declare function reportMeta(input: ReportDocument | AssemblyResult): {
   markdown: string;
 };
 //#endregion
-export { type AssetUrl, ReportDocumentPage, type ReportListData, ReportListPage, ReportPage, type ReportPageData, type ReportPageProps, type ReportSummary, type ReportTocItem, ReportView, type ReportViewProps, reportAssetHrefOf, reportHrefOf, reportMeta };
+export { type AssetUrl, ReportDocumentPage, type ReportDocumentPageProps, type ReportListData, ReportListPage, ReportPage, type ReportPageComments, type ReportPageData, type ReportPageProps, type ReportSummary, type ReportTocItem, ReportView, type ReportViewProps, reportAssetHrefOf, reportHrefOf, reportMeta };

package/dist/site.mjs

@@ -1,15 +1,11 @@
-import { t as assembleDocument } from "./assemble-Czu-J7tB.mjs";
+import { t as assembleDocument } from "./assemble-3cx8L2vo.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";
+import { CommentsDock, commentScopeProps } from "@godcreator/comments/site";
 import { Fragment } from "react";
 import katex from "katex";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
-//#region src/site/page-data.ts
-/** 报告页地址 */
-const reportHrefOf = (hrefBase, reportId) => `${hrefBase}/${reportId}`;
-/** 报告里一张图的地址：组装后图的路径是 assets/<文档 id>/<文件名>，挂在报告页地址下面 */
-const reportAssetHrefOf = (hrefBase, reportId, compiledPath) => `${reportHrefOf(hrefBase, reportId)}/${compiledPath}`;
-//#endregion
 //#region src/site/report-view.tsx
 function RenderError({ children }) {
 	return /* @__PURE__ */ jsx("div", {
@@ -182,19 +178,56 @@ function ReportView({ report, assetUrl }) {
 				})]
 			}, node.id);
 			case "figure": {
-				const source = report.assets[node.src] ?? node.src;
+				const image = (src, id, alt) => {
+					const source = report.assets[src] ?? src;
+					return /* @__PURE__ */ jsx("img", {
+						id,
+						src: assetUrl?.(source, src) ?? source,
+						alt,
+						loading: "lazy"
+					});
+				};
+				const caption = /* @__PURE__ */ jsxs("figcaption", {
+					id: `${node.id}-caption`,
+					children: [label?.number && /* @__PURE__ */ jsxs("span", { children: [label.label, " "] }), inlines(node.caption)]
+				});
+				if (!node.panels) return /* @__PURE__ */ jsxs("figure", {
+					"data-report-source": origin?.file,
+					"data-report-pointer": origin?.pointer,
+					children: [image(node.src, node.id, node.alt), caption]
+				}, node.id);
 				return /* @__PURE__ */ jsxs("figure", {
+					className: "report-multi-figure",
 					"data-report-source": origin?.file,
 					"data-report-pointer": origin?.pointer,
-					children: [/* @__PURE__ */ jsx("img", {
+					children: [/* @__PURE__ */ jsx("div", {
 						id: node.id,
-						src: assetUrl?.(source, node.src) ?? source,
-						alt: node.alt,
-						loading: "lazy"
-					}), /* @__PURE__ */ jsxs("figcaption", {
-						id: `${node.id}-caption`,
-						children: [label?.number && /* @__PURE__ */ jsxs("span", { children: [label.label, " "] }), inlines(node.caption)]
-					})]
+						className: "report-panels",
+						style: {
+							gridTemplateColumns: `repeat(${node.columns}, minmax(0, 1fr))`,
+							gridTemplateRows: `repeat(${node.rows}, auto)`
+						},
+						children: node.panels.map((panel) => /* @__PURE__ */ jsxs("div", {
+							className: "report-panel",
+							style: {
+								gridRow: panel.row,
+								gridColumn: panel.column
+							},
+							children: [/* @__PURE__ */ jsx("div", {
+								className: "report-panel-image",
+								children: image(panel.src, panel.id, panel.alt)
+							}), /* @__PURE__ */ jsxs("div", {
+								id: `${panel.id}-caption`,
+								className: "report-panel-caption",
+								children: [
+									"(",
+									panel.label,
+									")",
+									panel.caption && /* @__PURE__ */ jsxs(Fragment$1, { children: [" ", inlines(panel.caption)] })
+								]
+							})]
+						}, panel.id))
+					}), caption]
 				}, node.id);
 			}
 			case "code": return /* @__PURE__ */ jsx("pre", {
@@ -340,15 +373,16 @@ function ReportListPage() {
 		}) })
 	] });
 }
-function ReportDocumentPage() {
-	const { report, toc, reportId, siteName, hrefBase } = useLoaderData();
+/** 报告页：正文是评论范围，右下角是本页评论；评论归属键是报告页的地址 */
+function ReportDocumentPage({ commentAction, CommentBody, AvatarComponent }) {
+	const { report, toc, reportId, siteName, hrefBase, comments } = useLoaderData();
 	const { metadata } = report.document;
 	const metaLine = [
 		metadata.revision,
 		metadata.date,
 		metadata.authors?.join("、")
 	].filter((part) => part !== void 0 && part !== "");
-	return /* @__PURE__ */ jsxs(DocsPage, {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs(DocsPage, {
 		toc,
 		children: [
 			/* @__PURE__ */ jsx("title", { children: `${metadata.title} · ${siteName}` }),
@@ -362,12 +396,22 @@ function ReportDocumentPage() {
 				to: hrefBase,
 				children: "← 全部报告"
 			}),
-			/* @__PURE__ */ jsx(DocsBody, { children: /* @__PURE__ */ jsx(ReportView, {
-				report,
-				assetUrl: (_source, compiledPath) => reportAssetHrefOf(hrefBase, reportId, compiledPath)
-			}) })
+			/* @__PURE__ */ jsx(DocsBody, {
+				...commentScopeProps,
+				children: /* @__PURE__ */ jsx(ReportView, {
+					report,
+					assetUrl: (_source, compiledPath) => reportAssetHrefOf(hrefBase, reportId, compiledPath)
+				})
+			})
 		]
-	});
+	}), /* @__PURE__ */ jsx(CommentsDock, {
+		pagePath: reportHrefOf(hrefBase, reportId),
+		action: commentAction,
+		threads: comments.threads,
+		access: comments.access,
+		BodyComponent: CommentBody,
+		...AvatarComponent !== void 0 ? { AvatarComponent } : {}
+	})] });
 }
 //#endregion
 //#region src/site/report-meta.ts
@@ -396,7 +440,7 @@ function reportMeta(input) {
 			case "abstract": return `## ${node.title ?? "摘要"}\n\n${node.paragraphs.map((p) => block(p)).join("\n\n")}\n\n关键词：${node.keywords.join("；")}`;
 			case "paragraph": return inline(node.content);
 			case "equation": return `$$\n${node.latex}\n$$${report?.index[node.id]?.number ? `\n(${report.index[node.id].number})` : ""}`;
-			case "figure": return `![${node.alt}](${node.src})\n\n${report?.index[node.id]?.label ?? ""} ${inline(node.caption)}`;
+			case "figure": return `${node.panels ? node.panels.map((panel) => `![${panel.alt}](${panel.src})\n${report?.index[panel.id]?.label ?? panel.id}${panel.caption ? " " + inline(panel.caption) : ""}`).join("\n\n") : `![${node.alt}](${node.src})`}\n\n${report?.index[node.id]?.label ?? ""} ${inline(node.caption)}`;
 			case "table": return `${node.caption ? `${report?.index[node.id]?.label ?? ""} ${inline(node.caption)}\n\n` : ""}${node.rows.map((row) => row.cells.map((cell) => cell.blocks.map((child) => block(child, depth)).join("\n")).join(" | ")).join("\n")}`;
 			case "list": return node.items.map((item, i) => `${node.ordered ? `${(node.start ?? 1) + i}.` : "-"} ${item.blocks.map((child) => block(child, depth)).join("\n")}`).join("\n");
 			case "code": return `\`\`\`${node.language}\n${node.text}\n\`\`\``;

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

@@ -51,13 +51,38 @@ interface ReportList {
     blocks: (Paragraph | ReportList)[];
   }[];
 }
-interface Figure {
+/** 多图里的一张：放在第 row 行第 column 列（从 1 起），图下显示「(label)」，caption 是写在编号后面的小标题；label 由人写，不自动编 */
+interface FigurePanel {
+  id: string;
+  row: number;
+  column: number;
+  label: string;
+  src: string;
+  alt: string;
+  caption?: ReportInline[];
+}
+interface SingleImageFigure {
   type: 'figure';
   id: string;
   src: string;
   caption: ReportInline[];
   alt: string;
+  rows?: never;
+  columns?: never;
+  panels?: never;
+}
+/** 一个图号下的多张图：rows 行 columns 列的网格，每张图写明自己的格子，没写到的格子留空；caption 是整个图的图题 */
+interface MultiImageFigure {
+  type: 'figure';
+  id: string;
+  caption: ReportInline[];
+  rows: number;
+  columns: number;
+  panels: FigurePanel[];
+  src?: never;
+  alt?: never;
 }
+type Figure = SingleImageFigure | MultiImageFigure;
 interface Equation {
   type: 'equation';
   id: string;
@@ -169,4 +194,4 @@ declare class ReportContentError extends Error {
   constructor(message: string, file?: string, pointer?: string);
 }
 //#endregion
-export { TableCell as C, Table as S, ReportIndex as _, CellBlock as a, Section as b, ContentWarning as c, Include as d, IndexEntry as f, ReportDocument as g, ReportContentError as h, Bibliography as i, Equation as l, ReportBlock as m, AssemblyOptions as n, Code as o, Paragraph as p, AssemblyResult as r, CompiledReport as s, Abstract as t, Figure as u, ReportInline as v, SourceLocation as x, ReportList as y };
+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 };

package/engine/README.md

@@ -13,16 +13,16 @@
 .\.venv\Scripts\python.exe -m unittest discover -s tests -v
 ```
 
-## 报告包的数据入口
+## word-report 交给引擎的数据
 
-网站只用于阅读和评论。`@godcreator/docsite-reports` 的 `report-docx` CLI 与 `./export` API 先把分章内容编译成完整 `format: docreport` / `schemaVersion: 1` 文档与 `assets/`，交给以下入口。它们不依赖 gwb。`--data-only` 必须传递；这个模式不导入快照目录中的 `report.py`。未展开的文档引用不会通过正式 Schema。
+网站只用于阅读和评论。`@godcreator/word-report` 的命令行 `report-docx` 与 `./node` 出口的 `reportExport` 先把分章内容编译成完整 `format: docreport` / `schemaVersion: 1` 文档与 `assets/`，交给以下入口。它们不依赖 gwb。`--data-only` 必须传递；这个模式不导入快照目录中的 `report.py`。未展开的文档引用不会通过正式 Schema。
 
 ```powershell
 .\.venv\Scripts\python.exe -m docreport validate <快照目录> --data-only
 .\.venv\Scripts\python.exe -m docreport build <快照目录> --data-only --out out\<新的运行目录>
 ```
 
-需要版式数据时，可加 `--layout <layout.json>`，内容为已有 `validate_layout` 支持的节点 ID 字典：段落样式、图片宽度、表格列宽与行高、顶层章节起页与方向。默认采用 `templates/project-report.dotx`。报告包的 CLI/API 不接受任意 Python 布局程序。
+需要版式数据时，可加 `--layout <layout.json>`，内容为已有 `validate_layout` 支持的节点 ID 字典：段落样式、图片宽度、表格列宽与行高、顶层章节起页与方向。默认采用 `templates/project-report.dotx`。word-report 的命令行与 `reportExport` 不接受任意 Python 布局程序。
 
 已有 demo 保留其受信任的 `report.py` 与原入口，用于原有版式和专属验收回归：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godcreator/word-report",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "author": {
     "name": "godcreator"
   },
@@ -42,6 +42,7 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@godcreator/comments": "^0.1.3",
     "sharp": "^0.35.5"
   },
   "peerDependencies": {

package/styles/report.css

@@ -6,6 +6,12 @@
 .report-document figure { margin: 1.5rem 0; text-align: center; }
 .report-document img { margin: 0 auto; max-width: 100%; height: auto; }
 .report-document figcaption, .report-document caption { color: var(--color-fd-muted-foreground); font-size: .9em; }
+/* 多图：行列由报告写定（网格与每张的格子写在元素的 style 上），各列等宽、没写到的格子留空，任何宽度都不重排；同一行里图片上下居中、(a)(b) 对齐在同一条线上 */
+.report-panels { display: grid; gap: .75rem 1rem; }
+.report-panel { min-width: 0; display: flex; flex-direction: column; }
+.report-panel-image { flex: 1; display: flex; align-items: center; justify-content: center; }
+.report-panel-caption { margin-top: .25rem; font-size: .9em; color: var(--color-fd-muted-foreground); }
+.report-multi-figure > figcaption { margin-top: .5rem; }
 .report-document .report-equation { display: flex; align-items: center; gap: 1rem; margin: 1.25rem 0; }
 .report-math-block { display: block; flex: 1; min-width: 0; overflow-x: auto; overflow-y: hidden; padding: .5em 0; }
 .report-equation-number { flex-shrink: 0; }

package/template/report.tsx

@@ -1,10 +1,12 @@
 import type { Route } from './+types/report'
 import { ReportDocumentPage } from '@godcreator/word-report/site'
 import { reportPageLoader } from '@godcreator/word-report/site/server'
+import { commentAvatar, CommentBody } from '@/lib/content'
 import { wordReportSite } from './site.server'
 
 export const loader = (args: Route.LoaderArgs) => reportPageLoader(args, wordReportSite())
 
+/** 评论写进站点的评论写入路由 /comments（comments 功能），和内容页一样 */
 export default function Report() {
-  return <ReportDocumentPage />
+  return <ReportDocumentPage commentAction="/comments" CommentBody={CommentBody} AvatarComponent={commentAvatar} />
 }

package/template/routes.ts

@@ -2,7 +2,7 @@ import { relative, type RouteConfig } from '@react-router/dev/routes'
 
 const { route } = relative(import.meta.dirname)
 
-// 地址与 site.server.ts 的 reportHrefBase 一致；参数名 report、* 是 reportPageLoader、reportAssetLoader 读的
+// 地址与 href.ts 的 reportHrefBase 一致；参数名 report、* 是 reportPageLoader、reportAssetLoader 读的
 export default [
   route('reports', './list.tsx'),
   route('reports/:report', './report.tsx'),

package/template/site.server.ts

@@ -1,9 +1,19 @@
+import { commentsAccessOf } from '@godcreator/comments/site'
+import { pageThreadsOf } from '@godcreator/comments/site/server'
 import type { WordReportSite } from '@godcreator/word-report/site/server'
 import { site } from '@/lib/site.server'
 import { reportHrefBase } from './href'
 
-/** 报告功能的站点信息，每次请求现组装：报告在站点根下的 reports/，站名取页面树根（content/meta.json 的 title） */
+/** 报告功能的站点信息，每次请求现组装：报告在站点根下的 reports/，站名取页面树根（content/meta.json 的 title），评论取站点的评论集合 */
 export function wordReportSite(): WordReportSite {
   const name = site.source.getPageTree().name
-  return { siteDir: site.dir, siteName: typeof name === 'string' ? name : '', hrefBase: reportHrefBase }
+  return {
+    siteDir: site.dir,
+    siteName: typeof name === 'string' ? name : '',
+    hrefBase: reportHrefBase,
+    pageComments: (page) => ({
+      threads: pageThreadsOf({ entries: site.commentEntries, people: site.people(), page }),
+      access: commentsAccessOf(site.identity()),
+    }),
+  }
 }