@stll/folio-core 0.8.0 → 0.10.0

package/dist/utils/fontResolver.js

@@ -59,9 +59,9 @@ const APTOS_MEASURED_LINE_HEIGHT = {
 * font's `FontLineHeight`, never hand-written. For "hhea" entries the raw
 * `hheaAscent`/`hheaDescent`/`hheaLineGap`/`unitsPerEm` fields below are read
 * directly from the real font files' `hhea` table; the ratio is whatever
-* falls out of the formula in `singleLineRatioOf`. "legacy" entries (e.g.
-* garamond, lucida sans, lucida console) are unverified hand-transcribed
-* ratios carried over unchanged, pending measurement.
+* falls out of the formula in `singleLineRatioOf`. The remaining "legacy"
+* entry (lucida sans) is an unverified hand-transcribed ratio carried over
+* unchanged, pending measurement.
 */
 const FONT_MAPPINGS = {
 	aptos: {
@@ -355,9 +355,9 @@ const FONT_MAPPINGS = {
 			"serif"
 		],
 		singleLineRatio: singleLineRatioOf({
-			source: "legacy",
-			ratio: 1.068,
-			note: "Unverified hand-transcribed ratio; not yet measured against real Word output."
+			source: "measured",
+			ratio: 1.1273,
+			note: "Measured at 11pt against a 12.4pt reference-layout line pitch."
 		})
 	},
 	"century gothic": {

package/dist/utils/formatToStyle.js

@@ -1,6 +1,6 @@
 import { AUTO_PARAGRAPH_SPACING_PX, eighthsToPixels, formatPx, halfPointsToPixels, halfPointsToPoints, twipsToPixels } from "./units.js";
-import { resolveFontFamily, resolveThemeFont } from "./fontResolver.js";
 import { resolveColor, resolveHighlightToCss, resolveShadingColor } from "./colorResolver.js";
+import { resolveFontFamily, resolveThemeFont } from "./fontResolver.js";
 //#region src/utils/formatToStyle.ts
 /**
 * Convert TextFormatting to CSS properties for a run/span

package/dist/utils/paragraphFormattingMerge.d.ts

@@ -1,14 +1,25 @@
 import { document_d_exports } from "../types/document.js";
 
 //#region src/utils/paragraphFormattingMerge.d.ts
+/**
+ * Merge custom tab stops across OOXML paragraph-property layers.
+ *
+ * Tabs cascade by position rather than replacing the inherited collection:
+ * a higher-priority stop supersedes the stop at the same position, while a
+ * `clear` stop removes that inherited position during layout. Keeping the
+ * clear entry also lets the tab calculator suppress an automatic stop at the
+ * same position.
+ */
+declare function mergeParagraphTabStops(inherited: document_d_exports.TabStop[] | undefined, direct: document_d_exports.TabStop[]): document_d_exports.TabStop[];
+declare function mergeParagraphTabStops(inherited: document_d_exports.TabStop[] | undefined, direct: document_d_exports.TabStop[] | undefined): document_d_exports.TabStop[] | undefined;
 /**
  * Merge paragraph properties for OOXML style cascade resolution.
  *
  * The source is the higher-priority layer. Most `w:pPr` properties replace an
  * inherited value when present; nested child containers merge by child field;
- * tabs replace as a complete ordered collection; paragraph mark `w:rPr` uses
- * the run-formatting merge rules.
+ * tabs merge by position; paragraph mark `w:rPr` uses the run-formatting
+ * merge rules.
  */
 declare function mergeParagraphFormatting(target: document_d_exports.ParagraphFormatting | undefined, source: document_d_exports.ParagraphFormatting | undefined): document_d_exports.ParagraphFormatting | undefined;
 //#endregion
-export { mergeParagraphFormatting };
+export { mergeParagraphFormatting, mergeParagraphTabStops };

package/dist/utils/paragraphFormattingMerge.js

@@ -3,6 +3,8 @@ import { mergeTextFormatting } from "./textFormattingMerge.js";
 const PARAGRAPH_REPLACE_KEYS = [
 	"alignment",
 	"bidi",
+	"kinsoku",
+	"overflowPunctuation",
 	"spaceBefore",
 	"spaceAfter",
 	"lineSpacing",
@@ -30,13 +32,20 @@ const copyDefinedParagraphProperty = (target, source, key) => {
 	const value = source[key];
 	if (value !== void 0) target[key] = value;
 };
+function mergeParagraphTabStops(inherited, direct) {
+	if (direct === void 0) return inherited === void 0 ? void 0 : [...inherited];
+	const stopsByPosition = /* @__PURE__ */ new Map();
+	for (const stop of inherited ?? []) stopsByPosition.set(stop.position, stop);
+	for (const stop of direct) stopsByPosition.set(stop.position, stop);
+	return [...stopsByPosition.values()].toSorted((a, b) => a.position - b.position);
+}
 /**
 * Merge paragraph properties for OOXML style cascade resolution.
 *
 * The source is the higher-priority layer. Most `w:pPr` properties replace an
 * inherited value when present; nested child containers merge by child field;
-* tabs replace as a complete ordered collection; paragraph mark `w:rPr` uses
-* the run-formatting merge rules.
+* tabs merge by position; paragraph mark `w:rPr` uses the run-formatting
+* merge rules.
 */
 function mergeParagraphFormatting(target, source) {
 	if (!source) return target;
@@ -47,6 +56,7 @@ function mergeParagraphFormatting(target, source) {
 	}
 	const result = { ...target };
 	for (const key of PARAGRAPH_REPLACE_KEYS) copyDefinedParagraphProperty(result, source, key);
+	if (source.indentFirstLine !== void 0) result.hangingIndent = source.hangingIndent === true;
 	const mergedRunProperties = mergeTextFormatting(result.runProperties, source.runProperties);
 	if (mergedRunProperties) result.runProperties = mergedRunProperties;
 	if (source.borders !== void 0) result.borders = {
@@ -61,8 +71,8 @@ function mergeParagraphFormatting(target, source) {
 		...result.frame,
 		...source.frame
 	};
-	if (source.tabs !== void 0) result.tabs = [...source.tabs];
+	if (source.tabs !== void 0) result.tabs = mergeParagraphTabStops(result.tabs, source.tabs);
 	return result;
 }
 //#endregion
-export { mergeParagraphFormatting };
+export { mergeParagraphFormatting, mergeParagraphTabStops };

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.8.0",
+  "version": "0.10.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",
@@ -113,6 +113,7 @@
     "better-result": "2.9.2",
     "csstype": "^3.1.3",
     "fast-xml-parser": "^5.9.3",
+    "hyphen": "1.14.1",
     "jszip": "3.10.1",
     "marked": "^18.0.5",
     "prosemirror-commands": "^1.7.1",
@@ -130,6 +131,9 @@
     "y-prosemirror": "^1.3.7",
     "yjs": "^13.6.31"
   },
+  "devDependencies": {
+    "@types/hyphen": "1.14.0"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [

package/dist/docx/capabilities.d.ts

@@ -1,41 +0,0 @@
-//#region src/docx/capabilities.d.ts
-declare const FOLIO_DOCX_CAPABILITY_MANIFEST_VERSION: 1;
-declare const FOLIO_DOCX_CAPABILITY_HOSTS: readonly ["browser", "server"];
-declare const FOLIO_DOCX_COMPATIBILITY_HOSTS: readonly ["browser", "server", "unknown"];
-declare const FOLIO_DOCX_PROFILES: readonly ["strict", "transitional"];
-declare const FOLIO_DOCX_COMPATIBILITY_PROFILES: readonly ["strict", "transitional", "unknown"];
-declare const FOLIO_DOCX_CAPABILITY_OPERATIONS: readonly ["create", "edit", "preserve", "read", "render"];
-declare const FOLIO_DOCX_SUPPORT_STATES: readonly ["supported", "partial", "unsupported"];
-declare const FOLIO_DOCX_CAPABILITY_IDS: readonly ["comments", "contentControls", "fields", "headersFooters", "hyperlinks", "images", "math", "notes", "numbering", "opaqueDrawing", "paragraphs", "sections", "styles", "tables", "trackedChanges"];
-type FolioDocxCapabilityHost = (typeof FOLIO_DOCX_CAPABILITY_HOSTS)[number];
-type FolioDocxCompatibilityHost = (typeof FOLIO_DOCX_COMPATIBILITY_HOSTS)[number];
-type FolioDocxProfile = (typeof FOLIO_DOCX_PROFILES)[number];
-type FolioDocxCompatibilityProfile = (typeof FOLIO_DOCX_COMPATIBILITY_PROFILES)[number];
-type FolioDocxCapabilityOperation = (typeof FOLIO_DOCX_CAPABILITY_OPERATIONS)[number];
-type FolioDocxSupportState = (typeof FOLIO_DOCX_SUPPORT_STATES)[number];
-type FolioDocxCapabilityId = (typeof FOLIO_DOCX_CAPABILITY_IDS)[number];
-type FolioDocxFeatureCapability = {
-  readonly id: FolioDocxCapabilityId;
-  readonly feature: "comments" | "contentControls" | "drawings" | "fields" | "headersFooters" | "hyperlinks" | "images" | "math" | "notes" | "numbering" | "paragraphs" | "revisions" | "sections" | "styles" | "tables";
-  readonly hosts: readonly FolioDocxCapabilityHost[];
-  readonly profiles: readonly FolioDocxProfile[];
-  readonly support: Readonly<Record<FolioDocxCapabilityOperation, FolioDocxSupportState>>;
-  readonly evidence: readonly {
-    readonly type: "test";
-    readonly path: string;
-  }[];
-};
-type FolioDocxCapabilityManifest = {
-  readonly version: typeof FOLIO_DOCX_CAPABILITY_MANIFEST_VERSION;
-  readonly capabilities: Readonly<Record<FolioDocxCapabilityId, FolioDocxFeatureCapability>>;
-};
-declare const FOLIO_DOCX_CAPABILITY_MANIFEST: FolioDocxCapabilityManifest;
-declare const InvalidFolioDocxCapabilityIdError_base: import("better-result").TaggedErrorClass<"InvalidFolioDocxCapabilityIdError", {
-  message: string;
-  receivedId: unknown;
-}>;
-declare class InvalidFolioDocxCapabilityIdError extends InvalidFolioDocxCapabilityIdError_base {}
-declare const isFolioDocxCapabilityId: (value: unknown) => value is FolioDocxCapabilityId;
-declare const getFolioDocxCapability: (id: unknown) => FolioDocxFeatureCapability;
-//#endregion
-export { FOLIO_DOCX_CAPABILITY_HOSTS, FOLIO_DOCX_CAPABILITY_IDS, FOLIO_DOCX_CAPABILITY_MANIFEST, FOLIO_DOCX_CAPABILITY_MANIFEST_VERSION, FOLIO_DOCX_CAPABILITY_OPERATIONS, FOLIO_DOCX_COMPATIBILITY_HOSTS, FOLIO_DOCX_COMPATIBILITY_PROFILES, FOLIO_DOCX_PROFILES, FOLIO_DOCX_SUPPORT_STATES, FolioDocxCapabilityHost, FolioDocxCapabilityId, FolioDocxCapabilityManifest, FolioDocxCapabilityOperation, FolioDocxCompatibilityHost, FolioDocxCompatibilityProfile, FolioDocxFeatureCapability, FolioDocxProfile, FolioDocxSupportState, InvalidFolioDocxCapabilityIdError, getFolioDocxCapability, isFolioDocxCapabilityId };