@stll/folio-core 0.37.4 → 0.37.5

package/dist/docx/serializer/textFormattingSerializer.js

@@ -0,0 +1,142 @@
+import { HIGHLIGHT_COLOR_VALUES } from "../../types/documentEnumValues.js";
+import { isValidHexColor } from "../../utils/colorResolver.js";
+import { roundHorizontalScalePercentForSerialization } from "../../utils/horizontalScale.js";
+import { escapeXml, intAttr } from "./xmlUtils.js";
+//#region src/docx/serializer/textFormattingSerializer.ts
+const VALID_HIGHLIGHT_COLORS = new Set(HIGHLIGHT_COLOR_VALUES);
+/**
+* Serialize a color element (w:color)
+*/
+function serializeColorElement(color) {
+	if (!color) return "";
+	const { auto, rgb, themeColor, themeTint, themeShade } = color;
+	const attrs = [];
+	if (auto) attrs.push("w:val=\"auto\"");
+	else if (rgb && isValidHexColor(rgb)) attrs.push(`w:val="${escapeXml(rgb)}"`);
+	if (themeColor) attrs.push(`w:themeColor="${escapeXml(themeColor)}"`);
+	if (themeTint) attrs.push(`w:themeTint="${escapeXml(themeTint)}"`);
+	if (themeShade) attrs.push(`w:themeShade="${escapeXml(themeShade)}"`);
+	return attrs.length === 0 ? "" : `<w:color ${attrs.join(" ")}/>`;
+}
+/**
+* Serialize shading properties (w:shd)
+*/
+function serializeShading(shading) {
+	if (!shading) return "";
+	const { pattern, color, fill } = shading;
+	const attrs = [];
+	if (pattern) attrs.push(`w:val="${escapeXml(pattern)}"`);
+	else attrs.push("w:val=\"clear\"");
+	if (color) {
+		const { rgb, auto, themeColor: _themeColor, themeTint: _themeTint, themeShade: _themeShade } = color;
+		if (rgb && isValidHexColor(rgb)) attrs.push(`w:color="${escapeXml(rgb)}"`);
+		else if (auto) attrs.push("w:color=\"auto\"");
+	}
+	if (fill) {
+		const { rgb, auto, themeColor, themeTint, themeShade } = fill;
+		if (rgb && isValidHexColor(rgb)) attrs.push(`w:fill="${escapeXml(rgb)}"`);
+		else if (auto) attrs.push("w:fill=\"auto\"");
+		if (themeColor) attrs.push(`w:themeFill="${escapeXml(themeColor)}"`);
+		if (themeTint) attrs.push(`w:themeFillTint="${escapeXml(themeTint)}"`);
+		if (themeShade) attrs.push(`w:themeFillShade="${escapeXml(themeShade)}"`);
+	}
+	return attrs.length === 0 ? "" : `<w:shd ${attrs.join(" ")}/>`;
+}
+/**
+* Serialize text formatting properties to w:rPr XML
+*/
+function serializeTextFormatting(input) {
+	if (!input) return "";
+	const { bold, boldCs, italic, italicCs, underline, strike, doubleStrike, vertAlign, smallCaps, allCaps, hidden, color, highlight, shading, fontSize, fontSizeCs, fontFamily, language, spacing, position, scale, kerning, effect, emphasisMark, emboss, imprint, outline, shadow, rtl, cs, styleId } = input;
+	const parts = [];
+	if (styleId) parts.push(`<w:rStyle w:val="${escapeXml(styleId)}"/>`);
+	if (fontFamily) {
+		const { ascii, hAnsi, eastAsia, cs: complexScript, hint, asciiTheme, hAnsiTheme, eastAsiaTheme, csTheme } = fontFamily;
+		const fontAttrs = [];
+		if (ascii) fontAttrs.push(`w:ascii="${escapeXml(ascii)}"`);
+		if (hAnsi) fontAttrs.push(`w:hAnsi="${escapeXml(hAnsi)}"`);
+		if (eastAsia) fontAttrs.push(`w:eastAsia="${escapeXml(eastAsia)}"`);
+		if (complexScript) fontAttrs.push(`w:cs="${escapeXml(complexScript)}"`);
+		if (hint) fontAttrs.push(`w:hint="${escapeXml(hint)}"`);
+		if (asciiTheme) fontAttrs.push(`w:asciiTheme="${escapeXml(asciiTheme)}"`);
+		if (hAnsiTheme) fontAttrs.push(`w:hAnsiTheme="${escapeXml(hAnsiTheme)}"`);
+		if (eastAsiaTheme) fontAttrs.push(`w:eastAsiaTheme="${escapeXml(eastAsiaTheme)}"`);
+		if (csTheme) fontAttrs.push(`w:cstheme="${escapeXml(csTheme)}"`);
+		if (fontAttrs.length > 0) parts.push(`<w:rFonts ${fontAttrs.join(" ")}/>`);
+	}
+	if (bold === true) parts.push("<w:b/>");
+	else if (bold === false) parts.push("<w:b w:val=\"0\"/>");
+	if (boldCs === true) parts.push("<w:bCs/>");
+	else if (boldCs === false) parts.push("<w:bCs w:val=\"0\"/>");
+	if (italic === true) parts.push("<w:i/>");
+	else if (italic === false) parts.push("<w:i w:val=\"0\"/>");
+	if (italicCs === true) parts.push("<w:iCs/>");
+	else if (italicCs === false) parts.push("<w:iCs w:val=\"0\"/>");
+	if (allCaps === true) parts.push("<w:caps/>");
+	else if (allCaps === false) parts.push("<w:caps w:val=\"0\"/>");
+	if (smallCaps === true) parts.push("<w:smallCaps/>");
+	else if (smallCaps === false) parts.push("<w:smallCaps w:val=\"0\"/>");
+	if (strike === true) parts.push("<w:strike/>");
+	else if (strike === false) parts.push("<w:strike w:val=\"0\"/>");
+	if (doubleStrike === true) parts.push("<w:dstrike/>");
+	else if (doubleStrike === false) parts.push("<w:dstrike w:val=\"0\"/>");
+	if (outline === true) parts.push("<w:outline/>");
+	else if (outline === false) parts.push("<w:outline w:val=\"0\"/>");
+	if (shadow === true) parts.push("<w:shadow/>");
+	else if (shadow === false) parts.push("<w:shadow w:val=\"0\"/>");
+	if (emboss === true) parts.push("<w:emboss/>");
+	else if (emboss === false) parts.push("<w:emboss w:val=\"0\"/>");
+	if (imprint === true) parts.push("<w:imprint/>");
+	else if (imprint === false) parts.push("<w:imprint w:val=\"0\"/>");
+	if (hidden === true) parts.push("<w:vanish/>");
+	else if (hidden === false) parts.push("<w:vanish w:val=\"0\"/>");
+	const colorXml = serializeColorElement(color);
+	if (colorXml) parts.push(colorXml);
+	if (spacing !== void 0) parts.push(`<w:spacing w:val="${intAttr(spacing)}"/>`);
+	const horizontalScale = roundHorizontalScalePercentForSerialization(scale);
+	if (horizontalScale !== void 0) parts.push(`<w:w w:val="${intAttr(horizontalScale)}"/>`);
+	if (kerning !== void 0) parts.push(`<w:kern w:val="${intAttr(kerning)}"/>`);
+	if (position !== void 0) parts.push(`<w:position w:val="${intAttr(position)}"/>`);
+	if (fontSize !== void 0) parts.push(`<w:sz w:val="${intAttr(fontSize)}"/>`);
+	if (fontSizeCs !== void 0) parts.push(`<w:szCs w:val="${intAttr(fontSizeCs)}"/>`);
+	let customHighlightShadingXml = "";
+	if (highlight) {
+		if (VALID_HIGHLIGHT_COLORS.has(highlight)) parts.push(`<w:highlight w:val="${highlight}"/>`);
+		else if (!shading) {
+			const hex = highlight.replace(/^#/u, "");
+			if (/^[0-9a-fA-F]{6}$/u.test(hex)) customHighlightShadingXml = `<w:shd w:val="clear" w:color="auto" w:fill="${hex}"/>`;
+		}
+	}
+	if (underline) {
+		const { style, color: underlineColor } = underline;
+		const uAttrs = [`w:val="${style}"`];
+		if (underlineColor) {
+			const { rgb, themeColor, themeTint, themeShade, auto: _auto } = underlineColor;
+			if (rgb && isValidHexColor(rgb)) uAttrs.push(`w:color="${escapeXml(rgb)}"`);
+			if (themeColor) uAttrs.push(`w:themeColor="${escapeXml(themeColor)}"`);
+			if (themeTint) uAttrs.push(`w:themeTint="${escapeXml(themeTint)}"`);
+			if (themeShade) uAttrs.push(`w:themeShade="${escapeXml(themeShade)}"`);
+		}
+		parts.push(`<w:u ${uAttrs.join(" ")}/>`);
+	}
+	if (effect) parts.push(`<w:effect w:val="${effect}"/>`);
+	const shadingXml = serializeShading(shading) || customHighlightShadingXml;
+	if (shadingXml) parts.push(shadingXml);
+	if (vertAlign) parts.push(`<w:vertAlign w:val="${vertAlign}"/>`);
+	if (rtl === true) parts.push("<w:rtl/>");
+	else if (rtl === false) parts.push("<w:rtl w:val=\"0\"/>");
+	if (cs === true) parts.push("<w:cs/>");
+	else if (cs === false) parts.push("<w:cs w:val=\"0\"/>");
+	if (emphasisMark) parts.push(`<w:em w:val="${emphasisMark}"/>`);
+	if (language) {
+		const { val, eastAsia, bidi } = language;
+		const languageAttrs = [];
+		if (val) languageAttrs.push(`w:val="${escapeXml(val)}"`);
+		if (eastAsia) languageAttrs.push(`w:eastAsia="${escapeXml(eastAsia)}"`);
+		if (bidi) languageAttrs.push(`w:bidi="${escapeXml(bidi)}"`);
+		if (languageAttrs.length > 0) parts.push(`<w:lang ${languageAttrs.join(" ")}/>`);
+	}
+	return parts.length === 0 ? "" : `<w:rPr>${parts.join("")}</w:rPr>`;
+}
+//#endregion
+export { serializeShading, serializeTextFormatting };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { document_d_exports } from "./types/document.js";
-import { FolioContentBlock, FolioContentContainerPathEntry, FolioContentIdStability, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentLineSpacingRule, FolioContentParagraphAlignment, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation } from "./compare/content-types.js";
+import { FolioContentBlock, FolioContentContainerPathEntry, FolioContentIdStability, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentLineSpacingRule, FolioContentParagraphAlignment, FolioContentParagraphKind, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation } from "./compare/content-types.js";
 import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIBlockStructuralBoundary, FolioAIBlockTableLocation, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineBooleanProperty, FolioAIInlineFormatting, FolioAIInlineFormattingPatch, FolioAIParagraphSpacing, FolioAISignatureParty } from "./ai-edits/types.js";
 import { WORD_DIFF_GRANULARITIES, WordDiffGranularity, WordDiffNormalization, WordDiffOptions, WordDiffSegment, diffWordSegments } from "./ai-edits/word-diff.js";
 import { FolioAIEditApplyOutcome, FolioRevisionStamp, FolioWordDiffOptions, applyFolioAIEditOperations } from "./ai-edits/apply.js";
