@stll/folio-core 0.33.0 → 0.33.2

package/dist/compare/__fixtures__/body-sequence.d.ts

@@ -13,14 +13,88 @@
  * gets written.
  */
 type CellContent = string | readonly BodyItem[];
+/** `w:tcPr` children a fixture can author, each named after the element. */
+type CellProperties = {
+  /** `w:gridSpan`: grid columns this cell occupies. */
+  gridSpan?: number;
+  /** `w:vMerge`: the cell starts a vertical merge, or continues one. */
+  verticalMerge?: "restart" | "continue";
+  /** `w:tcW` in twips. */
+  width?: number;
+  /** `w:shd` fill colour, as six hex digits. */
+  shadingFill?: string;
+  /** `w:vAlign`. */
+  verticalAlign?: "top" | "center" | "bottom";
+  /** `w:tcBorders`, single style on all four sides, in eighths of a point. */
+  borderSize?: number;
+  /** `w:tcMar`, the same margin on all four sides, in twips. */
+  margin?: number;
+};
+/** A cell: its content alone, or its content and its own `w:tcPr`. */
+type Cell = CellContent | ({
+  content: CellContent;
+} & CellProperties);
+/** A row: its cells alone, or its cells and its own `w:trPr`. */
+type TableRow = readonly Cell[] | {
+  cells: readonly Cell[];
+  /** `w:trHeight` in twips. */
+  height?: number;
+  /** `w:tblHeader`: the row repeats at the top of every page. */
+  header?: boolean;
+  /** `w:jc` on the row. */
+  justification?: "left" | "center" | "right";
+};
+/** `w:tblPr` children a fixture can author, each named after the element. */
+type TableProperties = {
+  /** `w:tblStyle`. */
+  styleId?: string;
+  /** `w:tblW`. */
+  width?: {
+    value: number;
+    type: "auto" | "dxa" | "pct";
+  };
+  /** `w:jc` on the table. */
+  justification?: "left" | "center" | "right";
+  /** `w:tblInd` in twips. */
+  indent?: number;
+  /** `w:tblBorders`, single style on every side, in eighths of a point. */
+  borderSize?: number;
+  /** `w:shd` fill colour on the table, as six hex digits. */
+  shadingFill?: string;
+  /** `w:tblLayout`. */
+  layout?: "fixed" | "autofit";
+  /** `w:tblCellMar`, the same margin on all four sides, in twips. */
+  cellMargin?: number;
+  /** `w:tblLook` value, as four hex digits. */
+  look?: string;
+};
+/**
+ * One inline of a paragraph: plain text, or text carrying an external
+ * hyperlink. A link is the case where a revision wrapper and the linked runs
+ * have to nest one inside the other, so the fixture has to be able to author
+ * one.
+ */
+type ParagraphInline = string | {
+  text: string;
+  href: string;
+};
 /** One body-level item: a paragraph, or a table given row by row. */
 type BodyItem = {
   kind: "paragraph";
-  text: string;
+  text: string | readonly ParagraphInline[];
   styleId?: string;
+  /**
+   * An authored `w14:paraId`, for a package whose ids a producer wrote
+   * without respecting the 31-bit bound the schema puts on them.
+   */
+  paraId?: string;
 } | {
   kind: "table";
-  rows: readonly (readonly CellContent[])[];
+  rows: readonly TableRow[];
+  /** `w:tblPr` children, written in the order the schema requires. */
+  properties?: TableProperties;
+  /** `w:tblGrid` column widths, in twips. One per grid column. */
+  columnWidths?: readonly number[];
   /**
    * Rows a package hides with `w:hidden`. The snapshot skips their whole
    * subtree, so a document that has one is the case where the snapshot
@@ -28,6 +102,14 @@ type BodyItem = {
    */
   hiddenRows?: readonly number[];
 };
-declare const buildBodySequenceDocx: (items: readonly BodyItem[]) => Promise<ArrayBuffer>;
+type BodySequenceOptions = {
+  /**
+   * A default header part, written as its own sequence. A header is a story of
+   * its own: it ends with its own paragraph, and a comparison writes it with
+   * its own revision ids.
+   */
+  header?: readonly BodyItem[];
+};
+declare const buildBodySequenceDocx: (items: readonly BodyItem[], { header }?: BodySequenceOptions) => Promise<ArrayBuffer>;
 //#endregion
-export { BodyItem, CellContent, buildBodySequenceDocx };
+export { BodyItem, BodySequenceOptions, Cell, CellContent, CellProperties, ParagraphInline, TableProperties, TableRow, buildBodySequenceDocx };

package/dist/compare/__fixtures__/body-sequence.js

