@stll/folio-core 0.33.0 → 0.33.2

package/dist/compare/verification.js

@@ -1,4 +1,19 @@
+import { PARAGRAPH_MARK_CHANGE_KINDS } from "@stll/docx-core/model";
 //#region src/compare/verification.ts
+/**
+* What the round-trip self-check found, and how to say it safely.
+*
+* The check compares two block projections: what accepting the generated
+* revisions leaves against the target, and what rejecting them leaves against
+* the base. A projection carries each block's container, style, list level and
+* text, so WHICH field diverged names which part of the pipeline lost the
+* difference — and that is worth reporting as a typed cause rather than as one
+* opaque "did not reproduce".
+*
+* Every `detail` string here is structural: counts, offsets, container kinds.
+* Never a phrase of either document, because a caller may log it, put it in a
+* report, or quote it in a review.
+*/
 /** The two directions of the round trip, each an invariant of its own. */
 const COMPARE_VERIFICATION_INVARIANTS = Object.freeze(["accept-reproduces-target", "reject-reproduces-base"]);
 /**
@@ -10,6 +25,7 @@ const COMPARE_VERIFICATION_CAUSES = Object.freeze([
 	"invisible-structure",
 	"block-count",
 	"container",
+	"table-geometry",
 	"style",
 	"list-level",
 	"inline-formatting",
@@ -116,6 +132,21 @@ const firstDivergence = (actual, expected) => {
 	};
 };
 /**
+* The failure two table-geometry projections describe, or `null` when they
+* agree. One line per table, so the detail names which table diverged and
+* whether the count itself did — never a property value, which could carry a
+* style name either document chose.
+*/
+const classifyGeometryMismatch = ({ invariant, story, actual, expected }) => {
+	if (sameProjection(actual, expected)) return null;
+	return {
+		invariant,
+		cause: "table-geometry",
+		story,
+		detail: actual.length === expected.length ? `table ${String(actual.findIndex((entry, index) => entry !== expected[index]))} of ${String(actual.length)} carries different properties` : `${String(actual.length)} tables against ${String(expected.length)}`
+	};
+};
+/**
 * The failure two projections describe, or `null` when they agree.
 *
 * Total over the causes by construction: the last branch is unconditional, so
@@ -142,5 +173,88 @@ const classifyProjectionMismatch = ({ invariant, story, actual, expected }) => {
 	if (actual.length !== expected.length) return failure("block-count", `${counts}, first differing ${at}`);
 	return failure("text", `a ${containerKind(left.container)} block's text does not match ${at}, length ${String(left.text.length)} against ${String(right.text.length)} (${counts})`);
 };
+const isAParagraphMarkChangeKind = (value) => PARAGRAPH_MARK_CHANGE_KINDS.some((kind) => kind === value);
+const isRecord = (value) => typeof value === "object" && value !== null;
+const isParagraph = (value) => isRecord(value) && value["type"] === "paragraph";
+/**
+* A row the package marks deleted, whose cells' marks go with it.
+*
+* A deleted table row is written as `w:trPr/w:del` PLUS a deletion on every
+* mark the row's cells end with: accepting takes the whole row away, so those
+* marks never have to join anything and are the shape the format asks for.
+*/
+const isADeletedTableRow = (value) => {
+	const change = value["structuralChange"];
+	return isRecord(change) && change["type"] === "tableRowDeletion";
+};
+/**
+* Every container in a package whose final paragraph mark carries a revision.
+*
+* A deleted paragraph mark says "join this paragraph with the one after it",
+* and an inserted one says that break was ADDED, so rejecting it closes the
+* paragraph back over the next one. The last paragraph of a body, a table
+* cell, a header or footer, a note or a text box has no paragraph after it, so
+* neither direction states an edit that can be carried out: a consumer refuses
+* the package, or opens it and leaves a revision standing that neither
+* accepting nor rejecting everything can clear. The exception is a cell of a
+* row the package is DELETING: there the mark leaves with its row.
+*
+* The walk is over the package model rather than over a list of the containers
+* known today: a container is any sequence that ends in a paragraph, so a part
+* the model grows later is covered the day it arrives instead of the day
+* someone remembers this function.
+*
+* `since` scopes it to the revisions a comparison MINTED: a base may arrive
+* carrying one of these on a paragraph in a part no story mounts, which folio
+* preserves the way it preserves everything else it parses. What this proves
+* is that the comparison writes none of its own.
+*/
+const revisedFinalParagraphMarks = (packageModel, { since = 0 } = {}) => {
+	const found = [];
+	const trail = ["package"];
+	const pathOf = () => {
+		let path = "";
+		for (const segment of trail) path += typeof segment === "number" ? `[${String(segment)}]` : `.${segment}`;
+		return path.slice(1);
+	};
+	const visit = (value, insideADeletedRow) => {
+		if (Array.isArray(value)) {
+			const last = value.at(-1);
+			const mark = isParagraph(last) ? last["pPrMark"] : void 0;
+			const kind = isRecord(mark) ? mark["kind"] : void 0;
+			const info = isRecord(mark) ? mark["info"] : void 0;
+			const revisionId = isRecord(info) ? info["id"] : void 0;
+			const isOurs = typeof revisionId === "number" ? revisionId >= since : true;
+			if (isAParagraphMarkChangeKind(kind) && isOurs && !insideADeletedRow) found.push({
+				container: pathOf(),
+				paragraphIndex: value.length - 1,
+				kind
+			});
+			for (const [index, item] of value.entries()) {
+				trail.push(index);
+				visit(item, insideADeletedRow);
+				trail.pop();
+			}
+			return;
+		}
+		if (value instanceof Map) {
+			for (const [key, item] of value) {
+				trail.push(String(key));
+				visit(item, insideADeletedRow);
+				trail.pop();
+			}
+			return;
+		}
+		if (!isRecord(value) || value instanceof Date || ArrayBuffer.isView(value)) return;
+		const inADeletedRow = insideADeletedRow || isADeletedTableRow(value);
+		for (const [key, item] of Object.entries(value)) {
+			trail.push(key);
+			visit(item, inADeletedRow);
+			trail.pop();
+		}
+	};
+	visit(packageModel, false);
+	return found;
+};
 //#endregion
