@stll/folio-core 0.54.2 → 0.55.0

package/dist/docx/runParser.js

@@ -9,6 +9,7 @@ import { imageRawXmlFingerprint } from "./imageRawXml.js";
 import { EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, TextEffectSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
 import { preserveRunChild } from "./preservedRunContent.js";
 import { standalonePreviewLedger } from "./previewBudget.js";
+import { parseBoundaryJoins } from "./reviewResolutionProvenance.js";
 import { parseShading } from "./shadingParser.js";
 import { captureShapeAlternateContent } from "./shapeAlternateContent.js";
 import { parseShapeFromDrawing, shouldPreserveRawShapeDrawing } from "./shapeParser.js";
@@ -22,6 +23,25 @@ import { WORDPROCESSINGML_NAMESPACE_URIS, cloneWithXmlnsDeclarations, findAllDee
 import { DRAWING_RAW_XML_MODES } from "@stll/docx-core/model";
 //#region src/docx/runParser.ts
 /**
+* Run Parser - Parse text runs (w:r) with complete formatting
+*
+* A run is a contiguous region of text with the same character formatting.
+* Runs can contain:
+* - Text (w:t)
+* - Tabs (w:tab)
+* - Line breaks (w:br)
+* - Symbols (w:sym)
+* - Footnote/endnote references
+* - Field characters
+* - Drawings/images (w:drawing)
+* - And more...
+*
+* OOXML Reference:
+* - Run: w:r
+* - Run properties: w:rPr
+* - Text content: w:t
+*/
+/**
 * Sanity cap on `w:lang` `@w:val`/`@w:eastAsia`/`@w:bidi` tag length. BCP-47
 * tags top out well under this; a hostile/corrupt tag here would drive the
 * hyphenation dictionary lookup and segmenter cache keying with an
@@ -81,6 +101,11 @@ const OWNED_BY_A_SIBLING_RECORD = {
 		reader: "runParser#parseRun"
 	}) },
 	paragraphMark: {
+		specVanish: ownedElsewhere({
+			container: "run-properties",
+			child: "specVanish",
+			reader: "paragraphProperties#parseParagraphProperties"
+		}),
 		ins: ownedElsewhere({
 			container: "run-properties",
 			child: "ins",
@@ -354,7 +379,6 @@ const RUN_PROPERTY_HANDLERS = {
 	},
 	paragraphMark: {
 		...RUN_PROPERTY_BASE_HANDLERS,
-		specVanish: readLastOccurrenceOnly(() => void 0),
 		...OWNED_BY_A_SIBLING_RECORD.paragraphMark
 	},
 	standalone: {
@@ -386,7 +410,8 @@ const RUN_PROPERTY_HANDLERS = {
 * it beat are not kept.
 *
 * An element that states nothing at all still yields a record: `undefined` here
-* means the owner carried no `w:rPr`, never that the one it carried was empty.
+* means the owner carried no `w:rPr`, or a paragraph-mark carrier contained
+* only metadata owned by the paragraph. An authored empty set remains {}.
 */
 function parseRunProperties(rPr, theme, owner) {
 	if (!rPr) return;
@@ -403,6 +428,8 @@ function parseRunProperties(rPr, theme, owner) {
 		}
 	});
 	if (preserved) formatting.preserved = preserved;
+	const children = getChildElements(rPr);
+	if (owner === RUN_PROPERTY_OWNERS.paragraphMark && Object.keys(formatting).length === 0 && children.length > 0 && children.every((child) => WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "") && Object.hasOwn(OWNED_BY_A_SIBLING_RECORD.paragraphMark, getLocalName(child.name)))) return;
 	return formatting;
 }
 function parseRunPropertyChanges(rPr, theme, currentFormatting) {
@@ -413,6 +440,8 @@ function parseRunPropertyChanges(rPr, theme, currentFormatting) {
 			type: "runPropertyChange",
 			info: parsePropertyChangeInfo(changeElement)
 		};
+		const boundaryJoins = parseBoundaryJoins(changeElement);
+		if (boundaryJoins !== void 0) change.boundaryJoins = boundaryJoins;
 		const previousFormatting = parseRunProperties(previousRPr, theme, RUN_PROPERTY_OWNERS.standalone);
 		if (previousFormatting) change.previousFormatting = previousFormatting;
 		if (currentFormatting) change.currentFormatting = currentFormatting;
@@ -602,130 +631,141 @@ function parseDrawingContent(element, rels, media, previews) {
 function parseRunContents(runElement, rels, media, previews, rootXmlns = {}) {
 	const contents = [];
 	const children = getChildElements(runElement);
-	for (const child of children) switch (getLocalName(child.name)) {
-		case "t":
-			contents.push(parseTextContent(child));
-			break;
-		case "tab":
-			contents.push(parseTabContent());
-			break;
-		case "ptab":
-			contents.push(parsePositionalTabContent(child));
-			break;
-		case "br":
-			contents.push(parseBreakContent(child));
-			break;
-		case "sym":
-			contents.push(parseSymbolContent(child));
-			break;
-		case "footnoteReference":
-			contents.push(parseFootnoteReference(child));
-			break;
-		case "endnoteReference":
-			contents.push(parseEndnoteReference(child));
-			break;
-		case "fldChar":
-			contents.push(parseFieldChar(child));
-			break;
-		case "instrText":
-			contents.push(parseInstrText(child));
-			break;
-		case "softHyphen":
-			contents.push({ type: "softHyphen" });
-			break;
-		case "noBreakHyphen":
-			contents.push({ type: "noBreakHyphen" });
-			break;
-		case "drawing": {
-			const drawing = parseDrawingContent(child, rels, media, previews);
-			if (drawing) contents.push(drawing);
-			break;
-		}
-		case "pict": {
-			const vmlDrawing = parseVmlImageContent(child, rels, media, previews, rootXmlns);
-			if (vmlDrawing) {
-				contents.push(vmlDrawing);
+	for (const child of children) {
+		const localName = getLocalName(child.name);
+		switch (localName) {
+			case "t":
+				contents.push(parseTextContent(child));
+				break;
+			case "tab":
+				contents.push(parseTabContent());
+				break;
+			case "ptab":
+				contents.push(parsePositionalTabContent(child));
+				break;
+			case "br":
+				contents.push(parseBreakContent(child));
+				break;
+			case "sym":
+				contents.push(parseSymbolContent(child));
+				break;
+			case "footnoteReference":
+				contents.push(parseFootnoteReference(child));
+				break;
+			case "endnoteReference":
+				contents.push(parseEndnoteReference(child));
+				break;
+			case "footnoteRef":
+			case "endnoteRef":
+				if (WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "")) contents.push({
+					type: "noteMarker",
+					kind: localName === "footnoteRef" ? "footnote" : "endnote"
+				});
+				else contents.push(preserveRunChild(child));
+				break;
+			case "fldChar":
+				contents.push(parseFieldChar(child));
+				break;
+			case "instrText":
+				contents.push(parseInstrText(child));
+				break;
+			case "softHyphen":
+				contents.push({ type: "softHyphen" });
+				break;
+			case "noBreakHyphen":
+				contents.push({ type: "noBreakHyphen" });
+				break;
+			case "drawing": {
+				const drawing = parseDrawingContent(child, rels, media, previews);
+				if (drawing) contents.push(drawing);
 				break;
 			}
-			if (shouldPreserveRawVmlPict(child)) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
-			break;
-		}
-		case "object": {
-			const objectPreview = parseVmlImageContent(child, rels, media, previews, rootXmlns);
-			contents.push(objectPreview ?? preserveRunChild(child));
-			break;
-		}
-		case "rPr": break;
-		case "commentReference": break;
-		case "lastRenderedPageBreak":
-			contents.push({ type: "renderedPageBreak" });
-			break;
-		case "cr":
-			contents.push({
-				type: "break",
-				sourceElement: "cr"
-			});
-			break;
-		case "AlternateContent": {
-			const alternateChildren = getChildElements(child);
-			const choiceEl = alternateChildren.find((el) => getLocalName(el.name) === "Choice");
-			const fallbackEl = alternateChildren.find((el) => getLocalName(el.name) === "Fallback");
-			const contentsBeforeAlternate = contents.length;
-			const choiceTextBoxDrawing = choiceEl ? getChildElements(choiceEl).find((element) => getLocalName(element.name) === "drawing" && isTextBoxDrawing(element)) : void 0;
-			const groupedChoiceDrawing = choiceEl ? getChildElements(choiceEl).find((element) => getLocalName(element.name) === "drawing" && findAllDeep(element, "wpg", "wgp").length > 0) : void 0;
-			if (groupedChoiceDrawing) {
-				const groupedDrawing = parseDrawingContent(groupedChoiceDrawing, rels, media, previews);
-				if (groupedDrawing?.type === "drawing" && groupedDrawing.rawXmlMode === DRAWING_RAW_XML_MODES.PREVIEW_ONLY && groupedDrawing.image.src) {
-					contents.push({
-						...groupedDrawing,
-						rawXml: captureVerbatimXml(child)
-					});
+			case "pict": {
+				const vmlDrawing = parseVmlImageContent(child, rels, media, previews, rootXmlns);
+				if (vmlDrawing) {
+					contents.push(vmlDrawing);
 					break;
 				}
+				if (shouldPreserveRawVmlPict(child)) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
+				break;
 			}
-			const fallbackPict = fallbackEl ? getChildElements(fallbackEl).find((el) => getLocalName(el.name) === "pict") : void 0;
-			const fallbackVml = fallbackPict && !choiceTextBoxDrawing ? parseVmlImageContent(fallbackPict, rels, media, previews, rootXmlns) : null;
-			if (fallbackVml?.image.src) {
-				fallbackVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
-				contents.push(fallbackVml);
+			case "object": {
+				const objectPreview = parseVmlImageContent(child, rels, media, previews, rootXmlns);
+				contents.push(objectPreview ?? preserveRunChild(child));
 				break;
 			}
-			const targetEl = selectAlternateContentBranch(child);
-			if (targetEl) for (const innerChild of getChildElements(targetEl)) {
-				const innerName = getLocalName(innerChild.name);
-				if (innerName === "drawing") {
-					const innerDrawing = parseDrawingContent(innerChild, rels, media, previews);
-					if (innerDrawing) {
-						if (innerDrawing.type === "drawing" && (innerDrawing.rawXml !== void 0 || !innerDrawing.image.src)) innerDrawing.rawXml = captureVerbatimXml(child);
-						if (innerDrawing.type === "shape") {
-							const alternateContent = captureShapeAlternateContent({
-								shape: innerDrawing.shape,
-								alternateContent: child,
-								branch: targetEl,
-								drawing: innerChild
-							});
-							if (alternateContent) innerDrawing.alternateContent = alternateContent;
-						}
-						contents.push(innerDrawing);
-					}
-				} else if (innerName === "pict") {
-					const innerVml = parseVmlImageContent(innerChild, rels, media, previews, rootXmlns);
-					if (innerVml) {
-						innerVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
-						contents.push(innerVml);
+			case "rPr": break;
+			case "commentReference": break;
+			case "lastRenderedPageBreak":
+				contents.push({ type: "renderedPageBreak" });
+				break;
+			case "cr":
+				contents.push({
+					type: "break",
+					sourceElement: "cr"
+				});
+				break;
+			case "AlternateContent": {
+				const alternateChildren = getChildElements(child);
+				const choiceEl = alternateChildren.find((el) => getLocalName(el.name) === "Choice");
+				const fallbackEl = alternateChildren.find((el) => getLocalName(el.name) === "Fallback");
+				const contentsBeforeAlternate = contents.length;
+				const choiceTextBoxDrawing = choiceEl ? getChildElements(choiceEl).find((element) => getLocalName(element.name) === "drawing" && isTextBoxDrawing(element)) : void 0;
+				const groupedChoiceDrawing = choiceEl ? getChildElements(choiceEl).find((element) => getLocalName(element.name) === "drawing" && findAllDeep(element, "wpg", "wgp").length > 0) : void 0;
+				if (groupedChoiceDrawing) {
+					const groupedDrawing = parseDrawingContent(groupedChoiceDrawing, rels, media, previews);
+					if (groupedDrawing?.type === "drawing" && groupedDrawing.rawXmlMode === DRAWING_RAW_XML_MODES.PREVIEW_ONLY && groupedDrawing.image.src) {
+						contents.push({
+							...groupedDrawing,
+							rawXml: captureVerbatimXml(child)
+						});
+						break;
 					}
-				} else contents.push(...parseRunContents({
-					...targetEl,
-					elements: [innerChild]
-				}, rels, media, previews, rootXmlns));
+				}
+				const fallbackPict = fallbackEl ? getChildElements(fallbackEl).find((el) => getLocalName(el.name) === "pict") : void 0;
+				const fallbackVml = fallbackPict && !choiceTextBoxDrawing ? parseVmlImageContent(fallbackPict, rels, media, previews, rootXmlns) : null;
+				if (fallbackVml?.image.src) {
+					fallbackVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
+					contents.push(fallbackVml);
+					break;
+				}
+				const targetEl = selectAlternateContentBranch(child);
+				if (targetEl) for (const innerChild of getChildElements(targetEl)) {
+					const innerName = getLocalName(innerChild.name);
+					if (innerName === "drawing") {
+						const innerDrawing = parseDrawingContent(innerChild, rels, media, previews);
+						if (innerDrawing) {
+							if (innerDrawing.type === "drawing" && (innerDrawing.rawXml !== void 0 || !innerDrawing.image.src)) innerDrawing.rawXml = captureVerbatimXml(child);
+							if (innerDrawing.type === "shape") {
+								const alternateContent = captureShapeAlternateContent({
+									shape: innerDrawing.shape,
+									alternateContent: child,
+									branch: targetEl,
+									drawing: innerChild
+								});
+								if (alternateContent) innerDrawing.alternateContent = alternateContent;
+							}
+							contents.push(innerDrawing);
+						}
+					} else if (innerName === "pict") {
+						const innerVml = parseVmlImageContent(innerChild, rels, media, previews, rootXmlns);
+						if (innerVml) {
+							innerVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
+							contents.push(innerVml);
+						}
+					} else contents.push(...parseRunContents({
+						...targetEl,
+						elements: [innerChild]
+					}, rels, media, previews, rootXmlns));
+				}
+				const hasTextBoxBranch = [choiceEl, fallbackEl].some((branch) => getChildElements(branch).some((element) => getLocalName(element.name) === "drawing" && isTextBoxDrawing(element)));
+				if (contents.length === contentsBeforeAlternate && !hasTextBoxBranch) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
+				break;
 			}
-			const hasTextBoxBranch = [choiceEl, fallbackEl].some((branch) => getChildElements(branch).some((element) => getLocalName(element.name) === "drawing" && isTextBoxDrawing(element)));
-			if (contents.length === contentsBeforeAlternate && !hasTextBoxBranch) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
-			break;
+			default:
+				contents.push(preserveRunChild(child));
+				break;
 		}
-		default:
-			contents.push(preserveRunChild(child));
-			break;
 	}
 	return contents;
 }

package/dist/docx/saveDiagnostics.d.ts

@@ -0,0 +1,11 @@
+//#region src/docx/saveDiagnostics.d.ts
+/** Save diagnostics describe fidelity fallbacks without including document content. */
+type SaveDiagnostic = {
+  type: "sourceReplayMismatch";
+  part: string;
+};
+type SaveDiagnosticOptions = {
+  onDiagnostic?: ((diagnostic: SaveDiagnostic) => void) | undefined;
+};
+//#endregion
+export { SaveDiagnostic, SaveDiagnosticOptions };

package/dist/docx/selectiveSave.d.ts

@@ -1,6 +1,7 @@
 import { document_d_exports } from "../types/document.js";
+import { SaveDiagnosticOptions } from "./saveDiagnostics.js";
 //#region src/docx/selectiveSave.d.ts
-type SelectiveSaveOptions = {
+type SelectiveSaveOptions = SaveDiagnosticOptions & {
   /** Changed paragraph IDs to selectively patch */
   changedParaIds: Set<string>;
   /** Whether paragraph membership, order, or block structure changed. */

package/dist/docx/selectiveSave.js

@@ -268,7 +268,10 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 		}
 		if (!await patchCommentsExtended(zip, commentPlan, updates)) return null;
 		if (!await patchNumberingPart(zip, doc, updates)) return null;
-		for (const [path, xml] of await collectHeaderFooterUpdates(doc, zip)) updates.set(path, xml);
+		for (const [path, xml] of await collectHeaderFooterUpdates(doc, {
+			sourceZip: zip,
+			onDiagnostic: options.onDiagnostic
+		})) updates.set(path, xml);
 		await queueSettingsUpdates(zip, updates);
 		const corePropsFile = zip.file("docProps/core.xml");
 		if (corePropsFile) {

package/dist/docx/selectiveXmlPatch.d.ts

@@ -1,11 +1,5 @@
+import { XmlElement } from "./xmlParser.js";
 //#region src/docx/selectiveXmlPatch.d.ts
-/**
- * Selective XML Patch Module
- *
- * Patches only changed paragraphs in document.xml, preserving
- * unchanged content byte-for-byte. Uses string offset tracking
- * with proper tag depth counting (not regex) to handle nested elements.
- */
 /**
  * Whether `char` ends an element's tag name in XML — a whitespace separator
  * (space, tab, CR, or LF, all valid before attributes per XML 1.0 §3.1), the
@@ -170,6 +164,20 @@ type XmlSplice = {
  * end, so its original offsets cannot be applied to the resulting string.
  */
 declare const spliceXml: (xml: string, splices: readonly XmlSplice[]) => string | null;
+/**
+ * A paragraph splice cannot change the owning part's root declarations. Refuse
+ * fragments that inherit a prefix from the serialized root when the source
+ * root does not bind that prefix to the same URI; the caller can then use the
+ * full serializer, which owns the root namespace set.
+ */
+type SpliceNamespaceOptions = {
+  originalXml: string;
+  serializedXml: string;
+  fragments: readonly string[];
+  originalRoot?: XmlElement;
+  serializedRoot?: XmlElement;
+};
+declare const spliceSupportsRootNamespaces: ({ originalXml, serializedXml, fragments, originalRoot, serializedRoot }: SpliceNamespaceOptions) => boolean;
 type NoteElementName = "footnote" | "endnote";
 declare const collectChangedNoteParaIds: (baselineXml: string, currentXml: string) => Set<string>;
 type BuildPatchedNotePartXmlOptions = {
@@ -265,4 +273,4 @@ declare const patchNumberingDefinitions: ({ originalXml, baselineXml, currentXml
  */
 declare function appendNumberingDefs(xml: string, currentXml: string, added: ChangedNumberingDefs): string | null;
 //#endregion
-export { ChangedNumberingDefs, NotePartPatch, NotePartPatchRefusal, ParagraphContainer, ParagraphOffsets, PatchValidationResult, ScannedParagraph, XmlSplice, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, scanParagraphs, spliceXml, validatePatchSafety };
+export { ChangedNumberingDefs, NotePartPatch, NotePartPatchRefusal, ParagraphContainer, ParagraphOffsets, PatchValidationResult, ScannedParagraph, XmlSplice, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, scanParagraphs, spliceSupportsRootNamespaces, spliceXml, validatePatchSafety };

package/dist/docx/selectiveXmlPatch.js

@@ -1,8 +1,10 @@
 import { patchBreaksCommentRangeBalance } from "./commentRangeIntegrity.js";
 import { resolveParagraphIdentities } from "./paraIdAttribute.js";
+import { readRootNamespaceBindings } from "./serializer/partNamespaces.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { PARAGRAPH_SCAN_NAMES, hasCanonicalWordprocessingPrefixes, matchCloseTag, matchOpenTag, resolveSelectiveScanPrefixes, splicesAsCanonical } from "./wordprocessingPrefixes.js";
-import { WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, findAttributeByNamespaceUri, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
+import { resolveNamespaceUri } from "./xmlNamespaceContext.js";
+import { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, findAttributeByNamespaceUri, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
 //#region src/docx/selectiveXmlPatch.ts
 /**
 * Selective XML Patch Module
@@ -425,6 +427,14 @@ const routeChangedParagraphs = (originalXml, serializedXml, changedIds) => {
 			newXml: authored ? newXml : withoutMintedIds(newXml, sourceXml)
 		});
 	}
+	if (!spliceSupportsRootNamespaces({
+		originalXml,
+		serializedXml,
+		fragments: splices.map(({ newXml }) => newXml)
+	})) return {
+		type: "refused",
+		reason: "root-namespace-requirements-changed"
+	};
 	const candidate = spliceXml(originalXml, splices);
 	if (candidate === null) return {
 		type: "refused",
@@ -514,6 +524,68 @@ const spliceXml = (xml, splices) => {
 	}
 	return patchBreaksCommentRangeBalance(xml, result) ? null : result;
 };
+const spliceSupportsRootNamespaces = ({ originalXml, serializedXml, fragments, originalRoot, serializedRoot }) => {
+	const original = originalRoot ?? parseXmlDocument(originalXml);
+	const serialized = serializedRoot ?? parseXmlDocument(serializedXml);
+	if (!original || !serialized) return false;
+	const originalBindings = readRootNamespaceBindings(originalXml);
+	const serializedBindings = readRootNamespaceBindings(serializedXml);
+	const mcNamespace = /* @__PURE__ */ new Set([NAMESPACES.mc]);
+	const ignorableUris = (root) => {
+		const uris = /* @__PURE__ */ new Set();
+		for (const prefix of (getAttributeByNamespaceUri(root, mcNamespace, "Ignorable") ?? "").split(/\s+/u).filter(Boolean)) {
+			const uri = resolveNamespaceUri(root.namespaceScope, prefix);
+			if (uri) uris.add(uri);
+		}
+		return uris;
+	};
+	const originalNamespaceUses = /* @__PURE__ */ new Set();
+	const collectSourceNamespaces = (element) => {
+		const uri = getNamespaceUri(element);
+		if (uri) originalNamespaceUses.add(uri);
+		for (const attribute of Object.keys(element.attributes ?? {})) {
+			if (attribute === "xmlns" || attribute.startsWith("xmlns:")) continue;
+			const prefix = getNamespacePrefix(attribute);
+			const attributeUri = prefix ? resolveNamespaceUri(element.namespaceScope, prefix) : void 0;
+			if (attributeUri) originalNamespaceUses.add(attributeUri);
+		}
+		for (const child of element.elements ?? []) collectSourceNamespaces(child);
+	};
+	collectSourceNamespaces(original);
+	const originalIgnorable = ignorableUris(original);
+	const serializedIgnorable = ignorableUris(serialized);
+	const inheritedPrefixes = /* @__PURE__ */ new Set();
+	const visit = (element, ancestorIgnorableUris) => {
+		const localIgnorableUris = new Set(ancestorIgnorableUris);
+		for (const uri of ignorableUris(element)) localIgnorableUris.add(uri);
+		const requirePrefix = (prefix) => {
+			const localUri = resolveNamespaceUri(element.namespaceScope, prefix);
+			if (!localUri) inheritedPrefixes.add(prefix);
+			const uri = localUri ?? serializedBindings.get(prefix);
+			if (!uri) return false;
+			return !serializedIgnorable.has(uri) || originalNamespaceUses.has(uri) || originalIgnorable.has(uri) || localIgnorableUris.has(uri);
+		};
+		const namePrefix = element.name?.split(":").at(0);
+		if (namePrefix && namePrefix !== element.name && !requirePrefix(namePrefix)) return false;
+		for (const attribute of Object.keys(element.attributes ?? {})) {
+			if (attribute === "xmlns" || attribute.startsWith("xmlns:")) continue;
+			const prefix = attribute.split(":").at(0);
+			if (prefix && prefix !== attribute && !requirePrefix(prefix)) return false;
+		}
+		for (const child of element.elements ?? []) if (!visit(child, localIgnorableUris)) return false;
+		return true;
+	};
+	for (const fragment of fragments) {
+		const parsed = parseXmlDocument(fragment);
+		if (!parsed) return false;
+		if (!visit(parsed, /* @__PURE__ */ new Set())) return false;
+	}
+	for (const prefix of inheritedPrefixes) {
+		const serializedUri = serializedBindings.get(prefix);
+		if (serializedUri === void 0 || originalBindings.get(prefix) !== serializedUri) return false;
+	}
+	return true;
+};
 /**
 * Depth-count the end of the element that opens at `start` (an `<openLiteral…>`
 * offset), returning its full range. Nested same-name opens increment depth;
@@ -1269,4 +1341,4 @@ function escapeRegExp(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 //#endregion
-export { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, scanParagraphs, spliceXml, validatePatchSafety };
+export { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, scanParagraphs, spliceSupportsRootNamespaces, spliceXml, validatePatchSafety };

package/dist/docx/serializer/headerFooterSerializer.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../../types/document.js";
+import { SaveDiagnosticOptions } from "../saveDiagnostics.js";
 import { SourcePart } from "./partNamespaces.js";
 //#region src/docx/serializer/headerFooterSerializer.d.ts
 /**
@@ -9,6 +10,9 @@ import { SourcePart } from "./partNamespaces.js";
  *   document bound keeps its URI
  * @returns Complete XML string for header*.xml or footer*.xml
  */
-declare function serializeHeaderFooter(hf: document_d_exports.HeaderFooter, source?: SourcePart): string;
+type HeaderFooterSerializeOptions = SourcePart & SaveDiagnosticOptions & {
+  originalBuffer?: ArrayBuffer | undefined;
+};
+declare function serializeHeaderFooter(hf: document_d_exports.HeaderFooter, source?: HeaderFooterSerializeOptions): string;
 //#endregion
 export { serializeHeaderFooter };

package/dist/docx/serializer/headerFooterSerializer.js

@@ -1,5 +1,6 @@
-import { canReplayHeaderFooterVerbatim, getHeaderFooterVerbatimXml } from "../headerFooterVerbatim.js";
+import { canReplayHeaderFooterBlocks, canReplayHeaderFooterVerbatim, getHeaderFooterSourceBaseline, getHeaderFooterVerbatimXml } from "../headerFooterVerbatim.js";
 import { isEmptyParagraph } from "../paragraphParser.js";
+import { buildStoryBlockReplay } from "../storyBlockReplay.js";
 import { captureVerbatimXml } from "../verbatimCapture.js";
 import { getLocalName, parseXmlDocument } from "../xmlParser.js";
 import { serializeBlockCustomXml } from "./blockCustomXmlSerializer.js";
@@ -49,17 +50,14 @@ function serializeBlock(block) {
 		default: return block;
 	}
 }
-/**
-* Serialize a HeaderFooter object to valid OOXML XML
-*
-* @param hf - HeaderFooter object to serialize
-* @param source - The part being replaced, so a prefix only the source
-*   document bound keeps its URI
-* @returns Complete XML string for header*.xml or footer*.xml
-*/
 function serializeHeaderFooter(hf, source) {
+	const baseline = getHeaderFooterSourceBaseline(hf, source?.originalBuffer);
+	if (baseline.type === "mismatch") source?.onDiagnostic?.({
+		type: "sourceReplayMismatch",
+		part: source.path
+	});
 	const verbatim = getHeaderFooterVerbatimXml(hf);
-	if (verbatim && canReplayHeaderFooterVerbatim(hf)) return verbatim;
+	if (baseline.type === "captured" && verbatim && canReplayHeaderFooterVerbatim(hf)) return verbatim;
 	const rootTag = hf.type === "header" ? "w:hdr" : "w:ftr";
 	const watermarkXml = serializeWatermarkParagraph(hf);
 	const watermarkInsertIndex = hf.watermarkBlockIndex !== void 0 ? Math.max(0, Math.min(hf.watermarkBlockIndex, hf.content.length)) : 0;
@@ -75,13 +73,23 @@ function serializeHeaderFooter(hf, source) {
 		});
 		contentXml = blocksXml.slice(0, watermarkInsertIndex).join("") + (mergesIntoRetainedHost ? "" : watermarkXml) + blocksXml.slice(watermarkInsertIndex).join("");
 	} else contentXml = blocksXml.join("");
-	return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({
+	const serializedXml = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({
 		partPath: source?.path ?? `word/${hf.type}.xml`,
 		rootName: rootTag,
 		baselinePrefixes: HEADER_FOOTER_BASELINE_PREFIXES,
 		sourceBindings: source?.bindings,
 		body: contentXml
 	});
+	if (baseline.type === "captured" && verbatim && canReplayHeaderFooterBlocks(hf, baseline.content)) {
+		const replayed = buildStoryBlockReplay({
+			sourceXml: verbatim,
+			baselineContent: baseline.content,
+			currentContent: hf.content,
+			serializedXml
+		});
+		if (replayed !== null) return replayed;
+	}
+	return serializedXml;
 }
 function serializeRawWatermarkIntoHost({ hostXml, rawWatermarkXml }) {
 	const rawHost = parseXmlDocument(rawWatermarkXml);

package/dist/docx/serializer/noteSerializer.d.ts

@@ -16,9 +16,9 @@ declare function serializeFootnotes(footnotes: readonly document_d_exports.Footn
 declare function serializeEndnotes(endnotes: readonly document_d_exports.Endnote[]): string;
 /** Serialize a brand-new footnote part, including Word's required separators
  * and the automatic reference mark at the start of every normal note. */
-declare function serializeNewFootnotesPart(footnotes: readonly document_d_exports.Footnote[]): string;
+declare function serializeNewFootnotesPart(footnotes: readonly document_d_exports.Footnote[], document?: document_d_exports.Document): string;
 /** Serialize a brand-new endnote part, including Word's required separators
  * and the automatic reference mark at the start of every normal note. */
-declare function serializeNewEndnotesPart(endnotes: readonly document_d_exports.Endnote[]): string;
+declare function serializeNewEndnotesPart(endnotes: readonly document_d_exports.Endnote[], document?: document_d_exports.Document): string;
 //#endregion
 export { serializeEndnotes, serializeFootnotes, serializeNewEndnotesPart, serializeNewFootnotesPart };