@@ -12,6 +12,12 @@ const NAMESPACE = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
 const RELATIONSHIPS = "http://schemas.openxmlformats.org/package/2006/relationships";
 const OFFICE_RELATIONSHIPS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
 const WORDPROCESSING = "application/vnd.openxmlformats-officedocument.wordprocessingml";
+const MARKUP_COMPATIBILITY = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+const PACKAGE_RELATIONSHIPS = "http://schemas.openxmlformats.org/package/2006";
+const CORE_PROPERTIES_TYPE = "application/vnd.openxmlformats-package.core-properties+xml";
+const EXTENDED_PROPERTIES = "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties";
+const EXTENDED_PROPERTIES_TYPE = "application/vnd.openxmlformats-officedocument.extended-properties+xml";
+const WORDML_2010 = "http://schemas.microsoft.com/office/word/2010/wordml";
 /**
 * `createFolders: false` because JSZip stamps the folder entries it
 * synthesizes with `new Date()`, which the fixed date above does not reach.
@@ -20,14 +26,62 @@ const ZIP_ENTRY_OPTIONS = {
 	date: new Date(Date.UTC(2e3, 0, 1)),
 	createFolders: false
 };
+const isRowOptions = (row) => "cells" in row;
+const isCellSpec = (cell) => typeof cell === "object" && "content" in cell;
+const rowCells = (row) => isRowOptions(row) ? row.cells : row;
+const rowOptions = (row) => isRowOptions(row) ? row : {};
+const cellContent = (cell) => isCellSpec(cell) ? cell.content : cell;
+const cellProperties = (cell) => isCellSpec(cell) ? cell : {};
+/**
+* A paragraph's id is derived from its own content, not from its position.
+*
+* Two packages authored from two descriptions are a base and a target, and a
+* paragraph that appears in both is the same paragraph. Numbering the ids in
+* document order would instead give the same id to the paragraph that happens
+* to sit at the same index, which is how the fixture would tell a comparison
+* that a removed paragraph was a rewrite of the one after it.
+*/
+const createParaIdAllocator = () => {
+	const taken = /* @__PURE__ */ new Set();
+	return (content) => {
+		let hash = 2166136261;
+		for (let index = 0; index < content.length; index += 1) hash = Math.imul(hash ^ content.charCodeAt(index), 16777619) >>> 0;
+		let candidate = hash % 2147483646;
+		while (taken.has((candidate + 1).toString(16).toUpperCase().padStart(8, "0"))) candidate = (candidate + 1) % 2147483646;
+		const paraId = (candidate + 1).toString(16).toUpperCase().padStart(8, "0");
+		taken.add(paraId);
+		return paraId;
+	};
+};
+const run = (text) => `<w:r><w:t xml:space="preserve">${text}</w:t></w:r>`;
+const inlineXml = (inline, { links }) => typeof inline === "string" ? run(inline) : `<w:hyperlink r:id="${links.get(inline.href) ?? ""}">${run(inline.text)}</w:hyperlink>`;
 /**
 * An empty paragraph is a `w:p` with no run at all, which is what a package
 * holds for a blank line or an empty cell. It is not the same thing as a
 * paragraph whose run carries an empty string, and both shapes occur.
 */