-export { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, classifyProjectionMismatch, projectSupportedInlineFormatting, sameProjection };
+export { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, classifyGeometryMismatch, classifyProjectionMismatch, projectSupportedInlineFormatting, revisedFinalParagraphMarks, sameProjection };

package/dist/compat/eigenpal.d.ts

@@ -1,16 +1,16 @@
+import { document_d_exports } from "../types/document.js";
 import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIBlockTableLocation, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, 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";
-import { document_d_exports } from "../types/document.js";
 import { ApplyFolioDocumentOperationsOptions, 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, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "../document-operations.js";
 import { createFolioAIEditSnapshot, hashFolioAIBlockText, isFolioAIContentBlock, normalizeFolioAIBlockText } from "../ai-edits/snapshot.js";
-import { DeriveBlockIdInput, FolioBlockId, deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId } from "../types/block-id.js";
+import { DeriveBlockIdInput, FolioBlockId, currentFolioBlockId, deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId } from "../types/block-id.js";
 import { AIBarStatus, AIChatMode, AICitation, AICitationSource, AIGenerateInput, AISuggestion, AISuggestionApplyMode, AISuggestionPreset, AISuggestionSeverity, AISuggestionStatus, DEFAULT_AI_SUGGESTION_PRESETS } from "../ai-suggestions/types.js";
 import { ApplyResult, applySuggestions } from "../ai-suggestions/apply.js";
 import { ResolvedAnchor, isSuggestionStale, resolveSuggestionAnchor } from "../ai-suggestions/conflict.js";
 import { PositionalText, buildPositionalText } from "../ai-suggestions/text-positions.js";
-import { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareVerification, CompareVerificationCause, CompareVerificationFailure, CompareVerificationInvariant } from "../compare/verification.js";
-import { COMPARE_UNSUPPORTED_REASONS, CompareChange, CompareChangeLocation, CompareDocxApplyError, CompareDocxError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, CompareFormatRange, CompareResult, CompareUnsupportedPart, CompareUnsupportedReason, InvalidCompareDocxOptionsError } from "../compare/types.js";
+import { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareVerification, CompareVerificationCause, CompareVerificationFailure, CompareVerificationInvariant, FinalParagraphMarkRevision } from "../compare/verification.js";
+import { COMPARE_UNSUPPORTED_REASONS, CompareChange, CompareChangeLocation, CompareDocxApplyError, CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, CompareFormatRange, CompareResult, CompareUnsupportedPart, CompareUnsupportedReason, InvalidCompareDocxOptionsError } from "../compare/types.js";
 import { MAX_COMPARE_OPERATIONS, compareDocx } from "../compare/compare.js";
 import { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DocumentPreset, DocumentStyleSet } from "../style-sets/types.js";
 import { CreateEmptyDocumentOptions, createEmptyDocument } from "../utils/createDocument.js";
@@ -37,4 +37,4 @@ import { getGoogleFontsEnabled, setEmbeddedFontFamilyMap, setGoogleFontsEnabled
 import { DOCX_CONFORMANCE_CLASSES } from "../index.js";
 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, CompareDocxApplyError, type CompareDocxError, 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_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 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 FolioAISignatureParty, type FolioBlockId, 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, 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, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, 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, 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_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 FinalParagraphMarkRevision, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, 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 FolioAISignatureParty, type FolioBlockId, 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, 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, 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/compat/eigenpal.js

@@ -6,7 +6,7 @@ import { isSuggestionStale, resolveSuggestionAnchor } from "../ai-suggestions/co
 import { buildPositionalText } from "../ai-suggestions/text-positions.js";
 import { DEFAULT_AI_SUGGESTION_PRESETS } from "../ai-suggestions/types.js";
 import { MAX_COMPARE_OPERATIONS, compareDocx } from "../compare/compare.js";
-import { COMPARE_UNSUPPORTED_REASONS, CompareDocxApplyError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, InvalidCompareDocxOptionsError } from "../compare/types.js";
+import { COMPARE_UNSUPPORTED_REASONS, CompareDocxApplyError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, InvalidCompareDocxOptionsError } from "../compare/types.js";
 import { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS } from "../compare/verification.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, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "../document-operations.js";
 import { inspectDocxCompatibility } from "../docx/compatibility.js";
@@ -27,8 +27,8 @@ import { clearTemplateSlashMenu, consumeTemplateSlashQuery, getTemplateSlashMenu
 import { extractDocumentStyleSet, extractDocumentStyleSetFromDocx, inspectDocumentStyles, inspectDocumentStylesFromDocx } from "../style-sets/extract.js";
 import { STELLA_STYLE_SET_NAME, createStellaStyleDocumentPreset, createStellaStyleSet } from "../style-sets/stellaStyle.js";
 import { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION } from "../style-sets/types.js";
-import { deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId } from "../types/block-id.js";
+import { currentFolioBlockId, deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId } from "../types/block-id.js";
 import { createEmptyDocument } from "../utils/createDocument.js";
 import { getGoogleFontsEnabled, setEmbeddedFontFamilyMap, setGoogleFontsEnabled } from "../utils/fontResolver.js";
 import { mergeDocumentContent } from "../utils/mergeDocumentContent.js";
-export { COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareDocxApplyError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, 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, InvalidCompareDocxOptionsError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, 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 { COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareDocxApplyError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, 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, InvalidCompareDocxOptionsError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, 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/document-operations.d.ts

@@ -1,3 +1,4 @@
+import { FolioTableTemplates } from "./ai-edits/table-template.js";
 import { FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditNormalization, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAITextRangeHandle } from "./ai-edits/types.js";
 import { FolioAIEditView, FolioRevisionStamp, FolioWordDiffOptions } from "./ai-edits/apply.js";
 //#region src/document-operations.d.ts
@@ -266,7 +267,15 @@ type ApplyFolioDocumentOperationsOptions = {
   revisionStamp?: FolioRevisionStamp;
   /** Token size a replacement's redline is cut at. Word-level by default. */
   wordDiff?: FolioWordDiffOptions;
+  /**
+   * Tables and rows an `insertTable` / `insertTableRow` in the batch places
+   * verbatim, by operation id. Outside the serialized batch because a table
+   * node is not JSON: the contract still describes a table by its cell texts,
+   * and an in-process caller that already holds the table — a comparison
+   * copying the target document's — hands the whole thing over instead.
+   */
+  tableTemplates?: FolioTableTemplates;
 };
-declare const applyFolioDocumentOperations: ({ view, snapshot, batch, story, author, createCommentId, createUndoHandle, revisionStamp, wordDiff }: ApplyFolioDocumentOperationsOptions) => FolioDocumentOperationResult;
+declare const applyFolioDocumentOperations: ({ view, snapshot, batch, story, author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates }: ApplyFolioDocumentOperationsOptions) => FolioDocumentOperationResult;
 //#endregion
 export { ApplyFolioDocumentOperationsOptions, 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, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };

package/dist/document-operations.js

@@ -879,7 +879,7 @@ const getFolioDocumentOperationReceiptsForStory = ({ operations, applied, story
 	});
 	return receipts;
 };
-const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", author, createCommentId, createUndoHandle, revisionStamp, wordDiff }) => {
+const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates }) => {
 	const parsedBatch = parseFolioDocumentOperationBatch(batch);
 	const apply = ({ targetView, targetCreateCommentId = createCommentId, preview = false }) => {
 		return (preview ? previewFolioAIEditOperations : applyFolioAIEditOperations)({
@@ -890,7 +890,8 @@ const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", a
 			...author !== void 0 && { author },
 			...targetCreateCommentId !== void 0 && { createCommentId: targetCreateCommentId },
 			...revisionStamp !== void 0 && { revisionStamp },
-			...wordDiff !== void 0 && { wordDiff }
+			...wordDiff !== void 0 && { wordDiff },
+			...tableTemplates !== void 0 && { tableTemplates }
 		});
 	};
 	const preview = () => apply({

package/dist/docx/appVersionNormalization.d.ts

@@ -0,0 +1,49 @@
+//#region src/docx/appVersionNormalization.d.ts
+/**
+ * Keep the application version a package states about itself in the form the
+ * schema gives it.
+ *
+ * `AppVersion` in the extended-properties part is `XX.YYYY`: a one- or
+ * two-digit integer, a dot, and four digits. Producers exist that write a
+ * three-part version there instead, and folio copies `docProps/app.xml`
+ * through verbatim when it saves a document it did not create — so a package
+ * can carry a value with two dots in, and a save that copies it out hands a
+ * consumer a package it refuses to open at all.
+ *
+ * {@link appVersionInSchemaForm} is the one mapping, and it is a pure function
+ * of the value alone: it keeps the leading integer where the value opens with
+ * one the form allows, and writes the build digits the form requires. Nothing
+ * else in the part is touched, and a package that carries no extended
+ * properties keeps carrying none — synthesizing metadata a document never
+ * stated is a different decision.
+ */
+declare const AppVersionSchemaError_base: import("better-result").TaggedErrorClass<"AppVersionSchemaError">;
+/**
+ * A value reached the package that the schema form does not accept.
+ *
+ * The normalization hands every value it writes to one choke point, which
+ * throws this rather than letting the package go out carrying a version a
+ * consumer refuses.
+ */
+declare class AppVersionSchemaError extends AppVersionSchemaError_base<{
+  message: string;
+  appVersion: string;
+}> {}
+/**
+ * `value` when it already fits, and a value derived from it when it does not.
+ *
+ * The derivation reads the value and nothing else — not the package, not the
+ * clock, not folio's own version — so two saves of one document state the same
+ * application version.
+ */
+declare const appVersionInSchemaForm: (value: string) => string;
+/**
+ * Rewrite the application version an extended-properties part states.
+ *
+ * Returns the part unchanged when the value already fits and when the part
+ * states no version at all, so a save of a document that never carried a
+ * malformed one is byte-identical.
+ */
+declare const normalizeAppVersionInExtendedProperties: (xml: string) => string;
+//#endregion
+export { AppVersionSchemaError, appVersionInSchemaForm, normalizeAppVersionInExtendedProperties };

package/dist/docx/appVersionNormalization.js

@@ -0,0 +1,74 @@
+import { TaggedError } from "better-result";
+//#region src/docx/appVersionNormalization.ts
+/**
+* Keep the application version a package states about itself in the form the
+* schema gives it.
+*
+* `AppVersion` in the extended-properties part is `XX.YYYY`: a one- or
+* two-digit integer, a dot, and four digits. Producers exist that write a
+* three-part version there instead, and folio copies `docProps/app.xml`
+* through verbatim when it saves a document it did not create — so a package
+* can carry a value with two dots in, and a save that copies it out hands a
+* consumer a package it refuses to open at all.
+*
+* {@link appVersionInSchemaForm} is the one mapping, and it is a pure function
+* of the value alone: it keeps the leading integer where the value opens with
+* one the form allows, and writes the build digits the form requires. Nothing
+* else in the part is touched, and a package that carries no extended
+* properties keeps carrying none — synthesizing metadata a document never
+* stated is a different decision.
+*/
+/** `XX.YYYY`: the only form the extended-properties `AppVersion` may take. */
+const SCHEMA_FORM = /^\d{1,2}\.\d{4}$/u;
+/** The leading integer, when the value opens with one the form allows. */
+const LEADING_MAJOR = /^\d{1,2}(?!\d)/u;
+/** Major version for a value that does not open with one. */
+const DEFAULT_MAJOR = "1";
+/**
+* The build digits a rewritten value gets. A value the form rejects states no
+* build this pass could carry over, so every rewrite lands on the same one.
+*/
+const CANONICAL_BUILD = "0000";
+/**
+* A value reached the package that the schema form does not accept.
+*
+* The normalization hands every value it writes to one choke point, which
+* throws this rather than letting the package go out carrying a version a
+* consumer refuses.
+*/
+var AppVersionSchemaError = class extends TaggedError("AppVersionSchemaError") {};
+/**
+* `value` when it already fits, and a value derived from it when it does not.
+*
+* The derivation reads the value and nothing else — not the package, not the
+* clock, not folio's own version — so two saves of one document state the same
+* application version.
+*/
+const appVersionInSchemaForm = (value) => {
+	if (SCHEMA_FORM.test(value)) return value;
+	const normalized = `${LEADING_MAJOR.exec(value.trim())?.[0] ?? DEFAULT_MAJOR}.${CANONICAL_BUILD}`;
+	if (!SCHEMA_FORM.test(normalized)) throw new AppVersionSchemaError({
+		message: `Derived application version ${normalized} is not of the form XX.YYYY`,
+		appVersion: value
+	});
+	return normalized;
+};
+/**
+* The element and its content, with the prefix and attributes it was written
+* with preserved: the replacement rewrites the value between the tags and
+* leaves the rest of the part byte-identical.
+*/
+const APP_VERSION_ELEMENT = /(<(?:[^\s<>/:]+:)?AppVersion(?:\s[^<>]*)?>)([^<]*)(<\/(?:[^\s<>/:]+:)?AppVersion>)/u;
+/**
+* Rewrite the application version an extended-properties part states.
+*
+* Returns the part unchanged when the value already fits and when the part
+* states no version at all, so a save of a document that never carried a
+* malformed one is byte-identical.
+*/
+const normalizeAppVersionInExtendedProperties = (xml) => xml.replace(APP_VERSION_ELEMENT, (whole, open, value, close) => {
+	const replacement = appVersionInSchemaForm(value);
+	return replacement === value ? whole : `${open}${replacement}${close}`;
+});
+//#endregion
+export { AppVersionSchemaError, appVersionInSchemaForm, normalizeAppVersionInExtendedProperties };

package/dist/docx/blockContentParser.js

@@ -6,7 +6,8 @@ import { parseParagraph } from "./paragraphParser.js";
 import { enrichParagraphTextBoxes } from "./paragraphTextBoxEnrichment.js";
 import { parseSdtProperties } from "./sdtProperties.js";
 import { parseTable } from "./tableParser.js";
-import { elementToXml, findChild, getChildElements, getLocalName, mergeXmlnsDeclarations } from "./xmlParser.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { findChild, getChildElements, getLocalName, mergeXmlnsDeclarations } from "./xmlParser.js";
 //#region src/docx/blockContentParser.ts
 const computeListMarker = (paragraph, { numbering, listCounters, abstractCounters, restartedNumIds, previousList, siblingNumIdsByAbstractNumId }) => {
 	const listRendering = paragraph.listRendering;
@@ -192,7 +193,7 @@ const captureSdtSiblingMarkers = (sdt) => {
 			sawContent = true;
 			continue;
 		}
-		const xml = elementToXml(ch);
+		const xml = captureVerbatimXml(ch);
 		if (sawContent) afterParts.push(xml);
 		else beforeParts.push(xml);
 	}

package/dist/docx/drawingUtils.js

@@ -1,5 +1,6 @@
 import { ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, ShapeOutlineStyleSchema, narrowEnum } from "./parserEnums.js";
-import { elementToXml, findByFullName, findChildByLocalName, findChildrenByLocalName, getAttribute, getChildElements, getTextContent, parseNumericAttribute } from "./xmlParser.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { findByFullName, findChildByLocalName, findChildrenByLocalName, getAttribute, getChildElements, getTextContent, parseNumericAttribute } from "./xmlParser.js";
 //#region src/docx/drawingUtils.ts
 /**
 * Map OOXML scheme names to standard theme color slots.
@@ -162,7 +163,7 @@ function parseGradientFill(gradientFill) {
 	}
 	return {
 		type: "gradient",
-		rawXml: elementToXml(gradientFill),
+		rawXml: captureVerbatimXml(gradientFill),
 		gradient: {
 			type,
 			...angle !== void 0 ? { angle } : {},
@@ -177,7 +178,7 @@ function parseOutline(spPr) {
 	const ln = spPr ? findChildByLocalName(spPr, "ln") : null;
 	if (!ln) return;
 	if (findChildByLocalName(ln, "noFill")) return;
-	const outline = { rawXml: elementToXml(ln) };
+	const outline = { rawXml: captureVerbatimXml(ln) };
 	const w = getAttribute(ln, null, "w");
 	if (w) {
 		const parsed = Number.parseInt(w, 10);

package/dist/docx/hyperlinkParser.d.ts

@@ -16,6 +16,14 @@ import { XmlElement } from "./xmlParser.js";
  * @returns Parsed Hyperlink object
  */
 declare function parseHyperlink(node: XmlElement, rels: document_d_exports.RelationshipMap | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, media?: Map<string, document_d_exports.MediaFile> | null, rootXmlns?: Record<string, string>): document_d_exports.Hyperlink;
+/**
+ * One `w:hyperlink` child, or `null` for markup the model does not carry.
+ *
+ * Exposed so a caller that has to segment a hyperlink — one holding revision
+ * wrappers, which the model nests the other way round — parses its plain
+ * children exactly as {@link parseHyperlink} does.
+ */
+declare function parseHyperlinkChild(node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, inScopeXmlns: Record<string, string>): document_d_exports.Hyperlink["children"][number] | null;
 /**
  * Get the display text of a hyperlink
  *
@@ -104,4 +112,4 @@ declare function createExternalHyperlink(url: string, children: document_d_expor
   target?: string;
 }): document_d_exports.Hyperlink;
 //#endregion
-export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };
+export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, parseHyperlinkChild, resolveHyperlinkUrl };

package/dist/docx/hyperlinkParser.js

@@ -71,22 +71,28 @@ function parseHyperlink(node, rels, styles = null, theme = null, media = null, r
 	const docLocation = getAttribute(node, "w", "docLocation");
 	if (docLocation) hyperlink.docLocation = docLocation;
 	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
-	const children = getChildElements(node);
-	for (const child of children) switch (getLocalName(child.name)) {
-		case "r":
-			hyperlink.children.push(parseRun(child, styles, theme, rels, media, inScopeXmlns));
-			break;
-		case "bookmarkStart":
-			hyperlink.children.push(parseBookmarkStart(child));
-			break;
-		case "bookmarkEnd":
-			hyperlink.children.push(parseBookmarkEnd(child));
-			break;
-		default: break;
+	for (const child of getChildElements(node)) {
+		const parsed = parseHyperlinkChild(child, styles, theme, rels, media, inScopeXmlns);
+		if (parsed) hyperlink.children.push(parsed);
 	}
 	return hyperlink;
 }
 /**
+* One `w:hyperlink` child, or `null` for markup the model does not carry.
+*
+* Exposed so a caller that has to segment a hyperlink — one holding revision
+* wrappers, which the model nests the other way round — parses its plain
+* children exactly as {@link parseHyperlink} does.
+*/
+function parseHyperlinkChild(node, styles, theme, rels, media, inScopeXmlns) {
+	switch (getLocalName(node.name)) {
+		case "r": return parseRun(node, styles, theme, rels, media, inScopeXmlns);
+		case "bookmarkStart": return parseBookmarkStart(node);
+		case "bookmarkEnd": return parseBookmarkEnd(node);
+		default: return null;
+	}
+}
+/**
 * Get the display text of a hyperlink
 *
 * Concatenates text from all child runs.
@@ -219,4 +225,4 @@ function createExternalHyperlink(url, children, options) {
 	};
 }
 //#endregion
-export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };
+export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, parseHyperlinkChild, resolveHyperlinkUrl };

package/dist/docx/paraIdRangeNormalization.d.ts

@@ -0,0 +1,40 @@
+//#region src/docx/paraIdRangeNormalization.d.ts
+/**
+ * Keep every paragraph id a package carries inside the range the schema gives
+ * it.
+ *
+ * `w14:paraId`, `w14:textId` and the comment-part ids that reference a
+ * paragraph are `ST_LongHexNumber` with a maximum: the value has to be below
+ * `0x80000000`, so the ids are 31-bit. Producers exist that write eight hex
+ * digits without that bound, and folio preserves the ids a document arrives
+ * with — so a package can carry an out-of-range id in, and a save that copies
+ * it through hands a consumer a package it will refuse.
+ *
+ * {@link paraIdInRange} is the one mapping, and it is a pure function of the
+ * value alone. That is what lets the parser and the save agree without
+ * consulting each other: a paragraph's id in the model is the id the file gets,
+ * so bringing an id into range does not make a document's own identity move
+ * under it between reading and writing. The package pass below is the same
+ * mapping applied to every attribute that carries such an id, so a paragraph
+ * and every reference to it move together.
+ */
+/**
+ * `value` when it already fits, and a value derived from it when it does not.
+ *
+ * The replacement is derived from the id being replaced and from nothing else.
+ * A package-aware search for a free id would read better here and would be
+ * wrong: the parser has no package to search, and an id that means one
+ * paragraph while reading and another while writing is worse than the
+ * vanishing chance of two rewritten ids landing on one value, which is a
+ * duplicate rather than a package a consumer refuses.
+ */
+declare const paraIdInRange: (value: string) => string;
+/**
+ * Rewrite out-of-range paragraph ids across a whole package.
+ *
+ * Returns the parts unchanged when every id already fits, so a save of a
+ * document that never carried one is byte-identical.
+ */
+declare const normalizeParaIdRangeInXmlParts: (parts: ReadonlyMap<string, string>) => Map<string, string>;
+//#endregion
+export { normalizeParaIdRangeInXmlParts, paraIdInRange };

package/dist/docx/paraIdRangeNormalization.js

@@ -0,0 +1,64 @@
+import { deterministicHexId } from "../utils/hexId.js";
+//#region src/docx/paraIdRangeNormalization.ts
+/**
+* Keep every paragraph id a package carries inside the range the schema gives
+* it.
+*
+* `w14:paraId`, `w14:textId` and the comment-part ids that reference a
+* paragraph are `ST_LongHexNumber` with a maximum: the value has to be below
+* `0x80000000`, so the ids are 31-bit. Producers exist that write eight hex
+* digits without that bound, and folio preserves the ids a document arrives
+* with — so a package can carry an out-of-range id in, and a save that copies
+* it through hands a consumer a package it will refuse.
+*
+* {@link paraIdInRange} is the one mapping, and it is a pure function of the
+* value alone. That is what lets the parser and the save agree without
+* consulting each other: a paragraph's id in the model is the id the file gets,
+* so bringing an id into range does not make a document's own identity move
+* under it between reading and writing. The package pass below is the same
+* mapping applied to every attribute that carries such an id, so a paragraph
+* and every reference to it move together.
+*/
+/** Exclusive upper bound on a paragraph id: the values are 31-bit. */
+const MAX_PARA_ID_EXCLUSIVE = 2147483648;
+/**
+* Every attribute that carries a paragraph id or the text-revision marker
+* written beside one: the paragraph's own `w14:paraId` / `w14:textId` (the
+* parser accepts a `w:` prefix too), the comment part's `w15:paraId` and the
+* `w15:paraIdParent` that links a reply to its thread, and the durable-comment
+* part's `w16cid:paraId`.
+*/
+const PARA_ID_ATTRIBUTE = /\b(w|w14|w15|w16cid):(paraId|paraIdParent|textId)=(?<quote>["'])([0-9A-Fa-f]{8})\k<quote>/gu;
+/** A candidate part is one that mentions any of those attributes at all. */
+const PARA_ID_CANDIDATE = /\b(?:w|w14|w15|w16cid):(?:paraId|paraIdParent|textId)=/u;
+/**
+* `value` when it already fits, and a value derived from it when it does not.
+*
+* The replacement is derived from the id being replaced and from nothing else.
+* A package-aware search for a free id would read better here and would be
+* wrong: the parser has no package to search, and an id that means one
+* paragraph while reading and another while writing is worse than the
+* vanishing chance of two rewritten ids landing on one value, which is a
+* duplicate rather than a package a consumer refuses.
+*/
+const paraIdInRange = (value) => Number.parseInt(value, 16) < MAX_PARA_ID_EXCLUSIVE ? value : deterministicHexId(value);
+/**
+* Rewrite out-of-range paragraph ids across a whole package.
+*
+* Returns the parts unchanged when every id already fits, so a save of a
+* document that never carried one is byte-identical.
+*/
+const normalizeParaIdRangeInXmlParts = (parts) => {
+	const normalized = new Map(parts);
+	for (const [path, xml] of parts) {
+		if (!PARA_ID_CANDIDATE.test(xml)) continue;
+		const rewritten = xml.replaceAll(PARA_ID_ATTRIBUTE, (whole, prefix, name, quote, value) => {
+			const replacement = paraIdInRange(value);
+			return replacement === value ? whole : `${prefix}:${name}=${quote}${replacement}${quote}`;
+		});
+		if (rewritten !== xml) normalized.set(path, rewritten);
+	}
+	return normalized;
+};
+//#endregion
+export { normalizeParaIdRangeInXmlParts, paraIdInRange };