@stll/folio-core 0.33.1 → 0.34.0

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/headerFooterParser.js

@@ -31,27 +31,21 @@ function parseHeader(headerXml, hdrFtrType = "default", styles = null, theme = n
 		result.rawWatermarkXml = watermarkResult.rawParagraphXml;
 		result.watermarkBlockIndex = watermarkResult.blockIndex;
 	}
-	result.content = parseBlockContent(watermarkResult ? withoutChild(rootElement, watermarkResult.hostingParagraph) : rootElement, styles, theme, numbering, rels, media, {
+	result.content = parseBlockContent(rootElement, styles, theme, numbering, rels, media, {
 		inHeaderFooter: true,
 		rootXmlns: collectXmlnsDeclarations(rootElement)
 	});
+	if (watermarkResult) {
+		const host = result.content.at(watermarkResult.blockIndex);
+		if (host?.type === "paragraph") result.content[watermarkResult.blockIndex] = {
+			...host,
+			content: []
+		};
+	}
 	assignHeaderFooterVerbatimXml(result, headerXml);
 	return result;
 }
 /**
-* Return a shallow copy of `parent` whose `elements` array omits the
-* single child reference `child`. Used to skip the watermark paragraph
-* when feeding the header into `parseBlockContent` — without this the
-* body parser would emit an empty placeholder paragraph where the
-* watermark sits in the source.
-*/
-function withoutChild(parent, child) {
-	return {
-		...parent,
-		elements: (parent.elements ?? []).filter((el) => el !== child)
-	};
-}
-/**
 * Parse a footer XML file (word/footer*.xml)
 *
 * @param footerXml - The raw XML content of the footer file

package/dist/docx/paragraphParser.js

@@ -10,7 +10,8 @@ import { consolidateParagraphContent } from "./runConsolidator.js";
 import { parseRun, parseRunProperties } from "./runParser.js";
 import { parseSdtProperties } from "./sdtProperties.js";
 import { parseSectionProperties } from "./sectionParser.js";
-import { WORDPROCESSINGML_NAMESPACE_URIS, elementToXml, findChild, findChildByNamespaceUri, findChildren, getAttribute, getChildElements, getLocalName, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute } from "./xmlParser.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { WORDPROCESSINGML_NAMESPACE_URIS, findChild, findChildByNamespaceUri, findChildren, getAttribute, getChildElements, getLocalName, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute } from "./xmlParser.js";
 import { panic } from "better-result";
 import { PARAGRAPH_MARK_CHANGE_KINDS, normalizeRevisionId } from "@stll/docx-core/model";
 //#region src/docx/paragraphParser.ts
@@ -762,6 +763,47 @@ function parseSimpleField(node, styles, theme, rels, media, rootXmlns = {}) {
 function hasRunPayloadElement(runElement) {
 	return getChildElements(runElement).some((child) => !matchesName(child, "w", "rPr"));
 }
+const LEGACY_FORM_CHECKBOX_GLYPHS = {
+	checked: "☒",
+	unchecked: "☐"
+};
+const LEGACY_FORM_CHECKBOX_INSTRUCTION = "FORMCHECKBOX";
+function getLegacyFormCheckboxDisplay(runElement) {
+	const fieldChar = findChild(runElement, "w", "fldChar");
+	const fieldData = fieldChar ? findChild(fieldChar, "w", "ffData") : null;
+	const checkBox = fieldData ? findChild(fieldData, "w", "checkBox") : null;
+	if (!checkBox) return;
+	const checked = findChild(checkBox, "w", "checked");
+	const defaultChecked = findChild(checkBox, "w", "default");
+	let isChecked = defaultChecked ? parseBooleanElement(defaultChecked) : false;
+	if (checked) isChecked = parseBooleanElement(checked);
+	const explicitSize = parseNumericAttribute(findChild(checkBox, "w", "size"), "w", "val");
+	const text = isChecked ? LEGACY_FORM_CHECKBOX_GLYPHS.checked : LEGACY_FORM_CHECKBOX_GLYPHS.unchecked;
+	if (explicitSize === void 0) return { text };
+	return {
+		text,
+		fontSize: explicitSize
+	};
+}
+function createLegacyFormCheckboxResultRun(display, inheritedFormatting) {
+	const run = {
+		type: "run",
+		content: [{
+			type: "text",
+			text: display.text
+		}]
+	};
+	const hasInheritedFormatting = inheritedFormatting !== void 0 && Object.keys(inheritedFormatting).length > 0;
+	if (display.fontSize !== void 0) run.formatting = hasInheritedFormatting ? {
+		...inheritedFormatting,
+		fontSize: display.fontSize
+	} : { fontSize: display.fontSize };
+	else if (hasInheritedFormatting) run.formatting = inheritedFormatting;
+	return run;
+}
+function isLegacyFormCheckboxInstruction(instruction) {
+	return instruction.trim().split(/\s+/u).at(0)?.toUpperCase() === LEGACY_FORM_CHECKBOX_INSTRUCTION;
+}
 /**
 * Parse all content within a paragraph
 *
@@ -778,6 +820,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 	let afterSeparator = false;
 	let complexFieldLock = false;
 	let complexFieldDirty = false;
+	let complexFieldFallbackDisplay;
 	let complexFieldFormatting;
 	for (const child of children) {
 		const localName = getLocalName(child.name);
@@ -789,6 +832,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 				let hasFieldBegin = false;
 				let beginFldLock = false;
 				let beginDirty = false;
+				const beginFallbackDisplay = getLegacyFormCheckboxDisplay(runElement);
 				let hasFieldSeparate = false;
 				let hasFieldEnd = false;
 				let endOriginalValue;
@@ -815,6 +859,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 					complexFieldResultRuns = [];
 					complexFieldLock = beginFldLock;
 					complexFieldDirty = beginDirty;
+					complexFieldFallbackDisplay = beginFallbackDisplay;
 					complexFieldFormatting = run.formatting;
 				}
 				if (inComplexField) {
@@ -839,6 +884,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 					}
 					if (hasFieldEnd) {
 						let resultRuns = complexFieldResultRuns;
+						if (resultRuns.length === 0 && complexFieldFallbackDisplay !== void 0 && isLegacyFormCheckboxInstruction(complexFieldInstr)) resultRuns = [createLegacyFormCheckboxResultRun(complexFieldFallbackDisplay, complexFieldFormatting)];
 						if (resultRuns.length === 0 && !afterSeparator && endOriginalValue !== void 0) resultRuns = [{
 							type: "run",
 							content: [{
@@ -995,7 +1041,7 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 			case "oMath":
 			case "oMathPara": {
 				const isBlock = localName === "oMathPara";
-				const ommlXml = elementToXml(child);
+				const ommlXml = captureVerbatimXml(child);
 				const plainText = extractMathText(child);
 				const mathEq = {
 					type: "mathEquation",

package/dist/docx/rezip.d.ts

@@ -106,11 +106,11 @@ declare function updateMultipleFiles(originalBuffer: ArrayBuffer, updates: Map<s
  * Apply file updates to an already-loaded JSZip instance and generate the output.
  * Use this when the zip is already loaded to avoid a redundant decompression pass.
  *
- * This is the selective save's exit, so it owes the package the same id passes
+ * This is the selective save's exit, so it owes the package the same passes
  * {@link generateDocxZip} runs: a save that rewrites only the changed
  * paragraphs still has to see the parts it left alone, both to know which
- * revision ids are free and because an out-of-range paragraph id can sit in a
- * part it never touched.
+ * revision ids are free and because an out-of-range paragraph id, or a
+ * malformed application version, can sit in a part it never touched.
  */
 declare function applyUpdatesToZip(zip: JSZip, updates: Map<string, string | ArrayBuffer>, options?: RepackOptions): Promise<ArrayBuffer>;
 /**
@@ -159,7 +159,13 @@ declare function hasUnmaterializedHeaderFooter(doc: document_d_exports.Document)
  * have been set without yet resolving in that header's rels).
  */
 declare function hasModelDrivenPictureWatermark(doc: document_d_exports.Document): boolean;
-declare function collectHeaderFooterUpdates(doc: document_d_exports.Document): Map<string, string>;
+/**
+ * Re-serialize every header/footer the model still owns, keyed by part path.
+ *
+ * `sourceZip` supplies each part as it stands before the save so the rebuilt
+ * root can keep any prefix binding only the source document declared.
+ */
+declare function collectHeaderFooterUpdates(doc: document_d_exports.Document, sourceZip: JSZip): Promise<Map<string, string>>;
 /** `word/Footnotes.xml` -> `word/_rels/Footnotes.xml.rels` (casing preserved). */
 declare function notePartRelsPath(partPath: string): string;
 /** Update existing core-property values without synthesizing absent metadata. */

package/dist/docx/rezip.js

@@ -1,4 +1,5 @@
 import { isAllowedExternalWatermarkImageUrl } from "../watermark/index.js";
+import { normalizeAppVersionInExtendedProperties } from "./appVersionNormalization.js";
 import { withoutOrphanCommentRanges } from "./commentRangeIntegrity.js";
 import { applyReplyThreadMarkers } from "./commentReplyMarkers.js";
 import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
@@ -16,6 +17,7 @@ import { serializeFontTableXml } from "./serializer/fontTableSerializer.js";
 import { serializeHeaderFooter } from "./serializer/headerFooterSerializer.js";
 import { serializeEndnotes, serializeFootnotes, serializeNewEndnotesPart, serializeNewFootnotesPart } from "./serializer/noteSerializer.js";
 import { serializeNumberingXml } from "./serializer/numberingSerializer.js";
+import { readRootNamespaceBindings } from "./serializer/partNamespaces.js";
 import { serializeSettingsXml } from "./serializer/settingsSerializer.js";
 import { serializeStyle, serializeStylesXml } from "./serializer/stylesSerializer.js";
 import { serializeThemeXml } from "./serializer/themeSerializer.js";
@@ -122,13 +124,12 @@ function assertDocumentPackageFidelity(originalDocumentXml, serializedDocumentXm
 async function serializeCommentsToZip(doc, zip, compressionLevel) {
 	const comments = doc.package.document.comments ?? [];
 	const sourceCommentsFile = findZipEntryCaseInsensitive(zip, "word/comments.xml");
+	const sourceCommentsXml = sourceCommentsFile ? await sourceCommentsFile.async("text") : void 0;
 	if (comments.length === 0) {
-		if (!sourceCommentsFile) return;
-		const sourceCommentsXml = await sourceCommentsFile.async("text");
-		if (!hasCommentEntries(sourceCommentsXml)) return;
+		if (sourceCommentsXml === void 0 || !hasCommentEntries(sourceCommentsXml)) return;
 	}
 	ensureThreadedCommentParaIds(comments);
-	const commentsXml = serializeComments(comments);
+	const commentsXml = serializeComments(comments, sourceCommentsXml === void 0 ? void 0 : readRootNamespaceBindings(sourceCommentsXml));
 	zip.file(sourceCommentsFile?.name ?? "word/comments.xml", commentsXml, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
@@ -428,6 +429,30 @@ const normalizePackageIdsInZip = async (zip, compressionLevel) => {
 		compressionOptions: { level: compressionLevel }
 	});
 };
+const EXTENDED_PROPERTIES_PATH = "docProps/app.xml";
+/**
+* Bring the application version the package states about itself into the form
+* the schema gives it. A package that holds no extended properties keeps
+* holding none.
+*/
+const normalizeAppVersionInZip = async (zip, compressionLevel) => {
+	const extendedProperties = zip.file(EXTENDED_PROPERTIES_PATH);
+	if (!extendedProperties) return;
+	const xml = await extendedProperties.async("text");
+	const normalized = normalizeAppVersionInExtendedProperties(xml);
+	if (normalized !== xml) zip.file(EXTENDED_PROPERTIES_PATH, normalized, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+};
+/**
+* Every pass a save owes the package as a whole, in one function so that the
+* full repack and the selective save cannot drift into running different ones.
+*/
+const normalizePackageOnSave = async (zip, compressionLevel) => {
+	await normalizePackageIdsInZip(zip, compressionLevel);
+	await normalizeAppVersionInZip(zip, compressionLevel);
+};
 /**
 * The single exit for a repacked package. Reconciliation runs here rather than
 * at each caller so no save path can emit a package whose relationships or
@@ -435,7 +460,7 @@ const normalizePackageIdsInZip = async (zip, compressionLevel) => {
 */
 const generateDocxZip = async (zip, compressionLevel) => {
 	await reconcilePackageReferences(zip, compressionLevel);
-	await normalizePackageIdsInZip(zip, compressionLevel);
+	await normalizePackageOnSave(zip, compressionLevel);
 	return zip.generateAsync({
 		type: "arraybuffer",
 		compression: "DEFLATE",
@@ -470,14 +495,14 @@ const finishRepack = async ({ document, originalZip, outputZip, originalDocument
 	await processNewHyperlinks(parts, outputZip, compressionLevel);
 	assertValidFolioDocumentModel(document, "Cannot repack invalid DOCX document model");
 	applyReplyThreadMarkers(document);
-	const documentXml = serializeDocument(document);
+	const documentXml = serializeDocument(document, originalDocumentXml === void 0 ? void 0 : readRootNamespaceBindings(originalDocumentXml));
 	if (originalDocumentXml) assertDocumentPackageFidelity(originalDocumentXml, documentXml, document);
 	outputZip.file("word/document.xml", documentXml, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});
 	await rebindWatermarkRelIds(document, outputZip, compressionLevel);
-	serializeHeadersFootersToZip(document, outputZip, compressionLevel);
+	await serializeHeadersFootersToZip(document, outputZip, compressionLevel);
 	await serializeNotesToZip({
 		doc: document,
 		originalZip,
@@ -559,14 +584,14 @@ async function repackDocxFromRaw(doc, rawContent, options = {}) {
 	await processNewHyperlinks(parts, newZip, compressionLevel);
 	assertValidFolioDocumentModel(exportDocument, "Cannot repack invalid DOCX document model");
 	applyReplyThreadMarkers(exportDocument);
-	const documentXml = serializeDocument(exportDocument);
+	const documentXml = serializeDocument(exportDocument, rawContent.documentXml ? readRootNamespaceBindings(rawContent.documentXml) : void 0);
 	if (rawContent.documentXml) assertDocumentPackageFidelity(rawContent.documentXml, documentXml, exportDocument);
 	newZip.file("word/document.xml", documentXml, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});
 	await rebindWatermarkRelIds(exportDocument, newZip, compressionLevel);
-	serializeHeadersFootersToZip(exportDocument, newZip, compressionLevel);
+	await serializeHeadersFootersToZip(exportDocument, newZip, compressionLevel);
 	await serializeNotesToZip({
 		doc: exportDocument,
 		originalZip: rawContent.originalZip,
@@ -775,11 +800,11 @@ async function updateMultipleFiles(originalBuffer, updates, options = {}) {
 * Apply file updates to an already-loaded JSZip instance and generate the output.
 * Use this when the zip is already loaded to avoid a redundant decompression pass.
 *
-* This is the selective save's exit, so it owes the package the same id passes
+* This is the selective save's exit, so it owes the package the same passes
 * {@link generateDocxZip} runs: a save that rewrites only the changed
 * paragraphs still has to see the parts it left alone, both to know which
-* revision ids are free and because an out-of-range paragraph id can sit in a
-* part it never touched.
+* revision ids are free and because an out-of-range paragraph id, or a
+* malformed application version, can sit in a part it never touched.
 */
 async function applyUpdatesToZip(zip, updates, options = {}) {
 	const { compressionLevel = 6 } = options;
@@ -787,7 +812,7 @@ async function applyUpdatesToZip(zip, updates, options = {}) {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});
-	await normalizePackageIdsInZip(zip, compressionLevel);
+	await normalizePackageOnSave(zip, compressionLevel);
 	return await zip.generateAsync({
 		type: "arraybuffer",
 		compression: "DEFLATE",
@@ -1090,7 +1115,13 @@ async function rebindWatermarkRelIds(doc, zip, compressionLevel) {
 		});
 	}
 }
-function collectHeaderFooterUpdates(doc) {
+/**
+* Re-serialize every header/footer the model still owns, keyed by part path.
+*
+* `sourceZip` supplies each part as it stands before the save so the rebuilt
+* root can keep any prefix binding only the source document declared.
+*/
+async function collectHeaderFooterUpdates(doc, sourceZip) {
 	const updates = /* @__PURE__ */ new Map();
 	const rels = doc.package.relationships;
 	if (!rels) return updates;
@@ -1107,8 +1138,13 @@ function collectHeaderFooterUpdates(doc) {
 		for (const [rId, headerFooter] of map.entries()) {
 			const rel = rels.get(rId);
 			if (rel && rel.type === type && rel.target) {
-				const filename = resolveRelativePath(documentRelsPath, rel.target);
-				updates.set(filename, serializeHeaderFooter(headerFooter));
+				const path = resolveRelativePath(documentRelsPath, rel.target);
+				const sourceFile = findZipEntryCaseInsensitive(sourceZip, path.toLowerCase());
+				const bindings = sourceFile ? readRootNamespaceBindings(await sourceFile.async("text")) : /* @__PURE__ */ new Map();
+				updates.set(path, serializeHeaderFooter(headerFooter, {
+					path,
+					bindings
+				}));
 			}
 		}
 	}
@@ -1117,9 +1153,9 @@ function collectHeaderFooterUpdates(doc) {
 /**
 * Serialize modified headers and footers into the ZIP
 */
-function serializeHeadersFootersToZip(doc, zip, compressionLevel) {
+async function serializeHeadersFootersToZip(doc, zip, compressionLevel) {
 	const compressionOptions = { level: compressionLevel };
-	for (const [filename, xml] of collectHeaderFooterUpdates(doc)) zip.file(filename, xml, {
+	for (const [filename, xml] of await collectHeaderFooterUpdates(doc, zip)) zip.file(filename, xml, {
 		compression: "DEFLATE",
 		compressionOptions
 	});

package/dist/docx/runParser.js

@@ -7,8 +7,9 @@ import { parseShapeFromDrawing, shouldPreserveRawShapeDrawing } from "./shapePar
 import { isTextBoxDrawing } from "./textBoxParser.js";
 import { requiresXmlSpacePreserve } from "./textWhitespace.js";
 import { resolveThemeFontRef } from "./themeParser.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
 import { parseVmlImageContent } from "./vmlImageParser.js";
-import { cloneWithXmlnsDeclarations, elementToXml, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute } from "./xmlParser.js";
+import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute } from "./xmlParser.js";
 import { DRAWING_RAW_XML_MODES, normalizeRevisionId } from "@stll/docx-core/model";
 //#region src/docx/runParser.ts
 /**
@@ -489,7 +490,7 @@ function parseDrawingContent(element, rels, media) {
 	if (groupImage) return {
 		type: "drawing",
 		image: groupImage,
-		rawXml: elementToXml(element)
+		rawXml: captureVerbatimXml(element)
 	};
 	if (shouldPreserveRawShapeDrawing(element)) return {
 		type: "drawing",
@@ -502,7 +503,7 @@ function parseDrawingContent(element, rels, media) {
 			},
 			wrap: { type: "inline" }
 		},
-		rawXml: elementToXml(element),
+		rawXml: captureVerbatimXml(element),
 		rawXmlMode: DRAWING_RAW_XML_MODES.PRESERVE_ONLY
 	};
 	const shape = parseShapeFromDrawing(element);
@@ -516,7 +517,7 @@ function parseDrawingContent(element, rels, media) {
 		type: "drawing",
 		image
 	};
-	if (!image.src) drawing.rawXml = elementToXml(element);
+	if (!image.src) drawing.rawXml = captureVerbatimXml(element);
 	return drawing;
 }
 /**
@@ -593,7 +594,7 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 			if (groupedChoiceDrawing) {
 				const groupedDrawing = parseDrawingContent(groupedChoiceDrawing, rels, media);
 				if (groupedDrawing?.type === "drawing" && groupedDrawing.image.src) {
-					groupedDrawing.rawXml = elementToXml(child);
+					groupedDrawing.rawXml = captureVerbatimXml(child);
 					contents.push(groupedDrawing);
 					break;
 				}
@@ -601,7 +602,7 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 			const fallbackPict = fallbackEl ? getChildElements(fallbackEl).find((el) => getLocalName(el.name) === "pict") : void 0;
 			const fallbackVml = fallbackPict && !choiceTextBoxDrawing ? parseVmlImageContent(fallbackPict, rels, media, rootXmlns) : null;
 			if (fallbackVml?.image.src) {
-				fallbackVml.rawXml = elementToXml(cloneWithXmlnsDeclarations(child, rootXmlns));
+				fallbackVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
 				contents.push(fallbackVml);
 				break;
 			}
@@ -611,13 +612,13 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 				if (innerName === "drawing") {
 					const innerDrawing = parseDrawingContent(innerChild, rels, media);
 					if (innerDrawing) {
-						if (innerDrawing.type === "drawing" && (innerDrawing.rawXml !== void 0 || !innerDrawing.image.src)) innerDrawing.rawXml = elementToXml(child);
+						if (innerDrawing.type === "drawing" && (innerDrawing.rawXml !== void 0 || !innerDrawing.image.src)) innerDrawing.rawXml = captureVerbatimXml(child);
 						contents.push(innerDrawing);
 					}
 				} else if (innerName === "pict") {
 					const innerVml = parseVmlImageContent(innerChild, rels, media, rootXmlns);
 					if (innerVml) {
-						innerVml.rawXml = elementToXml(cloneWithXmlnsDeclarations(child, rootXmlns));
+						innerVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
 						contents.push(innerVml);
 					}
 				}

package/dist/docx/sdtProperties.js

@@ -1,5 +1,6 @@
 import { SdtLockSchema, narrowEnum } from "./parserEnums.js";
-import { elementToXml, findChild, getAttributeAnyPrefix, getLocalName, parseBooleanElement } from "./xmlParser.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { findChild, getAttributeAnyPrefix, getLocalName, parseBooleanElement } from "./xmlParser.js";
 //#region src/docx/sdtProperties.ts
 function parseListItems(el) {
 	const items = [];
@@ -201,7 +202,7 @@ function rewriteOpenTagAttrPrefixes(raw, canonical, local) {
 function parseSdtProperties(sdtPr, sdtEndPr) {
 	const props = { sdtType: "richText" };
 	if (sdtPr) {
-		props.rawPropertiesXml = normalizeWordPrefix(elementToXml(sdtPr), sdtPr);
+		props.rawPropertiesXml = normalizeWordPrefix(captureVerbatimXml(sdtPr), sdtPr);
 		for (const el of sdtPr.elements ?? []) {
 			if (el.type !== "element") continue;
 			const name = el.name ? getLocalName(el.name) : "";
@@ -283,7 +284,7 @@ function parseSdtProperties(sdtPr, sdtEndPr) {
 			}
 		}
 	}
-	if (sdtEndPr) props.rawEndPropertiesXml = normalizeWordPrefix(elementToXml(sdtEndPr), sdtEndPr);
+	if (sdtEndPr) props.rawEndPropertiesXml = normalizeWordPrefix(captureVerbatimXml(sdtEndPr), sdtEndPr);
 	return props;
 }
 //#endregion

package/dist/docx/selectiveSave.js

@@ -13,6 +13,7 @@ import { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExten
 import { serializeDocument } from "./serializer/documentSerializer.js";
 import { serializeEndnotes, serializeFootnotes } from "./serializer/noteSerializer.js";
 import { serializeNumberingXml } from "./serializer/numberingSerializer.js";
+import { readRootNamespaceBindings } from "./serializer/partNamespaces.js";
 //#region src/docx/selectiveSave.ts
 /**
 * Check if document content has new images (data: URL without rId) or
@@ -209,7 +210,6 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 	if (!validateFolioDocumentModel(doc).valid) return null;
 	const comments = doc.package.document.comments ?? [];
 	const hasComments = comments.length > 0;
-	const headerFooterUpdates = collectHeaderFooterUpdates(doc);
 	try {
 		const zip = await (await import("jszip")).default.loadAsync(originalBuffer);
 		for (const [path, file] of Object.entries(zip.files)) if (!file.dir && isUnsafePackagePath(path)) return null;
@@ -228,15 +228,16 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 				if (unrouted === null || unrouted.size > 0) return null;
 			}
 			if (bodyChangedIds.size > 0) {
-				const patchedDocXml = buildPatchedDocumentXml(originalDocXml, serializeDocument(doc), bodyChangedIds);
+				const patchedDocXml = buildPatchedDocumentXml(originalDocXml, serializeDocument(doc, readRootNamespaceBindings(originalDocXml)), bodyChangedIds);
 				if (!patchedDocXml) return null;
 				updates.set("word/document.xml", patchedDocXml);
 			}
 		}
-		const hadCommentsFile = zip.file("word/comments.xml") !== null;
-		if (hasComments || hadCommentsFile) {
+		const sourceCommentsFile = zip.file("word/comments.xml");
+		if (hasComments || sourceCommentsFile) {
 			ensureThreadedCommentParaIds(comments);
-			updates.set("word/comments.xml", serializeComments(comments));
+			const sourceBindings = sourceCommentsFile ? readRootNamespaceBindings(await sourceCommentsFile.async("text")) : void 0;
+			updates.set("word/comments.xml", serializeComments(comments, sourceBindings));
 		}
 		if (hasComments) {
 			const ctFile = zip.file("[Content_Types].xml");
@@ -256,7 +257,7 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 		}
 		if (!await patchCommentsExtended(zip, comments, updates)) return null;
 		await patchNumberingPart(zip, doc, updates);
-		for (const [path, xml] of headerFooterUpdates) updates.set(path, xml);
+		for (const [path, xml] of await collectHeaderFooterUpdates(doc, zip)) updates.set(path, xml);
 		await queueSettingsUpdates(zip, updates);
 		const corePropsFile = zip.file("docProps/core.xml");
 		if (corePropsFile) {

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

@@ -7,7 +7,7 @@ import { Comment } from "../../types/content.js";
  * comment — leaving the previous file in place would otherwise re-emit
  * the orphaned comment threads on every save.
  */
-declare function serializeComments(comments: Comment[]): string;
+declare function serializeComments(comments: Comment[], sourceBindings?: ReadonlyMap<string, string>): string;
 /**
  * Assign a deterministic `w14:paraId` to the LAST paragraph of every comment
  * that needs a commentsExtended entry (a reply, a reply's parent, or a resolved