-const paragraph = (text, styleId) => {
+/** A blank line carries no run at all, so an empty string is no inline. */
+const nonEmptyInlines = (text) => text.length === 0 ? [] : [text];
+const paragraph = (text, context, { styleId, paraId } = {}) => {
 	const properties = styleId === void 0 ? "" : `<w:pPr><w:pStyle w:val="${styleId}"/></w:pPr>`;
-	return text.length === 0 ? `<w:p>${properties}</w:p>` : `<w:p>${properties}<w:r><w:t xml:space="preserve">${text}</w:t></w:r></w:p>`;
+	const inlines = typeof text === "string" ? nonEmptyInlines(text) : text;
+	const content = inlines.map((inline) => typeof inline === "string" ? inline : inline.text).join("");
+	const id = paraId ?? context.paraId(`${styleId ?? ""}|${content}`);
+	return `<w:p w14:paraId="${id}" w14:textId="${id}">${properties}${inlines.map((inline) => inlineXml(inline, context)).join("")}</w:p>`;
+};
+/** Every href the body carries, in document order, so the ids are stable. */
+const collectHrefs = (items, hrefs) => {
+	for (const item of items) {
+		if (item.kind === "paragraph") {
+			if (typeof item.text === "string") continue;
+			for (const inline of item.text) if (typeof inline !== "string" && !hrefs.includes(inline.href)) hrefs.push(inline.href);
+			continue;
+		}
+		for (const row of item.rows) for (const cell of rowCells(row)) {
+			const content = cellContent(cell);
+			if (typeof content !== "string") collectHrefs(content, hrefs);
+		}
+	}
 };
 const EMPTY_PARAGRAPH = {
 	kind: "paragraph",
@@ -44,20 +98,123 @@ const closedSequence = (items) => {
 	return last === void 0 || last.kind === "table" ? [...items, EMPTY_PARAGRAPH] : items;
 };
 /** A cell must also contain a paragraph, which the empty sequence supplies. */
-const cellXml = (content) => typeof content === "string" ? paragraph(content) : itemsXml(closedSequence(content));
-const table = (item) => {
+const cellXml = (content, context) => typeof content === "string" ? paragraph(content, context) : itemsXml(closedSequence(content), context);
+/** `w:tbl` is `w:tblPr, w:tblGrid, rows`: a fixture without the grid is not one. */
+const tableGrid = (item) => {
+	if (item.columnWidths) return `<w:tblGrid>${item.columnWidths.map((width) => `<w:gridCol w:w="${String(width)}"/>`).join("")}</w:tblGrid>`;
+	let columns = 0;
+	for (const row of item.rows) {
+		let spanned = 0;
+		for (const cell of rowCells(row)) spanned += cellProperties(cell).gridSpan ?? 1;
+		columns = Math.max(columns, spanned);
+	}
+	return `<w:tblGrid>${`<w:gridCol w:w="2000"/>`.repeat(columns)}</w:tblGrid>`;
+};
+const BORDER_SIDES = [
+	"top",
+	"left",
+	"bottom",
+	"right",
+	"insideH",
+	"insideV"
+];
+const CELL_BORDER_SIDES = [
+	"top",
+	"left",
+	"bottom",
+	"right"
+];
+const MARGIN_SIDES = [
+	"top",
+	"left",
+	"bottom",
+	"right"
+];
+const borders = (element, sides, size) => `<w:${element}>${sides.map((side) => `<w:${side} w:val="single" w:sz="${String(size)}" w:space="0" w:color="000000"/>`).join("")}</w:${element}>`;
+const margins = (element, value) => `<w:${element}>${MARGIN_SIDES.map((side) => `<w:${side} w:w="${String(value)}" w:type="dxa"/>`).join("")}</w:${element}>`;
+/**
+* `w:tblPr` children in the order CT_TblPrBase declares: tblStyle, tblW, jc,
+* tblInd, tblBorders, shd, tblLayout, tblCellMar, tblLook. `w:tblW` is always
+* written.
+*/
+const tableProperties = ({ properties }) => {
+	const width = properties?.width ?? {
+		value: 0,
+		type: "auto"
+	};
+	return `<w:tblPr>${[
+		...properties?.styleId === void 0 ? [] : [`<w:tblStyle w:val="${properties.styleId}"/>`],
+		`<w:tblW w:w="${String(width.value)}" w:type="${width.type}"/>`,
+		...properties?.justification === void 0 ? [] : [`<w:jc w:val="${properties.justification}"/>`],
+		...properties?.indent === void 0 ? [] : [`<w:tblInd w:w="${String(properties.indent)}" w:type="dxa"/>`],
+		...properties?.borderSize === void 0 ? [] : [borders("tblBorders", BORDER_SIDES, properties.borderSize)],
+		...properties?.shadingFill === void 0 ? [] : [`<w:shd w:val="clear" w:color="auto" w:fill="${properties.shadingFill}"/>`],
+		...properties?.layout === void 0 ? [] : [`<w:tblLayout w:type="${properties.layout}"/>`],
+		...properties?.cellMargin === void 0 ? [] : [margins("tblCellMar", properties.cellMargin)],
+		...properties?.look === void 0 ? [] : [`<w:tblLook w:val="${properties.look}"/>`]
+	].join("")}</w:tblPr>`;
+};
+/**
+* `w:trPr` children. `CT_TrPrBase` is a repeated choice rather than a
+* sequence, so the order here is the readable one rather than a required one.
+*/
+const rowProperties = (row, hidden) => {
+	const { header, height, justification } = rowOptions(row);
+	const parts = [
+		...height === void 0 ? [] : [`<w:trHeight w:val="${String(height)}"/>`],
+		...header === true ? ["<w:tblHeader/>"] : [],
+		...justification === void 0 ? [] : [`<w:jc w:val="${justification}"/>`],
+		...hidden ? ["<w:hidden/>"] : []
+	];
+	return parts.length === 0 ? "" : `<w:trPr>${parts.join("")}</w:trPr>`;
+};
+/** `w:tcPr` children in schema order; `w:tcW` is always written. */
+const cellPropertiesXml = (cell) => {
+	const properties = cellProperties(cell);
+	return `<w:tcPr>${[
+		`<w:tcW w:w="${String(properties.width ?? 2e3)}" w:type="dxa"/>`,
+		...properties.gridSpan === void 0 ? [] : [`<w:gridSpan w:val="${String(properties.gridSpan)}"/>`],
+		...properties.verticalMerge === void 0 ? [] : [properties.verticalMerge === "restart" ? `<w:vMerge w:val="restart"/>` : `<w:vMerge/>`],
+		...properties.borderSize === void 0 ? [] : [borders("tcBorders", CELL_BORDER_SIDES, properties.borderSize)],
+		...properties.shadingFill === void 0 ? [] : [`<w:shd w:val="clear" w:color="auto" w:fill="${properties.shadingFill}"/>`],
+		...properties.margin === void 0 ? [] : [margins("tcMar", properties.margin)],
+		...properties.verticalAlign === void 0 ? [] : [`<w:vAlign w:val="${properties.verticalAlign}"/>`]
+	].join("")}</w:tcPr>`;
+};
+const table = (item, context) => {
 	const hidden = new Set(item.hiddenRows ?? []);
-	return `<w:tbl><w:tblPr><w:tblW w:w="0" w:type="auto"/></w:tblPr>` + item.rows.map((cells, rowIndex) => `<w:tr>${hidden.has(rowIndex) ? `<w:trPr><w:hidden/></w:trPr>` : ""}${cells.map((content) => `<w:tc><w:tcPr><w:tcW w:w="2000" w:type="dxa"/></w:tcPr>${cellXml(content)}</w:tc>`).join("")}</w:tr>`).join("") + `</w:tbl>`;
+	return `<w:tbl>${tableProperties(item)}` + tableGrid(item) + item.rows.map((row, rowIndex) => `<w:tr>${rowProperties(row, hidden.has(rowIndex))}${rowCells(row).map((cell) => `<w:tc>${cellPropertiesXml(cell)}${cellXml(cellContent(cell), context)}</w:tc>`).join("")}</w:tr>`).join("") + `</w:tbl>`;
 };
-const itemsXml = (items) => items.map((item) => item.kind === "paragraph" ? paragraph(item.text, item.styleId) : table(item)).join("");
-const bodyXml = (items) => itemsXml(closedSequence(items));
-const buildBodySequenceDocx = async (items) => {
+const itemsXml = (items, context) => items.map((item) => item.kind === "paragraph" ? paragraph(item.text, context, {
+	...item.styleId === void 0 ? {} : { styleId: item.styleId },
+	...item.paraId === void 0 ? {} : { paraId: item.paraId }
+}) : table(item, context)).join("");
+const bodyXml = (items, context) => itemsXml(closedSequence(items), context);
+/** The relationship id the default header takes when a fixture asks for one. */
+const HEADER_RELATIONSHIP_ID = "rId2";
+const buildBodySequenceDocx = async (items, { header } = {}) => {
+	const hrefs = [];
+	collectHrefs(closedSequence(items), hrefs);
+	collectHrefs(closedSequence(header ?? []), hrefs);
+	const firstLinkRelationship = header ? 3 : 2;
+	const links = new Map(hrefs.map((href, index) => [href, `rId${index + firstLinkRelationship}`]));
+	const linkRelationships = hrefs.map((href, index) => `<Relationship Id="rId${index + firstLinkRelationship}" Type="${OFFICE_RELATIONSHIPS}/hyperlink" Target="${href}" TargetMode="External"/>`).join("");
+	const paraId = createParaIdAllocator();
 	const parts = {
-		"[Content_Types].xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="${WORDPROCESSING}.document.main+xml"/><Override PartName="/word/styles.xml" ContentType="${WORDPROCESSING}.styles+xml"/></Types>`,
-		"_rels/.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="${RELATIONSHIPS}"><Relationship Id="rId1" Type="${OFFICE_RELATIONSHIPS}/officeDocument" Target="word/document.xml"/></Relationships>`,
-		"word/_rels/document.xml.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="${RELATIONSHIPS}"><Relationship Id="rId1" Type="${OFFICE_RELATIONSHIPS}/styles" Target="styles.xml"/></Relationships>`,
+		"[Content_Types].xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="${WORDPROCESSING}.document.main+xml"/><Override PartName="/word/styles.xml" ContentType="${WORDPROCESSING}.styles+xml"/>` + (header ? `<Override PartName="/word/header1.xml" ContentType="${WORDPROCESSING}.header+xml"/>` : "") + `<Override PartName="/docProps/core.xml" ContentType="${CORE_PROPERTIES_TYPE}"/><Override PartName="/docProps/app.xml" ContentType="${EXTENDED_PROPERTIES_TYPE}"/></Types>`,
+		"_rels/.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="${RELATIONSHIPS}"><Relationship Id="rId1" Type="${OFFICE_RELATIONSHIPS}/officeDocument" Target="word/document.xml"/><Relationship Id="rId2" Type="${PACKAGE_RELATIONSHIPS}/metadata/core-properties" Target="docProps/core.xml"/><Relationship Id="rId3" Type="${OFFICE_RELATIONSHIPS}/extended-properties" Target="docProps/app.xml"/></Relationships>`,
+		"docProps/core.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><cp:coreProperties xmlns:cp="${PACKAGE_RELATIONSHIPS}/metadata/core-properties" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><dcterms:created xsi:type="dcterms:W3CDTF">2000-01-01T00:00:00Z</dcterms:created><dcterms:modified xsi:type="dcterms:W3CDTF">2000-01-01T00:00:00Z</dcterms:modified></cp:coreProperties>`,
+		"docProps/app.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Properties xmlns="${EXTENDED_PROPERTIES}"><AppVersion>1.0.0</AppVersion></Properties>`,
+		"word/_rels/document.xml.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="${RELATIONSHIPS}"><Relationship Id="rId1" Type="${OFFICE_RELATIONSHIPS}/styles" Target="styles.xml"/>` + (header ? `<Relationship Id="${HEADER_RELATIONSHIP_ID}" Type="${OFFICE_RELATIONSHIPS}/header" Target="header1.xml"/>` : "") + linkRelationships + `</Relationships>`,
 		"word/styles.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles xmlns:w="${NAMESPACE}"><w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style><w:style w:type="paragraph" w:styleId="Heading1"><w:name w:val="heading 1"/></w:style></w:styles>`,
-		"word/document.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="${NAMESPACE}"><w:body>` + bodyXml(items) + "<w:sectPr><w:pgSz w:w=\"12240\" w:h=\"15840\"/><w:pgMar w:top=\"1440\" w:right=\"1440\" w:bottom=\"1440\" w:left=\"1440\"/></w:sectPr></w:body></w:document>"
+		"word/document.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="${NAMESPACE}" xmlns:r="${OFFICE_RELATIONSHIPS}" xmlns:mc="${MARKUP_COMPATIBILITY}" xmlns:w14="${WORDML_2010}" mc:Ignorable="w14"><w:body>` + bodyXml(items, {
+			links,
+			paraId
+		}) + `<w:sectPr>` + (header ? `<w:headerReference w:type="default" r:id="${HEADER_RELATIONSHIP_ID}"/>` : "") + "<w:pgSz w:w=\"12240\" w:h=\"15840\"/><w:pgMar w:top=\"1440\" w:right=\"1440\" w:bottom=\"1440\" w:left=\"1440\"/></w:sectPr></w:body></w:document>",
+		...header ? { "word/header1.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:hdr xmlns:w="${NAMESPACE}" xmlns:r="${OFFICE_RELATIONSHIPS}" xmlns:mc="${MARKUP_COMPATIBILITY}" xmlns:w14="${WORDML_2010}" mc:Ignorable="w14">${itemsXml(closedSequence(header), {
+			links,
+			paraId
+		})}</w:hdr>` } : {}
 	};
 	const zip = new JSZip();
 	for (const name of Object.keys(parts).toSorted()) zip.file(name, parts[name] ?? "", ZIP_ENTRY_OPTIONS);

package/dist/compare/compare.d.ts

@@ -3,7 +3,7 @@ import { WordDiffGranularity } from "../ai-edits/word-diff.js";
 import { FolioRevisionStamp } from "../ai-edits/apply.js";
 import { FolioDocumentStoryHandle, FolioDocxReviewer } from "../ai-edits/headless.js";
 import { CompareVerification } from "./verification.js";
-import { CompareChange, CompareDocxApplyError, CompareDocxError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxSerializeError, CompareResult, CompareUnsupportedPart, InvalidCompareDocxOptionsError } from "./types.js";
+import { CompareChange, CompareDocxApplyError, CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxSerializeError, CompareResult, CompareUnsupportedPart, InvalidCompareDocxOptionsError } from "./types.js";
 import { CompareStoryPlan } from "./plan.js";
 import { Result } from "better-result";
 //#region src/compare/compare.d.ts
@@ -51,25 +51,32 @@ type PlannedStoryComparison = {
  * parsing, no serialization, no clock.
  */
 declare const planComparison: ({ pairs }: ParsedComparison) => Result<readonly PlannedStoryComparison[], CompareDocxOperationLimitError>;
-/** What stage 3 produced: the change list, and whether it was proven. */
+/** What stage 3 produced: the change list, whether it was proven, and whether it wrote anything. */
 type AppliedComparison = {
   changes: readonly CompareChange[];
   verification: CompareVerification;
+  /**
+   * Whether the stage wrote into the base document at all. A comparison that
+   * found nothing writes nothing, and the serialize stage then hands the
+   * arriving bytes back rather than reproducing them.
+   */
+  documentChanged: boolean;
 };
 /**
  * Stage 3: write the planned operations into the base document as tracked
  * changes, then check the work rather than trust it. Both directions of the
- * round trip are checked, structure included: accepting the story's generated
- * revisions must reproduce the target, and rejecting them must reproduce the
- * base it was compared from. A difference the operation vocabulary cannot
- * express would otherwise leave a redline that reads plausibly and is wrong.
+ * round trip are checked, structure and table geometry included: accepting the
+ * story's generated revisions must reproduce the target, and rejecting them
+ * must reproduce the base it was compared from. A difference the operation
+ * vocabulary cannot express would otherwise leave a redline that reads
+ * plausibly and is wrong.
  *
  * The check reports rather than throws. {@link compareDocx} decides what to do
  * with an unverified result, because "give me your best attempt and tell me
  * what you could not represent" and "give me nothing unless you can prove it"
  * are both legitimate asks and only the caller knows which one it is making.
  */
-declare const applyComparison: ({ reviewer, revisionStamp, granularity, numberingChanges }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Result<AppliedComparison, CompareDocxApplyError>;
+declare const applyComparison: ({ reviewer, targetReviewer, revisionStamp, granularity, numberingChanges }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Result<AppliedComparison, CompareDocxApplyError>;
 /**
  * Stage 4: the result package, with every ZIP entry date pinned.
  *
@@ -89,7 +96,7 @@ declare const applyComparison: ({ reviewer, revisionStamp, granularity, numberin
  * composition let the benchmark's own composition disagree with the shipped
  * one within a single run.
  */
-declare const serializeComparison: ({ baseBuffer, baseCarriedRevisions, reviewer, packageDate }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Promise<Result<ArrayBuffer, CompareDocxSerializeError>>;
+declare const serializeComparison: ({ baseBuffer, baseCarriedRevisions, reviewer, packageDate, revisionStamp }: ParsedComparison, { documentChanged }: AppliedComparison) => Promise<Result<ArrayBuffer, CompareDocxSerializeError | CompareDocxFinalParagraphMarkError>>;
 /**
  * Compare `base` against `target` and return `base` carrying the tracked
  * changes that turn it into `target`, alongside the change list describing

package/dist/compare/compare.js

@@ -1,10 +1,11 @@
 import { FolioDocxReviewer } from "../ai-edits/headless.js";
+import { projectTableGeometry } from "../ai-edits/table-geometry.js";
 import "../document-operations.js";
 import { pairFolioDocumentStories } from "../document-stories.js";
 import { planStoryCompare } from "./plan.js";
 import { withFixedPackageDates } from "./reproducible-package.js";
-import { CompareDocxApplyError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, InvalidCompareDocxOptionsError } from "./types.js";
-import { classifyProjectionMismatch, projectSupportedInlineFormatting } from "./verification.js";
+import { CompareDocxApplyError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, InvalidCompareDocxOptionsError } from "./types.js";
+import { classifyGeometryMismatch, classifyProjectionMismatch, projectSupportedInlineFormatting, revisedFinalParagraphMarks } from "./verification.js";
 import { Result, panic } from "better-result";
 //#region src/compare/compare.ts
 /**
@@ -151,6 +152,14 @@ const parseComparison = async (base, target, options) => {
 	const reviewer = baseParse.value;
 	const targetReviewer = targetParse.value;
 	const existing = existingRevisionsOf(reviewer);
+	for (const { handle } of reviewer.listStories()) reviewer.resolveReviewedStory({
+		story: handle,
+		view: "final"
+	});
+	for (const { handle } of targetReviewer.listStories()) targetReviewer.resolveReviewedStory({
+		story: handle,
+		view: "final"
+	});
 	const pairs = [];
 	const unsupported = [];
 	for (const { baseStory, revisedStory: targetStory } of pairFolioDocumentStories(reviewer.listStories().map(({ handle }) => handle), targetReviewer.listStories().map(({ handle }) => handle))) {
@@ -170,14 +179,6 @@ const parseComparison = async (base, target, options) => {
 			});
 			continue;
 		}
-		reviewer.resolveReviewedStory({
-			story: baseStory,
-			view: "final"
-		});
-		targetReviewer.resolveReviewedStory({
-			story: targetStory,
-			view: "final"
-		});
 		const baseSnapshot = reviewer.snapshotStory(baseStory);
 		const targetSnapshot = targetReviewer.snapshotStory(targetStory);
 		if (!baseSnapshot || !targetSnapshot) {
@@ -236,50 +237,126 @@ const planComparison = ({ pairs }) => {
 	return Result.ok(planned);
 };
 /**
+* What a skipped operation says about the plan that derived it.
+*
+* Two different things go wrong at apply time, and only one of them leaves the
+* result unusable. A reason that says the plan did not match the document it
+* was planned against is an engine defect — the operations came from this very
+* snapshot moments earlier, so nothing should have moved under them, and a
+* redline built on the rest is built on a document the plan no longer
+* describes. A reason that says the applier had nothing to write, or could not
+* write that shape THERE, leaves the redline standing and turns the question
+* into "was anything lost", which is what the round-trip check answers a few
+* lines below. Refusing on those instead trades a partial answer for none, and
+* refuses a whole document because one paragraph sits inside a structure the
+* block snapshot does not model — a text box, a content control — where a
+* paragraph mark has nowhere to go.
+*/
+const COMPARE_SKIP_DISPOSITION = {
+	missingBlock: "fatal",
+	changedBlock: "fatal",
+	ambiguousFind: "fatal",
+	missingFind: "fatal",
+	unsupportedBlock: "unwritable",
+	unsupportedMode: "fatal",
+	atomicBatchRejected: "fatal",
+	preconditionFailed: "fatal",
+	staleRange: "fatal",
+	emptyOperation: "unwritable",
+	noopOperation: "unwritable",
+	documentVersionMismatch: "fatal",
+	documentNotEditable: "fatal"
+};
+/**
+* The table each `insertTable` / `insertTableRow` in the plan should place,
+* resolved against the target document the plan named it in.
+*
+* The plan is pure and names a table by index; the node lives in the other
+* package, which only this stage holds. A request naming a table the target
+* does not have resolves to nothing and the operation falls back to its cell
+* texts, which is the same redline the comparison produced before.
+*/
+const resolveTableTemplates = (targetTables, requests) => {
+	const templates = /* @__PURE__ */ new Map();
+	for (const { operationId, targetTableIndex, targetRowIndex } of requests) {
+		const table = targetTables.get(targetTableIndex);
+		if (!table) continue;
+		if (targetRowIndex === void 0) {
+			templates.set(operationId, table);
+			continue;
+		}
+		const row = table.maybeChild(targetRowIndex);
+		if (row) templates.set(operationId, row);
+	}
+	return templates;
+};
+/**
 * Stage 3: write the planned operations into the base document as tracked
 * changes, then check the work rather than trust it. Both directions of the
-* round trip are checked, structure included: accepting the story's generated
-* revisions must reproduce the target, and rejecting them must reproduce the
-* base it was compared from. A difference the operation vocabulary cannot
-* express would otherwise leave a redline that reads plausibly and is wrong.
+* round trip are checked, structure and table geometry included: accepting the
+* story's generated revisions must reproduce the target, and rejecting them
+* must reproduce the base it was compared from. A difference the operation
+* vocabulary cannot express would otherwise leave a redline that reads
+* plausibly and is wrong.
 *
 * The check reports rather than throws. {@link compareDocx} decides what to do
 * with an unverified result, because "give me your best attempt and tell me
 * what you could not represent" and "give me nothing unless you can prove it"
 * are both legitimate asks and only the caller knows which one it is making.
 */
-const applyComparison = ({ reviewer, revisionStamp, granularity, numberingChanges }, planned) => {
+const applyComparison = ({ reviewer, targetReviewer, revisionStamp, granularity, numberingChanges }, planned) => {
 	const changes = [...numberingChanges];
 	const failures = [];
 	let idSeed = revisionStamp.idSeed;
+	let documentChanged = false;
 	for (const { pair, plan } of planned) {
 		changes.push(...plan.changes);
-		if (plan.operations.length === 0) continue;
+		if (plan.operations.length === 0 && plan.tableGeometryPairings.length === 0) continue;
 		const baseBeforeBlocks = reviewer.readReviewedStory({
 			story: pair.baseStory,
 			view: "final"
 		})?.snapshot.blocks ?? [];
 		const baseBefore = projectBlocks(baseBeforeBlocks);
-		const { skipped, nextRevisionId } = reviewer.applyDocumentOperationsToStory({
+		const baseBeforeGeometry = projectTableGeometry(reviewer.storyTables({ story: pair.baseStory }));
+		const targetTables = new Map(targetReviewer.storyTables({ story: pair.targetStory }).map(({ index, node }) => [index, node]));
+		const afterGeometry = reviewer.matchStoryTableGeometry({
 			story: pair.baseStory,
-			snapshot: pair.baseSnapshot,
+			targetTables,
+			pairings: plan.tableGeometryPairings,
 			revisionStamp: {
 				date: revisionStamp.date,
 				idSeed
-			},
-			wordDiff: { granularity },
-			batch: {
-				version: 1,
-				mode: "tracked-changes",
-				operations: plan.operations
 			}
 		});
-		if (nextRevisionId === void 0) panic("The applier did not report where it left the revision-id counter", { story: pair.baseStory });
-		idSeed = nextRevisionId;
-		if (skipped.length > 0) return Result.err(new CompareDocxApplyError({
-			message: "Some derived operations were refused, so the result would not match the target.",
-			skipped
-		}));
+		const geometryChanged = afterGeometry > idSeed;
+		documentChanged ||= geometryChanged;
+		idSeed = afterGeometry;
+		if (plan.operations.length === 0 && !geometryChanged) continue;
+		if (plan.operations.length > 0) {
+			const { skipped, nextRevisionId } = reviewer.applyDocumentOperationsToStory({
+				story: pair.baseStory,
+				snapshot: pair.baseSnapshot,
+				revisionStamp: {
+					date: revisionStamp.date,
+					idSeed
+				},
+				wordDiff: { granularity },
+				batch: {
+					version: 1,
+					mode: "tracked-changes",
+					operations: plan.operations
+				},
+				tableTemplates: resolveTableTemplates(targetTables, plan.tableTemplates)
+			});
+			if (nextRevisionId === void 0) panic("The applier did not report where it left the revision-id counter", { story: pair.baseStory });
+			idSeed = nextRevisionId;
+			documentChanged = true;
+			const refused = skipped.filter(({ reason }) => COMPARE_SKIP_DISPOSITION[reason] === "fatal");
+			if (refused.length > 0) return Result.err(new CompareDocxApplyError({
+				message: "Some derived operations were refused, so the result would not match the target.",
+				skipped: refused
+			}));
+		}
 		const acceptedStory = reviewer.readReviewedStory({
 			story: pair.baseStory,
 			view: "final"
@@ -324,13 +401,34 @@ const applyComparison = ({ reviewer, revisionStamp, granularity, numberingChange
 			});
 			if (formattingFailure) failures.push(formattingFailure);
 		}
+		const geometryAcceptFailure = classifyGeometryMismatch({
+			invariant: "accept-reproduces-target",
+			story: pair.baseStory,
+			actual: projectTableGeometry(reviewer.storyTables({
+				story: pair.baseStory,
+				view: "final"
+			})),
+			expected: projectTableGeometry(targetReviewer.storyTables({ story: pair.targetStory }))
+		});
+		if (geometryAcceptFailure) failures.push(geometryAcceptFailure);
+		const geometryRejectFailure = classifyGeometryMismatch({
+			invariant: "reject-reproduces-base",
+			story: pair.baseStory,
+			actual: projectTableGeometry(reviewer.storyTables({
+				story: pair.baseStory,
+				view: "original"
+			})),
+			expected: baseBeforeGeometry
+		});
+		if (geometryRejectFailure) failures.push(geometryRejectFailure);
 	}
 	return Result.ok({
 		changes,
 		verification: failures.length === 0 ? { status: "verified" } : {
 			status: "unverified",
 			failures
-		}
+		},
+		documentChanged
 	});
 };
 /**
@@ -352,8 +450,14 @@ const applyComparison = ({ reviewer, revisionStamp, granularity, numberingChange
 * composition let the benchmark's own composition disagree with the shipped
 * one within a single run.
 */
-const serializeComparison = async ({ baseBuffer, baseCarriedRevisions, reviewer, packageDate }, planned) => {
-	if (!baseCarriedRevisions && planned.every(({ plan }) => plan.operations.length === 0)) return Result.ok(baseBuffer);
+const serializeComparison = async ({ baseBuffer, baseCarriedRevisions, reviewer, packageDate, revisionStamp }, { documentChanged }) => {
+	if (!baseCarriedRevisions && !documentChanged) return Result.ok(baseBuffer);
+	const revisions = revisedFinalParagraphMarks(reviewer.toDocument(), { since: revisionStamp.idSeed });
+	const [first] = revisions;
+	if (first !== void 0) return Result.err(new CompareDocxFinalParagraphMarkError({
+		message: `A container's final paragraph mark carries a ${first.kind}, which no consumer can resolve: ${first.container} paragraph ${String(first.paragraphIndex)}.`,
+		revisions
+	}));
 	return await Result.tryPromise({
 		try: async () => await withFixedPackageDates(await reviewer.toBuffer(), packageDate),
 		catch: (cause) => new CompareDocxSerializeError({
@@ -393,7 +497,7 @@ const compareDocx = async (base, target, options) => {
 			failures: verification.failures
 		}));
 	}
-	const serialized = await serializeComparison(parsed.value, planned.value);
+	const serialized = await serializeComparison(parsed.value, applied.value);
 	if (serialized.isErr()) return Result.err(serialized.error);
 	return Result.ok({
 		buffer: serialized.value,