@stll/folio-core 0.9.0 → 0.10.0

package/dist/redline.js

@@ -1,75 +1,35 @@
-import { FolioDocxReviewer } from "./ai-edits/headless.js";
+import "./document-operations.js";
+import { pairFolioDocumentStories } from "./document-stories.js";
+import { FolioDocxReviewer, isFolioResolvedReviewedView } from "./ai-edits/headless.js";
+import { resolveFolioDocumentPrivacyTransforms, rewriteDocxMetadataPrivacy } from "./docx/metadataPrivacy.js";
 import { alignFolioBlocks } from "./version-comparison.js";
+import { TaggedError, panic } from "better-result";
 //#region src/redline.ts
 /**
-* Redline generator: compare two `.docx` buffers and produce a THIRD `.docx`
-* whose differences are recorded as real Word tracked changes (`w:ins` /
-* `w:del`), ready for review in Word or the folio editor — the
-* document-producing counterpart to {@link compareDocxVersions}'s structured
-* diff.
+* Compare two `.docx` buffers and produce a third buffer whose text
+* differences are represented as tracked changes.
 *
-* The pipeline is a composition of existing machinery, not a new engine:
-* the base buffer is opened in a headless {@link FolioDocxReviewer}, the two
-* snapshots are aligned with {@link alignFolioBlocks} (the same three-pass
-* alignment the comparer uses), each alignment event maps onto a
-* tracked-changes {@link FolioAIEditOperation}, and the reviewer's shared
-* apply path records them as redlines. Word-level minimality comes free:
-* the apply engine word-diffs a `replaceBlock` and only marks the divergent
-* tokens.
-*
-* ## Semantics and limitations
-*
-* - **As-accepted inputs.** Pending tracked changes in either input count as
-*   applied before comparison (mirroring {@link compareDocxVersions}): the
-*   base's own pending redlines are accepted in the output, so the tracked
-*   changes it carries are exactly base → revised. This is intentionally
-*   lossy about the inputs' own revision history and authorship.
-* - **Text redlines only.** Format-only changes and relocated blocks are
-*   redlined as plain edits (a move becomes a delete + insert, like Word
-*   compare with move detection off); block-level formatting is carried via
-*   the revised block's `styleId` on inserted blocks.
-* - **Anchoring.** Insertions anchor `before` the next surviving base block
-*   so consecutive additions keep their order; additions past the last base
-*   block anchor `after` it. A base document with no content blocks offers
-*   no anchor at all — such additions surface in `skipped` rather than
-*   silently vanishing.
-*/
-/**
-* For each event index, the base block id the next `revisedOnly` event
-* should anchor before: the base side of the nearest later `pair` or
-* `baseOnly` event, or `null` when only additions remain until the end of
-* the document. One backward pass, so a long run of trailing additions
-* (huge revised document vs. a small base) stays linear instead of
-* re-scanning the tail per added block.
+* Each matched editable story is processed independently through the shared
+* block alignment and document-operation paths. Package parts that exist on
+* only one side are reported because creating or removing those parts is a
+* distinct package-level operation.
 */
