@stll/folio-core 0.9.0 → 0.11.0

package/dist/utils/findReplace.d.ts

@@ -0,0 +1,32 @@
+import { document_d_exports } from "../types/document.js";
+import { Paragraph } from "../types/content.js";
+
+//#region src/utils/findReplace.d.ts
+type FindMatch = {
+  paragraphIndex: number;
+  contentIndex: number;
+  startOffset: number;
+  endOffset: number;
+  text: string;
+};
+type FindOptions = {
+  matchCase: boolean;
+  matchWholeWord: boolean;
+  useRegex?: boolean;
+};
+type FindResult = {
+  matches: FindMatch[];
+  totalCount: number;
+  currentIndex: number;
+};
+declare const createDefaultFindOptions: () => FindOptions;
+declare const escapeRegexString: (value: string) => string;
+declare const createSearchPattern: (searchText: string, options: FindOptions) => RegExp | null;
+declare const findAllMatches: (content: string, searchText: string, options: FindOptions) => Array<{
+  start: number;
+  end: number;
+}>;
+declare const findInDocument: (document: document_d_exports.Document | null | undefined, searchText: string, options: FindOptions) => FindMatch[];
+declare const findInParagraph: (paragraph: Paragraph, searchText: string, options: FindOptions, paragraphIndex: number) => FindMatch[];
+//#endregion
+export { FindMatch, FindOptions, FindResult, createDefaultFindOptions, createSearchPattern, escapeRegexString, findAllMatches, findInDocument, findInParagraph };

package/dist/utils/findReplace.js

@@ -0,0 +1,118 @@
+//#region src/utils/findReplace.ts
+const createDefaultFindOptions = () => ({
+	matchCase: false,
+	matchWholeWord: false,
+	useRegex: false
+});
+const escapeRegexString = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+const createSearchPattern = (searchText, options) => {
+	if (!searchText) return null;
+	try {
+		const source = options.useRegex ? searchText : escapeRegexString(searchText);
+		const pattern = options.matchWholeWord ? `\\b${source}\\b` : source;
+		return new RegExp(pattern, options.matchCase ? "gu" : "giu");
+	} catch {
+		return null;
+	}
+};
+const findAllMatches = (content, searchText, options) => {
+	if (!content || !searchText) return [];
+	const searchFor = options.matchCase ? searchText : searchText.toLowerCase();
+	const source = escapeRegexString(searchFor);
+	const pattern = new RegExp(options.matchWholeWord ? `\\b${source}\\b` : source, options.matchCase ? "gu" : "giu");
+	const matches = [];
+	let match;
+	while ((match = pattern.exec(content)) !== null) {
+		matches.push({
+			start: match.index,
+			end: match.index + match[0].length
+		});
+		if (match[0].length === 0) pattern.lastIndex++;
+	}
+	return matches;
+};
+const findInDocument = (document, searchText, options) => {
+	if (!document || !searchText) return [];
+	const body = document.package.document;
+	if (!isRecord(body) || !Array.isArray(body.content)) return [];
+	const matches = [];
+	forEachParagraph(body.content, (paragraph, paragraphIndex) => {
+		matches.push(...findInParagraph(paragraph, searchText, options, paragraphIndex));
+	});
+	return matches;
+};
+const findInParagraph = (paragraph, searchText, options, paragraphIndex) => {
+	const paragraphText = getParagraphPlainText(paragraph);
+	if (!paragraphText) return [];
+	return findAllMatches(paragraphText, searchText, options).map(({ start, end }) => ({
+		paragraphIndex,
+		contentIndex: findContentIndexAtOffset(paragraph, start),
+		startOffset: start,
+		endOffset: end,
+		text: paragraphText.slice(start, end)
+	}));
+};
+const forEachParagraph = (blocks, visit) => {
+	let paragraphIndex = 0;
+	const walkBlocks = (items) => {
+		for (const block of items) {
+			if (isParagraph(block)) {
+				visit(block, paragraphIndex);
+				paragraphIndex++;
+				continue;
+			}
+			if (isTable(block)) {
+				walkTable(block);
+				continue;
+			}
+			if (isBlockSdt(block)) walkBlocks(block.content);
+		}
+	};
+	const walkTable = (table) => {
+		for (const row of table.rows) {
+			if (!isTableRow(row)) continue;
+			for (const cell of row.cells) if (isTableCell(cell)) walkBlocks(cell.content);
+		}
+	};
+	walkBlocks(blocks);
+};
+const getRunText = (run) => {
+	let text = "";
+	for (const item of run.content) if (item.type === "text") text += item.text;
+	else if (item.type === "tab") text += "	";
+	else if (item.type === "break" && item.breakType === "textWrapping") text += "\n";
+	return text;
+};
+const getHyperlinkText = (hyperlink) => {
+	let text = "";
+	for (const child of hyperlink.children) if (child.type === "run") text += getRunText(child);
+	return text;
+};
+const getParagraphContentText = (content) => {
+	if (content.type === "run") return getRunText(content);
+	if (content.type === "hyperlink") return getHyperlinkText(content);
+	if (content.type === "inlineSdt") return content.content.map(getParagraphContentText).join("");
+	if (content.type === "simpleField") return content.content.map((child) => child.type === "run" ? getRunText(child) : getHyperlinkText(child)).join("");
+	if (content.type === "complexField") return content.fieldResult.map(getRunText).join("");
+	return "";
+};
+const getParagraphPlainText = (paragraph) => paragraph.content.map(getParagraphContentText).join("");
+const findContentIndexAtOffset = (paragraph, offset) => {
+	let currentOffset = 0;
+	for (let contentIndex = 0; contentIndex < paragraph.content.length; contentIndex++) {
+		const item = paragraph.content[contentIndex];
+		if (!item) continue;
+		const itemLength = getParagraphContentText(item).length;
+		if (currentOffset + itemLength > offset) return contentIndex;
+		currentOffset += itemLength;
+	}
+	return Math.max(0, paragraph.content.length - 1);
+};
+const isRecord = (value) => typeof value === "object" && value !== null;
+const isParagraph = (value) => isRecord(value) && value["type"] === "paragraph" && Array.isArray(value["content"]);
+const isTable = (value) => isRecord(value) && value["type"] === "table" && Array.isArray(value["rows"]);
+const isTableRow = (value) => isRecord(value) && Array.isArray(value["cells"]);
+const isTableCell = (value) => isRecord(value) && Array.isArray(value["content"]);
+const isBlockSdt = (value) => isRecord(value) && value["type"] === "blockSdt" && Array.isArray(value["content"]);
+//#endregion
+export { createDefaultFindOptions, createSearchPattern, escapeRegexString, findAllMatches, findInDocument, findInParagraph };

