@stll/folio-core 0.51.0 → 0.53.0

package/dist/docx/parser.js

@@ -1,6 +1,7 @@
 import { toArrayBuffer } from "../utils/docxInput.js";
 import { loadFontsWithMapping } from "../utils/fontLoader.js";
 import { MAX_PACKAGE_TIFF_PIXELS, convertTiffToPngDataUrl, isTiffMimeType } from "../utils/tiffConverter.js";
+import { ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES, getAltChunkRelationshipId, isAltChunkMarkup } from "./altChunk.js";
 import { DUPLICATE_COMMENT_ID_WARNING, normalizeCommentIds } from "./commentIdNormalization.js";
 import { parseComments } from "./commentParser.js";
 import { DANGLING_COMMENT_REFERENCE_WARNING, UNBALANCED_COMMENT_RANGE_WARNING, normalizeCommentReferences } from "./commentReferenceNormalization.js";
@@ -13,13 +14,14 @@ import { DocxEncryptionError } from "./encryption/errors.js";
 import { parseFontTable } from "./fontTableParser.js";
 import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
 import { parseFooter, parseHeader } from "./headerFooterParser.js";
-import { DANGLING_FOOTER_REFERENCE_WARNING, DANGLING_HEADER_REFERENCE_WARNING, normalizeHeaderFooterReferences } from "./headerFooterReferenceNormalization.js";
-import { assignHeaderFooterVerbatimXml, refreshHeaderFooterVerbatimFingerprint } from "./headerFooterVerbatim.js";
+import { DANGLING_FOOTER_REFERENCE_WARNING, DANGLING_HEADER_REFERENCE_WARNING, assignHeaderFooterRoles, normalizeHeaderFooterReferences } from "./headerFooterReferenceNormalization.js";
+import { assignHeaderFooterVerbatimXml, canReplayHeaderFooterVerbatim, refreshHeaderFooterVerbatimFingerprint } from "./headerFooterVerbatim.js";
 import { extractMetafileRaster, isMetafileMimeType } from "./metafileRaster.js";
 import { renderEmfSvg } from "./metafileSvg.js";
 import { DocxModelValidationError, formatDocumentModelIssues, validateFolioDocumentModel } from "./modelValidation.js";
 import { parseNumbering } from "./numberingParser.js";
 import { UNNUMBERED_PARAGRAPH_WARNING, UNNUMBERED_STYLE_WARNING, normalizeNumberingReferences, normalizeStyleNumberingReferences } from "./numberingReferenceNormalization.js";
+import { countOpaqueRevisionWrappers } from "./opaqueCarrier.js";
 import { assignDocumentParagraphPropertySourceContract } from "./paragraphPropertySource.js";
 import { createParseWarningCollector } from "./parseContext.js";
 import { formatParseWarnings } from "./parseWarningMessage.js";
@@ -30,9 +32,10 @@ import { parseSettings } from "./settingsParser.js";
 import { parseStylesPackage } from "./styleParser.js";
 import { applyThemeFontLang, parseTheme } from "./themeParser.js";
 import { UNBALANCED_MOVE_RANGE_WARNING, normalizeTrackedMoveRanges } from "./trackedMoveRangeNormalization.js";
-import { getMediaMimeType, mediaToDataUrl, unzipDocx } from "./unzip.js";
+import { getEntryUncompressedSize, getMediaMimeType, mediaToDataUrl, unzipDocx } from "./unzip.js";
+import { getAttribute, getChildElements, getLocalName, parseXmlDocument } from "./xmlParser.js";
 import { FOLIO_XML_RESOURCE_LIMITS } from "./xmlResourceLimits.js";
