@stll/folio-core 0.32.2 → 0.33.1

package/dist/ai-edits/word-diff.js

@@ -1,114 +1,274 @@
 //#region src/ai-edits/word-diff.ts
+/**
+* What one token is. `"word"` tokenises on whitespace and is what a redline
+* over prose should use; `"character"` marks the changed letters inside a
+* word, which reads well for a reference number or a date and badly for a
+* sentence.
+*/
+const WORD_DIFF_GRANULARITIES = Object.freeze(["word", "character"]);
 const WHITESPACE = /\s/u;
-const tokenize = (s) => {
+/** Punctuation, symbols and whitespace: everything that is not content. */
+const SEPARATOR_ONLY = /^[\s\p{P}\p{S}]*$/u;
+/**
+* A match of at most this many tokens that carries no letters or digits is
+* noise: a lone space, a comma, a stray closing bracket. Matching it splits
+* two rewrites into four.
+*/
+const MAX_SEPARATOR_ONLY_MATCH_UNITS = 3;
+/**
+* A match shorter than this, with changes on BOTH sides of it, is dropped into
+* them. An island that small is almost always a coincidence, and it costs the
+* reader two extra fragments to notice. A match that opens or closes the
+* string is not an island: it is where the reader anchors, and striking it
+* through to re-insert it identically reads as an edit nobody made.
+*/
+const MINIMUM_ISOLATED_MATCH_UNITS = 2;
+/**
+* Fragmentation floor. `sumOfSquares` rewards few long matches and punishes
+* many short ones — a single run of length L scores L^2, while L runs of
+* length 1 score L — so comparing it against the average string length
+* separates "a few words changed" from "rewritten, with coincidental
+* matches". Below the floor the paragraph is replaced whole.
+*/
+const FRAGMENTATION_SCALE = 32;
+/** Below this length every match is a large fraction of the string, so the floor says nothing. */
+const FRAGMENTATION_MINIMUM_AVERAGE_LENGTH = 8;
+const tokenizeWords = (value) => {
 	const tokens = [];
 	let tokenStart = 0;
 	let cursor = 0;
-	while (cursor < s.length) {
-		while (cursor < s.length && WHITESPACE.test(s.charAt(cursor))) cursor++;
-		if (cursor === s.length) break;
-		while (cursor < s.length && !WHITESPACE.test(s.charAt(cursor))) cursor++;
-		tokens.push(s.slice(tokenStart, cursor));
+	while (cursor < value.length) {
+		while (cursor < value.length && WHITESPACE.test(value.charAt(cursor))) cursor++;
+		if (cursor === value.length) break;
+		while (cursor < value.length && !WHITESPACE.test(value.charAt(cursor))) cursor++;
+		tokens.push(value.slice(tokenStart, cursor));
 		tokenStart = cursor;
 	}
 	const last = tokens.at(-1);
-	if (last === void 0) return s.length === 0 ? [] : [s];
-	if (tokenStart < s.length) tokens[tokens.length - 1] = last + s.slice(tokenStart);
+	if (last === void 0) return value.length === 0 ? [] : [value];
+	if (tokenStart < value.length) tokens[tokens.length - 1] = last + value.slice(tokenStart);
 	return tokens;
 };
+/** Code points, not UTF-16 units, so an emoji or a surrogate pair stays whole. */
+const tokenizeCharacters = (value) => [...value];
+const tokenize = (value, granularity) => granularity === "character" ? tokenizeCharacters(value) : tokenizeWords(value);
+/**
+* The key two tokens are matched on. `toLowerCase` rather than
+* `toLocaleLowerCase`: the ambient locale would make the same two documents
+* diff differently on two machines.
+*/
+const comparisonKey = (token, normalization) => {
+	const collapsed = normalization.whitespace === true ? token.replaceAll(/\s+/gu, " ").trim() : token;
+	return normalization.case === true ? collapsed.toLowerCase() : collapsed;
+};
+const isSeparatorOnly = (text) => SEPARATOR_ONLY.test(text);
 /**
-* Cell budget for the O(n*m) word-diff DP table below, mirroring
-* `MAX_LCS_CELLS` in `version-comparison.ts`. `before`/`after` come from
+* Cell budget for the O(n*m) DP table below. `before`/`after` come from
 * attacker-controlled document text (a `modified` block pair), so an
 * unbounded pair of large strings would otherwise force a quadratic-sized
 * allocation. Past this budget, skip the DP and fall back to a single
 * whole-string `del` + `ins` pair — a coarser diff, but O(1) memory.
 */
 const MAX_WORD_DIFF_CELLS = 4e6;
-const diffWordSegments = (before, after) => {
-	const a = tokenize(before);
-	const b = tokenize(after);
-	if (a.length === 0 && b.length === 0) return [];
-	const m = a.length;
-	const n = b.length;
-	if (m * n > MAX_WORD_DIFF_CELLS) {
-		const segments = [];
-		if (before.length > 0) segments.push({
-			type: "del",
-			text: before
-		});
-		if (after.length > 0) segments.push({
-			type: "ins",
-			text: after
-		});
-		return segments;
-	}
+/** The LCS alignment, as runs. Longest common subsequence on comparison keys. */
+const alignTokens = ({ before, after, normalization }) => {
+	const beforeKeys = before.map((token) => comparisonKey(token, normalization));
+	const afterKeys = after.map((token) => comparisonKey(token, normalization));
+	const m = before.length;
+	const n = after.length;
 	const dp = Array.from({ length: m + 1 }, () => Array.from({ length: n + 1 }, () => 0));
 	for (let i = 0; i < m; i++) for (let j = 0; j < n; j++) {
 		const row = dp[i + 1];
-		const prevRow = dp[i];
-		if (!row || !prevRow) continue;
-		const prev = prevRow[j] ?? 0;
-		const left = row[j] ?? 0;
-		const top = prevRow[j + 1] ?? 0;
-		row[j + 1] = a[i] === b[j] ? prev + 1 : Math.max(left, top);
+		const previousRow = dp[i];
+		if (!row || !previousRow) continue;
+		row[j + 1] = beforeKeys[i] === afterKeys[j] ? (previousRow[j] ?? 0) + 1 : Math.max(row[j] ?? 0, previousRow[j + 1] ?? 0);
 	}
-	const segments = [];
-	const push = (type, text) => {
-		if (text.length === 0) return;
-		const last = segments.at(-1);
-		if (last && last.type === type) {
-			last.text += text;
-			return;
-		}
-		segments.push({
-			type,
-			text
-		});
-	};
+	const reversed = [];
 	let i = m;
 	let j = n;
-	const reverse = [];
 	while (i > 0 && j > 0) {
-		if (a[i - 1] === b[j - 1]) {
-			reverse.push({
+		if (beforeKeys[i - 1] === afterKeys[j - 1]) {
+			reversed.push({
 				type: "equal",
-				text: a[i - 1] ?? ""
+				before: before[i - 1] ?? "",
+				after: after[j - 1] ?? "",
+				units: 1
 			});
 			i--;
 			j--;
 			continue;
 		}
 		if ((dp[i - 1]?.[j] ?? 0) > (dp[i]?.[j - 1] ?? 0)) {
-			reverse.push({
+			reversed.push({
 				type: "del",
-				text: a[i - 1] ?? ""
+				text: before[i - 1] ?? ""
 			});
 			i--;
 		} else {
-			reverse.push({
+			reversed.push({
 				type: "ins",
-				text: b[j - 1] ?? ""
+				text: after[j - 1] ?? ""
 			});
 			j--;
 		}
 	}
 	while (i > 0) {
-		reverse.push({
+		reversed.push({
 			type: "del",
-			text: a[i - 1] ?? ""
+			text: before[i - 1] ?? ""
 		});
 		i--;
 	}
 	while (j > 0) {
-		reverse.push({
+		reversed.push({
 			type: "ins",
-			text: b[j - 1] ?? ""
+			text: after[j - 1] ?? ""
 		});
 		j--;
 	}
-	for (const seg of reverse.toReversed()) push(seg.type, seg.text);
+	const runs = [];
+	for (const run of reversed.toReversed()) {
+		const last = runs.at(-1);
+		if (last?.type === "equal" && run.type === "equal") {
+			last.before += run.before;
+			last.after += run.after;
+			last.units += run.units;
+			continue;
+		}
+		if (last?.type === "del" && run.type === "del" || last?.type === "ins" && run.type === "ins") {
+			last.text += run.text;
+			continue;
+		}
+		runs.push({ ...run });
+	}
+	return runs;
+};
+/**
+* True when the surviving matches are too short, relative to the strings they
+* sit in, to be read as anything but coincidence.
+*/
+const isTooFragmented = (runs, averageLength) => {
+	if (averageLength < FRAGMENTATION_MINIMUM_AVERAGE_LENGTH) return false;
+	let sumOfSquares = 0;
+	for (const run of runs) if (run.type === "equal") sumOfSquares += run.before.length * run.before.length;
+	return sumOfSquares * FRAGMENTATION_SCALE < averageLength * averageLength;
+};
+/**
+* Turn a match the quality rules rejected back into the change it interrupts.
+*
+* Only a match with a change beside it can be rejected: with nothing to
+* absorb it, demoting would invent a deletion and an insertion of the same
+* text where the two strings agree.
+*/
+const demoteRejectedMatches = (runs) => {
+	const kept = [];
+	for (const [index, run] of runs.entries()) {
+		if (run.type !== "equal") {
+			kept.push(run);
+			continue;
+		}
+		const interruptsAChange = runs[index - 1] !== void 0 || runs[index + 1] !== void 0;
+		const isIsland = runs[index - 1] !== void 0 && runs[index + 1] !== void 0;
+		if (!(interruptsAChange && run.units <= MAX_SEPARATOR_ONLY_MATCH_UNITS && isSeparatorOnly(run.before) || isIsland && run.units < MINIMUM_ISOLATED_MATCH_UNITS)) {
+			kept.push(run);
+			continue;
+		}
+		kept.push({
+			type: "del",
+			text: run.before
+		}, {
+			type: "ins",
+			text: run.after
+		});
+	}
+	return kept;
+};
+const toSegments = (runs) => {
+	const segments = [];
+	const push = (type, text) => {
+		if (text.length === 0) return;
+		const last = segments.at(-1);
+		if (last?.type === type) {
+			last.text += text;
+			return;
+		}
+		segments.push({
+			type,
+			text
+		});
+	};
+	for (const run of runs) {
+		if (run.type === "equal") {
+			push("equal", run.before);
+			continue;
+		}
+		push(run.type, run.text);
+	}
+	return segments;
+};
+/**
+* Deletions before insertions within one changed region. Demoting a match
+* emits `del`, `ins`, `del`, `ins`; a reader wants the whole old text struck
+* through and then the whole new text.
+*/
+const orderDeletionsFirst = (runs) => {
+	const ordered = [];
+	let deletions = "";
+	let insertions = "";
+	const flush = () => {
+		if (deletions.length > 0) ordered.push({
+			type: "del",
+			text: deletions
+		});
+		if (insertions.length > 0) ordered.push({
+			type: "ins",
+			text: insertions
+		});
+		deletions = "";
+		insertions = "";
+	};
+	for (const run of runs) {
+		if (run.type === "del") {
+			deletions += run.text;
+			continue;
+		}
+		if (run.type === "ins") {
+			insertions += run.text;
+			continue;
+		}
+		flush();
+		ordered.push(run);
+	}
+	flush();
+	return ordered;
+};
+const wholeStringReplacement = (before, after) => {
+	const segments = [];
+	if (before.length > 0) segments.push({
+		type: "del",
+		text: before
+	});
+	if (after.length > 0) segments.push({
+		type: "ins",
+		text: after
+	});
 	return segments;
 };
+const diffWordSegments = (before, after, options = {}) => {
+	const granularity = options.granularity ?? "word";
+	const normalization = options.normalization ?? {};
+	const beforeTokens = tokenize(before, granularity);
+	const afterTokens = tokenize(after, granularity);
+	if (beforeTokens.length === 0 && afterTokens.length === 0) return [];
+	if (beforeTokens.length * afterTokens.length > MAX_WORD_DIFF_CELLS) return wholeStringReplacement(before, after);
+	const aligned = alignTokens({
+		before: beforeTokens,
+		after: afterTokens,
+		normalization
+	});
+	const surviving = demoteRejectedMatches(aligned);
+	if (isTooFragmented(surviving, (before.length + after.length) / 2)) return wholeStringReplacement(before, after);
+	return toSegments(orderDeletionsFirst(surviving));
+};
 //#endregion
-export { diffWordSegments };
+export { WORD_DIFF_GRANULARITIES, diffWordSegments };

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

@@ -0,0 +1,56 @@
+//#region src/compare/__fixtures__/body-sequence.d.ts
+/**
+ * A document body written from a sequence of paragraphs and tables.
+ *
+ * The edit-script DSL can move words and rows but cannot append a table, so a
+ * pair whose difference is "a paragraph AND a table were added after the last
+ * one" has to be authored as two packages. Generating both from one description
+ * keeps the difference visible in the diff instead of hidden in bytes.
+ */
+/**
+ * One cell's content: a line of text, or a sequence of its own — which is how
+ * a nested table, a blank line inside a cell, or a cell that ends with a table
+ * gets written.
+ */
+type CellContent = string | readonly BodyItem[];
+/**
+ * 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 | 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 a package hides with `w:hidden`. The snapshot skips their whole
+   * subtree, so a document that has one is the case where the snapshot
+   * walk and the live walk could disagree.
+   */
+  hiddenRows?: readonly number[];
+};
+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, BodySequenceOptions, CellContent, ParagraphInline, buildBodySequenceDocx };

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

@@ -0,0 +1,136 @@
+import JSZip from "jszip";
+//#region src/compare/__fixtures__/body-sequence.ts
+/**
+* A document body written from a sequence of paragraphs and tables.
+*
+* The edit-script DSL can move words and rows but cannot append a table, so a
+* pair whose difference is "a paragraph AND a table were added after the last
+* one" has to be authored as two packages. Generating both from one description
+* keeps the difference visible in the diff instead of hidden in bytes.
+*/
+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 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.
+*/
+const ZIP_ENTRY_OPTIONS = {
+	date: new Date(Date.UTC(2e3, 0, 1)),
+	createFolders: false
+};
+/**
+* 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.
+*/
+/** 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>`;
+	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 row) if (typeof cell !== "string") collectHrefs(cell, hrefs);
+	}
+};
+const EMPTY_PARAGRAPH = {
+	kind: "paragraph",
+	text: ""
+};
+/**
+* A container may not end with a table: the format requires a paragraph after
+* one, and a body's section properties do not supply it. One rule for both
+* containers, because a fixture that is well formed in a cell and malformed in
+* the body would be measuring two different things.
+*/
+const closedSequence = (items) => {
+	const last = items.at(-1);
+	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, 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 = (rows) => {
+	let columns = 0;
+	for (const cells of rows) columns = Math.max(columns, cells.length);
+	return `<w:tblGrid>${`<w:gridCol w:w="2000"/>`.repeat(columns)}</w:tblGrid>`;
+};
+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>` + tableGrid(item.rows) + 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, context)}</w:tc>`).join("")}</w:tr>`).join("") + `</w:tbl>`;
+};
+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"/>` + (header ? `<Override PartName="/word/header1.xml" ContentType="${WORDPROCESSING}.header+xml"/>` : "") + `<Override PartName="/docProps/core.xml" ContentType="${CORE_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"/></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>`,
+		"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}" 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);
+	return await zip.generateAsync({ type: "arraybuffer" });
+};
+//#endregion
+export { buildBodySequenceDocx };

package/dist/compare/__fixtures__/nested-table.d.ts

@@ -0,0 +1,16 @@
+//#region src/compare/__fixtures__/nested-table.d.ts
+/**
+ * A document that ends with a table whose last cell holds another table.
+ *
+ * The shape matters because the story's last block is then two levels deep,
+ * and a paragraph appended after the whole table has no block to anchor to
+ * that is not inside a cell. Authored here rather than committed as bytes so
+ * the structure under test is legible in the diff.
+ */
+type NestedTableDocxOptions = {
+  /** Appended after the outer table, at body level, when set. */
+  trailingParagraph?: string;
+};
+declare const buildNestedTableDocx: ({ trailingParagraph }?: NestedTableDocxOptions) => Promise<ArrayBuffer>;
+//#endregion
+export { NestedTableDocxOptions, buildNestedTableDocx };

package/dist/compare/__fixtures__/nested-table.js

@@ -0,0 +1,50 @@
+import JSZip from "jszip";
+//#region src/compare/__fixtures__/nested-table.ts
+/**
+* A document that ends with a table whose last cell holds another table.
+*
+* The shape matters because the story's last block is then two levels deep,
+* and a paragraph appended after the whole table has no block to anchor to
+* that is not inside a cell. Authored here rather than committed as bytes so
+* the structure under test is legible in the diff.
+*/
+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";
+/**
+* `createFolders: false` because JSZip stamps the folder entries it
+* synthesizes with `new Date()`, which the fixed date above does not reach.
+*/
+const ZIP_ENTRY_OPTIONS = {
+	date: new Date(Date.UTC(2e3, 0, 1)),
+	createFolders: false
+};
+const paragraph = (text) => text.length === 0 ? `<w:p/>` : `<w:p><w:r><w:t xml:space="preserve">${text}</w:t></w:r></w:p>`;
+/**
+* A table may not be the last child of a body or a cell, so every container
+* that ends with one is closed by a paragraph. Word writes that paragraph and
+* usually leaves it empty; a fixture that omits it is malformed, and the
+* comparison should be exercised against the shape real packages have.
+*/
+const closingParagraph = paragraph("");
+const cell = (inner) => `<w:tc><w:tcPr><w:tcW w:w="4680" w:type="dxa"/></w:tcPr>${inner}</w:tc>`;
+const table = (rows) => `<w:tbl><w:tblPr><w:tblW w:w="0" w:type="auto"/></w:tblPr><w:tblGrid><w:gridCol w:w="4680"/><w:gridCol w:w="4680"/></w:tblGrid>${rows.join("")}</w:tbl>`;
+/** The nested table sits in the outer table's last cell, deep in the story. */
+const NESTED_TABLE = table([`<w:tr>${cell(`${paragraph("The nested schedule lists the delivery dates.")}${closingParagraph}`)}</w:tr>`]);
+const OUTER_TABLE = table([`<w:tr>${cell(paragraph("Obligations of the supplier."))}${cell(paragraph("Obligations of the buyer."))}</w:tr>`, `<w:tr>${cell(paragraph("Deliver the goods to the named place."))}${cell(`${paragraph("See the schedule below.")}${NESTED_TABLE}${closingParagraph}`)}</w:tr>`]);
+const buildNestedTableDocx = async ({ trailingParagraph } = {}) => {
+	const body = paragraph("This agreement is made between the parties named below.") + OUTER_TABLE + (trailingParagraph === void 0 ? closingParagraph : `${paragraph(trailingParagraph)}${closingParagraph}`);
+	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>`,
+		"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:styles>`,
+		"word/document.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="${NAMESPACE}"><w:body>${body}<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>`
+	};
+	const zip = new JSZip();
+	for (const name of Object.keys(parts).toSorted()) zip.file(name, parts[name] ?? "", ZIP_ENTRY_OPTIONS);
+	return await zip.generateAsync({ type: "arraybuffer" });
+};
+//#endregion
+export { buildNestedTableDocx };

package/dist/compare/__fixtures__/numbered-list.d.ts

@@ -0,0 +1,34 @@
+//#region src/compare/__fixtures__/numbered-list.d.ts
+/**
+ * A small multi-level numbered list, authored here rather than committed as
+ * bytes.
+ *
+ * The corpus fixtures carry no numbering at all, so a probe that says "an added
+ * list item" while editing an unnumbered paragraph is testing something else
+ * and saying it is testing numbering. Generating the package keeps its content
+ * legible in the diff and keeps the provenance trivial.
+ */
+/**
+ * One item: its indent level and its text. `null` is a paragraph that keeps
+ * the list style and carries no numbering.
+ */
+type NumberedListItem = {
+  level: number | null;
+  text: string;
+};
+declare const NUMBERED_LIST_ITEMS: readonly NumberedListItem[];
+/** The same list with one item demoted one level: a level change and no text change. */
+declare const withItemDemoted: (items: readonly NumberedListItem[], index: number) => NumberedListItem[];
+/**
+ * The same list with one item no longer numbered: the paragraph keeps every
+ * word and stops being a list item, which is the edit a level change cannot
+ * express.
+ */
+declare const withItemUnnumbered: (items: readonly NumberedListItem[], index: number) => NumberedListItem[];
+type NumberedListDocxOptions = {
+  /** `w:numFmt` for the top level. Default `"decimal"`. */
+  format?: string;
+};
+declare const buildNumberedListDocx: (items?: readonly NumberedListItem[], { format }?: NumberedListDocxOptions) => Promise<ArrayBuffer>;
+//#endregion
+export { NUMBERED_LIST_ITEMS, NumberedListDocxOptions, NumberedListItem, buildNumberedListDocx, withItemDemoted, withItemUnnumbered };