@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/selectiveXmlPatch.js

@@ -1,3 +1,5 @@
+import { patchBreaksCommentRangeBalance } from "./commentRangeIntegrity.js";
+import { resolveParagraphIdentities } from "./paraIdAttribute.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, findAttributeByNamespaceUri, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
 //#region src/docx/selectiveXmlPatch.ts
@@ -94,24 +96,43 @@ function extractParagraphXml(serializedXml, paraId) {
 function buildParagraphOffsetIndex(xml) {
 	const seenCount = /* @__PURE__ */ new Map();
 	const ranges = /* @__PURE__ */ new Map();
-	const stack = [];
-	let pos = 0;
-	const noteOpen = (paraId) => {
-		if (paraId) seenCount.set(paraId, (seenCount.get(paraId) ?? 0) + 1);
-	};
-	const noteRange = (paraId, start, end) => {
-		if (paraId) ranges.set(paraId, {
+	for (const { start, end, paraId } of scanParagraphs(xml)) {
+		if (paraId === void 0) continue;
+		seenCount.set(paraId, (seenCount.get(paraId) ?? 0) + 1);
+		if (end > start) ranges.set(paraId, {
 			start,
 			end
 		});
-	};
+	}
+	const index = /* @__PURE__ */ new Map();
+	for (const [id, range] of ranges) if (seenCount.get(id) === 1) index.set(id, range);
+	return index;
+}
+/**
+* Every `<w:p>` element of `xml`, in the document order of its opening tags,
+* with the `w14:paraId` that tag carries.
+*
+* Document order is what makes the array an ordinal space: the *n*th entry of
+* the source part and the *n*th entry of the model's serialization name the
+* same paragraph, which is the only way to address a paragraph the producer
+* gave no id. A `<w:p>` nested inside another (inside `mc:AlternateContent`,
+* a text box) is one entry of its own, exactly as
+* {@link countParagraphElements} counts it, so the two never disagree about
+* what an ordinal is. An unterminated paragraph keeps `end === start`: it
+* occupies its ordinal but no splice can be built from it.
+*/
+function scanParagraphs(xml) {
+	const paragraphs = [];
+	const open = [];
+	let pos = 0;
 	while (pos < xml.length) {
 		const tagStart = xml.indexOf("<", pos);
 		if (tagStart === -1) break;
 		if (xml.startsWith("</w:p>", tagStart)) {
-			const frame = stack.pop();
+			const slot = open.pop();
 			const end = tagStart + 6;
-			if (frame) noteRange(frame.paraId, frame.start, end);
+			const paragraph = slot === void 0 ? void 0 : paragraphs[slot];
+			if (paragraph) paragraph.end = end;
 			pos = end;
 			continue;
 		}
@@ -122,18 +143,23 @@ function buildParagraphOffsetIndex(xml) {
 		const tagEnd = xml.indexOf(">", tagStart);
 		if (tagEnd === -1) break;
 		const openTag = xml.slice(tagStart, tagEnd + 1);
-		const paraId = /\bw14:paraId="(?<id>[^"]*)"/u.exec(openTag)?.groups?.["id"];
-		noteOpen(paraId);
-		if (xml[tagEnd - 1] === "/") noteRange(paraId, tagStart, tagEnd + 1);
-		else stack.push({
+		const paraId = /\bw14:paraId="(?<id>[^"]+)"/u.exec(openTag)?.groups?.["id"];
+		if (xml[tagEnd - 1] === "/") paragraphs.push({
 			start: tagStart,
+			end: tagEnd + 1,
 			paraId
 		});
+		else {
+			open.push(paragraphs.length);
+			paragraphs.push({
+				start: tagStart,
+				end: tagStart,
+				paraId
+			});
+		}
 		pos = tagEnd + 1;
 	}
-	const index = /* @__PURE__ */ new Map();
-	for (const [id, range] of ranges) if (seenCount.get(id) === 1) index.set(id, range);
-	return index;
+	return paragraphs;
 }
 /**
 * Count <w:p> elements in an XML string (top-level paragraph count).
@@ -162,40 +188,140 @@ function collectParaIds(xml) {
 	}
 	return ids;
 }
+/** Paragraph ids folio writes and this module may have to remove again. */
+const MINTED_PARA_ID_ATTRIBUTE = /\sw14:(?:para|text)Id="[^"]*"/gu;
 /**
-* Validate that a selective patch can be safely applied.
+* The replacement for a paragraph whose source open tag carries no paraId.
 *
-* Checks:
-* - All changed paraIds exist in original XML (exactly once)
-* - All changed paraIds exist in serialized XML (exactly once)
-* - Paragraph count matches between original and serialized (unless disabled)
+* The model always has a key, because folio mints one for every paragraph that
+* arrives without one, and the serializer writes whatever key the model holds.
+* Writing a minted key into the package would upgrade a producer's id-less
+* document to a partly-id'd one on any edit, declare a `w14` namespace the
+* part never had, and turn an id the minter itself calls positional into an
+* authored one the next reader trusts. So the save keeps the author's
+* convention: `ensureParaIds` is the one pass that gives a package ids, and it
+* runs when a host asks for it. An id the source *does* carry (a `w14:textId`
+* beside no paraId) is the author's and stays.
 */
-function validatePatchSafety(originalXml, serializedXml, changedIds, options = {}) {
-	if (changedIds.size === 0) return { safe: true };
+const withoutMintedIds = (paragraphXml, sourceOpenTag) => {
+	const tagEnd = paragraphXml.indexOf(">");
+	if (tagEnd === -1) return paragraphXml;
+	return paragraphXml.slice(0, tagEnd + 1).replace(MINTED_PARA_ID_ATTRIBUTE, (attribute) => sourceOpenTag.includes(attribute.trim()) ? attribute : "") + paragraphXml.slice(tagEnd + 1);
+};
+/**
+* Route every changed paragraph from the model's serialization to its region
+* of the source part.
+*
+* One owner for the question the patch turns on: *which paragraph of the file
+* is this model paragraph?* {@link resolveParagraphIdentities} answers it per
+* paragraph, and the union is consumed exhaustively here, so a paragraph the
+* source names by id keeps the id lookup — robust to any reordering — and one
+* the source never named falls back to its ordinal, which is sound exactly
+* when the identity plan says the two sequences line up. A package with ids on
+* some paragraphs and not others therefore needs no special case: its authored
+* ids are the witnesses that prove the ordinals for the rest.
+*/
+const routeChangedParagraphs = (originalXml, serializedXml, changedIds) => {
+	const original = scanParagraphs(originalXml);
+	const serialized = scanParagraphs(serializedXml);
+	const { identities, ordinalsAligned } = resolveParagraphIdentities({
+		sourceParaIds: original.map(({ paraId }) => paraId),
+		serializedParaIds: serialized.map(({ paraId }) => paraId)
+	});
 	const originalParaIds = collectParaIds(originalXml);
 	const serializedParaIds = collectParaIds(serializedXml);
+	const identityByParaId = /* @__PURE__ */ new Map();
+	for (const identity of identities) if (identity.type !== "anonymous" && serializedParaIds.get(identity.paraId) === 1) identityByParaId.set(identity.paraId, identity);
+	const splices = [];
 	for (const id of changedIds) {
-		const origCount = originalParaIds.get(id) || 0;
-		if (origCount === 0) return {
-			safe: false,
-			reason: `paraId-not-found-in-original: ${id}`
-		};
-		if (origCount > 1) return {
-			safe: false,
+		const originalCount = originalParaIds.get(id) ?? 0;
+		if (originalCount > 1) return {
+			type: "refused",
 			reason: `duplicate-paraId-in-original: ${id}`
 		};
-	}
-	for (const id of changedIds) {
-		const serCount = serializedParaIds.get(id) || 0;
-		if (serCount === 0) return {
-			safe: false,
+		const serializedCount = serializedParaIds.get(id) ?? 0;
+		if (originalCount === 1 && serializedCount === 0) return {
+			type: "refused",
 			reason: `paraId-not-found-in-serialized: ${id}`
 		};
-		if (serCount > 1) return {
-			safe: false,
+		if (serializedCount === 0) return {
+			type: "refused",
+			reason: `paraId-not-found-in-original: ${id}`
+		};
+		if (serializedCount > 1) return {
+			type: "refused",
 			reason: `duplicate-paraId-in-serialized: ${id}`
 		};
+		const identity = identityByParaId.get(id);
+		if (!identity) return {
+			type: "refused",
+			reason: `paraId-not-found-in-serialized: ${id}`
+		};
+		const replacement = serialized[identity.ordinal];
+		if (!replacement || replacement.end <= replacement.start) return {
+			type: "refused",
+			reason: `unterminated-paragraph: ${id}`
+		};
+		const newXml = serializedXml.slice(replacement.start, replacement.end);
+		switch (identity.type) {
+			case "authored": {
+				const offsets = findParagraphOffsets(originalXml, identity.paraId);
+				if (!offsets) return {
+					type: "refused",
+					reason: `paraId-not-found-in-original: ${id}`
+				};
+				splices.push({
+					start: offsets.start,
+					end: offsets.end,
+					newXml
+				});
+				break;
+			}
+			case "minted": {
+				if (!ordinalsAligned) return {
+					type: "refused",
+					reason: `unaligned-paragraph-ordinals: ${id}`
+				};
+				const source = original[identity.ordinal];
+				if (!source || source.end <= source.start) return {
+					type: "refused",
+					reason: `paraId-not-found-in-original: ${id}`
+				};
+				splices.push({
+					start: source.start,
+					end: source.end,
+					newXml: withoutMintedIds(newXml, originalXml.slice(source.start, source.end))
+				});
+				break;
+			}
+			case "anonymous": return {
+				type: "refused",
+				reason: `paraId-not-found-in-serialized: ${id}`
+			};
+			default: return identity;
+		}
 	}
+	return {
+		type: "routed",
+		splices
+	};
+};
+/**
+* Validate that a selective patch can be safely applied.
+*
+* Checks:
+* - Every changed paraId routes to one region of the original XML, by its
+*   authored id or, when the producer wrote none, by its paragraph ordinal
+* - All changed paraIds exist in serialized XML (exactly once)
+* - Paragraph count matches between original and serialized (unless disabled)
+*/
+function validatePatchSafety(originalXml, serializedXml, changedIds, options = {}) {
+	if (changedIds.size === 0) return { safe: true };
+	const routing = routeChangedParagraphs(originalXml, serializedXml, changedIds);
+	if (routing.type === "refused") return {
+		safe: false,
+		reason: routing.reason
+	};
 	if (options.checkParagraphCount === false) return { safe: true };
 	const originalCount = countParagraphElements(originalXml);
 	const serializedCount = countParagraphElements(serializedXml);
@@ -237,28 +363,31 @@ function buildPatchedNoteXml(originalXml, serializedXml, changedIds) {
 	return spliceChangedParagraphs(originalXml, serializedXml, changedIds);
 }
 /**
+* Apply `splices` to `xml`, end-to-start so earlier offsets stay valid.
+*
+* Every selective patch is a splice, and every splice goes through here, so
+* the refusal below is a property of the operation rather than a check each
+* site has to remember. A patch rewrites the regions an edit touched and keeps
+* 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.
+*/
+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);
+	return patchBreaksCommentRangeBalance(xml, result) ? null : result;
+};
+/**
 * Replace each changed paragraph in `originalXml` with its re-serialized form
-* extracted from `serializedXml`, splicing end-to-start so earlier offsets stay
-* valid. Assumes safety has already been validated. Returns null if an offset
-* or extraction unexpectedly fails.
+* extracted from `serializedXml`. Assumes safety has already been validated.
+* Returns null if an offset or extraction unexpectedly fails, or if
+* {@link spliceXml} refuses the result; the caller then falls back to a full
+* repack, whose parts are all re-serialized from one model.
 */
 function spliceChangedParagraphs(originalXml, serializedXml, changedIds) {
-	const replacements = [];
-	for (const paraId of changedIds) {
-		const origOffsets = findParagraphOffsets(originalXml, paraId);
-		if (!origOffsets) return null;
-		const newXml = extractParagraphXml(serializedXml, paraId);
-		if (!newXml) return null;
-		replacements.push({
-			start: origOffsets.start,
-			end: origOffsets.end,
-			newXml
-		});
-	}
-	replacements.sort((a, b) => b.start - a.start);
-	let result = originalXml;
-	for (const { start, end, newXml } of replacements) result = result.slice(0, start) + newXml + result.slice(end);
-	return result;
+	const routing = routeChangedParagraphs(originalXml, serializedXml, changedIds);
+	return routing.type === "refused" ? null : spliceXml(originalXml, routing.splices);
 }
 /**
 * Depth-count the end of the element that opens at `start` (an `<openLiteral…>`
@@ -424,11 +553,6 @@ const collectChangedNoteParaIds = (baselineXml, currentXml) => {
 	}
 	return changed;
 };
-const replaceRanges = (xml, replacements) => {
-	let result = xml;
-	for (const { start, end, newXml } of [...replacements].toSorted((a, b) => b.start - a.start)) result = result.slice(0, start) + newXml + result.slice(end);
-	return result;
-};
 /**
 * Patch an existing note part from its model serialization.
 *
@@ -440,56 +564,79 @@ const replaceRanges = (xml, replacements) => {
 * notes, and unaffected equal-shape paragraphs remain byte-exact.
 * `replacementXml` also supplies synthesized automatic note-reference marks,
 * which the parsed model intentionally omits.
+*
+* A comment can be anchored on a note's own text, so its range spans that
+* note's paragraphs and an edit inside the span moves a range half from one
+* paragraph to another. Replacing only the dirty paragraph then drops the half
+* it held and leaves the other standing, so {@link spliceXml} refuses the
+* result and the changed notes are rewritten whole instead — model content on
+* both sides of the range, with every other note still byte-exact.
 */
 function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }) {
 	const currentElements = collectNoteElementSyntax(serializedXml, elementName);
 	const originalElements = collectNoteElementSyntax(originalXml, elementName);
 	const replacementElements = collectNoteElementSyntax(replacementXml, elementName);
 	const replacementXmlnsDeclarations = collectXmlnsFromOpeningTag(replacementXml);
-	const ordinalReplacements = [];
+	const paragraphSplices = [];
+	/** The same edits at note granularity, should the paragraph splices be refused. */
+	const noteSplices = [];
 	const serializedParaIds = collectParaIds(serializedXml);
 	const effectiveChangedParaIds = changedParaIds ?? collectChangedNoteParaIds(baselineXml, serializedXml);
 	const unroutedChangedParaIds = new Set([...effectiveChangedParaIds].filter((paraId) => serializedParaIds.has(paraId)));
 	for (const [id, currentSyntaxEntries] of currentElements) {
 		const originalSyntaxEntries = originalElements.get(id);
 		const replacementSyntaxEntries = replacementElements.get(id);
-		if (currentSyntaxEntries.length !== 1 || originalSyntaxEntries?.length !== 1 || replacementSyntaxEntries?.length !== 1) return null;
+		if (currentSyntaxEntries.length !== 1 || originalSyntaxEntries?.length !== 1 || replacementSyntaxEntries?.length !== 1) return {
+			type: "refused",
+			reason: "unroutable-paragraph"
+		};
 		const currentSyntax = currentSyntaxEntries[0];
 		const originalSyntax = originalSyntaxEntries[0];
 		const replacementSyntax = replacementSyntaxEntries[0];
-		if (!currentSyntax || !originalSyntax || !replacementSyntax) return null;
+		if (!currentSyntax || !originalSyntax || !replacementSyntax) return {
+			type: "refused",
+			reason: "unroutable-paragraph"
+		};
 		const currentNote = extractNoteElement(serializedXml, currentSyntax, id);
 		const originalOffsets = findNoteElement(originalXml, originalSyntax, id);
 		const replacementNote = extractNoteElement(replacementXml, replacementSyntax, id);
-		if (!currentNote || !originalOffsets || !replacementNote) return null;
+		if (!currentNote || !originalOffsets || !replacementNote) return {
+			type: "refused",
+			reason: "unroutable-paragraph"
+		};
 		const originalNote = originalXml.slice(originalOffsets.start, originalOffsets.end);
 		const currentParagraphs = paragraphRanges(currentNote, currentSyntax.elementPrefix);
 		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 wholeNoteSplice = {
+			start: originalOffsets.start,
+			end: originalOffsets.end,
+			newXml: rewriteWordprocessingPrefixes(replacementNote, {
+				source: replacementSyntax,
+				target: originalSyntax,
+				sourceXmlnsDeclarations: replacementXmlnsDeclarations
+			})
+		};
+		noteSplices.push(wholeNoteSplice);
 		if (currentParagraphs.length !== originalParagraphs.length || currentParagraphs.length !== replacementParagraphs.length) {
 			for (const paraId of noteChangedParaIds) unroutedChangedParaIds.delete(paraId);
-			ordinalReplacements.push({
-				start: originalOffsets.start,
-				end: originalOffsets.end,
-				newXml: rewriteWordprocessingPrefixes(replacementNote, {
-					source: replacementSyntax,
-					target: originalSyntax,
-					sourceXmlnsDeclarations: replacementXmlnsDeclarations
-				})
-			});
+			paragraphSplices.push(wholeNoteSplice);
 			continue;
 		}
 		for (let index = 0; index < currentParagraphs.length; index++) {
 			const currentRange = currentParagraphs[index];
 			const originalRange = originalParagraphs[index];
 			const replacementRange = replacementParagraphs[index];
-			if (!currentRange || !originalRange || !replacementRange) return null;
+			if (!currentRange || !originalRange || !replacementRange) return {
+				type: "refused",
+				reason: "unroutable-paragraph"
+			};
 			const routedIds = [...collectParaIds(currentNote.slice(currentRange.start, currentRange.end)).keys()].filter((paraId) => unroutedChangedParaIds.has(paraId));
 			if (routedIds.length === 0) continue;
 			for (const paraId of routedIds) unroutedChangedParaIds.delete(paraId);
-			ordinalReplacements.push({
+			paragraphSplices.push({
 				start: originalOffsets.start + originalRange.start,
 				end: originalOffsets.start + originalRange.end,
 				newXml: rewriteWordprocessingPrefixes(replacementNote.slice(replacementRange.start, replacementRange.end), {
@@ -500,8 +647,23 @@ function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, repl
 			});
 		}
 	}
-	if (unroutedChangedParaIds.size > 0) return null;
-	return replaceRanges(originalXml, ordinalReplacements);
+	if (unroutedChangedParaIds.size > 0) return {
+		type: "refused",
+		reason: "unroutable-paragraph"
+	};
+	const patched = spliceXml(originalXml, paragraphSplices);
+	if (patched !== null) return {
+		type: "patched",
+		xml: patched
+	};
+	const wholeNotes = spliceXml(originalXml, noteSplices);
+	return wholeNotes === null ? {
+		type: "refused",
+		reason: "comment-range-balance"
+	} : {
+		type: "patched",
+		xml: wholeNotes
+	};
 }
 /**
 * The full range of the first `<openLiteral …>…</closeTag>` element, or null.
@@ -568,7 +730,7 @@ function buildNumberingElementOffsetIndex(xml, kind) {
 	}
 	return index;
 }
-const SYNTHETIC_NUM_FMT_PATTERN = /<w:numFmt w:val="decimalZero(?<width>[345])"\/>/u;
+const CUSTOM_NUM_FMT_PATTERN = /<w:numFmt w:val="custom"(?: w:format="(?<format>[^"]*)")?\/>/u;
 /**
 * The numbering definitions whose current serialization differs from the
 * baseline (re-parsed original) serialization — the ones actually edited. An id
@@ -605,30 +767,15 @@ function extractLevelNumFmtElement(levelXml) {
 	return match ? match[0] : null;
 }
 /**
-* A valid OOXML custom number format equivalent to a `decimalZero{width}`
-* synthetic value: a zero-padded first token folio's parser reads back to the
-* same width. Used only when the original element cannot be resolved, so a
-* changed definition never emits a non-OOXML synthetic value.
+* The `@w:format` an original level's number-format element declares, or null
+* when it declares no custom format at all. Telling a preserved format from an
+* edited one is what keeps a genuine change from being reverted.
 */
-function reconstructCustomNumFmt(width) {
-	return `<w:numFmt w:val="custom" w:format="${`${"0".repeat(Number.parseInt(width, 10) - 1)}1`}"/>`;
-}
-/**
-* The synthetic `decimalZero{width}` width the parser would derive from an
-* original level's number-format element (its custom `w:format` first token),
-* as the same digit-count string the SYNTHETIC_NUM_FMT_PATTERN captures. Mirrors
-* `parseCustomNumberFormat` (first comma-separated token, `^0+1$`, clamped to 5).
-* Returns null when the element carries no zero-padded custom format, so a
-* genuine format change is never mistaken for the original.
-*/
-function originalNumFmtWidth(numFmtElement) {
+function originalCustomNumFmtFormat(numFmtElement) {
 	for (const match of numFmtElement.matchAll(/<w:numFmt\b[^>]*\/>/gu)) {
 		const tag = match[0];
 		if (!/\bw:val="custom"/u.test(tag)) continue;
-		const format = /\bw:format="(?<format>[^"]*)"/u.exec(tag)?.groups?.["format"];
-		if (format === void 0) continue;
-		const firstToken = format.split(",")[0]?.trim() ?? "";
-		return /^0+1$/u.test(firstToken) ? String(Math.min(firstToken.length, 5)) : null;
+		return /\bw:format="(?<format>[^"]*)"/u.exec(tag)?.groups?.["format"] ?? null;
 	}
 	return null;
 }
@@ -661,21 +808,19 @@ function withXmlnsDeclarations(fragmentXml, xmlnsDecls) {
 	return fragmentXml.slice(0, nameEnd) + additions.join("") + fragmentXml.slice(nameEnd);
 }
 /**
-* Swap each synthetic `decimalZero{3,4,5}` numFmt in a re-serialized definition
-* back to the original level's number-format element.
+* Swap each re-serialized custom numFmt back to the original level's
+* number-format element.
 *
-* folio's parser collapses a Word custom / mc:AlternateContent number format
-* into a synthetic `decimalZero{3,4,5}` value the model cannot re-emit as valid
-* OOXML. When an unrelated field of the definition is edited, the whole
-* definition is re-serialized, so without this pass the level's custom format
-* would be replaced by an invalid value and lost on reparse. For each level
-* whose re-emitted numFmt is synthetic, restore the original level's numFmt
-* element by ilvl ONLY when the model's synthetic value still matches the
-* original's (the format was not edited, just preserved past an unrelated
-* change). When the model deliberately changed the width (e.g. decimalZero4 ->
-* decimalZero5), or the original cannot be resolved, emit a valid OOXML custom
-* format for the CURRENT width instead — honoring the edit and never leaving a
-* synthetic value.
+* The model holds a custom format as `custom` plus its `@w:format`, which the
+* serializer re-emits as a bare `<w:numFmt w:val="custom" w:format="…"/>`. That
+* is valid OOXML and reparses to the same model, but it is not what the source
+* wrote: Word wraps a custom format in an `mc:AlternateContent` whose Fallback
+* carries a plain format for pre-w14 readers, and the model has no field for
+* the Fallback. When an unrelated field of the definition is edited the whole
+* definition is re-serialized, so without this pass that wrapper would be
+* flattened away. Restore it by ilvl only when the model's format still matches
+* the original's; a level whose format was actually edited keeps the model's
+* own element, which is the edit.
 */
 function restoreLevelNumFmts(originalDefXml, currentDefXml) {
 	const replacements = [];
@@ -684,28 +829,29 @@ function restoreLevelNumFmts(originalDefXml, currentDefXml) {
 		const curOffsets = findElementByIdAttr(currentDefXml, LEVEL_OPEN_LITERAL, LEVEL_CLOSE_TAG, LEVEL_ID_ATTR, ilvl);
 		if (!curOffsets) continue;
 		const curLevel = currentDefXml.slice(curOffsets.start, curOffsets.end);
-		const synthetic = SYNTHETIC_NUM_FMT_PATTERN.exec(curLevel);
-		if (!synthetic) continue;
+		const custom = CUSTOM_NUM_FMT_PATTERN.exec(curLevel);
+		if (!custom) continue;
 		const origLevel = extractElementByIdAttr(originalDefXml, LEVEL_OPEN_LITERAL, LEVEL_CLOSE_TAG, LEVEL_ID_ATTR, ilvl);
-		const currentWidth = synthetic.groups["width"];
+		const currentFormat = custom.groups?.["format"] ?? null;
 		const original = origLevel ? extractLevelNumFmtElement(origLevel) : null;
-		let replacement;
-		if (original && origLevel && originalNumFmtWidth(original) === currentWidth) replacement = withXmlnsDeclarations(original, {
+		if (!original || !origLevel || originalCustomNumFmtFormat(original) !== currentFormat) continue;
+		const ancestorXmlns = {
 			...collectXmlnsFromOpeningTag(originalDefXml),
 			...collectXmlnsFromOpeningTag(origLevel)
-		});
-		else replacement = reconstructCustomNumFmt(currentWidth);
-		const restoredLevel = curLevel.slice(0, synthetic.index) + replacement + curLevel.slice(synthetic.index + synthetic[0].length);
+		};
+		const restoredLevel = spliceXml(curLevel, [{
+			start: custom.index,
+			end: custom.index + custom[0].length,
+			newXml: withXmlnsDeclarations(original, ancestorXmlns)
+		}]);
+		if (restoredLevel === null) continue;
 		replacements.push({
 			start: curOffsets.start,
 			end: curOffsets.end,
 			newXml: restoredLevel
 		});
 	}
-	replacements.sort((a, b) => b.start - a.start);
-	let result = currentDefXml;
-	for (const { start, end, newXml } of replacements) result = result.slice(0, start) + newXml + result.slice(end);
-	return result;
+	return spliceXml(currentDefXml, replacements) ?? currentDefXml;
 }
 /**
 * Build a patched `word/numbering.xml` by splicing the changed `w:abstractNum` /
@@ -733,10 +879,7 @@ function buildPatchedNumberingXml(originalXml, currentXml, changed) {
 		return true;
 	};
 	if (!collect("abstractNum", changed.abstractNums) || !collect("num", changed.nums)) return null;
-	replacements.sort((a, b) => b.start - a.start);
-	let result = originalXml;
-	for (const { start, end, newXml } of replacements) result = result.slice(0, start) + newXml + result.slice(end);
-	return result;
+	return spliceXml(originalXml, replacements);
 }
 /**
 * Numbering definitions present in `currentXml` (the model's serialization)
@@ -851,12 +994,12 @@ function appendNumberingDefs(xml, currentXml, added) {
 	return head + abstractXmls.join("") + middle + numXmls.join("") + tail;
 }
 /**
-* For an added abstract definition that still carries a synthetic numFmt, find
+* For an added abstract definition that carries a flattened custom numFmt, find
 * the original abstract it was cloned from (same serialized body apart from the
 * id) and restore the level formats from it.
 */
 function restoreClonedLevelNumFmts(originalXml, currentXml, addedDefXml, addedId) {
-	if (!SYNTHETIC_NUM_FMT_PATTERN.test(addedDefXml)) return addedDefXml;
+	if (!CUSTOM_NUM_FMT_PATTERN.test(addedDefXml)) return addedDefXml;
 	const addedBody = stripAbstractNumId(addedDefXml, addedId);
 	const originalIds = collectElementIds(originalXml, NUMBERING_OPEN_LITERAL.abstractNum, NUMBERING_ID_ATTR.abstractNum);
 	for (const [id] of originalIds) {
@@ -872,4 +1015,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, validatePatchSafety };
+export { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, scanParagraphs, spliceXml, validatePatchSafety };