@stll/folio-core 0.52.0 → 0.54.0

package/dist/docx/rezip.js

@@ -26,10 +26,11 @@ 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 { readRootNamespaceBindings, serializePartElement } from "./serializer/partNamespaces.js";
 import { serializeSettingsXml } from "./serializer/settingsSerializer.js";
 import { serializeStyle, serializeStylesXml } from "./serializer/stylesSerializer.js";
 import { serializeThemeXml } from "./serializer/themeSerializer.js";
+import { hasCanonicalWordprocessingPrefixes } from "./wordprocessingPrefixes.js";
 import { WORDPROCESSINGML_NAMESPACE_URIS, findChild, findChildByNamespaceUri, findChildrenByNamespaceUri, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, matchesName, parseXml, parseXmlDocument } from "./xmlParser.js";
 import { TaggedError, panic } from "better-result";
 import { escapeXmlAttribute, escapeXmlText, validateDocxPackage } from "@stll/docx-core";
@@ -363,7 +364,7 @@ function collectNewImages(blocks) {
 			for (const sub of item.content) if (sub.type === "run") collectFromRun(sub);
 		}
 	} else if (block.type === "table") for (const row of block.rows) for (const cell of row.cells) images.push(...collectNewImages(cell.content));
-	else if (block.type === "blockSdt") images.push(...collectNewImages(block.content));
+	else if (block.type === "blockSdt" || block.type === "blockCustomXml") images.push(...collectNewImages(block.content));
 	return images;
 }
 /** Map MIME type to file extension (inverse of getContentTypeForExtension) */
@@ -484,7 +485,7 @@ function collectHyperlinksWithoutRId(blocks) {
 	};
 	for (const block of blocks) if (block.type === "paragraph") collectInlineHyperlinks(block.content);
 	else if (block.type === "table") for (const row of block.rows) for (const cell of row.cells) hyperlinks.push(...collectHyperlinksWithoutRId(cell.content));
-	else if (block.type === "blockSdt") hyperlinks.push(...collectHyperlinksWithoutRId(block.content));
+	else if (block.type === "blockSdt" || block.type === "blockCustomXml") hyperlinks.push(...collectHyperlinksWithoutRId(block.content));
 	return hyperlinks;
 }
 /** The selective save boundary must use the same resource census as full repack. */