+var InvalidGenerateRedlineDocxOptionsError = class extends TaggedError("InvalidGenerateRedlineDocxOptionsError")() {};
 const nextBaseBlockIdByIndex = (events) => {
 	const nextIds = Array.from({ length: events.length });
 	let nextId = null;
-	for (let i = events.length - 1; i >= 0; i--) {
-		nextIds[i] = nextId;
-		const event = events[i];
+	for (let index = events.length - 1; index >= 0; index--) {
+		nextIds[index] = nextId;
+		const event = events[index];
 		if (event?.type === "pair") nextId = event.baseBlock.id;
 		else if (event?.type === "baseOnly") nextId = event.block.id;
 	}
 	return nextIds;
 };
-/**
-* Compare `base` and `revised` and return the base document with every
-* difference recorded as a tracked change. See the module doc comment for
-* semantics and limitations; `skipped` reports any block the generator could
-* not redline (e.g. additions with no anchor in an empty base document).
-*/
-const generateRedlineDocx = async (base, revised, options = {}) => {
-	const [baseReviewer, revisedReviewer] = await Promise.all([FolioDocxReviewer.fromBuffer(base, { author: options.author ?? "folio compare" }), FolioDocxReviewer.fromBuffer(revised)]);
-	baseReviewer.acceptAll();
-	const baseSnapshot = baseReviewer.snapshot();
-	const revisedBlocks = revisedReviewer.snapshot().blocks;
+const buildRedlineOperations = ({ baseSnapshot, revisedBlocks, nextOperationId }) => {
 	const events = alignFolioBlocks(baseSnapshot.blocks, revisedBlocks);
 	const anchorIds = nextBaseBlockIdByIndex(events);
 	const operations = [];
-	let operationSeq = 0;
-	const nextOperationId = () => `redline-${++operationSeq}`;
-	/** Additions past the last base block, kept in revised-document order. */
 	const trailingAdditions = [];
 	const lastBaseBlockId = baseSnapshot.blocks.at(-1)?.id ?? null;
 	events.forEach((event, eventIndex) => {
@@ -123,15 +83,88 @@ const generateRedlineDocx = async (base, revised, options = {}) => {
 		text: addition.text,
 		...addition.styleId !== void 0 && { styleId: addition.styleId }
 	});
-	const { applied, skipped } = baseReviewer.applyOperations(operations, {
-		mode: "tracked-changes",
-		snapshot: baseSnapshot
+	return operations;
+};
+const resolveInputView = (value, option) => {
+	if (value === void 0) return "final";
+	if (!isFolioResolvedReviewedView(value)) throw new InvalidGenerateRedlineDocxOptionsError({
+		message: `${option} must be original or final.`,
+		option,
+		receivedValue: value
 	});
+	return value;
+};
+/** Compare two buffers and return tracked changes for every matched editable story. */
+const generateRedlineDocx = async (base, revised, options = {}) => {
+	const baseView = resolveInputView(options.baseView, "baseView");
+	const revisedView = resolveInputView(options.revisedView, "revisedView");
+	const privacyTransforms = resolveFolioDocumentPrivacyTransforms(options.privacy?.transforms ?? []);
+	const [baseReviewer, revisedReviewer] = await Promise.all([FolioDocxReviewer.fromBuffer(base, { author: options.author ?? "folio compare" }), FolioDocxReviewer.fromBuffer(revised)]);
+	const baseStories = baseReviewer.listStories().map(({ handle }) => handle);
+	const revisedStories = revisedReviewer.listStories().map(({ handle }) => handle);
+	for (const story of baseStories) if (!baseReviewer.resolveReviewedStory({
+		story,
+		view: baseView
+	})) panic("A listed base story could not be resolved");
+	const applied = [];
+	const skipped = [];
+	const unprocessedStories = [];
+	let operationSequence = 0;
+	const nextOperationId = () => `redline-${++operationSequence}`;
+	for (const pair of pairFolioDocumentStories(baseStories, revisedStories)) {
+		if (!pair.baseStory) {
+			unprocessedStories.push({
+				...pair,
+				reason: "missing-base-story"
+			});
+			continue;
+		}
+		if (!pair.revisedStory) {
+			unprocessedStories.push({
+				...pair,
+				reason: "missing-revised-story"
+			});
+			continue;
+		}
+		const baseSnapshot = baseReviewer.snapshotStory(pair.baseStory);
+		const revisedSnapshot = revisedReviewer.readReviewedStory({
+			story: pair.revisedStory,
+			view: revisedView
+		})?.snapshot;
+		if (!baseSnapshot || !revisedSnapshot) panic("A matched document story could not be read");
+		const operations = buildRedlineOperations({
+			baseSnapshot,
+			revisedBlocks: revisedSnapshot.blocks,
+			nextOperationId
+		});
+		if (operations.length === 0) continue;
+		const result = baseReviewer.applyDocumentOperationsToStory({
+			story: pair.baseStory,
+			snapshot: baseSnapshot,
+			batch: {
+				version: 1,
+				mode: "tracked-changes",
+				operations
+			}
+		});
+		applied.push(...result.applied);
+		skipped.push(...result.skipped);
+	}
+	const redlineBuffer = await baseReviewer.toBuffer();
+	const privacyResult = privacyTransforms.length === 0 ? {
+		buffer: redlineBuffer,
+		privacyReport: {
+			appliedTransforms: [],
+			removedMetadataProperties: []
+		}
+	} : await rewriteDocxMetadataPrivacy(redlineBuffer, { transforms: privacyTransforms });
 	return {
-		buffer: await baseReviewer.toBuffer(),
+		buffer: privacyResult.buffer,
 		applied,
-		skipped
+		skipped,
+		unprocessedStories,
+		privacyReport: privacyResult.privacyReport
 	};
 };
 //#endregion
-export { generateRedlineDocx };
+export { InvalidGenerateRedlineDocxOptionsError, generateRedlineDocx };

package/dist/server.d.ts

@@ -1,7 +1,7 @@
 import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIComment, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditSnapshot, FolioAIInlineFormatting, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult } from "./ai-edits/types.js";
 import { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "./document-operations.js";
 import { FolioReviewChange, FolioReviewChangeKind } from "./ai-edits/read.js";
-import { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioReviewChangeFilter, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, applyFolioAIEditsToBuffer } from "./ai-edits/headless.js";
+import { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, FolioReviewChangeFilter, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, isFolioResolvedReviewedView, isFolioReviewedView } from "./ai-edits/headless.js";
 import { createFolioAITextRangeHandle } from "./ai-edits/snapshot.js";
 import { getFolioDocumentOutline, readFolioDocumentSection } from "./ai-edits/scoped-reading.js";
 import { DeriveBlockIdInput, FolioBlockId, deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId } from "./types/block-id.js";
@@ -11,9 +11,10 @@ import { DocumentStyleCatalog, DocumentStyleCatalogEntry, ExtractDocumentStyleSe
 import { STELLA_STYLE_SET_NAME, createStellaStyleDocumentPreset, createStellaStyleSet } from "./style-sets/stellaStyle.js";
 import { createDocx } from "./docx/rezip.js";
 import { EnsureParaIdsError, EnsureParaIdsOptions, EnsureParaIdsResult, ensureParaIds } from "./docx/ensureParaIds.js";
+import { FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, FolioDocumentMetadataProperty, FolioDocumentPrivacyArchiveError, FolioDocumentPrivacyOptions, FolioDocumentPrivacyReport, FolioDocumentPrivacyTransform, InvalidFolioDocumentPrivacyOptionsError, RewriteDocxMetadataPrivacyResult, isFolioDocumentPrivacyTransform, rewriteDocxMetadataPrivacy } from "./docx/metadataPrivacy.js";
 import { CreateCommentReplyInput, replyToComment } from "./docx/replyToComment.js";
 import { DocxArchiveError } from "./docx/server/boundedArchive.js";
 import { DocxParagraphSource, ExtractedDocxParagraph, ExtractedDocxText, extractDocxText } from "./docx/server/extractDocxText.js";
-import { GenerateRedlineDocxOptions, GenerateRedlineDocxResult, generateRedlineDocx } from "./redline.js";
-import { FolioBlockDiff, FolioFormatProperty, FolioVersionDiff, FolioVersionDiffSegment, compareDocxVersions } from "./version-comparison.js";
-export { type ApplyFolioAIEditsToBufferOptions, type ApplyFolioAIEditsToBufferResult, type CreateCommentReplyInput, type CreateEmptyDocumentOptions, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, type DeriveBlockIdInput, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, DocxArchiveError, type DocxParagraphSource, EnsureParaIdsError, type EnsureParaIdsOptions, type EnsureParaIdsResult, type ExtractDocumentStyleSetOptions, type ExtractedDocxParagraph, type ExtractedDocxText, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIComment, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditSnapshot, type FolioAIInlineFormatting, type FolioAITextRangeHandle, type FolioApplyDocumentOperationsOptions, type FolioApplyDocumentOperationsToStoryOptions, type FolioApplyOperationsOptions, type FolioBlockDiff, type FolioBlockId, type FolioDocumentNavigationTarget, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocumentOutline, type FolioDocumentOutlineEntry, type FolioDocumentSection, type FolioDocumentSectionHandle, type FolioDocumentSectionReadResult, type FolioDocumentStory, type FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, type FolioDocxReviewerOptions, type FolioEditableDocumentStoryHandle, type FolioFormatProperty, type FolioReviewChange, type FolioReviewChangeFilter, type FolioReviewChangeKind, type FolioReviewComment, type FolioReviewCommentFilter, type FolioReviewCommentReply, type FolioReviewReplyInput, type FolioVersionDiff, type FolioVersionDiffSegment, type GenerateRedlineDocxOptions, type GenerateRedlineDocxResult, InvalidFolioDocumentOperationBatchError, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, applyFolioAIEditsToBuffer, assertSupportedFolioDocumentOperationVersion, compareDocxVersions, createDocx, createEmptyDocument, createFolioAITextRangeHandle, createStellaStyleDocumentPreset, createStellaStyleSet, deriveBlockId, ensureParaIds, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractDocxText, generateRedlineDocx, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, inspectDocumentStyles, inspectDocumentStylesFromDocx, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch, readFolioDocumentSection, replyToComment };
+import { GenerateRedlineDocxOptions, GenerateRedlineDocxResult, GenerateRedlineUnprocessedStory, InvalidGenerateRedlineDocxOptionsError, generateRedlineDocx } from "./redline.js";
+import { FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, FolioBlockDiff, FolioCompareDocxVersionsOptions, FolioDocumentMetadataValue, FolioFormatProperty, FolioMetadataDiff, FolioStoryDiff, FolioVersionBlockHandle, FolioVersionComparisonPrivacyTransform, FolioVersionComparisonScope, FolioVersionDiff, FolioVersionDiffPrivacyOptions, FolioVersionDiffPrivacyReport, FolioVersionDiffSegment, FolioVersionDiffSummaryCounts, InvalidFolioVersionComparisonOptionsError, applyFolioVersionDiffPrivacy, compareDocxVersions, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope } from "./version-comparison.js";
+export { type ApplyFolioAIEditsToBufferOptions, type ApplyFolioAIEditsToBufferResult, type CreateCommentReplyInput, type CreateEmptyDocumentOptions, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, type DeriveBlockIdInput, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, DocxArchiveError, type DocxParagraphSource, EnsureParaIdsError, type EnsureParaIdsOptions, type EnsureParaIdsResult, type ExtractDocumentStyleSetOptions, type ExtractedDocxParagraph, type ExtractedDocxText, FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIComment, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditSnapshot, type FolioAIInlineFormatting, type FolioAITextRangeHandle, type FolioApplyDocumentOperationsOptions, type FolioApplyDocumentOperationsToStoryOptions, type FolioApplyOperationsOptions, type FolioBlockDiff, type FolioBlockId, type FolioCompareDocxVersionsOptions, type FolioDocumentMetadataProperty, type FolioDocumentMetadataValue, type FolioDocumentNavigationTarget, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocumentOutline, type FolioDocumentOutlineEntry, FolioDocumentPrivacyArchiveError, type FolioDocumentPrivacyOptions, type FolioDocumentPrivacyReport, type FolioDocumentPrivacyTransform, type FolioDocumentSection, type FolioDocumentSectionHandle, type FolioDocumentSectionReadResult, type FolioDocumentStory, type FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, type FolioDocxReviewerOptions, type FolioEditableDocumentStoryHandle, type FolioFormatProperty, type FolioMetadataDiff, type FolioReadReviewedStoryOptions, type FolioResolveReviewedStoryOptions, type FolioResolvedReviewedView, type FolioReviewChange, type FolioReviewChangeFilter, type FolioReviewChangeKind, type FolioReviewComment, type FolioReviewCommentFilter, type FolioReviewCommentReply, type FolioReviewReplyInput, type FolioReviewedStory, type FolioReviewedView, type FolioStoryDiff, type FolioVersionBlockHandle, type FolioVersionComparisonPrivacyTransform, type FolioVersionComparisonScope, type FolioVersionDiff, type FolioVersionDiffPrivacyOptions, type FolioVersionDiffPrivacyReport, type FolioVersionDiffSegment, type FolioVersionDiffSummaryCounts, type GenerateRedlineDocxOptions, type GenerateRedlineDocxResult, type GenerateRedlineUnprocessedStory, InvalidFolioDocumentOperationBatchError, InvalidFolioDocumentPrivacyOptionsError, InvalidFolioVersionComparisonOptionsError, InvalidGenerateRedlineDocxOptionsError, type RewriteDocxMetadataPrivacyResult, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, applyFolioVersionDiffPrivacy, assertSupportedFolioDocumentOperationVersion, compareDocxVersions, createDocx, createEmptyDocument, createFolioAITextRangeHandle, createStellaStyleDocumentPreset, createStellaStyleSet, deriveBlockId, ensureParaIds, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractDocxText, generateRedlineDocx, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, inspectDocumentStyles, inspectDocumentStylesFromDocx, isFolioBlockId, isFolioDocumentOperationModeSupported, isFolioDocumentPrivacyTransform, isFolioResolvedReviewedView, isFolioReviewedView, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope, isSequentialFolioBlockId, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch, readFolioDocumentSection, replyToComment, rewriteDocxMetadataPrivacy };

package/dist/server.js

@@ -8,10 +8,11 @@ import { STELLA_STYLE_SET_NAME, createStellaStyleDocumentPreset, createStellaSty
 import { createDocx } from "./docx/rezip.js";
 import { getFolioDocumentOutline, readFolioDocumentSection } from "./ai-edits/scoped-reading.js";
 import { replyToComment } from "./docx/replyToComment.js";
-import { FolioDocumentStoryNotFoundError, FolioDocxReviewer, applyFolioAIEditsToBuffer } from "./ai-edits/headless.js";
-import { compareDocxVersions } from "./version-comparison.js";
-import { generateRedlineDocx } from "./redline.js";
+import { FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioDocumentStoryNotFoundError, FolioDocxReviewer, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, isFolioResolvedReviewedView, isFolioReviewedView } from "./ai-edits/headless.js";
+import { FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, FolioDocumentPrivacyArchiveError, InvalidFolioDocumentPrivacyOptionsError, isFolioDocumentPrivacyTransform, rewriteDocxMetadataPrivacy } from "./docx/metadataPrivacy.js";
+import { FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, InvalidFolioVersionComparisonOptionsError, applyFolioVersionDiffPrivacy, compareDocxVersions, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope } from "./version-comparison.js";
+import { InvalidGenerateRedlineDocxOptionsError, generateRedlineDocx } from "./redline.js";
 import { EnsureParaIdsError, ensureParaIds } from "./docx/ensureParaIds.js";
 import { DocxArchiveError } from "./docx/server/boundedArchive.js";
 import { extractDocxText } from "./docx/server/extractDocxText.js";
-export { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DocxArchiveError, EnsureParaIdsError, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FolioDocumentStoryNotFoundError, FolioDocxReviewer, InvalidFolioDocumentOperationBatchError, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, applyFolioAIEditsToBuffer, assertSupportedFolioDocumentOperationVersion, compareDocxVersions, createDocx, createEmptyDocument, createFolioAITextRangeHandle, createStellaStyleDocumentPreset, createStellaStyleSet, deriveBlockId, ensureParaIds, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractDocxText, generateRedlineDocx, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, inspectDocumentStyles, inspectDocumentStylesFromDocx, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch, readFolioDocumentSection, replyToComment };
+export { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DocxArchiveError, EnsureParaIdsError, FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, FolioDocumentPrivacyArchiveError, FolioDocumentStoryNotFoundError, FolioDocxReviewer, InvalidFolioDocumentOperationBatchError, InvalidFolioDocumentPrivacyOptionsError, InvalidFolioVersionComparisonOptionsError, InvalidGenerateRedlineDocxOptionsError, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, applyFolioVersionDiffPrivacy, assertSupportedFolioDocumentOperationVersion, compareDocxVersions, createDocx, createEmptyDocument, createFolioAITextRangeHandle, createStellaStyleDocumentPreset, createStellaStyleSet, deriveBlockId, ensureParaIds, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractDocxText, generateRedlineDocx, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, inspectDocumentStyles, inspectDocumentStylesFromDocx, isFolioBlockId, isFolioDocumentOperationModeSupported, isFolioDocumentPrivacyTransform, isFolioResolvedReviewedView, isFolioReviewedView, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope, isSequentialFolioBlockId, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch, readFolioDocumentSection, replyToComment, rewriteDocxMetadataPrivacy };

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 };