@stll/folio-core 0.32.2 → 0.33.0

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,33 @@
+//#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 body-level item: a paragraph, or a table given row by row. */
+type BodyItem = {
+  kind: "paragraph";
+  text: string;
+  styleId?: 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[];
+};
+declare const buildBodySequenceDocx: (items: readonly BodyItem[]) => Promise<ArrayBuffer>;
+//#endregion
+export { BodyItem, CellContent, buildBodySequenceDocx };

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

@@ -0,0 +1,67 @@
+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";
+/**
+* `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
+};
+/**
+* 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) => {
+	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 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) => typeof content === "string" ? paragraph(content) : itemsXml(closedSequence(content));
+const table = (item) => {
+	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>`;
+};
+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 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: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>"
+	};
+	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 };

package/dist/compare/__fixtures__/numbered-list.js

@@ -0,0 +1,85 @@
+import JSZip from "jszip";
+//#region src/compare/__fixtures__/numbered-list.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.
+*/
+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 LIST_LEVELS = 3;
+const abstractLevels = (topLevelFormat) => Array.from({ length: LIST_LEVELS }, (_unused, level) => {
+	return `<w:lvl w:ilvl="${String(level)}"><w:start w:val="1"/><w:numFmt w:val="${level === 0 ? topLevelFormat : "lowerLetter"}"/><w:lvlText w:val="%${String(level + 1)}."/><w:lvlJc w:val="left"/></w:lvl>`;
+}).join("");
+const listParagraph = (level, text) => {
+	return `<w:p><w:pPr><w:pStyle w:val="ListParagraph"/>${level === null ? "" : `<w:numPr><w:ilvl w:val="${String(level)}"/><w:numId w:val="1"/></w:numPr>`}</w:pPr><w:r><w:t xml:space="preserve">${text}</w:t></w:r></w:p>`;
+};
+const NUMBERED_LIST_ITEMS = Object.freeze([
+	{
+		level: 0,
+		text: "The supplier shall deliver the goods to the named place."
+	},
+	{
+		level: 1,
+		text: "Delivery is complete on unloading at that place."
+	},
+	{
+		level: 1,
+		text: "Risk passes to the buyer on completion of delivery."
+	},
+	{
+		level: 0,
+		text: "The buyer shall pay within thirty days of the invoice date."
+	},
+	{
+		level: 1,
+		text: "Late payment carries interest at the statutory rate."
+	},
+	{
+		level: 0,
+		text: "Either party may terminate for material breach."
+	}
+]);
+/** The same list with one item demoted one level: a level change and no text change. */
+const withItemDemoted = (items, index) => items.map((item, at) => at === index ? {
+	level: Math.min(LIST_LEVELS - 1, (item.level ?? 0) + 1),
+	text: item.text
+} : item);
+/**
+* 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.
+*/
+const withItemUnnumbered = (items, index) => items.map((item, at) => at === index ? {
+	level: null,
+	text: item.text
+} : item);
+const buildNumberedListDocx = async (items = NUMBERED_LIST_ITEMS, { format = "decimal" } = {}) => {
+	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"/><Override PartName="/word/numbering.xml" ContentType="${WORDPROCESSING}.numbering+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"/><Relationship Id="rId2" Type="${OFFICE_RELATIONSHIPS}/numbering" Target="numbering.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:style w:type="paragraph" w:styleId="ListParagraph"><w:name w:val="List Paragraph"/></w:style></w:styles>`,
+		"word/numbering.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:numbering xmlns:w="${NAMESPACE}"><w:abstractNum w:abstractNumId="0">${abstractLevels(format)}</w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num></w:numbering>`,
+		"word/document.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="${NAMESPACE}"><w:body>` + items.map(({ level, text }) => listParagraph(level, text)).join("") + "<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 { NUMBERED_LIST_ITEMS, buildNumberedListDocx, withItemDemoted, withItemUnnumbered };

package/dist/compare/column-alignment.d.ts

@@ -0,0 +1,27 @@
+import { FolioAIBlock, FolioAIBlockTableLocation } from "../ai-edits/types.js";
+//#region src/compare/column-alignment.d.ts
+type TableColumnAlignmentStep = {
+  type: "baseColumn";
+  blocks: readonly FolioAIBlock[];
+  location: FolioAIBlockTableLocation;
+  columnIndex: number;
+} | {
+  type: "targetColumn";
+  blocks: readonly FolioAIBlock[];
+  location: FolioAIBlockTableLocation;
+  columnIndex: number;
+  anchor: {
+    blockId: string;
+    position: "after" | "before";
+  };
+};
+type TableColumnAlignment = {
+  steps: TableColumnAlignmentStep[];
+  baseBlocks: FolioAIBlock[];
+  targetBlocks: FolioAIBlock[];
+  baseColumnKeys: ReadonlyMap<number, number>;
+  targetColumnKeys: ReadonlyMap<number, number>;
+};
+declare const alignTableColumns: (baseBlocks: readonly FolioAIBlock[], targetBlocks: readonly FolioAIBlock[]) => TableColumnAlignment | null;
+//#endregion
+export { TableColumnAlignment, TableColumnAlignmentStep, alignTableColumns };