@@ -40,4 +40,4 @@ import { getGoogleFontsEnabled, setEmbeddedFontFamilyMap, setGoogleFontsEnabled
 import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
 type Document = document_d_exports.Document;
 type DocxConformanceClass = document_d_exports.DocxConformanceClass;
-export { type AIBarStatus, type AIChatMode, type AICitation, type AICitationRange, type AICitationSource, type AIGenerateInput, type AISuggestion, type AISuggestionApplyMode, type AISuggestionPreset, type AISuggestionSeverity, type AISuggestionStatus, type AcceptAutocompleteResult, type AnonymizationMatch, type AnonymizationTerm, type ApplyFolioDocumentOperationsOptions, type ApplyResult, type AutocompleteSuggestionPluginOptions, type AutocompleteSuggestionState, type AutocompleteSuggestionStatus, type AutocompleteTriggerCheck, type AutocompleteTriggerOptions, type AutocompleteTriggerSkipReason, type BlockRect, COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, type CompareChange, type CompareChangeLocation, type CompareContentOptions, CompareDocxApplyError, type CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, type CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, type CompareFormatRange, type CompareResult, type CompareUnsupportedPart, type CompareUnsupportedReason, type CompareVerification, type CompareVerificationCause, type CompareVerificationFailure, type CompareVerificationInvariant, type CreateEmptyDocumentOptions, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, type DeriveBlockIdInput, type DirectiveKind, type DirectiveRange, type Document, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, type DocxCompatibility, type DocxCompatibilityContext, type DocxCompatibilityIssue, type DocxCompatibilityLocation, type DocxCompatibilityPart, type DocxConformanceClass, type EmbeddedFont, type EmbeddedFontParts, type ExtractDocumentStyleSetOptions, FOLIO_CONTENT_COMPARISON_LIMITS, 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_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, type FinalParagraphMarkRevision, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIBlockStructuralBoundary, type FolioAIBlockTableLocation, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyOutcome, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAIInlineBooleanProperty, type FolioAIInlineFormatting, type FolioAIInlineFormattingPatch, type FolioAIParagraphSpacing, type FolioAISignatureParty, type FolioBlockId, type FolioContentBlock, type FolioContentBlockProperty, type FolioContentComparison, type FolioContentComparisonError, type FolioContentComparisonEvent, type FolioContentComparisonLimit, FolioContentComparisonLimitError, type FolioContentContainerPathEntry, type FolioContentFormatRange, type FolioContentFormattingChange, type FolioContentIdStability, type FolioContentInlineBooleanProperty, type FolioContentInlineFormatting, type FolioContentInlineFormattingPatch, type FolioContentLineSpacingRule, type FolioContentParagraphAlignment, type FolioContentParagraphFormattingPatch, type FolioContentParagraphSpacing, type FolioContentRun, type FolioContentSnapshot, type FolioContentStructuralChange, type FolioContentTableLocation, type FolioContentTextSegment, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocxCompatibilityHost, type FolioDocxCompatibilityProfile, type FolioRevisionStamp, type FolioWordDiffOptions, type ImageMeta, type ImageRef, type InspectDocxCompatibilityOptions, InvalidCompareDocxOptionsError, InvalidFolioContentComparisonError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, type MarkdownOptions, type MarkdownResult, type PositionalText, type ResolvedAnchor, STELLA_STYLE_SET_NAME, type TemplatePreviewSpan, type TemplatePreviewValue, type TemplatePreviewValues, type TemplateSlashMenuKeyAction, type TemplateSlashMenuState, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, type WordDiffGranularity, type WordDiffNormalization, type WordDiffOptions, type WordDiffSegment, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareContent, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, currentFolioBlockId, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };
+export { type AIBarStatus, type AIChatMode, type AICitation, type AICitationRange, type AICitationSource, type AIGenerateInput, type AISuggestion, type AISuggestionApplyMode, type AISuggestionPreset, type AISuggestionSeverity, type AISuggestionStatus, type AcceptAutocompleteResult, type AnonymizationMatch, type AnonymizationTerm, type ApplyFolioDocumentOperationsOptions, type ApplyResult, type AutocompleteSuggestionPluginOptions, type AutocompleteSuggestionState, type AutocompleteSuggestionStatus, type AutocompleteTriggerCheck, type AutocompleteTriggerOptions, type AutocompleteTriggerSkipReason, type BlockRect, COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, type CompareChange, type CompareChangeLocation, type CompareContentOptions, CompareDocxApplyError, type CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, type CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, type CompareFormatRange, type CompareResult, type CompareUnsupportedPart, type CompareUnsupportedReason, type CompareVerification, type CompareVerificationCause, type CompareVerificationFailure, type CompareVerificationInvariant, type CreateEmptyDocumentOptions, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, type DeriveBlockIdInput, type DirectiveKind, type DirectiveRange, type Document, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, type DocxCompatibility, type DocxCompatibilityContext, type DocxCompatibilityIssue, type DocxCompatibilityLocation, type DocxCompatibilityPart, type DocxConformanceClass, type EmbeddedFont, type EmbeddedFontParts, type ExtractDocumentStyleSetOptions, FOLIO_CONTENT_COMPARISON_LIMITS, 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_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, type FinalParagraphMarkRevision, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIBlockStructuralBoundary, type FolioAIBlockTableLocation, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyOutcome, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAIInlineBooleanProperty, type FolioAIInlineFormatting, type FolioAIInlineFormattingPatch, type FolioAIParagraphSpacing, type FolioAISignatureParty, type FolioBlockId, type FolioContentBlock, type FolioContentBlockProperty, type FolioContentComparison, type FolioContentComparisonError, type FolioContentComparisonEvent, type FolioContentComparisonLimit, FolioContentComparisonLimitError, type FolioContentContainerPathEntry, type FolioContentFormatRange, type FolioContentFormattingChange, type FolioContentIdStability, type FolioContentInlineBooleanProperty, type FolioContentInlineFormatting, type FolioContentInlineFormattingPatch, type FolioContentLineSpacingRule, type FolioContentParagraphAlignment, type FolioContentParagraphFormattingPatch, type FolioContentParagraphKind, type FolioContentParagraphSpacing, type FolioContentRun, type FolioContentSnapshot, type FolioContentStructuralChange, type FolioContentTableLocation, type FolioContentTextSegment, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocxCompatibilityHost, type FolioDocxCompatibilityProfile, type FolioRevisionStamp, type FolioWordDiffOptions, type ImageMeta, type ImageRef, type InspectDocxCompatibilityOptions, InvalidCompareDocxOptionsError, InvalidFolioContentComparisonError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, type MarkdownOptions, type MarkdownResult, type PositionalText, type ResolvedAnchor, STELLA_STYLE_SET_NAME, type TemplatePreviewSpan, type TemplatePreviewValue, type TemplatePreviewValues, type TemplateSlashMenuKeyAction, type TemplateSlashMenuState, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, type WordDiffGranularity, type WordDiffNormalization, type WordDiffOptions, type WordDiffSegment, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareContent, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, currentFolioBlockId, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };

package/dist/internal/paragraphFormattingSerialization.d.ts

@@ -0,0 +1,23 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/internal/paragraphFormattingSerialization.d.ts
+type ExhaustiveFields<Source, Classified extends keyof Source> = Exclude<keyof Source, Classified> extends never ? Source : never;
+type ParagraphNumberingReference = document_d_exports.ParagraphFormatting["numPr"] | null;
+type ClassifiedParagraphFormattingField = "alignment" | "bidi" | "kinsoku" | "overflowPunctuation" | "spaceBefore" | "spaceAfter" | "lineSpacing" | "lineSpacingRule" | "snapToGrid" | "beforeAutospacing" | "afterAutospacing" | "spacingExplicit" | "indentLeft" | "indentRight" | "indentFirstLine" | "hangingIndent" | "borders" | "shading" | "tabs" | "keepNext" | "keepLines" | "widowControl" | "pageBreakBefore" | "contextualSpacing" | "numPr" | "numPrFromStyle" | "outlineLevel" | "styleId" | "frame" | "suppressLineNumbers" | "suppressAutoHyphens" | "runProperties" | "runInWithNext";
+type ExhaustiveParagraphFormatting = ExhaustiveFields<document_d_exports.ParagraphFormatting, ClassifiedParagraphFormattingField>;
+/** Compare numbering references by their emitted id and effective level. */
+declare const paragraphNumberingReferencesEqual: (left: ParagraphNumberingReference, right: ParagraphNumberingReference) => boolean;
+/** Whether resolved numbering still belongs to the paragraph's style tier. */
+declare const isStyleSourcedParagraphNumbering: (numPr: ParagraphNumberingReference, numPrFromStyle: ParagraphNumberingReference) => boolean;
+/** Exact fallback-emission instructions for the modeled part of `w:pPr`. */
+type ModeledParagraphFormattingEmission = Readonly<{
+  propertiesXml?: string;
+  paragraphMarkPropertiesInnerXml?: string;
+}>;
+/**
+ * Resolve paragraph formatting into its exact fallback `w:pPr` instructions.
+ * Every input field is classified here so parser capture fingerprints and the
+ * serializer cannot drift apart when paragraph formatting grows.
+ */
+declare const modelParagraphFormattingEmission: (input: ExhaustiveParagraphFormatting | undefined) => ModeledParagraphFormattingEmission;
+//#endregion
+export { ModeledParagraphFormattingEmission, isStyleSourcedParagraphNumbering, modelParagraphFormattingEmission, paragraphNumberingReferencesEqual };

package/dist/internal/paragraphFormattingSerialization.js

@@ -0,0 +1,157 @@
+import { serializeBorder } from "../docx/serializer/borderSerializer.js";
+import { serializeShading, serializeTextFormatting } from "../docx/serializer/textFormattingSerializer.js";
+import { escapeXml, intAttr } from "../docx/serializer/xmlUtils.js";
+//#region src/internal/paragraphFormattingSerialization.ts
+const modelParagraphNumberingReference = (reference) => {
+	if (!reference) return null;
+	const { numId, ilvl } = reference;
+	return {
+		...numId !== void 0 ? { numId } : {},
+		...ilvl !== void 0 ? { ilvl } : {}
+	};
+};
+/** Compare numbering references by their emitted id and effective level. */
+const paragraphNumberingReferencesEqual = (left, right) => {
+	const modeledLeft = modelParagraphNumberingReference(left);
+	const modeledRight = modelParagraphNumberingReference(right);
+	if (modeledLeft === null || modeledRight === null) return modeledLeft === null && modeledRight === null;
+	return modeledLeft.numId === modeledRight.numId && (modeledLeft.ilvl ?? 0) === (modeledRight.ilvl ?? 0);
+};
+/** Whether resolved numbering still belongs to the paragraph's style tier. */
+const isStyleSourcedParagraphNumbering = (numPr, numPrFromStyle) => numPr != null && numPrFromStyle != null && paragraphNumberingReferencesEqual(numPr, numPrFromStyle);
+const serializeToggle = (name, value) => {
+	if (value === true) return `<w:${name}/>`;
+	if (value === false) return `<w:${name} w:val="0"/>`;
+	return "";
+};
+const serializeParagraphBorders = (borders) => {
+	if (!borders) return "";
+	const { top, left, bottom, right, between, bar } = borders;
+	const parts = [
+		serializeBorder(top, "top"),
+		serializeBorder(left, "left"),
+		serializeBorder(bottom, "bottom"),
+		serializeBorder(right, "right"),
+		serializeBorder(between, "between"),
+		serializeBorder(bar, "bar")
+	].filter(Boolean);
+	return parts.length === 0 ? "" : `<w:pBdr>${parts.join("")}</w:pBdr>`;
+};
+const serializeTabStops = (tabs) => {
+	if (!tabs || tabs.length === 0) return "";
+	return `<w:tabs>${tabs.map((tab) => {
+		const { alignment, position, leader } = tab;
+		const attrs = [`w:val="${alignment}"`, `w:pos="${intAttr(position)}"`];
+		if (leader && leader !== "none") attrs.push(`w:leader="${leader}"`);
+		return `<w:tab ${attrs.join(" ")}/>`;
+	}).join("")}</w:tabs>`;
+};
+const serializeSpacing = (formatting) => {
+	const attrs = [];
+	if (formatting.spaceBefore !== void 0) attrs.push(`w:before="${intAttr(formatting.spaceBefore)}"`);
+	if (formatting.spaceAfter !== void 0) attrs.push(`w:after="${intAttr(formatting.spaceAfter)}"`);
+	if (formatting.lineSpacing !== void 0) attrs.push(`w:line="${intAttr(formatting.lineSpacing)}"`);
+	if (formatting.lineSpacingRule) attrs.push(`w:lineRule="${formatting.lineSpacingRule}"`);
+	if (formatting.beforeAutospacing !== void 0) attrs.push(`w:beforeAutospacing="${formatting.beforeAutospacing ? "1" : "0"}"`);
+	if (formatting.afterAutospacing !== void 0) attrs.push(`w:afterAutospacing="${formatting.afterAutospacing ? "1" : "0"}"`);
+	return attrs.length === 0 ? "" : `<w:spacing ${attrs.join(" ")}/>`;
+};
+const serializeIndentation = (formatting) => {
+	const attrs = [];
+	if (formatting.indentLeft !== void 0) attrs.push(`w:left="${intAttr(formatting.indentLeft)}"`);
+	if (formatting.indentRight !== void 0) attrs.push(`w:right="${intAttr(formatting.indentRight)}"`);
+	if (formatting.indentFirstLine !== void 0) {
+		const attribute = formatting.hangingIndent ? "hanging" : "firstLine";
+		const value = formatting.hangingIndent ? Math.abs(formatting.indentFirstLine) : formatting.indentFirstLine;
+		attrs.push(`w:${attribute}="${intAttr(value)}"`);
+	}
+	return attrs.length === 0 ? "" : `<w:ind ${attrs.join(" ")}/>`;
+};
+const serializeNumbering = (numPr) => {
+	const modeled = modelParagraphNumberingReference(numPr ?? null);
+	if (!modeled) return "";
+	const parts = [];
+	if (modeled.ilvl !== void 0) parts.push(`<w:ilvl w:val="${intAttr(modeled.ilvl)}"/>`);
+	if (modeled.numId !== void 0) parts.push(`<w:numId w:val="${intAttr(modeled.numId)}"/>`);
+	return parts.length === 0 ? "" : `<w:numPr>${parts.join("")}</w:numPr>`;
+};
+const serializeFrameProperties = (frame) => {
+	if (!frame) return "";
+	const { dropCap, lines, width, height, hSpace, vSpace, hAnchor, vAnchor, x, y, xAlign, yAlign, wrap } = frame;
+	const attrs = [];
+	if (dropCap) attrs.push(`w:dropCap="${dropCap}"`);
+	if (lines !== void 0) attrs.push(`w:lines="${intAttr(lines)}"`);
+	if (width !== void 0) attrs.push(`w:w="${intAttr(width)}"`);
+	if (height !== void 0) attrs.push(`w:h="${intAttr(height)}"`);
+	if (hSpace !== void 0) attrs.push(`w:hSpace="${intAttr(hSpace)}"`);
+	if (vSpace !== void 0) attrs.push(`w:vSpace="${intAttr(vSpace)}"`);
+	if (hAnchor) attrs.push(`w:hAnchor="${hAnchor}"`);
+	if (vAnchor) attrs.push(`w:vAnchor="${vAnchor}"`);
+	if (x !== void 0) attrs.push(`w:x="${x}"`);
+	if (y !== void 0) attrs.push(`w:y="${y}"`);
+	if (xAlign) attrs.push(`w:xAlign="${xAlign}"`);
+	if (yAlign) attrs.push(`w:yAlign="${yAlign}"`);
+	if (wrap) attrs.push(`w:wrap="${wrap}"`);
+	return attrs.length === 0 ? "" : `<w:framePr ${attrs.join(" ")}/>`;
+};
+const modelSpacingProvenance = (spacingExplicit) => {
+	if (spacingExplicit) {
+		const { before: _before, after: _after } = spacingExplicit;
+	}
+};
+const extractRunPropertiesInnerXml = (runPropertiesXml) => {
+	if (!runPropertiesXml.startsWith("<w:rPr>") || !runPropertiesXml.endsWith("</w:rPr>")) return "";
+	return runPropertiesXml.slice(7, -8);
+};
+/**
+* Resolve paragraph formatting into its exact fallback `w:pPr` instructions.
+* Every input field is classified here so parser capture fingerprints and the
+* serializer cannot drift apart when paragraph formatting grows.
+*/
+const modelParagraphFormattingEmission = (input) => {
+	if (!input) return {};
+	const { alignment, bidi, kinsoku, overflowPunctuation, spaceBefore, spaceAfter, lineSpacing, lineSpacingRule, snapToGrid, beforeAutospacing, afterAutospacing, spacingExplicit, indentLeft, indentRight, indentFirstLine, hangingIndent, borders, shading, tabs, keepNext, keepLines, widowControl, pageBreakBefore, contextualSpacing, numPr, numPrFromStyle, outlineLevel, styleId, frame, suppressLineNumbers, suppressAutoHyphens, runProperties, runInWithNext } = input;
+	modelSpacingProvenance(spacingExplicit);
+	const propertiesXml = [
+		styleId ? `<w:pStyle w:val="${escapeXml(styleId)}"/>` : "",
+		serializeToggle("keepNext", keepNext),
+		serializeToggle("keepLines", keepLines),
+		serializeToggle("pageBreakBefore", pageBreakBefore),
+		serializeFrameProperties(frame),
+		serializeToggle("widowControl", widowControl),
+		isStyleSourcedParagraphNumbering(numPr, numPrFromStyle) ? "" : serializeNumbering(numPr),
+		serializeToggle("suppressLineNumbers", suppressLineNumbers),
+		serializeParagraphBorders(borders),
+		serializeShading(shading),
+		serializeTabStops(tabs),
+		serializeToggle("suppressAutoHyphens", suppressAutoHyphens),
+		serializeToggle("kinsoku", kinsoku),
+		serializeToggle("overflowPunct", overflowPunctuation),
+		serializeToggle("bidi", bidi),
+		serializeToggle("snapToGrid", snapToGrid),
+		serializeSpacing({
+			spaceBefore,
+			spaceAfter,
+			lineSpacing,
+			lineSpacingRule,
+			beforeAutospacing,
+			afterAutospacing
+		}),
+		serializeIndentation({
+			indentLeft,
+			indentRight,
+			indentFirstLine,
+			hangingIndent
+		}),
+		serializeToggle("contextualSpacing", contextualSpacing),
+		alignment ? `<w:jc w:val="${alignment}"/>` : "",
+		outlineLevel !== void 0 ? `<w:outlineLvl w:val="${outlineLevel}"/>` : ""
+	].join("");
+	const paragraphMarkPropertiesInnerXml = `${extractRunPropertiesInnerXml(serializeTextFormatting(runProperties))}${runInWithNext === true ? "<w:specVanish/>" : ""}`;
+	const emission = {};
+	if (propertiesXml) emission.propertiesXml = propertiesXml;
+	if (paragraphMarkPropertiesInnerXml) emission.paragraphMarkPropertiesInnerXml = paragraphMarkPropertiesInnerXml;
+	return emission;
+};
+//#endregion
+export { isStyleSourcedParagraphNumbering, modelParagraphFormattingEmission, paragraphNumberingReferencesEqual };

package/dist/prosemirror/conversion/fromProseDoc.js

@@ -1,8 +1,8 @@
-import { numPrEqual } from "../../docx/numberingParser.js";
 import { PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, ParagraphPropertySourceValidationError, copyDocumentParagraphPropertySourceContract, copyDocumentParagraphPropertySources, copyParagraphPropertyCapture, copyParagraphPropertySource, decodeTableCellParagraphSourcePayload, getDocumentParagraphPropertySourceContract, getParagraphPropertySource, getParagraphPropertySourceCandidate, getParagraphPropertySourceToken, getParagraphPropertySourceTransferId, getProseDocumentParagraphPropertySourceContract, getProseParagraphPropertySourceToken, isParagraphPropertySourceToken, linkParagraphPropertySourceCandidate, paragraphPropertySourceBelongsToDocument, paragraphPropertySourceTokenMatchesContract, recreateProseNodeWithParagraphPropertySource, restoreTableCellsWithParagraphPropertySources, visitDocumentStoryParagraphs, visitTableCellParagraphPropertySourceBindings } from "../../docx/paragraphPropertySource.js";
 import { visitDocxParagraphs } from "../../docx/paragraphTraversal.js";
 import { ShapeOutlineStyleSchema, narrowEnum } from "../../docx/parserEnums.js";
 import { DATE_UTC_ATTRIBUTE } from "../../docx/trackedChangeInfo.js";
+import { isStyleSourcedParagraphNumbering, modelParagraphFormattingEmission, paragraphNumberingReferencesEqual } from "../../internal/paragraphFormattingSerialization.js";
 import { createStyleEngine } from "../../style-engine/styleEngine.js";
 import { OUTLINE_STYLE_CSS_ALIASES, normalizeShapeTextAnchor } from "../../types/documentEnumValues.js";
 import { canonicalJson } from "../../utils/canonicalJson.js";
@@ -106,9 +106,10 @@ const uniqueParagraphsById = (content, includeTransferIds = false) => {
 const restoreParagraphPropertySource = (paragraph, baseParagraph) => {
 	copyParagraphPropertySource(paragraph, baseParagraph);
 	const baseFormatting = baseParagraph.formatting;
-	if (!baseFormatting?.numPr || !baseFormatting.numPrFromStyle || !numPrEqual(baseFormatting.numPr, baseFormatting.numPrFromStyle)) return;
-	const { numPr, numPrFromStyle, ...authoredFormatting } = baseFormatting;
-	if (canonicalJson(paragraph.formatting ?? {}) !== canonicalJson(authoredFormatting)) return;
+	if (!baseFormatting) return;
+	const { numPr, numPrFromStyle } = baseFormatting;
+	if (!numPr || !numPrFromStyle || !isStyleSourcedParagraphNumbering(numPr, numPrFromStyle)) return;
+	if (canonicalJson(modelParagraphFormattingEmission(paragraph.formatting)) !== canonicalJson(modelParagraphFormattingEmission(baseFormatting))) return;
 	paragraph.formatting = {
 		...paragraph.formatting,
 		numPr,
@@ -777,15 +778,6 @@ const propertyChangeFromAttrs = (change) => {
 		...currentFormatting !== void 0 && { currentFormatting }
 	};
 };
-/**
-* Whether the paragraph's numbering still comes verbatim from its style —
-* serialize no direct `<w:numPr>` then. The moment a list command changes
-* `numPr` the values diverge and the numbering serializes as direct
-* formatting, so a stale provenance value can never swallow a user edit.
-*/
-function isStyleSourcedNumPr(attrs) {
-	return attrs.numPrFromStyle != null && attrs.numPr != null && numPrEqual(attrs.numPr, attrs.numPrFromStyle);
-}
 function assignBooleanToggle(result, attrs, orig, key) {
 	const value = attrs[key] ?? void 0;
 	if (value === (orig[key] ?? void 0)) return;
@@ -834,10 +826,10 @@ function paragraphAttrsToFormatting(attrs) {
 		else Reflect.deleteProperty(result, "lineSpacingRule");
 		if (directAlignment === void 0) Reflect.deleteProperty(result, "alignment");
 		else result.alignment = directAlignment;
-		if (isStyleSourcedNumPr(attrs)) {
+		if (isStyleSourcedParagraphNumbering(attrs.numPr, attrs.numPrFromStyle)) {
 			delete result.numPr;
 			delete result.numPrFromStyle;
-		} else if (attrs.numPr !== orig.numPr && !numPrEqual(attrs.numPr, orig.numPr)) {
+		} else if (attrs.numPr !== orig.numPr && !paragraphNumberingReferencesEqual(attrs.numPr, orig.numPr)) {
 			if (attrs.numPr) result.numPr = attrs.numPr;
 			else delete result.numPr;
 			delete result.numPrFromStyle;
@@ -874,7 +866,7 @@ function paragraphAttrsToFormatting(attrs) {
 	if (attrs.indentRight) f.indentRight = attrs.indentRight;
 	if (attrs.indentFirstLine) f.indentFirstLine = attrs.indentFirstLine;
 	if (attrs.hangingIndent) f.hangingIndent = attrs.hangingIndent;
-	if (attrs.numPr && !isStyleSourcedNumPr(attrs)) f.numPr = attrs.numPr;
+	if (attrs.numPr && !isStyleSourcedParagraphNumbering(attrs.numPr, attrs.numPrFromStyle)) f.numPr = attrs.numPr;
 	if (attrs.styleId) f.styleId = attrs.styleId;
 	if (attrs.borders) f.borders = attrs.borders;
 	if (attrs.shading) f.shading = attrs.shading;

package/dist/server.d.ts

@@ -1,3 +1,4 @@
+import { FolioContentParagraphKind } from "./compare/content-types.js";
 import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIBlockStructuralBoundary, FolioAIComment, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditSnapshot, FolioAIInlineBooleanProperty, FolioAIInlineFormatting, FolioAIInlineFormattingPatch, FolioAIParagraphSpacing, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult } from "./ai-edits/types.js";
 import { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, 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";
@@ -27,4 +28,4 @@ import { FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS, FOLIO_DOCX_PACKAGE_INSPECTION_E
 import { FOLIO_YJS_DOCX_MATERIALIZATION_ERROR_CODES, FOLIO_YJS_PROSEMIRROR_FRAGMENT_NAME, FOLIO_YJS_UPDATE_MAX_BYTES, FolioYjsDocxMaterializationError, FolioYjsDocxMaterializationErrorCode, MaterializeYjsDocxOptions, materializeYjsDocx } from "./docx/server/materializeYjsDocx.js";
 import { GenerateRedlineDocxOptions, GenerateRedlineDocxResult, GenerateRedlineUnprocessedStory, InvalidGenerateRedlineDocxOptionsError, generateRedlineDocx } from "./redline.js";
 import { FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, FolioBlockDiff, FolioBlockProperty, FolioCompareDocxVersionsOptions, FolioDocumentMetadataValue, FolioFormatProperty, FolioMetadataDiff, FolioStoryDiff, FolioVersionBlockHandle, FolioVersionChangeProperty, FolioVersionComparisonPrivacyTransform, FolioVersionComparisonScope, FolioVersionDiff, FolioVersionDiffPrivacyOptions, FolioVersionDiffPrivacyReport, FolioVersionDiffSegment, FolioVersionDiffSummaryCounts, InvalidFolioVersionComparisonOptionsError, applyFolioVersionDiffPrivacy, compareDocxVersions, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope } from "./version-comparison.js";
-export { type ApplyDocxXmlPatchProposalArgs, type ApplyFolioAIEditsToBufferOptions, type ApplyFolioAIEditsToBufferResult, BILINGUAL_TABLE_LAYOUTS, type BilingualBorders, type BilingualParagraphRef, type BilingualRow, type BilingualRowKind, type BilingualTableLayout, type BilingualTableParagraphRef, type CreateBilingualDocumentOptions, type CreateBilingualDocumentResult, type CreateBilingualDocxOptions, type CreateBilingualDocxResult, type CreateCommentReplyInput, type CreateEmptyDocumentOptions, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, type DeriveBlockIdInput, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, DocxArchiveError, type DocxArchiveOptions, type DocxParagraphSource, type DocxTableRowKind, type DocxTableRowPosition, EnsureParaIdsError, type EnsureParaIdsOptions, type EnsureParaIdsResult, type EvaluateDocxXmlPatchProposalArgs, type ExtractDocumentStyleSetOptions, type ExtractedDocxParagraph, type ExtractedDocxTableCell, type ExtractedDocxTableCellParagraph, type ExtractedDocxText, FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, 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_DOCX_CONFORMANCE_CHECKS, FOLIO_DOCX_CONFORMANCE_ISSUE_CODES, FOLIO_DOCX_CONFORMANCE_PROFILE, FOLIO_DOCX_CONFORMANCE_REPORT_VERSION, FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS, FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES, FOLIO_DOCX_PACKAGE_INSPECTION_VERSION, FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE, FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION, FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS, FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES, FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE, FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, FOLIO_YJS_DOCX_MATERIALIZATION_ERROR_CODES, FOLIO_YJS_PROSEMIRROR_FRAGMENT_NAME, FOLIO_YJS_UPDATE_MAX_BYTES, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIBlockStructuralBoundary, type FolioAIComment, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditSnapshot, type FolioAIInlineBooleanProperty, type FolioAIInlineFormatting, type FolioAIInlineFormattingPatch, type FolioAIParagraphSpacing, type FolioAITextRangeHandle, type FolioApplyDocumentOperationsOptions, type FolioApplyDocumentOperationsToStoryOptions, type FolioApplyOperationsOptions, type FolioBlockDiff, type FolioBlockId, type FolioBlockProperty, type FolioCompareDocxVersionsOptions, type FolioDocumentMetadataProperty, type FolioDocumentMetadataValue, type FolioDocumentNavigationTarget, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationBatchPrecondition, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationQueuedOperation, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, 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, type FolioDocxConformanceCheck, type FolioDocxConformanceCheckId, type FolioDocxConformanceCheckStatus, type FolioDocxConformanceIssue, type FolioDocxConformanceIssueCode, type FolioDocxConformanceReport, type FolioDocxConformanceStatus, type FolioDocxInspectedXmlPart, type FolioDocxPackageInspection, FolioDocxPackageInspectionError, type FolioDocxPackageInspectionErrorCode, type FolioDocxPackageInspectionLimits, type FolioDocxPackagePart, type FolioDocxPackagePartKind, type FolioDocxPreparedXmlReplacement, FolioDocxReviewer, type FolioDocxReviewerOptions, type FolioDocxXmlPatchApplication, FolioDocxXmlPatchApplicationError, type FolioDocxXmlPatchApplicationReceipt, type FolioDocxXmlPatchProposal, type FolioDocxXmlPatchProposalEvaluation, type FolioDocxXmlPatchProposalIssue, type FolioDocxXmlPatchProposalIssueCode, type FolioDocxXmlPatchProposalLimits, type FolioDocxXmlReplacement, 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 FolioVersionChangeProperty, type FolioVersionComparisonPrivacyTransform, type FolioVersionComparisonScope, type FolioVersionDiff, type FolioVersionDiffPrivacyOptions, type FolioVersionDiffPrivacyReport, type FolioVersionDiffSegment, type FolioVersionDiffSummaryCounts, FolioYjsDocxMaterializationError, type FolioYjsDocxMaterializationErrorCode, type GenerateRedlineDocxOptions, type GenerateRedlineDocxResult, type GenerateRedlineUnprocessedStory, HEADING_LEVELS, type HeadingLevel, type InspectDocxPackageOptions, InvalidBilingualDocumentOptionsError, InvalidFolioDocumentOperationBatchError, InvalidFolioDocumentPrivacyOptionsError, InvalidFolioDocxXmlPatchProposalError, InvalidFolioDocxXmlPatchProposalOptionsError, InvalidFolioReportBuilderOptionsError, InvalidFolioVersionComparisonOptionsError, InvalidGenerateRedlineDocxOptionsError, type MaterializeYjsDocxOptions, type ParseOptions, type RewriteDocxMetadataPrivacyResult, STELLA_STYLE_SET_NAME, type TableCellSpec, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioDocxXmlPatchApplicationProfileError, UnsupportedFolioReviewedViewError, type ValidateDocxConformanceOptions, applyDocxXmlPatchProposal, applyFolioAIEditsToBuffer, applyFolioVersionDiffPrivacy, assertSupportedFolioDocumentOperationVersion, bookmark, compareDocxVersions, createBilingualDocument, createBilingualDocx, createDocx, createEmptyDocument, createFolioAITextRangeHandle, createStellaStyleDocumentPreset, createStellaStyleSet, createTableOfContentsField, deriveBlockId, docxToMarkdown, endnote, ensureParaIds, evaluateDocxXmlPatchProposal, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractDocxText, generateRedlineDocx, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, hashFolioAIBlockText, heading, hyperlink, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxPackage, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isFolioDocumentPrivacyTransform, isFolioResolvedReviewedView, isFolioReviewedView, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope, isSequentialFolioBlockId, isSupportedFolioDocumentOperationVersion, materializeYjsDocx, normalizeFolioAIBlockText, pageBreak, paragraph, parseDocx, parseFolioDocumentOperationBatch, parseFolioDocxXmlPatchProposal, readBilingualDocument, readBilingualDocx, readFolioDocumentSection, replyToComment, rewriteDocxMetadataPrivacy, run, table, validateDocxConformance };
+export { type ApplyDocxXmlPatchProposalArgs, type ApplyFolioAIEditsToBufferOptions, type ApplyFolioAIEditsToBufferResult, BILINGUAL_TABLE_LAYOUTS, type BilingualBorders, type BilingualParagraphRef, type BilingualRow, type BilingualRowKind, type BilingualTableLayout, type BilingualTableParagraphRef, type CreateBilingualDocumentOptions, type CreateBilingualDocumentResult, type CreateBilingualDocxOptions, type CreateBilingualDocxResult, type CreateCommentReplyInput, type CreateEmptyDocumentOptions, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, type DeriveBlockIdInput, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, DocxArchiveError, type DocxArchiveOptions, type DocxParagraphSource, type DocxTableRowKind, type DocxTableRowPosition, EnsureParaIdsError, type EnsureParaIdsOptions, type EnsureParaIdsResult, type EvaluateDocxXmlPatchProposalArgs, type ExtractDocumentStyleSetOptions, type ExtractedDocxParagraph, type ExtractedDocxTableCell, type ExtractedDocxTableCellParagraph, type ExtractedDocxText, FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, 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_DOCX_CONFORMANCE_CHECKS, FOLIO_DOCX_CONFORMANCE_ISSUE_CODES, FOLIO_DOCX_CONFORMANCE_PROFILE, FOLIO_DOCX_CONFORMANCE_REPORT_VERSION, FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS, FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES, FOLIO_DOCX_PACKAGE_INSPECTION_VERSION, FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE, FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION, FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS, FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES, FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE, FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, FOLIO_YJS_DOCX_MATERIALIZATION_ERROR_CODES, FOLIO_YJS_PROSEMIRROR_FRAGMENT_NAME, FOLIO_YJS_UPDATE_MAX_BYTES, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIBlockStructuralBoundary, type FolioAIComment, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditSnapshot, type FolioAIInlineBooleanProperty, type FolioAIInlineFormatting, type FolioAIInlineFormattingPatch, type FolioAIParagraphSpacing, type FolioAITextRangeHandle, type FolioApplyDocumentOperationsOptions, type FolioApplyDocumentOperationsToStoryOptions, type FolioApplyOperationsOptions, type FolioBlockDiff, type FolioBlockId, type FolioBlockProperty, type FolioCompareDocxVersionsOptions, type FolioContentParagraphKind, type FolioDocumentMetadataProperty, type FolioDocumentMetadataValue, type FolioDocumentNavigationTarget, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationBatchPrecondition, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationQueuedOperation, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, 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, type FolioDocxConformanceCheck, type FolioDocxConformanceCheckId, type FolioDocxConformanceCheckStatus, type FolioDocxConformanceIssue, type FolioDocxConformanceIssueCode, type FolioDocxConformanceReport, type FolioDocxConformanceStatus, type FolioDocxInspectedXmlPart, type FolioDocxPackageInspection, FolioDocxPackageInspectionError, type FolioDocxPackageInspectionErrorCode, type FolioDocxPackageInspectionLimits, type FolioDocxPackagePart, type FolioDocxPackagePartKind, type FolioDocxPreparedXmlReplacement, FolioDocxReviewer, type FolioDocxReviewerOptions, type FolioDocxXmlPatchApplication, FolioDocxXmlPatchApplicationError, type FolioDocxXmlPatchApplicationReceipt, type FolioDocxXmlPatchProposal, type FolioDocxXmlPatchProposalEvaluation, type FolioDocxXmlPatchProposalIssue, type FolioDocxXmlPatchProposalIssueCode, type FolioDocxXmlPatchProposalLimits, type FolioDocxXmlReplacement, 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 FolioVersionChangeProperty, type FolioVersionComparisonPrivacyTransform, type FolioVersionComparisonScope, type FolioVersionDiff, type FolioVersionDiffPrivacyOptions, type FolioVersionDiffPrivacyReport, type FolioVersionDiffSegment, type FolioVersionDiffSummaryCounts, FolioYjsDocxMaterializationError, type FolioYjsDocxMaterializationErrorCode, type GenerateRedlineDocxOptions, type GenerateRedlineDocxResult, type GenerateRedlineUnprocessedStory, HEADING_LEVELS, type HeadingLevel, type InspectDocxPackageOptions, InvalidBilingualDocumentOptionsError, InvalidFolioDocumentOperationBatchError, InvalidFolioDocumentPrivacyOptionsError, InvalidFolioDocxXmlPatchProposalError, InvalidFolioDocxXmlPatchProposalOptionsError, InvalidFolioReportBuilderOptionsError, InvalidFolioVersionComparisonOptionsError, InvalidGenerateRedlineDocxOptionsError, type MaterializeYjsDocxOptions, type ParseOptions, type RewriteDocxMetadataPrivacyResult, STELLA_STYLE_SET_NAME, type TableCellSpec, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioDocxXmlPatchApplicationProfileError, UnsupportedFolioReviewedViewError, type ValidateDocxConformanceOptions, applyDocxXmlPatchProposal, applyFolioAIEditsToBuffer, applyFolioVersionDiffPrivacy, assertSupportedFolioDocumentOperationVersion, bookmark, compareDocxVersions, createBilingualDocument, createBilingualDocx, createDocx, createEmptyDocument, createFolioAITextRangeHandle, createStellaStyleDocumentPreset, createStellaStyleSet, createTableOfContentsField, deriveBlockId, docxToMarkdown, endnote, ensureParaIds, evaluateDocxXmlPatchProposal, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractDocxText, generateRedlineDocx, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, hashFolioAIBlockText, heading, hyperlink, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxPackage, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isFolioDocumentPrivacyTransform, isFolioResolvedReviewedView, isFolioReviewedView, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope, isSequentialFolioBlockId, isSupportedFolioDocumentOperationVersion, materializeYjsDocx, normalizeFolioAIBlockText, pageBreak, paragraph, parseDocx, parseFolioDocumentOperationBatch, parseFolioDocxXmlPatchProposal, readBilingualDocument, readBilingualDocx, readFolioDocumentSection, replyToComment, rewriteDocxMetadataPrivacy, run, table, validateDocxConformance };

package/dist/version-comparison.js

@@ -21,39 +21,35 @@ import { TaggedError, panic } from "better-result";
 * ## Alignment
 *
 * Compatible body and table/container segments are aligned by the neutral
-* comparison core. Within each compatible segment, blocks are paired in
-* three passes, each only considering blocks the previous pass left unpaired:
+* comparison core. Quadratic structural candidate alignment shares bounded
+* cell and token budgets across the comparison. Within each compatible
+* segment, blocks are paired in four confidence-ordered passes:
 *
 * 1. **Stable-id pairing.** Blocks whose ids are equal and whose snapshot
-*    provenance marks those ids stable are paired directly. A source
-*    `w14:paraId` is stable identity independent of text, so an equal-id pair
-*    with different text is a genuine edit (`modified`). Deterministically
-*    synthesized ids and `seq-NNNN` fallbacks are positional instead: the
-*    adapter preserves that provenance so an ordinal shift falls through to
-*    exact-text alignment rather than becoming a false identity match.
-* 2. **Exact-text pairing.** An order-preserving LCS over remaining blocks,
-*    matched by exact text equality. This is what recovers same-text blocks
-*    that pass 1 missed because a fallback id shifted with the ordinal. Its
-*    O(m·n) table is skipped ({@link exceedsLcsBudget}) once the unpaired
-*    counts on both sides would exceed a fixed cell budget, so a document
-*    with few/no stable ids can't force a quadratic-sized allocation; those
-*    blocks fall through to pass 3 instead.
-* 3. **Positional fallback.** Whatever a monotonicity filter leaves
-*    unpaired is split into the gaps between anchored pairs (pass 1 + 2,
-*    time-ordered); within each gap the shorter side is zipped positionally
-*    against the longer one (`modified`), and any excess on either side is
-*    reported as `added` / `deleted`.
-*
-* The combined anchor set from passes 1 and 2 is re-filtered to the longest
-* increasing subsequence by revised-side index before pass 3 runs, so a
-* pathological crossing match (content reordered across versions) can't
-* produce an out-of-order gap — the alignment always walks both documents
-* forward.
+*    provenance marks those ids stable become the highest-confidence
+*    monotone anchor candidates. A source `w14:paraId` is stable identity
+*    independent of text, so an equal-id pair with different text is a genuine
+*    edit (`modified`). Deterministically synthesized ids and `seq-NNNN`
+*    fallbacks are positional instead: the adapter preserves that provenance
+*    so an ordinal shift falls through to exact-text alignment rather than
+*    becoming a false identity match.
+* 2. **Exact-text pairing.** Within each stable-id gap, nonblank text that is
+*    unique on both sides becomes an exact anchor. An O(n log n) increasing-
+*    subsequence selection keeps those anchors ordered; repeated or blank
+*    text is deliberately not treated as identity evidence.
+* 3. **Residual-id continuity.** Within the stable-plus-exact gaps, a unique
+*    id whose provenance changed between positional and stable may pair. This
+*    preserves identity across serialize-and-reopen boundaries without
+*    letting weaker evidence cross an established correspondence.
+* 4. **Positional fallback.** Whatever remains is split into the gaps between
+*    the confidence-ordered anchors; within each gap the shorter side is
+*    zipped positionally against the longer one (`modified`), and any excess
+*    on either side is reported as `added` / `deleted`.
 *
 * ## Move detection
 *
 * Relocated content would otherwise report as an unrelated `deleted` +
-* `added` pair (both order-preserving passes drop crossing matches by
+* `added` pair (the monotone alignment passes drop crossing matches by
 * design). The neutral comparison core re-classifies eligible exact and
 * closely edited pairs as `movedFrom` / `movedTo` entries sharing a
 * `moveGroupId`. Candidate counts and similarity work share bounded budgets

package/package.json

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