-import { TaggedError } from "better-result";
+import { TaggedError, panic } from "better-result";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/parser.ts
 /**
@@ -63,6 +66,101 @@ const sha256Hex = async (buffer) => {
 	for (const byte of bytes) digest += byte.toString(16).padStart(2, "0");
 	return digest;
 };
+const countAltChunks = (blocks) => {
+	let count = 0;
+	for (const block of blocks) switch (block.type) {
+		case "preservedBlock":
+			count += isAltChunkMarkup(block.xml) ? 1 : 0;
+			break;
+		case "table":
+			for (const row of block.rows) for (const cell of row.cells) count += countAltChunks(cell.content);
+			break;
+		case "blockSdt":
+		case "blockCustomXml":
+			count += countAltChunks(block.content);
+			break;
+		case "paragraph":
+		case "bookmarkStart":
+		case "bookmarkEnd": break;
+		default: panic(`Unsupported block while counting altChunks: ${JSON.stringify(block)}`);
+	}
+	return count;
+};
+const ALT_CHUNK_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/aFChunk";
+const ALT_CHUNK_STRICT_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/aFChunk";
+const CONTENT_TYPES_NAMESPACE_URI = "http://schemas.openxmlformats.org/package/2006/content-types";
+const contentTypeOf = (contentTypesXml, partPath) => {
+	if (!contentTypesXml) return;
+	const root = parseXmlDocument(contentTypesXml);
+	if (!root || root.namespaceUri !== CONTENT_TYPES_NAMESPACE_URI) return;
+	const extension = partPath.slice(partPath.lastIndexOf(".") + 1).toLowerCase();
+	let defaultContentType;
+	for (const child of getChildElements(root)) {
+		if (child.namespaceUri !== CONTENT_TYPES_NAMESPACE_URI) continue;
+		const name = getLocalName(child.name);
+		const contentType = getAttribute(child, null, "ContentType");
+		if (name === "Override" && getAttribute(child, null, "PartName") === `/${partPath}`) return contentType ?? void 0;
+		if (name === "Default" && getAttribute(child, null, "Extension")?.toLowerCase() === extension) defaultContentType = contentType ?? void 0;
+	}
+	return defaultContentType;
+};
+const extractAltChunkPlainText = async (xml, context) => {
+	const relationshipId = getAltChunkRelationshipId(xml);
+	const relationship = relationshipId === void 0 ? void 0 : context.relationships.get(relationshipId);
+	if (!relationship || relationship.targetMode === "External" || relationship.type !== ALT_CHUNK_RELATIONSHIP_TYPE && relationship.type !== ALT_CHUNK_STRICT_RELATIONSHIP_TYPE) return;
+	const partPath = resolveRelativePath(context.relationshipsPath, relationship.target);
+	if (contentTypeOf(context.raw.contentTypesXml, partPath)?.split(";")[0]?.trim().toLowerCase() !== "text/plain") return;
+	const file = context.raw.originalZip.file(partPath);
+	if (!file) return;
+	const declaredSize = getEntryUncompressedSize(file);
+	if (declaredSize === null || declaredSize > context.budget.remainingBytes) return void 0;
+	const bytes = await file.async("uint8array");
+	if (bytes.byteLength > context.budget.remainingBytes) return;
+	context.budget.remainingBytes -= bytes.byteLength;
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return;
+	}
+};
+const attachAltChunkPlainText = async (blocks, context) => {
+	for (const block of blocks) {
+		if (block.type === "preservedBlock" && isAltChunkMarkup(block.xml)) {
+			const readerText = await extractAltChunkPlainText(block.xml, context);
+			if (readerText !== void 0) block.readerText = readerText;
+			continue;
+		}
+		if (block.type === "table") {
+			for (const row of block.rows) for (const cell of row.cells) await attachAltChunkPlainText(cell.content, context);
+			continue;
+		}
+		if (block.type === "blockSdt" || block.type === "blockCustomXml") await attachAltChunkPlainText(block.content, context);
+	}
+};
+const countOpaqueRevisionCarriers = (blocks) => {
+	let count = 0;
+	for (const block of blocks) switch (block.type) {
+		case "preservedBlock":
+			count += countOpaqueRevisionWrappers(block.xml);
+			break;
+		case "table":
+			count += block.preserved?.children?.reduce((total, child) => total + countOpaqueRevisionWrappers(child.xml), 0) ?? 0;
+			for (const row of block.rows) {
+				count += row.preserved?.children?.reduce((total, child) => total + countOpaqueRevisionWrappers(child.xml), 0) ?? 0;
+				for (const cell of row.cells) count += countOpaqueRevisionCarriers(cell.content);
+			}
+			break;
+		case "blockSdt":
+		case "blockCustomXml":
+			count += countOpaqueRevisionCarriers(block.content);
+			break;
+		case "paragraph":
+		case "bookmarkStart":
+		case "bookmarkEnd": break;
+		default: panic(`Unsupported block while counting opaque revisions: ${JSON.stringify(block)}`);
+	}
+	return count;
+};
 /**
 * Parse a DOCX file into a complete Document model
 *
@@ -210,6 +308,11 @@ async function parseDocxWithPreviewBudget(input, options, previewBudget) {
 			code: DANGLING_FOOTER_REFERENCE_WARNING,
 			count: headerFooterReferenceNormalization.removedDanglingFooterReferences
 		});
+		assignHeaderFooterRoles({
+			documentBody,
+			...headers !== void 0 ? { headers } : {},
+			...footers !== void 0 ? { footers } : {}
+		});
 		const numberingReferenceNormalization = normalizeNumberingReferences({
 			documentBody,
 			numbering,
@@ -272,27 +375,77 @@ async function parseDocxWithPreviewBudget(input, options, previewBudget) {
 		} else onProgress("Skipping font loading", 95);
 		onProgress("Assembling document...", 95);
 		const properties = timeStage("coreProperties", () => parseCoreProperties(raw.corePropsXml));
+		const pkg = {
+			conformanceClass: detectDocxConformanceClass(raw.documentXml),
+			document: documentBody,
+			settings,
+			...styleDefinitions !== void 0 ? { styles: styleDefinitions } : {},
+			theme,
+			numbering: numbering.definitions,
+			...fontTable ? { fontTable } : {},
+			...headers !== void 0 ? { headers } : {},
+			...footers !== void 0 ? { footers } : {},
+			...footnotes !== void 0 ? { footnotes } : {},
+			...endnotes !== void 0 ? { endnotes } : {},
+			relationships: rels,
+			media,
+			...properties !== void 0 ? { properties } : {}
+		};
 		const document = {
-			package: {
-				conformanceClass: detectDocxConformanceClass(raw.documentXml),
-				document: documentBody,
-				settings,
-				...styleDefinitions !== void 0 ? { styles: styleDefinitions } : {},
-				theme,
-				numbering: numbering.definitions,
-				...fontTable ? { fontTable } : {},
-				...headers !== void 0 ? { headers } : {},
-				...footers !== void 0 ? { footers } : {},
-				...footnotes !== void 0 ? { footnotes } : {},
-				...endnotes !== void 0 ? { endnotes } : {},
-				relationships: rels,
-				media,
-				...properties !== void 0 ? { properties } : {}
-			},
+			package: pkg,
 			originalBuffer: raw.originalBuffer,
 			...templateVariables !== void 0 ? { templateVariables } : {},
 			...requiredFonts.length > 0 ? { requiredFonts } : {}
 		};
+		const altChunkBudget = { remainingBytes: ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES };
+		await attachAltChunkPlainText(pkg.document.content, {
+			relationships: rels,
+			relationshipsPath: DOCUMENT_RELATIONSHIPS_PATH,
+			raw,
+			budget: altChunkBudget
+		});
+		const altChunkContextForPart = (partPath) => {
+			const relationshipsPath = getRelationshipsPathForPart(partPath);
+			const relationshipsXml = getMapCaseInsensitive(raw.allXml, relationshipsPath);
+			return {
+				relationships: relationshipsXml ? parseRelationships(relationshipsXml) : /* @__PURE__ */ new Map(),
+				relationshipsPath,
+				raw,
+				budget: altChunkBudget
+			};
+		};
+		for (const [rId, header] of pkg.headers ?? []) {
+			const relationship = rels.get(rId);
+			if (relationship?.target) {
+				const replayable = canReplayHeaderFooterVerbatim(header);
+				await attachAltChunkPlainText(header.content, altChunkContextForPart(getRelationshipPartPath(relationship.target)));
+				if (replayable) refreshHeaderFooterVerbatimFingerprint(header);
+			}
+		}
+		for (const [rId, footer] of pkg.footers ?? []) {
+			const relationship = rels.get(rId);
+			if (relationship?.target) {
+				const replayable = canReplayHeaderFooterVerbatim(footer);
+				await attachAltChunkPlainText(footer.content, altChunkContextForPart(getRelationshipPartPath(relationship.target)));
+				if (replayable) refreshHeaderFooterVerbatimFingerprint(footer);
+			}
+		}
+		const footnoteContext = altChunkContextForPart("word/footnotes.xml");
+		for (const footnote of pkg.footnotes ?? []) await attachAltChunkPlainText(footnote.content, footnoteContext);
+		const endnoteContext = altChunkContextForPart("word/endnotes.xml");
+		for (const endnote of pkg.endnotes ?? []) await attachAltChunkPlainText(endnote.content, endnoteContext);
+		const altChunkCount = countAltChunks(pkg.document.content) + [...pkg.headers?.values() ?? []].reduce((total, part) => total + countAltChunks(part.content), 0) + [...pkg.footers?.values() ?? []].reduce((total, part) => total + countAltChunks(part.content), 0) + (pkg.footnotes ?? []).reduce((total, part) => total + countAltChunks(part.content), 0) + (pkg.endnotes ?? []).reduce((total, part) => total + countAltChunks(part.content), 0);
+		if (altChunkCount > 0) parseContext.warn({
+			code: PARSE_WARNING_CODES.altChunkUnsupported,
+			element: "w:altChunk",
+			count: altChunkCount
+		});
+		const opaqueRevisionCount = countOpaqueRevisionCarriers(pkg.document.content) + [...pkg.headers?.values() ?? []].reduce((total, part) => total + countOpaqueRevisionCarriers(part.content), 0) + [...pkg.footers?.values() ?? []].reduce((total, part) => total + countOpaqueRevisionCarriers(part.content), 0) + (pkg.footnotes ?? []).reduce((total, part) => total + countOpaqueRevisionCarriers(part.content), 0) + (pkg.endnotes ?? []).reduce((total, part) => total + countOpaqueRevisionCarriers(part.content), 0);
+		if (opaqueRevisionCount > 0) parseContext.warn({
+			code: PARSE_WARNING_CODES.revisionCarrierOpaque,
+			element: "w:ins/w:del/w:moveFrom/w:moveTo",
+			count: opaqueRevisionCount
+		});
 		assignDocumentParagraphPropertySourceContract(document, await paragraphPropertySourceDigest);
 		previews.enforce(previewBudget);
 		const validation = validateFolioDocumentModel(document);

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. */
@@ -1444,6 +1445,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 +1552,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 +1573,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.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,14 @@ const routeChangedParagraphs = (originalXml, serializedXml, changedIds) => {
 			newXml: authored ? newXml : withoutMintedIds(newXml, sourceXml)
 		});
 	}
+	const candidate = spliceXml(originalXml, splices);
+	if (candidate === null || !splicesAsCanonical(candidate, PARAGRAPH_SCAN_NAMES)) return {
+		type: "refused",
+		reason: "replacement-namespace-conflict"
+	};
 	return {
 		type: "routed",
-		splices
+		xml: candidate
 	};
 };
 /**
@@ -459,7 +466,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
@@ -647,6 +654,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 +722,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);
@@ -716,7 +758,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 +779,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;
@@ -892,8 +944,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 +1124,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 };