@@ -1338,7 +1339,8 @@ async function serializeHeadersFootersToZip(doc, zip, compressionLevel) {
 }
 async function serializeNotesToZip({ doc, originalZip, newZip, compressionLevel, changedNoteParaIds }) {
 	const footnotes = doc.package.footnotes ?? [];
-	if (footnotes.length > 0) if (findNotePartEntry(originalZip, "word/footnotes.xml")) await patchNotePartIntoZip({
+	const originalFootnotes = doc.package.footnotes === void 0 ? null : findNotePartEntry(originalZip, "word/footnotes.xml");
+	if (footnotes.length > 0 || originalFootnotes) if (originalFootnotes) await patchNotePartIntoZip({
 		conventionalLowerPath: "word/footnotes.xml",
 		currentXml: serializeFootnotes(footnotes),
 		replacementXml: serializeNewFootnotesPart(footnotes),
@@ -1358,7 +1360,8 @@ async function serializeNotesToZip({ doc, originalZip, newZip, compressionLevel,
 		compressionLevel
 	});
 	const endnotes = doc.package.endnotes ?? [];
-	if (endnotes.length > 0) if (findNotePartEntry(originalZip, "word/endnotes.xml")) await patchNotePartIntoZip({
+	const originalEndnotes = doc.package.endnotes === void 0 ? null : findNotePartEntry(originalZip, "word/endnotes.xml");
+	if (endnotes.length > 0 || originalEndnotes) if (originalEndnotes) await patchNotePartIntoZip({
 		conventionalLowerPath: "word/endnotes.xml",
 		currentXml: serializeEndnotes(endnotes),
 		replacementXml: serializeNewEndnotesPart(endnotes),
@@ -1444,6 +1447,25 @@ async function serializeNumberingIntoZip(doc, originalZip, newZip, compressionLe
 const STYLES_PART_PATH = "word/styles.xml";
 const STYLES_CLOSE_ROOT = "</w:styles>";
 /**
+* One serialized element with the namespace declarations its own prefixes
+* need, for splicing into a part whose root binds them differently (or not
+* at all). A prefix no table knows throws rather than being written unbound.
+*/
+const selfBoundFragment = (fragment, partPath) => {
+	const openEnd = fragment.indexOf(">");
+	const selfClosing = fragment[openEnd - 1] === "/";
+	const rootName = /^<(?<name>[^\s/>]+)/u.exec(fragment)?.groups?.["name"];
+	if (openEnd === -1 || rootName === void 0) throw new DocxPackageFidelityError(`Cannot splice a malformed element into ${partPath}`);
+	return serializePartElement({
+		partPath,
+		rootName,
+		rootAttributes: fragment.slice(rootName.length + 1, selfClosing ? openEnd - 1 : openEnd).trim(),
+		baselinePrefixes: [],
+		sourceBindings: void 0,
+		body: selfClosing ? "" : fragment.slice(openEnd + 1, fragment.lastIndexOf("</"))
+	});
+};
+/**
 * The style table a package folio creates starts from: `docDefaults` and
 * `Normal`, and nothing else. A document that carries its own style table
 * replaces this part wholesale.
@@ -1532,7 +1554,8 @@ async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compression
 	if (!styles || styles.styles.length === 0) return;
 	const file = findNotePartEntry(originalZip, STYLES_PART_PATH);
 	const originalXml = file ? await file.async("text") : null;
-	const rootClose = originalXml?.lastIndexOf(STYLES_CLOSE_ROOT) ?? -1;
+	const rootName = originalXml === null ? void 0 : /<(?![?!])(?<name>[^\s/>]+)/u.exec(originalXml)?.groups?.["name"];
+	const rootClose = originalXml !== null && rootName !== void 0 && getLocalName(rootName) === "styles" ? originalXml.lastIndexOf(`</${rootName}>`) : -1;
 	if (file === null || originalXml === null || rootClose < 0) {
 		await materializeNewNotePart({
 			contentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml",
@@ -1552,7 +1575,8 @@ async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compression
 		added.push(style);
 	}
 	if (added.length === 0) return;
-	const patched = originalXml.slice(0, rootClose) + added.map(serializeStyle).join("") + originalXml.slice(rootClose);
+	const canonical = hasCanonicalWordprocessingPrefixes(originalXml);
+	const patched = originalXml.slice(0, rootClose) + added.map((style) => canonical ? serializeStyle(style) : selfBoundFragment(serializeStyle(style), file.name)).join("") + originalXml.slice(rootClose);
 	newZip.file(file.name, patched, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }

package/dist/docx/sdtProperties.js

@@ -6,7 +6,7 @@ import { WORDPROCESSINGML_NAMESPACE_URIS, findChild, findChildByLocalName, getAt
 //#region src/docx/sdtProperties.ts
 function parseListItems(el) {
 	const items = [];
-	for (const child of el.elements ?? []) if (child.type === "element" && (child.name === "w:listItem" || child.name?.endsWith(":listItem"))) {
+	for (const child of el.elements ?? []) if (child.type === "element" && getLocalName(child.name ?? "") === "listItem") {
 		const displayText = getAttributeAnyPrefix(child, "displayText");
 		const value = getAttributeAnyPrefix(child, "value");
 		if (displayText === null && value === null) continue;

package/dist/docx/sdtPropertiesPatch.js

@@ -1,3 +1,4 @@
+import { OOXML_NAMESPACE_SCOPE, findChild, getAttribute, parseXml } from "./xmlParser.js";
 import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/sdtPropertiesPatch.ts
 /**
@@ -66,6 +67,8 @@ const withDateState = (xml, props) => {
 	const fullDate = props.dateValueISO;
 	const format = props.dateFormat;
 	if (fullDate === void 0 && format === void 0) return xml;
+	const capturedDate = parseXml(xml, OOXML_NAMESPACE_SCOPE).elements?.at(0);
+	if ((fullDate === void 0 || getAttribute(capturedDate, "w", "fullDate") === fullDate) && (format === void 0 || getAttribute(findChild(capturedDate, "w", "dateFormat"), "w", "val") === format)) return xml;
 	const attributes = (prefix, matched) => fullDate === void 0 ? matched : `${withoutAttr(matched, "fullDate")} ${prefix}:fullDate="${escapeXmlAttribute(fullDate)}"`;
 	const formatChild = (prefix) => format === void 0 ? "" : `<${prefix}:dateFormat ${prefix}:val="${escapeXmlAttribute(format)}"/>`;
 	const opened = /<(?<prefix>\w+):date\b(?<attrs>[^>]*)>(?<inner>[\s\S]*?)<\/\w+:date>/iu;

package/dist/docx/selectiveSave.js

@@ -126,12 +126,15 @@ async function ensureCommentsExtendedPackaging(zip, updates) {
 * (`w:nsid`/`w:tmpl`, custom formats, level sub-elements), so only the changed
 * definitions are spliced by id; every other definition stays byte-exact.
 *
-* Any absent numbering part, unchanged numbering, or unsplittable edit leaves
-* the original part untouched — the file is simply not added to `updates`.
+* Unchanged numbering leaves the original part untouched. Numbering the
+* splice cannot write (a package without a numbering part, or an edit it
+* cannot split) answers `false`: the paragraphs may reference those
+* definitions, so the caller falls back to a full repack rather than save a
+* package whose `w:numPr` names an instance it does not define.
 */
 async function patchNumberingPart(zip, doc, updates) {
 	const numbering = doc.package.numbering;
-	if (!numbering || numbering.abstractNums.length === 0 && numbering.nums.length === 0) return;
+	if (!numbering || numbering.abstractNums.length === 0 && numbering.nums.length === 0) return true;
 	const conventionalLowerPath = "word/numbering.xml";
 	let file = zip.file(conventionalLowerPath);
 	if (!file) {
@@ -140,15 +143,19 @@ async function patchNumberingPart(zip, doc, updates) {
 			break;
 		}
 	}
-	if (!file) return;
+	if (!file) return false;
 	const originalXml = await file.async("text");
+	const baselineXml = serializeNumberingXml(parseNumbering(originalXml).definitions);
+	const currentXml = serializeNumberingXml(numbering);
+	if (currentXml === baselineXml) return true;
 	const patched = patchNumberingDefinitions({
 		originalXml,
-		baselineXml: serializeNumberingXml(parseNumbering(originalXml).definitions),
-		currentXml: serializeNumberingXml(numbering)
+		baselineXml,
+		currentXml
 	});
-	if (patched === null || patched === originalXml) return;
-	updates.set(file.name, patched);
+	if (patched === null) return false;
+	if (patched !== originalXml) updates.set(file.name, patched);
+	return true;
 }
 /**
 * Attempt a selective save — patch only changed paragraphs in document.xml.
@@ -250,7 +257,7 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 			}
 		}
 		if (!await patchCommentsExtended(zip, commentPlan, updates)) return null;
-		await patchNumberingPart(zip, doc, updates);
+		if (!await patchNumberingPart(zip, doc, updates)) return null;
 		for (const [path, xml] of await collectHeaderFooterUpdates(doc, zip)) updates.set(path, xml);
 		await queueSettingsUpdates(zip, updates);
 		const corePropsFile = zip.file("docProps/core.xml");

package/dist/docx/selectiveXmlPatch.d.ts

@@ -165,7 +165,9 @@ type XmlSplice = {
  * the rest of the part byte-for-byte, so it can write half a comment range:
  * invalid OOXML that anchors the comment to nothing. Answers null when it
  * would, leaving the caller to rewrite a wider region — ultimately the whole
- * part from the model, which is balanced with itself.
+ * part from the model, which is balanced with itself. Overlapping source
+ * regions are refused too: replacing an inner region moves the outer region's
+ * end, so its original offsets cannot be applied to the resulting string.
  */
 declare const spliceXml: (xml: string, splices: readonly XmlSplice[]) => string | null;
 type NoteElementName = "footnote" | "endnote";

package/dist/docx/selectiveXmlPatch.js

@@ -1,6 +1,7 @@
 import { patchBreaksCommentRangeBalance } from "./commentRangeIntegrity.js";
 import { resolveParagraphIdentities } from "./paraIdAttribute.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";
 //#region src/docx/selectiveXmlPatch.ts
 /**
@@ -108,29 +109,6 @@ function buildParagraphOffsetIndex(xml) {
 	for (const [id, range] of ranges) if (seenCount.get(id) === 1) index.set(id, range);
 	return index;
 }
-/** The containers {@link scanParagraphs} tracks, by the literal tag the part writes. */
-const TRACKED_CONTAINERS = [
-	{
-		name: "mc:Fallback",
-		key: "fallback"
-	},
-	{
-		name: "mc:AlternateContent",
-		key: "alternateContent"
-	},
-	{
-		name: "w:txbxContent",
-		key: "textBox"
-	},
-	{
-		name: "w:tc",
-		key: "tableCell"
-	}
-].map(({ name, key }) => ({
-	key,
-	open: `<${name}`,
-	close: `</${name}>`
-}));
 /**
 * Every `<w:p>` element of `xml`, in the document order of its opening tags,
 * with the `w14:paraId` that tag carries and the containers around it.
@@ -145,6 +123,8 @@ const TRACKED_CONTAINERS = [
 * no splice can be built from it.
 */
 function scanParagraphs(xml) {
+	const resolution = resolveSelectiveScanPrefixes(xml);
+	const mcPrefixes = resolution.type === "resolved" ? resolution.prefixes.mc : ["mc"];
 	const paragraphs = [];
 	const open = [];
 	const depth = {
@@ -153,6 +133,28 @@ function scanParagraphs(xml) {
 		textBox: 0,
 		tableCell: 0
 	};
+	const containers = [
+		{
+			key: "fallback",
+			prefixes: mcPrefixes,
+			name: "Fallback"
+		},
+		{
+			key: "alternateContent",
+			prefixes: mcPrefixes,
+			name: "AlternateContent"
+		},
+		{
+			key: "textBox",
+			prefixes: ["w"],
+			name: "txbxContent"
+		},
+		{
+			key: "tableCell",
+			prefixes: ["w"],
+			name: "tc"
+		}
+	];
 	let pos = 0;
 	scan: while (pos < xml.length) {
 		const tagStart = xml.indexOf("<", pos);
@@ -165,13 +167,14 @@ function scanParagraphs(xml) {
 			pos = end;
 			continue;
 		}
-		for (const { key, open: openLiteral, close } of TRACKED_CONTAINERS) {
-			if (xml.startsWith(close, tagStart)) {
+		for (const { key, prefixes, name } of containers) {
+			const closeLength = matchCloseTag(xml, tagStart, prefixes, name);
+			if (closeLength !== -1) {
 				depth[key] = Math.max(0, depth[key] - 1);
-				pos = tagStart + close.length;
+				pos = tagStart + closeLength;
 				continue scan;
 			}
-			if (xml.startsWith(openLiteral, tagStart) && isXmlNameBoundary(xml[tagStart + openLiteral.length])) {
+			if (matchOpenTag(xml, tagStart, prefixes, name) !== -1) {
 				const tagEnd = xml.indexOf(">", tagStart);
 				if (tagEnd === -1) break scan;
 				if (xml[tagEnd - 1] !== "/") depth[key] += 1;
@@ -333,10 +336,9 @@ const nearestSharedParaId = (own, other, paragraph, step) => {
 * - an id-less paragraph whose story's ordinals do not line up.
 */
 const routeChangedParagraphs = (originalXml, serializedXml, changedIds) => {
-	const rootName = rootElementName(originalXml);
-	if (rootName !== void 0 && !rootName.startsWith("w:")) return {
+	if (!splicesAsCanonical(originalXml, PARAGRAPH_SCAN_NAMES)) return {
 		type: "refused",
-		reason: `non-canonical-wordprocessingml-prefix: ${rootName}`
+		reason: `non-canonical-wordprocessingml-prefix: ${rootElementName(originalXml) ?? "unknown"}`
 	};
 	const original = addressableParagraphs(originalXml);
 	const serialized = addressableParagraphs(serializedXml);
@@ -423,9 +425,18 @@ const routeChangedParagraphs = (originalXml, serializedXml, changedIds) => {
 			newXml: authored ? newXml : withoutMintedIds(newXml, sourceXml)
 		});
 	}
+	const candidate = spliceXml(originalXml, splices);
+	if (candidate === null) return {
+		type: "refused",
+		reason: "unsafe-paragraph-splices"
+	};
+	if (!splicesAsCanonical(candidate, PARAGRAPH_SCAN_NAMES)) return {
+		type: "refused",
+		reason: "replacement-namespace-conflict"
+	};
 	return {
 		type: "routed",
-		splices
+		xml: candidate
 	};
 };
 /**
@@ -459,7 +470,7 @@ function validatePatchSafety(originalXml, serializedXml, changedIds) {
 function buildPatchedDocumentXml(originalXml, serializedXml, changedIds) {
 	if (changedIds.size === 0) return originalXml;
 	const routing = routeChangedParagraphs(originalXml, serializedXml, changedIds);
-	return routing.type === "refused" ? null : spliceXml(originalXml, routing.splices);
+	return routing.type === "refused" ? null : routing.xml;
 }
 /**
 * Build a patched note part (word/footnotes.xml / word/endnotes.xml) by
@@ -489,11 +500,18 @@ function buildPatchedNoteXml(originalXml, serializedXml, changedIds) {
 * the rest of the part byte-for-byte, so it can write half a comment range:
 * invalid OOXML that anchors the comment to nothing. Answers null when it
 * would, leaving the caller to rewrite a wider region — ultimately the whole
-* part from the model, which is balanced with itself.
+* part from the model, which is balanced with itself. Overlapping source
+* regions are refused too: replacing an inner region moves the outer region's
+* end, so its original offsets cannot be applied to the resulting string.
 */
 const spliceXml = (xml, splices) => {
 	let result = xml;
-	for (const { start, end, newXml } of [...splices].toSorted((a, b) => b.start - a.start)) result = result.slice(0, start) + newXml + result.slice(end);
+	let unpatchedEnd = xml.length;
+	for (const { start, end, newXml } of [...splices].toSorted((a, b) => b.start - a.start)) {
+		if (end > unpatchedEnd) return null;
+		result = result.slice(0, start) + newXml + result.slice(end);
+		unpatchedEnd = start;
+	}
 	return patchBreaksCommentRangeBalance(xml, result) ? null : result;
 };
 /**
@@ -647,6 +665,40 @@ const paragraphRanges = (xml, wordPrefix) => {
 	}
 	return ranges;
 };
+const OPENING_PARA_ID = /^<[^>]*?\sw14:paraId="(?<id>[^"]*)"/u;
+const openingParaId = (paragraph) => OPENING_PARA_ID.exec(paragraph)?.groups?.["id"];
+/** A note's XML outside its paragraphs, one entry per gap between them. */
+const noteGaps = (note, ranges) => {
+	const gaps = [];
+	let cursor = 0;
+	for (const range of ranges) {
+		gaps.push(note.slice(cursor, range.start));
+		cursor = range.end;
+	}
+	gaps.push(note.slice(cursor));
+	return gaps;
+};
+/**
+* Whether a note's block structure differs between two serializations of it:
+* a paragraph added, removed or replaced by another, or anything written
+* between paragraphs changed — a table, a row, a cell's properties, a
+* row-level revision. Paragraph-by-paragraph splicing pairs paragraphs by
+* ordinal, so it is only faithful when neither happened; a note whose shape
+* changed is rewritten whole. A paragraph the baseline has no id for pairs
+* with any id, because that id was minted after reading, not changed.
+*/
+const noteShapeChanged = (baseline, current) => {
+	const baselineRanges = paragraphRanges(baseline.note, baseline.prefix);
+	const currentRanges = paragraphRanges(current.note, current.prefix);
+	if (baselineRanges.length !== currentRanges.length) return true;
+	const currentGaps = noteGaps(current.note, currentRanges);
+	if (noteGaps(baseline.note, baselineRanges).some((gap, index) => gap !== currentGaps[index])) return true;
+	return baselineRanges.some((range, index) => {
+		const baselineId = openingParaId(baseline.note.slice(range.start, range.end));
+		const currentRange = currentRanges[index];
+		return baselineId !== void 0 && baselineId !== openingParaId(current.note.slice(currentRange.start, currentRange.end));
+	});
+};
 const collectChangedNoteParaIds = (baselineXml, currentXml) => {
 	const changed = /* @__PURE__ */ new Set();
 	const baselineIds = collectParaIds(baselineXml);
@@ -681,6 +733,7 @@ const collectChangedNoteParaIds = (baselineXml, currentXml) => {
 */
 function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }) {
 	const currentElements = collectNoteElementSyntax(serializedXml, elementName);
+	const baselineElements = collectNoteElementSyntax(baselineXml, elementName);
 	const originalElements = collectNoteElementSyntax(originalXml, elementName);
 	const replacementElements = collectNoteElementSyntax(replacementXml, elementName);
 	const replacementXmlnsDeclarations = collectXmlnsFromOpeningTag(replacementXml);
@@ -690,9 +743,25 @@ function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, repl
 	const serializedParaIds = collectParaIds(serializedXml);
 	const effectiveChangedParaIds = changedParaIds ?? collectChangedNoteParaIds(baselineXml, serializedXml);
 	const unroutedChangedParaIds = new Set([...effectiveChangedParaIds].filter((paraId) => serializedParaIds.has(paraId)));
+	/** Notes the model has and the part does not: new notes, appended to the part. */
+	const addedNotes = [];
 	for (const [id, currentSyntaxEntries] of currentElements) {
 		const originalSyntaxEntries = originalElements.get(id);
 		const replacementSyntaxEntries = replacementElements.get(id);
+		if (originalSyntaxEntries === void 0) {
+			const replacementSyntax = currentSyntaxEntries.length === 1 && replacementSyntaxEntries?.length === 1 ? replacementSyntaxEntries[0] : void 0;
+			const replacementNote = replacementSyntax ? extractNoteElement(replacementXml, replacementSyntax, id) : null;
+			if (!replacementSyntax || !replacementNote) return {
+				type: "refused",
+				reason: "unroutable-paragraph"
+			};
+			for (const paraId of collectParaIds(replacementNote).keys()) unroutedChangedParaIds.delete(paraId);
+			addedNotes.push({
+				note: replacementNote,
+				syntax: replacementSyntax
+			});
+			continue;
+		}
 		if (currentSyntaxEntries.length !== 1 || originalSyntaxEntries?.length !== 1 || replacementSyntaxEntries?.length !== 1) return {
 			type: "refused",
 			reason: "unroutable-paragraph"
@@ -716,7 +785,17 @@ function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, repl
 		const originalParagraphs = paragraphRanges(originalNote, originalSyntax.elementPrefix);
 		const replacementParagraphs = paragraphRanges(replacementNote, replacementSyntax.elementPrefix);
 		const noteChangedParaIds = [...collectParaIds(currentNote).keys()].filter((paraId) => unroutedChangedParaIds.has(paraId));
-		if (noteChangedParaIds.length === 0) continue;
+		const baselineSyntaxEntries = baselineElements.get(id);
+		const baselineSyntax = baselineSyntaxEntries?.length === 1 ? baselineSyntaxEntries[0] : void 0;
+		const baselineNote = baselineSyntax ? extractNoteElement(baselineXml, baselineSyntax, id) : null;
+		const reshaped = baselineSyntax !== void 0 && baselineNote !== null && baselineNote !== currentNote && noteShapeChanged({
+			note: baselineNote,
+			prefix: baselineSyntax.elementPrefix
+		}, {
+			note: currentNote,
+			prefix: currentSyntax.elementPrefix
+		});
+		if (noteChangedParaIds.length === 0 && !reshaped) continue;
 		const wholeNoteSplice = {
 			start: originalOffsets.start,
 			end: originalOffsets.end,
@@ -727,7 +806,7 @@ function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, repl
 			})
 		};
 		noteSplices.push(wholeNoteSplice);
-		if (currentParagraphs.length !== originalParagraphs.length || currentParagraphs.length !== replacementParagraphs.length) {
+		if (reshaped || currentParagraphs.length !== originalParagraphs.length || currentParagraphs.length !== replacementParagraphs.length) {
 			for (const paraId of noteChangedParaIds) unroutedChangedParaIds.delete(paraId);
 			paragraphSplices.push(wholeNoteSplice);
 			continue;
@@ -754,10 +833,36 @@ function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, repl
 			});
 		}
 	}
+	for (const [id, baselineSyntaxEntries] of baselineElements) {
+		if (currentElements.has(id) || baselineSyntaxEntries.length !== 1) continue;
+		const originalSyntaxEntries = originalElements.get(id);
+		const originalSyntax = originalSyntaxEntries?.length === 1 ? originalSyntaxEntries[0] : void 0;
+		const originalOffsets = originalSyntax && findNoteElement(originalXml, originalSyntax, id);
+		if (!originalOffsets) return {
+			type: "refused",
+			reason: "unroutable-paragraph"
+		};
+		const removal = {
+			start: originalOffsets.start,
+			end: originalOffsets.end,
+			newXml: ""
+		};
+		paragraphSplices.push(removal);
+		noteSplices.push(removal);
+	}
 	if (unroutedChangedParaIds.size > 0) return {
 		type: "refused",
 		reason: "unroutable-paragraph"
 	};
+	if (addedNotes.length > 0) {
+		const appended = appendNotesSplice(originalXml, originalElements, addedNotes, { sourceXmlnsDeclarations: replacementXmlnsDeclarations });
+		if (!appended) return {
+			type: "refused",
+			reason: "unroutable-paragraph"
+		};
+		paragraphSplices.push(appended);
+		noteSplices.push(appended);
+	}
 	const patched = spliceXml(originalXml, paragraphSplices);
 	if (patched !== null) return {
 		type: "patched",
@@ -773,6 +878,31 @@ function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, repl
 	};
 }
 /**
+* Insert new notes after the part's last note, spelled with that note's
+* prefixes. Null when the part holds no note to follow.
+*/
+const appendNotesSplice = (originalXml, originalElements, addedNotes, { sourceXmlnsDeclarations }) => {
+	let last = null;
+	for (const [id, entries] of originalElements) for (const syntax of entries) {
+		const offsets = findNoteElement(originalXml, syntax, id);
+		if (offsets && (!last || offsets.end > last.end)) last = {
+			end: offsets.end,
+			syntax
+		};
+	}
+	if (!last) return null;
+	const target = last.syntax;
+	return {
+		start: last.end,
+		end: last.end,
+		newXml: addedNotes.map(({ note, syntax }) => rewriteWordprocessingPrefixes(note, {
+			source: syntax,
+			target,
+			sourceXmlnsDeclarations
+		})).join("")
+	};
+};
+/**
 * The full range of the first `<openLiteral …>…</closeTag>` element, or null.
 * Used to locate an unkeyed sub-element (a level's `mc:AlternateContent`).
 */
@@ -892,8 +1022,24 @@ function originalCustomNumFmtFormat(numFmtElement) {
 */
 function collectXmlnsFromOpeningTag(elementXml) {
 	const out = {};
-	const tagEnd = elementXml.indexOf(">");
-	const openTag = tagEnd === -1 ? elementXml : elementXml.slice(0, tagEnd);
+	let tagStart = elementXml.indexOf("<");
+	while (tagStart !== -1 && (elementXml.startsWith("<?", tagStart) || elementXml.startsWith("<!--", tagStart))) {
+		const endMarker = elementXml.startsWith("<!--", tagStart) ? "-->" : "?>";
+		const end = elementXml.indexOf(endMarker, tagStart);
+		if (end === -1) return out;
+		tagStart = elementXml.indexOf("<", end + endMarker.length);
+	}
+	if (tagStart === -1) return out;
+	let tagEnd = tagStart + 1;
+	let quote = null;
+	while (tagEnd < elementXml.length) {
+		const character = elementXml[tagEnd];
+		if (character === quote) quote = null;
+		else if (quote === null && (character === "\"" || character === "'")) quote = character;
+		else if (quote === null && character === ">") break;
+		tagEnd += 1;
+	}
+	const openTag = elementXml.slice(tagStart, tagEnd);
 	const pattern = /\s(?<name>xmlns(?::[\w.-]+)?)="(?<uri>[^"]*)"/gu;
 	let match;
 	while ((match = pattern.exec(openTag)) !== null) out[match.groups["name"]] = match.groups["uri"];
@@ -1056,9 +1202,10 @@ const patchNumberingByNamespace = ({ original, currentXml, changed, added }) =>
 const patchNumberingDefinitions = ({ originalXml, baselineXml, currentXml }) => {
 	const changed = collectChangedNumberingDefs(baselineXml, currentXml);
 	const added = collectAddedNumberingDefs(baselineXml, currentXml);
+	if (changed.abstractNums.size === 0 && changed.nums.size === 0 && added.abstractNums.size === 0 && added.nums.size === 0) return originalXml;
 	const original = parseXmlDocument(originalXml);
 	if (!original || getLocalName(original.name) !== "numbering" || !WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(original) ?? "")) return null;
-	if (getNamespacePrefix(original.name ?? "") !== "w") return patchNumberingByNamespace({
+	if (getNamespacePrefix(original.name ?? "") !== "w" || !hasCanonicalWordprocessingPrefixes(originalXml)) return patchNumberingByNamespace({
 		original,
 		currentXml,
 		changed,

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

@@ -0,0 +1,5 @@
+import { document_d_exports } from "../../types/document.js";
+//#region src/docx/serializer/blockCustomXmlSerializer.d.ts
+declare const serializeBlockCustomXml: (block: document_d_exports.BlockCustomXml, serializeChild: (child: document_d_exports.BlockContent) => string) => string;
+//#endregion
+export { serializeBlockCustomXml };

package/dist/docx/serializer/blockCustomXmlSerializer.js

@@ -0,0 +1,4 @@
+//#region src/docx/serializer/blockCustomXmlSerializer.ts
+const serializeBlockCustomXml = (block, serializeChild) => block.openingXml + block.content.map(serializeChild).join("") + block.closingXml;
+//#endregion
+export { serializeBlockCustomXml };

package/dist/docx/serializer/documentSerializer.js

@@ -1,3 +1,4 @@
+import { serializeBlockCustomXml } from "./blockCustomXmlSerializer.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeBookmarkMarker } from "./markupRangeAttributes.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
@@ -45,6 +46,7 @@ function serializeBlockContent(block) {
 		case "paragraph": return serializeParagraph(block);
 		case "table": return serializeTable(block, serializeParagraph);
 		case "blockSdt": return serializeBlockSdt(block, serializeBlockContent);
+		case "blockCustomXml": return serializeBlockCustomXml(block, serializeBlockContent);
 		case "preservedBlock": return block.xml;
 		case "bookmarkStart":
 		case "bookmarkEnd": return serializeBookmarkMarker(block);

package/dist/docx/serializer/headerFooterSerializer.js

@@ -2,6 +2,7 @@ import { canReplayHeaderFooterVerbatim, getHeaderFooterVerbatimXml } from "../he
 import { isEmptyParagraph } from "../paragraphParser.js";
 import { captureVerbatimXml } from "../verbatimCapture.js";
 import { getLocalName, parseXmlDocument } from "../xmlParser.js";
+import { serializeBlockCustomXml } from "./blockCustomXmlSerializer.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeBookmarkMarker } from "./markupRangeAttributes.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
@@ -41,6 +42,7 @@ function serializeBlock(block) {
 		case "paragraph": return serializeParagraph(block);
 		case "table": return serializeTable(block, serializeParagraph);
 		case "blockSdt": return serializeBlockSdt(block, serializeBlock);
+		case "blockCustomXml": return serializeBlockCustomXml(block, serializeBlock);
 		case "preservedBlock": return block.xml;
 		case "bookmarkStart":
 		case "bookmarkEnd": return serializeBookmarkMarker(block);

package/dist/docx/serializer/noteSerializer.js

@@ -1,3 +1,4 @@
+import { serializeBlockCustomXml } from "./blockCustomXmlSerializer.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeBookmarkMarker } from "./markupRangeAttributes.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
@@ -43,6 +44,7 @@ function serializeBlock(block) {
 		case "paragraph": return serializeParagraph(block);
 		case "table": return serializeTable(block, serializeParagraph);
 		case "blockSdt": return serializeBlockSdt(block, serializeBlock);
+		case "blockCustomXml": return serializeBlockCustomXml(block, serializeBlock);
 		case "preservedBlock": return block.xml;
 		case "bookmarkStart":
 		case "bookmarkEnd": return serializeBookmarkMarker(block);
@@ -65,7 +67,7 @@ function serializeRequiredNoteSeparators(elementName) {
 	return `<w:${elementName} w:type="separator" w:id="-1">${NOTE_SEPARATOR_BODY}<w:r><w:separator/></w:r></w:p></w:${elementName}><w:${elementName} w:type="continuationSeparator" w:id="0">${NOTE_SEPARATOR_BODY}<w:r><w:continuationSeparator/></w:r></w:p></w:${elementName}>`;
 }
 function insertNoteReferenceMark(xml, elementName) {
-	if (xml.includes(`<w:${elementName}Ref`)) return xml;
+	if (new RegExp(`<(?:[\\w.-]+:)?${elementName}Ref[\\s/>]`, "u").test(xml)) return xml;
 	const paragraphOpen = /<w:p(?=[\s>])[^>]*>/u.exec(xml);
 	if (!paragraphOpen) return `${`<w:p><w:r><w:rPr><w:rStyle w:val="${elementName === "footnote" ? "FootnoteReference" : "EndnoteReference"}"/></w:rPr><w:${elementName}Ref/></w:r></w:p>`}${xml}`;
 	const paragraphStart = paragraphOpen.index + paragraphOpen[0].length;