package/dist/utils/headerFooter.js

@@ -156,7 +156,18 @@ const createEmptyHeaderFooter = (document, position, isFirstPage) => {
 	const sectionProps = pkg.document.finalSectionProperties;
 	if (!sectionProps) return null;
 	const hdrFtrType = isFirstPage ? "first" : "default";
-	const rId = `rId_new_${position}_${hdrFtrType}`;
+	const baseRId = `rId_new_${position}_${hdrFtrType}`;
+	const usedRIds = /* @__PURE__ */ new Set([
+		...pkg.headers?.keys() ?? [],
+		...pkg.footers?.keys() ?? [],
+		...pkg.relationships?.keys() ?? []
+	]);
+	let rId = baseRId;
+	let rIdSuffix = 2;
+	while (usedRIds.has(rId)) {
+		rId = `${baseRId}_${rIdSuffix}`;
+		rIdSuffix++;
+	}
 	const emptyHf = {
 		type: position,
 		hdrFtrType,
@@ -174,11 +185,23 @@ const createEmptyHeaderFooter = (document, position, isFirstPage) => {
 		type: hdrFtrType,
 		rId
 	};
+	const usedTargets = /* @__PURE__ */ new Set();
+	for (const relationship of pkg.relationships?.values() ?? []) if (relationship.target) usedTargets.add(relationship.target);
+	let targetNumber = 1;
+	while (usedTargets.has(`${position}${targetNumber}.xml`)) targetNumber++;
+	const relationshipType = position === "header" ? "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header" : "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer";
+	const relationships = new Map(pkg.relationships);
+	relationships.set(rId, {
+		id: rId,
+		type: relationshipType,
+		target: `${position}${targetNumber}.xml`
+	});
 	return {
 		...document,
 		package: {
 			...pkg,
 			[mapKey]: newMap,
+			relationships,
 			document: {
 				...pkg.document,
 				finalSectionProperties: {

package/dist/version-comparison.d.ts

@@ -1,59 +1,111 @@
 import { FolioAIBlock } from "./ai-edits/types.js";
+import { FolioDocumentStoryHandle } from "./ai-edits/headless.js";
 import { WordDiffSegment } from "./ai-edits/word-diff.js";
+import { FOLIO_DOCUMENT_METADATA_PROPERTIES, FolioDocumentMetadataProperty, FolioDocumentPrivacyOptions, FolioDocumentPrivacyReport, FolioDocumentPrivacyTransform } from "./docx/metadataPrivacy.js";
 
 //#region src/version-comparison.d.ts
 /** One word-level diff segment within a `modified` block. Mirrors {@link WordDiffSegment}. */
 type FolioVersionDiffSegment = WordDiffSegment;
+/** Independently selectable comparison scopes. */
+declare const FOLIO_VERSION_COMPARISON_SCOPES: readonly ["text", "formatting", "metadata"];
+type FolioVersionComparisonScope = (typeof FOLIO_VERSION_COMPARISON_SCOPES)[number];
+declare const isFolioVersionComparisonScope: (value: unknown) => value is FolioVersionComparisonScope;
+type FolioCompareDocxVersionsOptions = {
+  /** Selected scopes; defaults to text and formatting. */include?: readonly FolioVersionComparisonScope[]; /** Optional output-only privacy transforms. Source buffers are never mutated. */
+  privacy?: FolioVersionDiffPrivacyOptions;
+};
+declare const InvalidFolioVersionComparisonOptionsError_base: import("better-result").TaggedErrorClass<"InvalidFolioVersionComparisonOptionsError", {
+  message: string;
+  option: "include" | "privacy.transforms";
+  receivedValue: unknown;
+}>;
+declare class InvalidFolioVersionComparisonOptionsError extends InvalidFolioVersionComparisonOptionsError_base {}
+type FolioDocumentMetadataValue = string | number | null;
+type FolioMetadataDiff = {
+  property: FolioDocumentMetadataProperty;
+  baseValue: FolioDocumentMetadataValue;
+  revisedValue: FolioDocumentMetadataValue;
+};
+declare const FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS: readonly ["remove-attribution", "remove-timestamps", "remove-descriptive-metadata"];
+type FolioVersionComparisonPrivacyTransform = FolioDocumentPrivacyTransform;
+declare const isFolioVersionComparisonPrivacyTransform: (value: unknown) => value is FolioVersionComparisonPrivacyTransform;
+type FolioVersionDiffPrivacyOptions = FolioDocumentPrivacyOptions;
+type FolioVersionDiffPrivacyReport = FolioDocumentPrivacyReport;
 /** Run-level formatting properties compared for `formatChanged` detection. */
 declare const FORMAT_PROPERTIES: readonly ["bold", "italic", "underline", "strike", "fontFamily", "fontSizePt", "color"];
 /** A run-level formatting property that can differ in a `formatChanged` block. */
 type FolioFormatProperty = (typeof FORMAT_PROPERTIES)[number];
+/** Stable location of one compared block within its source document. */
+type FolioVersionBlockHandle = {
+  story: FolioDocumentStoryHandle;
+  blockId: string;
+};
 /** One block-level change between two document versions, in revised-side document order. */
 type FolioBlockDiff = {
   type: "added";
   blockId: string;
   kind: string;
   text: string;
+  revisedHandle: FolioVersionBlockHandle;
 } | {
   type: "deleted";
   blockId: string;
   kind: string;
   text: string;
+  baseHandle: FolioVersionBlockHandle;
 } | {
   type: "modified";
   blockId: string;
   kind: string;
   segments: FolioVersionDiffSegment[];
+  baseHandle: FolioVersionBlockHandle;
+  revisedHandle: FolioVersionBlockHandle;
 } | {
   type: "formatChanged";
   blockId: string;
   kind: string;
   text: string;
   changedProperties: FolioFormatProperty[];
+  baseHandle: FolioVersionBlockHandle;
+  revisedHandle: FolioVersionBlockHandle;
 } | {
   type: "movedFrom";
   blockId: string;
   kind: string;
   text: string;
   moveGroupId: number;
+  baseHandle: FolioVersionBlockHandle;
 } | {
   type: "movedTo";
   blockId: string;
   kind: string;
   text: string;
   moveGroupId: number;
+  revisedHandle: FolioVersionBlockHandle;
+};
+type FolioVersionDiffSummaryCounts = {
+  added: number;
+  deleted: number;
+  modified: number;
+  formatChanged: number;
+  moved: number;
+  metadataChanged: number;
+  unchanged: number;
+};
+/** Changes within one matched, added, or deleted document story. */
+type FolioStoryDiff = {
+  baseStory: FolioDocumentStoryHandle | null;
+  revisedStory: FolioDocumentStoryHandle | null;
+  changes: FolioBlockDiff[];
+  summaryCounts: FolioVersionDiffSummaryCounts;
 };
 /** Result of {@link compareDocxVersions}. */
 type FolioVersionDiff = {
-  /** Every changed block, in revised-side document order (deletions and move sources slotted where they sat). */changes: FolioBlockDiff[]; /** Counts across every paired/unpaired block, including the unchanged blocks `changes` omits. `moved` counts pairs, not entries. */
-  summaryCounts: {
-    added: number;
-    deleted: number;
-    modified: number;
-    formatChanged: number;
-    moved: number;
-    unchanged: number;
-  };
+  /** Every changed block, in revised-side document order (deletions and move sources slotted where they sat). */changes: FolioBlockDiff[]; /** Per-story results in base order followed by stories added in the revised document. */
+  stories: FolioStoryDiff[]; /** Changed package metadata fields in stable property order. */
+  metadataChanges: FolioMetadataDiff[]; /** Applied privacy policy and the fields it removed from this result. */
+  privacyReport: FolioVersionDiffPrivacyReport; /** Counts across every paired/unpaired block, including the unchanged blocks `changes` omits. `moved` counts pairs, not entries. */
+  summaryCounts: FolioVersionDiffSummaryCounts;
 };
 /** True when an `unpairedBaseCount * unpairedRevisedCount` LCS table would exceed {@link MAX_LCS_CELLS}. */
 declare const exceedsLcsBudget: (unpairedBaseCount: number, unpairedRevisedCount: number) => boolean;
@@ -81,12 +133,14 @@ type FolioAlignedBlockEvent = {
  * one document walk instead of re-deriving it.
  */
 declare const alignFolioBlocks: (baseBlocks: readonly FolioAIBlock[], revisedBlocks: readonly FolioAIBlock[]) => FolioAlignedBlockEvent[];
+/** Apply auditable, output-only privacy transforms to a structured version diff. */
+declare const applyFolioVersionDiffPrivacy: (diff: FolioVersionDiff, options: FolioVersionDiffPrivacyOptions) => FolioVersionDiff;
 /**
  * Compare two `.docx` buffers and return a structured, block-level diff.
  * See the module doc comment for the as-accepted comparison semantics, the
  * three-pass alignment algorithm, move detection, and format-only change
  * detection.
  */
-declare const compareDocxVersions: (base: ArrayBuffer, revised: ArrayBuffer) => Promise<FolioVersionDiff>;
+declare const compareDocxVersions: (base: ArrayBuffer, revised: ArrayBuffer, options?: FolioCompareDocxVersionsOptions) => Promise<FolioVersionDiff>;
 //#endregion
-export { FolioAlignedBlockEvent, FolioBlockDiff, FolioFormatProperty, FolioVersionDiff, FolioVersionDiffSegment, alignFolioBlocks, compareDocxVersions, exceedsLcsBudget };
+export { FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, FolioAlignedBlockEvent, FolioBlockDiff, FolioCompareDocxVersionsOptions, type FolioDocumentMetadataProperty, FolioDocumentMetadataValue, FolioFormatProperty, FolioMetadataDiff, FolioStoryDiff, FolioVersionBlockHandle, FolioVersionComparisonPrivacyTransform, FolioVersionComparisonScope, FolioVersionDiff, FolioVersionDiffPrivacyOptions, FolioVersionDiffPrivacyReport, FolioVersionDiffSegment, FolioVersionDiffSummaryCounts, InvalidFolioVersionComparisonOptionsError, alignFolioBlocks, applyFolioVersionDiffPrivacy, compareDocxVersions, exceedsLcsBudget, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope };

package/dist/version-comparison.js

@@ -1,6 +1,9 @@
 import { getFolioParaIdFromBlockId } from "./types/block-id.js";
 import { diffWordSegments } from "./ai-edits/word-diff.js";
+import { pairFolioDocumentStories } from "./document-stories.js";
 import { FolioDocxReviewer } from "./ai-edits/headless.js";
+import { FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, PRIVATE_METADATA_PROPERTIES_BY_TRANSFORM, isFolioDocumentPrivacyTransform } from "./docx/metadataPrivacy.js";
+import { TaggedError, panic } from "better-result";
 //#region src/version-comparison.ts
 /**
 * Document version-diff engine: compare two `.docx` buffers block by block
@@ -76,6 +79,16 @@ import { FolioDocxReviewer } from "./ai-edits/headless.js";
 * content that makes the preview texts disagree, detection backs off to
 * `unchanged` rather than misattribute properties.
 */
+/** Independently selectable comparison scopes. */
+const FOLIO_VERSION_COMPARISON_SCOPES = Object.freeze([
+	"text",
+	"formatting",
+	"metadata"
+]);
+const isFolioVersionComparisonScope = (value) => FOLIO_VERSION_COMPARISON_SCOPES.some((scope) => scope === value);
+var InvalidFolioVersionComparisonOptionsError = class extends TaggedError("InvalidFolioVersionComparisonOptionsError")() {};
+const FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS = FOLIO_DOCUMENT_PRIVACY_TRANSFORMS;
+const isFolioVersionComparisonPrivacyTransform = (value) => isFolioDocumentPrivacyTransform(value);
 /** Run-level formatting properties compared for `formatChanged` detection. */
 const FORMAT_PROPERTIES = [
 	"bold",
@@ -324,7 +337,7 @@ const meetsMoveWordCount = (text) => {
 * per text, so duplicated boilerplate above the word floor pairs
 * first-to-first rather than fanning out.
 */
-const detectMoves = (changes, counts) => {
+const detectMoves = (changes, counts, firstMoveGroupId) => {
 	const deletedIndexesByText = /* @__PURE__ */ new Map();
 	changes.forEach((change, index) => {
 		if (change.type === "deleted" && meetsMoveWordCount(change.text)) {
@@ -334,7 +347,7 @@ const detectMoves = (changes, counts) => {
 		}
 	});
 	if (deletedIndexesByText.size === 0) return;
-	let moveGroupId = 0;
+	let moveGroupId = firstMoveGroupId - 1;
 	changes.forEach((change, index) => {
 		if (change.type !== "added") return;
 		const deletedIndex = deletedIndexesByText.get(change.text)?.shift();
@@ -347,53 +360,72 @@ const detectMoves = (changes, counts) => {
 			blockId: deleted.blockId,
 			kind: deleted.kind,
 			text: deleted.text,
-			moveGroupId
+			moveGroupId,
+			baseHandle: deleted.baseHandle
 		};
 		changes[index] = {
 			type: "movedTo",
 			blockId: change.blockId,
 			kind: change.kind,
 			text: change.text,
-			moveGroupId
+			moveGroupId,
+			revisedHandle: change.revisedHandle
 		};
 		counts.deleted--;
 		counts.added--;
 		counts.moved++;
 	});
 };
-/**
-* Compare two `.docx` buffers and return a structured, block-level diff.
-* See the module doc comment for the as-accepted comparison semantics, the
-* three-pass alignment algorithm, move detection, and format-only change
-* detection.
-*/
-const compareDocxVersions = async (base, revised) => {
-	const [baseReviewer, revisedReviewer] = await Promise.all([FolioDocxReviewer.fromBuffer(base), FolioDocxReviewer.fromBuffer(revised)]);
-	const baseBlocks = baseReviewer.snapshot().blocks;
-	const revisedBlocks = revisedReviewer.snapshot().blocks;
+const createSummaryCounts = () => ({
+	added: 0,
+	deleted: 0,
+	modified: 0,
+	formatChanged: 0,
+	moved: 0,
+	metadataChanged: 0,
+	unchanged: 0
+});
+const addSummaryCounts = (target, source) => {
+	target.added += source.added;
+	target.deleted += source.deleted;
+	target.modified += source.modified;
+	target.formatChanged += source.formatChanged;
+	target.moved += source.moved;
+	target.metadataChanged += source.metadataChanged;
+	target.unchanged += source.unchanged;
+};
+const compareStoryBlocks = ({ baseStory, revisedStory, baseBlocks, revisedBlocks, firstMoveGroupId, includeText, includeFormatting }) => {
 	const changes = [];
-	const counts = {
-		added: 0,
-		deleted: 0,
-		modified: 0,
-		formatChanged: 0,
-		moved: 0,
-		unchanged: 0
-	};
+	const counts = createSummaryCounts();
 	for (const event of alignFolioBlocks(baseBlocks, revisedBlocks)) {
 		if (event.type === "pair") {
+			if (!baseStory || !revisedStory) panic("A paired comparison event requires both story handles");
 			const { baseBlock, revisedBlock } = event;
+			const baseHandle = {
+				story: baseStory,
+				blockId: baseBlock.id
+			};
+			const revisedHandle = {
+				story: revisedStory,
+				blockId: revisedBlock.id
+			};
 			if (baseBlock.text !== revisedBlock.text) {
+				if (!includeText) {
+					counts.unchanged++;
+					continue;
+				}
 				counts.modified++;
 				changes.push({
 					type: "modified",
 					blockId: revisedBlock.id,
 					kind: revisedBlock.kind,
-					segments: diffWordSegments(baseBlock.text, revisedBlock.text)
+					segments: diffWordSegments(baseBlock.text, revisedBlock.text),
+					baseHandle,
+					revisedHandle
 				});
 				continue;
 			}
-			const changedProperties = diffPreviewRunFormatting(baseBlock, revisedBlock);
+			const changedProperties = includeFormatting ? diffPreviewRunFormatting(baseBlock, revisedBlock) : [];
 			if (changedProperties.length > 0) {
 				counts.formatChanged++;
 				changes.push({
@@ -401,7 +433,9 @@ const compareDocxVersions = async (base, revised) => {
 					blockId: revisedBlock.id,
 					kind: revisedBlock.kind,
 					text: revisedBlock.text,
-					changedProperties
+					changedProperties,
+					baseHandle,
+					revisedHandle
 				});
 				continue;
 			}
@@ -409,28 +443,152 @@ const compareDocxVersions = async (base, revised) => {
 			continue;
 		}
 		if (event.type === "baseOnly") {
+			if (!includeText) continue;
+			if (!baseStory) panic("A base-only comparison event requires a base story handle");
 			counts.deleted++;
 			changes.push({
 				type: "deleted",
 				blockId: event.block.id,
 				kind: event.block.kind,
-				text: event.block.text
+				text: event.block.text,
+				baseHandle: {
+					story: baseStory,
+					blockId: event.block.id
+				}
 			});
 			continue;
 		}
+		if (!includeText) continue;
+		if (!revisedStory) panic("A revised-only comparison event requires a revised story handle");
 		counts.added++;
 		changes.push({
 			type: "added",
 			blockId: event.block.id,
 			kind: event.block.kind,
-			text: event.block.text
+			text: event.block.text,
+			revisedHandle: {
+				story: revisedStory,
+				blockId: event.block.id
+			}
 		});
 	}
-	detectMoves(changes, counts);
+	detectMoves(changes, counts, firstMoveGroupId);
+	return {
+		baseStory,
+		revisedStory,
+		changes,
+		summaryCounts: counts
+	};
+};
+const DEFAULT_COMPARISON_SCOPES = Object.freeze(["text", "formatting"]);
+const resolveComparisonScopes = (options) => {
+	const include = options.include ?? DEFAULT_COMPARISON_SCOPES;
+	if (include.length === 0 || include.some((scope) => !isFolioVersionComparisonScope(scope))) throw new InvalidFolioVersionComparisonOptionsError({
+		message: "Version comparison requires at least one recognized scope",
+		option: "include",
+		receivedValue: include
+	});
+	return new Set(include);
+};
+const resolvePrivacyTransforms = (transforms) => {
+	if (!Array.isArray(transforms) || transforms.some((transform) => !isFolioVersionComparisonPrivacyTransform(transform))) throw new InvalidFolioVersionComparisonOptionsError({
+		message: "Version comparison received an unrecognized privacy transform",
+		option: "privacy.transforms",
+		receivedValue: transforms
+	});
+	const requested = new Set(transforms);
+	return FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS.filter((transform) => requested.has(transform));
+};
+/** Apply auditable, output-only privacy transforms to a structured version diff. */
+const applyFolioVersionDiffPrivacy = (diff, options) => {
+	const requestedTransforms = resolvePrivacyTransforms(options.transforms);
+	const appliedTransformSet = /* @__PURE__ */ new Set([...diff.privacyReport.appliedTransforms, ...requestedTransforms]);
+	const appliedTransforms = FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS.filter((transform) => appliedTransformSet.has(transform));
+	const removedPropertySet = /* @__PURE__ */ new Set();
+	for (const transform of appliedTransforms) for (const property of PRIVATE_METADATA_PROPERTIES_BY_TRANSFORM[transform]) removedPropertySet.add(property);
+	const actuallyRemovedPropertySet = /* @__PURE__ */ new Set([...diff.privacyReport.removedMetadataProperties, ...diff.metadataChanges.filter(({ property }) => removedPropertySet.has(property)).map(({ property }) => property)]);
+	const removedMetadataProperties = FOLIO_DOCUMENT_METADATA_PROPERTIES.filter((property) => actuallyRemovedPropertySet.has(property));
+	const metadataChanges = diff.metadataChanges.filter(({ property }) => !removedPropertySet.has(property));
 	return {
+		...diff,
+		metadataChanges,
+		privacyReport: {
+			appliedTransforms,
+			removedMetadataProperties
+		},
+		summaryCounts: {
+			...diff.summaryCounts,
+			metadataChanged: metadataChanges.length
+		}
+	};
+};
+const normalizeMetadataValue = (properties, property) => {
+	const value = properties?.[property];
+	return value instanceof Date ? value.toISOString() : value ?? null;
+};
+const compareMetadata = (base, revised) => {
+	const changes = [];
+	for (const property of FOLIO_DOCUMENT_METADATA_PROPERTIES) {
+		const baseValue = normalizeMetadataValue(base, property);
+		const revisedValue = normalizeMetadataValue(revised, property);
+		if (baseValue !== revisedValue) changes.push({
+			property,
+			baseValue,
+			revisedValue
+		});
+	}
+	return changes;
+};
+/**
+* Compare two `.docx` buffers and return a structured, block-level diff.
+* See the module doc comment for the as-accepted comparison semantics, the
+* three-pass alignment algorithm, move detection, and format-only change
+* detection.
+*/
+const compareDocxVersions = async (base, revised, options = {}) => {
+	const scopes = resolveComparisonScopes(options);
+	const [baseReviewer, revisedReviewer] = await Promise.all([FolioDocxReviewer.fromBuffer(base), FolioDocxReviewer.fromBuffer(revised)]);
+	const changes = [];
+	const stories = [];
+	const counts = createSummaryCounts();
+	const baseStories = baseReviewer.listStories().map(({ handle }) => handle);
+	const revisedStories = revisedReviewer.listStories().map(({ handle }) => handle);
+	let nextMoveGroupId = 1;
+	for (const pair of pairFolioDocumentStories(baseStories, revisedStories)) {
+		const baseBlocks = pair.baseStory ? baseReviewer.readReviewedStory({
+			story: pair.baseStory,
+			view: "final"
+		})?.snapshot.blocks ?? [] : [];
+		const revisedBlocks = pair.revisedStory ? revisedReviewer.readReviewedStory({
+			story: pair.revisedStory,
+			view: "final"
+		})?.snapshot.blocks ?? [] : [];
+		const storyDiff = compareStoryBlocks({
+			...pair,
+			baseBlocks,
+			revisedBlocks,
+			firstMoveGroupId: nextMoveGroupId,
+			includeText: scopes.has("text"),
+			includeFormatting: scopes.has("formatting")
+		});
+		stories.push(storyDiff);
+		for (const change of storyDiff.changes) changes.push(change);
+		addSummaryCounts(counts, storyDiff.summaryCounts);
+		nextMoveGroupId += storyDiff.summaryCounts.moved;
+	}
+	const metadataChanges = scopes.has("metadata") ? compareMetadata(baseReviewer.getDocumentProperties(), revisedReviewer.getDocumentProperties()) : [];
+	counts.metadataChanged = metadataChanges.length;
+	const diff = {
 		changes,
+		stories,
+		metadataChanges,
+		privacyReport: {
+			appliedTransforms: [],
+			removedMetadataProperties: []
+		},
 		summaryCounts: counts
 	};
+	return options.privacy ? applyFolioVersionDiffPrivacy(diff, options.privacy) : diff;
 };
 //#endregion
-export { alignFolioBlocks, compareDocxVersions, exceedsLcsBudget };
+export { FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, InvalidFolioVersionComparisonOptionsError, alignFolioBlocks, applyFolioVersionDiffPrivacy, compareDocxVersions, exceedsLcsBudget, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",