@stll/folio-core 0.37.4 → 0.38.0

package/dist/docx/removeHeaderFooterParts.js

@@ -0,0 +1,87 @@
+import { isUnsafePackagePath } from "./packageParts.js";
+import { parseRelationships, resolveRelativePath } from "./relsParser.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, cloneElement, getAttribute, getLocalName, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
+import { panic } from "better-result";
+import { OOXML_NS } from "@stll/docx-utils";
+//#region src/docx/removeHeaderFooterParts.ts
+const DOCUMENT_RELS_PATH = "word/_rels/document.xml.rels";
+const officeRelationshipHasType = (type, kind) => [...OFFICE_RELATIONSHIP_NAMESPACE_URIS].some((namespace) => type === `${namespace}/${kind}`);
+const withoutChildren = (xml, remove) => {
+	const root = parseXmlDocument(xml);
+	if (!root) return panic("Cannot update malformed package metadata");
+	return captureVerbatimXml(cloneElement(root, { elements: (root.elements ?? []).filter((child) => !remove(child)) }));
+};
+/** Remove only parts whose last selection was explicitly resolved out of the document. */
+const removeResolvedHeaderFooterParts = async ({ document, zip, removedReferences, compressionLevel }) => {
+	if (removedReferences.length === 0) return;
+	const relsFile = zip.file(DOCUMENT_RELS_PATH);
+	if (!relsFile) return panic("A resolved header/footer part has no document relationships");
+	const relsXml = await relsFile.async("text");
+	const relationships = parseRelationships(relsXml);
+	const removedIds = /* @__PURE__ */ new Set();
+	const candidates = /* @__PURE__ */ new Set();
+	for (const { part, relationshipId } of removedReferences) {
+		if ((part === "header" ? document.package.headers : document.package.footers)?.has(relationshipId)) continue;
+		const relationship = relationships.get(relationshipId);
+		if (!relationship) continue;
+		if (!officeRelationshipHasType(relationship.type, part) || relationship.targetMode === "External") return panic("Resolved header/footer relationship has an unexpected part type");
+		const path = resolveRelativePath(DOCUMENT_RELS_PATH, relationship.target);
+		if (isUnsafePackagePath(path)) return panic("Resolved header/footer has an unsafe package path");
+		removedIds.add(relationshipId);
+		candidates.add(path);
+	}
+	if (removedIds.size === 0) return;
+	for (const relationship of relationships.values()) {
+		if (removedIds.has(relationship.id) || relationship.targetMode === "External") continue;
+		candidates.delete(resolveRelativePath(DOCUMENT_RELS_PATH, relationship.target));
+	}
+	for (const file of Object.values(zip.files)) {
+		if (file.dir || !file.name.endsWith(".rels") || file.name === DOCUMENT_RELS_PATH) continue;
+		const otherRelationships = parseRelationships(await file.async("text"));
+		for (const relationship of otherRelationships.values()) if (relationship.targetMode !== "External") candidates.delete(resolveRelativePath(file.name, relationship.target));
+	}
+	const retiredMedia = /* @__PURE__ */ new Set();
+	for (const path of candidates) {
+		const slash = path.lastIndexOf("/");
+		const relsPath = `${path.slice(0, slash + 1)}_rels/${path.slice(slash + 1)}.rels`;
+		const partRels = zip.file(relsPath);
+		if (!partRels) continue;
+		for (const relationship of parseRelationships(await partRels.async("text")).values()) {
+			if (!officeRelationshipHasType(relationship.type, "image") || relationship.targetMode === "External") continue;
+			const mediaPath = resolveRelativePath(relsPath, relationship.target);
+			if (!isUnsafePackagePath(mediaPath) && mediaPath.startsWith("word/media/")) retiredMedia.add(mediaPath);
+		}
+	}
+	const compressionOptions = { level: compressionLevel };
+	zip.file(DOCUMENT_RELS_PATH, withoutChildren(relsXml, (child) => getNamespaceUri(child) === OOXML_NS.pr && getLocalName(child.name) === "Relationship" && removedIds.has(getAttribute(child, null, "Id") ?? "")), {
+		compression: "DEFLATE",
+		compressionOptions
+	});
+	if (document.package.relationships) {
+		document.package.relationships = new Map(document.package.relationships);
+		for (const id of removedIds) document.package.relationships.delete(id);
+	}
+	for (const path of candidates) {
+		zip.remove(path);
+		const slash = path.lastIndexOf("/");
+		zip.remove(`${path.slice(0, slash + 1)}_rels/${path.slice(slash + 1)}.rels`);
+	}
+	for (const file of Object.values(zip.files)) {
+		if (file.dir || !file.name.endsWith(".rels")) continue;
+		for (const relationship of parseRelationships(await file.async("text")).values()) if (relationship.targetMode !== "External") retiredMedia.delete(resolveRelativePath(file.name, relationship.target));
+	}
+	for (const path of retiredMedia) {
+		zip.remove(path);
+		candidates.add(path);
+	}
+	const contentTypes = zip.file("[Content_Types].xml");
+	if (!contentTypes) return panic("The package has no content types");
+	const contentTypesXml = await contentTypes.async("text");
+	zip.file("[Content_Types].xml", withoutChildren(contentTypesXml, (child) => getNamespaceUri(child) === OOXML_NS.ct && getLocalName(child.name) === "Override" && candidates.has((getAttribute(child, null, "PartName") ?? "").replace(/^\//u, ""))), {
+		compression: "DEFLATE",
+		compressionOptions
+	});
+};
+//#endregion
+export { removeResolvedHeaderFooterParts };

package/dist/docx/rezip.d.ts

@@ -15,6 +15,8 @@ declare function findMaxRId(relsXml: string): number;
  * These are newly created hyperlinks that need relationship entries.
  */
 declare function collectHyperlinksWithoutRId(blocks: BlockContent[]): Hyperlink[];
+/** The selective save boundary must use the same resource census as full repack. */
+declare const hasUnmaterializedInlineResources: (blocks: BlockContent[]) => boolean;
 /**
  * Options for repacking DOCX
  */
@@ -197,4 +199,4 @@ declare function createEmptyDocx(): Promise<ArrayBuffer>;
  */
 declare function createDocx(doc: document_d_exports.Document): Promise<ArrayBuffer>;
 //#endregion
-export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocxPackageFidelityError, RepackOptions, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, isDocxBuffer, notePartRelsPath, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };
+export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocxPackageFidelityError, RepackOptions, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, isDocxBuffer, notePartRelsPath, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };

package/dist/docx/rezip.js

@@ -1,8 +1,11 @@
 import { consumeTrackedSectionEndpointRemoval } from "../internal/sectionEndpointResolution.js";
+import { consumeSectionReferenceResolution } from "../internal/sectionReferenceResolution.js";
 import { isAllowedExternalWatermarkImageUrl } from "../watermark/index.js";
 import { normalizeAppVersionInExtendedProperties } from "./appVersionNormalization.js";
 import { withoutOrphanCommentRanges } from "./commentRangeIntegrity.js";
 import { applyReplyThreadMarkers } from "./commentReplyMarkers.js";
+import { normalizeDrawingIds } from "./drawingIdNormalization.js";
+import { rebindDrawingImageRelationship } from "./drawingRelationships.js";
 import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
 import { assertValidFolioDocumentModel } from "./modelValidation.js";
 import { isNewDataUrlDrawing } from "./newImage.js";
@@ -10,8 +13,9 @@ import { parseNumbering } from "./numberingParser.js";
 import { isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries } from "./packageParts.js";
 import { normalizeParaIdRangeInXmlParts } from "./paraIdRangeNormalization.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
+import { removeResolvedHeaderFooterParts } from "./removeHeaderFooterParts.js";
 import { normalizeRevisionIdsInXmlParts } from "./revisionIdNormalization.js";
-import { appendNumberingDefs, buildPatchedNotePartXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds } from "./selectiveXmlPatch.js";
+import { buildPatchedNotePartXml, collectChangedNoteParaIds, collectParaIds, patchNumberingDefinitions } from "./selectiveXmlPatch.js";
 import { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
 import { serializeDocument } from "./serializer/documentSerializer.js";
 import { serializeFontTableXml } from "./serializer/fontTableSerializer.js";
@@ -23,7 +27,7 @@ import { serializeSettingsXml } from "./serializer/settingsSerializer.js";
 import { serializeStyle, serializeStylesXml } from "./serializer/stylesSerializer.js";
 import { serializeThemeXml } from "./serializer/themeSerializer.js";
 import { escapeXml } from "./serializer/xmlUtils.js";
-import { WORDPROCESSINGML_NAMESPACE_URIS, findChild, getAttribute, getChildElements, getLocalName, getNamespaceUri, matchesName, parseXml, parseXmlDocument } from "./xmlParser.js";
+import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, matchesName, parseXml, parseXmlDocument } from "./xmlParser.js";
 import { assertXmlResourceLimits } from "./xmlResourceLimits.js";
 import { panic } from "better-result";
 import { validateDocxPackage } from "@stll/docx-core";
@@ -99,17 +103,21 @@ const countDocumentSections = (xml) => {
 };
 const extractHeaderFooterReferences = (xml) => {
 	const references = [];
-	for (const match of xml.matchAll(/<w:(?<element>headerReference|footerReference)\b[^>]*>/gu)) {
-		const tag = match[0];
-		const type = /\bw:type="(?<type>[^"]+)"/u.exec(tag)?.groups?.["type"] ?? "default";
-		const rId = /\br:id="(?<rId>[^"]+)"/u.exec(tag)?.groups?.["rId"];
-		const element = match.groups?.["element"];
-		if (!rId || element !== "headerReference" && element !== "footerReference") continue;
-		references.push({
-			element,
-			type,
-			rId
-		});
+	assertXmlResourceLimits(xml);
+	const pending = [parseXml(xml)];
+	while (pending.length > 0) {
+		const node = pending.pop();
+		if (!node) break;
+		const element = getLocalName(node.name);
+		if ((element === "headerReference" || element === "footerReference") && isWordprocessingElement(node, element)) {
+			const rId = getAttributeByNamespaceUri(node, OFFICE_RELATIONSHIP_NAMESPACE_URIS, "id");
+			if (rId) references.push({
+				element,
+				type: getAttributeByNamespaceUri(node, WORDPROCESSINGML_NAMESPACE_URIS, "type") ?? "default",
+				rId
+			});
+		}
+		pending.push(...getChildElements(node));
 	}
 	return references;
 };
@@ -126,7 +134,7 @@ const consumeReferenceCount = (counts, key) => {
 	counts.set(key, count - 1);
 	return true;
 };
-function assertDocumentPackageFidelity(originalDocumentXml, serializedDocumentXml, doc, sectionEndpointRemoval) {
+function assertDocumentPackageFidelity({ originalDocumentXml, serializedDocumentXml, doc, sectionEndpointRemoval, sectionReferenceRemovals = [] }) {
 	const originalSectionCount = countDocumentSections(originalDocumentXml);
 	const serializedSectionCount = countDocumentSections(serializedDocumentXml);
 	const trackedRemovedSectionCount = sectionEndpointRemoval ? sectionEndpointRemoval.sourceParagraphEndpointCount - sectionEndpointRemoval.expectedParagraphEndpointCount : 0;
@@ -136,6 +144,9 @@ function assertDocumentPackageFidelity(originalDocumentXml, serializedDocumentXm
 	for (const reference of extractHeaderFooterReferences(serializedDocumentXml)) incrementReferenceCount(serializedReferenceCounts, headerFooterReferenceKey(reference));
 	const removedReferenceCounts = /* @__PURE__ */ new Map();
 	if (exactTrackedSectionRemoval && sectionEndpointRemoval) for (const { part, type, relationshipId } of sectionEndpointRemoval.removedReferences) incrementReferenceCount(removedReferenceCounts, `${part}Reference:${type}:${relationshipId}`);
+	const resolvedReferenceCounts = /* @__PURE__ */ new Map();
+	for (const { part, type, relationshipId } of sectionReferenceRemovals) incrementReferenceCount(resolvedReferenceCounts, `${part}Reference:${type}:${relationshipId}`);
+	for (const [key, count] of resolvedReferenceCounts) removedReferenceCounts.set(key, Math.max(count, removedReferenceCounts.get(key) ?? 0));
 	const missingRefs = [];
 	for (const reference of extractHeaderFooterReferences(originalDocumentXml)) {
 		if (!hasParsedHeaderFooterPart(doc, reference)) continue;
@@ -314,7 +325,7 @@ async function registerImageExtensions(zip, extensions, compressionLevel) {
 function collectNewImages(blocks) {
 	const images = [];
 	const collectFromRun = (run) => {
-		for (const c of run.content) if (isNewDataUrlDrawing(c)) images.push(c.image);
+		for (const c of run.content) if (isNewDataUrlDrawing(c)) images.push(c);
 	};
 	for (const block of blocks) if (block.type === "paragraph") {
 		for (const item of block.content) if (item.type === "run") collectFromRun(item);
@@ -370,7 +381,8 @@ async function processNewImages(parts, zip, compressionLevel) {
 		let maxId = findMaxRId(relsXml);
 		const relEntries = [];
 		const partPath = relsPath.replace("/_rels/", "/").replace(/\.rels$/u, "");
-		for (const image of newImages) {
+		for (const drawing of newImages) {
+			const { image } = drawing;
 			if (!image.src) continue;
 			const { data, extension } = decodeDataUrl(image.src);
 			maxImageNum++;
@@ -383,6 +395,11 @@ async function processNewImages(parts, zip, compressionLevel) {
 			});
 			relEntries.push(`<Relationship Id="${newRId}" Type="${RELATIONSHIP_TYPES.image}" Target="${escapeXml(relativeTargetForPart(partPath, mediaPath))}"/>`);
 			extensionsAdded.add(extension);
+			if (drawing.rawXml) drawing.rawXml = rebindDrawingImageRelationship({
+				xml: drawing.rawXml,
+				previousId: image.rId ?? "",
+				nextId: newRId
+			}) ?? panic("A detached drawing lost its embedded image relationship");
 			image.rId = newRId;
 		}
 		if (relEntries.length > 0) {
@@ -395,18 +412,51 @@ async function processNewImages(parts, zip, compressionLevel) {
 	}
 	await registerImageExtensions(zip, extensionsAdded, compressionLevel);
 }
+/** Materialize detached embedded media without replacing any existing package part. */
+const materializeEmbeddedMedia = async ({ document, zip, compressionLevel }) => {
+	const extensions = /* @__PURE__ */ new Set();
+	for (const media of document.package.media?.values() ?? []) {
+		if (findZipEntryCaseInsensitive(zip, media.path.toLowerCase())) continue;
+		if (isUnsafePackagePath(media.path) || !media.path.startsWith("word/media/")) panic("Detached media has an invalid package path");
+		const extension = media.path.split(".").at(-1)?.toLowerCase();
+		if (!extension || !/^[a-z0-9]+$/u.test(extension)) panic("Embedded media has an invalid extension");
+		zip.file(media.path, media.data, {
+			compression: "DEFLATE",
+			compressionOptions: { level: compressionLevel }
+		});
+		extensions.add(extension);
+	}
+	await registerImageExtensions(zip, extensions, compressionLevel);
+};
 /**
 * Collect all hyperlinks that have an href but no rId from block content.
 * These are newly created hyperlinks that need relationship entries.
 */
 function collectHyperlinksWithoutRId(blocks) {
 	const hyperlinks = [];
-	for (const block of blocks) if (block.type === "paragraph") {
-		for (const item of block.content) if (item.type === "hyperlink" && item.href && !item.rId && !item.anchor) hyperlinks.push(item);
-	} else if (block.type === "table") for (const row of block.rows) for (const cell of row.cells) hyperlinks.push(...collectHyperlinksWithoutRId(cell.content));
+	const collectInlineHyperlinks = (content) => {
+		for (const item of content) switch (item.type) {
+			case "hyperlink":
+				if (item.href && !item.rId && !item.anchor) hyperlinks.push(item);
+				break;
+			case "simpleField":
+			case "inlineSdt":
+			case "insertion":
+			case "deletion":
+			case "moveFrom":
+			case "moveTo":
+				collectInlineHyperlinks(item.content);
+				break;
+			default: break;
+		}
+	};
+	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 hyperlinks.push(...collectHyperlinksWithoutRId(block.content));
 	return hyperlinks;
 }
+/** The selective save boundary must use the same resource census as full repack. */
+const hasUnmaterializedInlineResources = (blocks) => collectNewImages(blocks).length > 0 || collectHyperlinksWithoutRId(blocks).length > 0;
 /**
 * Process newly created hyperlinks in every part: assign rIds and add
 * relationship entries to the owning part's rels. Mutates the hyperlinks' rId
@@ -512,15 +562,42 @@ const cloneDocxZip = (source) => {
 	clone.files = { ...source.files };
 	return clone;
 };
-const finishRepack = async ({ document, originalZip, outputZip, originalDocumentXml, originalCorePropertiesXml, compressionLevel, updateModifiedDate, modifiedBy, changedNoteParaIds, sectionEndpointRemoval }) => {
+const normalizeExportDrawingIds = ({ package: docxPackage }) => {
+	normalizeDrawingIds({
+		documentBody: docxPackage.document,
+		...docxPackage.headers !== void 0 ? { headers: docxPackage.headers } : {},
+		...docxPackage.footers !== void 0 ? { footers: docxPackage.footers } : {},
+		...docxPackage.footnotes !== void 0 ? { footnotes: docxPackage.footnotes } : {},
+		...docxPackage.endnotes !== void 0 ? { endnotes: docxPackage.endnotes } : {}
+	});
+};
+const finishRepack = async ({ document, originalZip, outputZip, originalDocumentXml, originalCorePropertiesXml, compressionLevel, updateModifiedDate, modifiedBy, changedNoteParaIds, sectionEndpointRemoval, sectionReferenceRemovals }) => {
 	await materializeNewHeaderFooterParts(document, outputZip, compressionLevel);
+	await materializeEmbeddedMedia({
+		document,
+		zip: outputZip,
+		compressionLevel
+	});
 	const parts = collectDocxParts(document, outputZip);
+	normalizeExportDrawingIds(document);
 	await processNewImages(parts, outputZip, compressionLevel);
 	await processNewHyperlinks(parts, outputZip, compressionLevel);
 	assertValidFolioDocumentModel(document, "Cannot repack invalid DOCX document model");
 	applyReplyThreadMarkers(document);
 	const documentXml = serializeDocument(document, originalDocumentXml === void 0 ? void 0 : readRootNamespaceBindings(originalDocumentXml));
-	if (originalDocumentXml) assertDocumentPackageFidelity(originalDocumentXml, documentXml, document, sectionEndpointRemoval);
+	if (originalDocumentXml) assertDocumentPackageFidelity({
+		originalDocumentXml,
+		serializedDocumentXml: documentXml,
+		doc: document,
+		...sectionEndpointRemoval !== void 0 && { sectionEndpointRemoval },
+		...sectionReferenceRemovals !== void 0 && { sectionReferenceRemovals }
+	});
+	await removeResolvedHeaderFooterParts({
+		document,
+		zip: outputZip,
+		removedReferences: [...sectionReferenceRemovals ?? [], ...sectionEndpointRemoval?.removedReferences ?? []],
+		compressionLevel
+	});
 	outputZip.file("word/document.xml", documentXml, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
@@ -550,7 +627,7 @@ const finishRepack = async ({ document, originalZip, outputZip, originalDocument
 	}
 	return generateDocxZip(outputZip, compressionLevel);
 };
-async function repackDocxWithSectionEndpointRemoval({ document: doc, options, sectionEndpointRemoval }) {
+async function repackDocxWithSectionEndpointRemoval({ document: doc, options, sectionEndpointRemoval, sectionReferenceRemovals }) {
 	if (!doc.originalBuffer) panic("Cannot repack document: no original buffer for round-trip. Use createDocx() for new documents.");
 	const { compressionLevel = 6, updateModifiedDate = true, modifiedBy, changedNoteParaIds } = options;
 	const exportDocument = withoutOrphanCommentRanges(doc);
@@ -568,15 +645,18 @@ async function repackDocxWithSectionEndpointRemoval({ document: doc, options, se
 		updateModifiedDate,
 		...modifiedBy !== void 0 ? { modifiedBy } : {},
 		...changedNoteParaIds !== void 0 ? { changedNoteParaIds } : {},
-		...sectionEndpointRemoval !== void 0 ? { sectionEndpointRemoval } : {}
+		...sectionEndpointRemoval !== void 0 ? { sectionEndpointRemoval } : {},
+		...sectionReferenceRemovals !== void 0 ? { sectionReferenceRemovals } : {}
 	});
 }
 function repackDocx(doc, options = {}) {
 	const sectionEndpointRemoval = consumeTrackedSectionEndpointRemoval(doc);
+	const sectionReferenceRemovals = consumeSectionReferenceResolution(doc);
 	return repackDocxWithSectionEndpointRemoval({
 		document: doc,
 		options,
-		...sectionEndpointRemoval ? { sectionEndpointRemoval } : {}
+		...sectionEndpointRemoval ? { sectionEndpointRemoval } : {},
+		sectionReferenceRemovals
 	});
 }
 /**
@@ -604,13 +684,23 @@ async function repackDocxFromRaw(doc, rawContent, options = {}) {
 		});
 	}
 	await materializeNewHeaderFooterParts(exportDocument, newZip, compressionLevel);
+	await materializeEmbeddedMedia({
+		document: exportDocument,
+		zip: newZip,
+		compressionLevel
+	});
 	const parts = collectDocxParts(exportDocument, newZip);
+	normalizeExportDrawingIds(exportDocument);
 	await processNewImages(parts, newZip, compressionLevel);
 	await processNewHyperlinks(parts, newZip, compressionLevel);
 	assertValidFolioDocumentModel(exportDocument, "Cannot repack invalid DOCX document model");
 	applyReplyThreadMarkers(exportDocument);
 	const documentXml = serializeDocument(exportDocument, rawContent.documentXml ? readRootNamespaceBindings(rawContent.documentXml) : void 0);
-	if (rawContent.documentXml) assertDocumentPackageFidelity(rawContent.documentXml, documentXml, exportDocument);
+	if (rawContent.documentXml) assertDocumentPackageFidelity({
+		originalDocumentXml: rawContent.documentXml,
+		serializedDocumentXml: documentXml,
+		doc: exportDocument
+	});
 	newZip.file("word/document.xml", documentXml, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
@@ -1056,9 +1146,8 @@ function hasModelDrivenPictureWatermark(doc) {
 * by coverage) carries the source header's rId, which is meaningless in a
 * sibling header's `word/_rels/header*.xml.rels`. Per header: keep the rId if
 * it already resolves; otherwise reuse an existing relationship to the same
-* media target, or mint a new one. The media bytes are shared (preserved from
-* the source), so no new media part is written. Raw-replay watermarks are
-* byte-exact and skipped.
+* media target, or mint a new one. Media bytes are materialized before this step. Raw watermark XML
+* changes only when its image relationship must be rebound.
 */
 async function rebindWatermarkRelIds(doc, zip, compressionLevel) {
 	const rels = doc.package.relationships;
@@ -1067,11 +1156,12 @@ async function rebindWatermarkRelIds(doc, zip, compressionLevel) {
 	const pending = [];
 	for (const [rId, hf] of headers) {
 		const watermark = hf.watermark;
-		if (!watermark || watermark.kind !== "picture" || hf.rawWatermarkXml) continue;
+		if (!watermark || watermark.kind !== "picture") continue;
 		const rel = rels.get(rId);
 		if (!rel?.target) continue;
 		pending.push({
 			watermark,
+			header: hf,
 			relsPath: headerFooterRelsPath(rel.target),
 			partPath: headerFooterFilename(rel.target)
 		});
@@ -1099,7 +1189,7 @@ async function rebindWatermarkRelIds(doc, zip, compressionLevel) {
 		}
 	};
 	const changedPaths = /* @__PURE__ */ new Set();
-	for (const { watermark, relsPath, partPath } of pending) {
+	for (const { watermark, header, relsPath, partPath } of pending) {
 		let canonical;
 		if (watermark.imageTarget !== void 0) if (watermark.imageTargetExternal) canonical = isAllowedExternalWatermarkImageUrl(watermark.imageTarget) ? {
 			mode: "external",
@@ -1129,6 +1219,11 @@ async function rebindWatermarkRelIds(doc, zip, compressionLevel) {
 			relsXmlByPath.set(relsPath, relsXml.replace("</Relationships>", `${relXml}</Relationships>`));
 			changedPaths.add(relsPath);
 		}
+		if (header.rawWatermarkXml && watermark.imageRId !== resolvedRId) header.rawWatermarkXml = rebindDrawingImageRelationship({
+			xml: header.rawWatermarkXml,
+			previousId: watermark.imageRId,
+			nextId: resolvedRId
+		}) ?? panic("A watermark lost its embedded image relationship");
 		watermark.imageRId = resolvedRId;
 	}
 	const compressionOptions = { level: compressionLevel };
@@ -1257,7 +1352,17 @@ async function serializeNumberingIntoZip(doc, originalZip, newZip, compressionLe
 	const numbering = doc.package.numbering;
 	if (!numbering || numbering.abstractNums.length === 0 && numbering.nums.length === 0) return;
 	const file = findNotePartEntry(originalZip, "word/numbering.xml");
-	if (!file) return;
+	if (!file) {
+		await materializeNewNotePart({
+			contentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml",
+			newZip,
+			partPath: "word/numbering.xml",
+			relationshipType: RELATIONSHIP_TYPES.numbering,
+			serializedPart: serializeNumberingXml(numbering),
+			compressionLevel
+		});
+		return;
+	}
 	let baseline = doc.originalBuffer ? numberingBaselines.get(doc) : void 0;
 	if (!baseline || baseline.originalBuffer !== doc.originalBuffer) {
 		const originalXml = await file.async("text");
@@ -1269,15 +1374,12 @@ async function serializeNumberingIntoZip(doc, originalZip, newZip, compressionLe
 		if (doc.originalBuffer) numberingBaselines.set(doc, baseline);
 	}
 	const currentXml = serializeNumberingXml(numbering);
-	const changed = collectChangedNumberingDefs(baseline.serializedXml, currentXml);
-	const added = collectAddedNumberingDefs(baseline.serializedXml, currentXml);
-	const hasChanged = changed.abstractNums.size > 0 || changed.nums.size > 0;
-	const hasAdded = added.abstractNums.size > 0 || added.nums.size > 0;
-	if (!hasChanged && !hasAdded) return;
-	const spliced = buildPatchedNumberingXml(baseline.originalXml, currentXml, changed);
-	if (spliced === null) return;
-	const patched = appendNumberingDefs(spliced, currentXml, added);
-	if (patched === null) return;
+	const patched = patchNumberingDefinitions({
+		originalXml: baseline.originalXml,
+		baselineXml: baseline.serializedXml,
+		currentXml
+	});
+	if (patched === null || patched === baseline.originalXml) return;
 	newZip.file(file.name, patched, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
@@ -1584,4 +1686,4 @@ const assertStyleNumberingReferences = (doc) => {
 	for (const numbering of doc.package.numbering?.nums ?? []) if (!availableAbstract.has(numbering.abstractNumId)) panic(`Numbering definition ${numbering.numId} references missing abstract numbering`);
 };
 //#endregion
-export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocxPackageFidelityError, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, isDocxBuffer, notePartRelsPath, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };
+export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocxPackageFidelityError, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, isDocxBuffer, notePartRelsPath, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };

package/dist/docx/runParser.js

@@ -2,6 +2,7 @@ import { isValidHexColor } from "../utils/colorResolver.js";
 import { parseHorizontalScalePercent } from "../utils/horizontalScale.js";
 import { parseGroupDrawing } from "./groupDrawingParser.js";
 import { parseImage } from "./imageParser.js";
+import { imageRawXmlFingerprint } from "./imageRawXml.js";
 import { EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, ShadingPatternSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
 import { parseShapeFromDrawing, shouldPreserveRawShapeDrawing } from "./shapeParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
@@ -10,7 +11,7 @@ import { resolveThemeFontRef } from "./themeParser.js";
 import { parsePropertyChangeInfo } from "./trackedChangeInfo.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { parseVmlImageContent } from "./vmlImageParser.js";
-import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute } from "./xmlParser.js";
+import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, selectAlternateContentBranch } from "./xmlParser.js";
 import { DRAWING_RAW_XML_MODES } from "@stll/docx-core/model";
 //#region src/docx/runParser.ts
 /**
@@ -76,6 +77,9 @@ function collectFirstRunPropertyChildren(rPr) {
 			case "color":
 				children.color ??= child;
 				break;
+			case "noProof":
+				children.noProof ??= child;
+				break;
 			case "cs":
 				children.cs ??= child;
 				break;
@@ -215,6 +219,8 @@ function parseRunProperties(rPr, theme, _styles) {
 	if (caps) formatting.allCaps = parseBooleanElement(caps);
 	const vanish = propertyChildren.vanish;
 	if (vanish) formatting.hidden = parseBooleanElement(vanish);
+	const noProof = propertyChildren.noProof;
+	if (noProof) formatting.noProof = parseBooleanElement(noProof);
 	const color = propertyChildren.color;
 	if (color) formatting.color = parseColorValue(getAttribute(color, "w", "val"), getAttribute(color, "w", "themeColor"), getAttribute(color, "w", "themeTint"), getAttribute(color, "w", "themeShade"));
 	const highlight = propertyChildren.highlight;
@@ -479,7 +485,8 @@ function parseDrawingContent(element, rels, media) {
 	if (groupImage) return {
 		type: "drawing",
 		image: groupImage,
-		rawXml: captureVerbatimXml(element)
+		rawXml: captureVerbatimXml(element),
+		rawImageFingerprint: imageRawXmlFingerprint(groupImage)
 	};
 	if (shouldPreserveRawShapeDrawing(element)) return {
 		type: "drawing",
@@ -506,7 +513,8 @@ function parseDrawingContent(element, rels, media) {
 		type: "drawing",
 		image
 	};
-	if (!image.src) drawing.rawXml = captureVerbatimXml(element);
+	drawing.rawXml = captureVerbatimXml(element);
+	drawing.rawImageFingerprint = imageRawXmlFingerprint(image);
 	return drawing;
 }
 /**
@@ -595,7 +603,7 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 				contents.push(fallbackVml);
 				break;
 			}
-			const targetEl = choiceEl ?? fallbackEl;
+			const targetEl = selectAlternateContentBranch(child);
 			if (targetEl) for (const innerChild of getChildElements(targetEl)) {
 				const innerName = getLocalName(innerChild.name);
 				if (innerName === "drawing") {
@@ -610,7 +618,10 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 						innerVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
 						contents.push(innerVml);
 					}
-				}
+				} else contents.push(...parseRunContents({
+					...targetEl,
+					elements: [innerChild]
+				}, rels, media, rootXmlns));
 			}
 			break;
 		}

package/dist/docx/sectionParser.js

@@ -1,6 +1,7 @@
 import { parseFooterReference, parseHeaderReference } from "./headerFooterRefParser.js";
 import { parseEndnoteProperties, parseFootnoteProperties } from "./notePropertiesParser.js";
 import { BorderStyleSchema, NumberFormatSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
+import { parseSectionReferenceHistory } from "./sectionReferenceHistory.js";
 import { parsePropertyChangeInfo } from "./trackedChangeInfo.js";
 import { findChild, findChildren, getAttribute, getChildElements, getLocalName, parseBooleanElement, parseNumericAttribute } from "./xmlParser.js";
 //#region src/docx/sectionParser.ts
@@ -348,6 +349,8 @@ function parseSectionProperties(sectPr) {
 			info: parsePropertyChangeInfo(changeElement)
 		};
 		if (previousSectPr) change.previousProperties = parseSectionProperties(previousSectPr);
+		const previousReferences = parseSectionReferenceHistory(changeElement);
+		if (previousReferences !== void 0) change.previousReferences = previousReferences;
 		return change;
 	});
 	if (propertyChanges.length > 0) props.propertyChanges = propertyChanges;

package/dist/docx/sectionReferenceHistory.d.ts

@@ -0,0 +1,17 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/sectionReferenceHistory.d.ts
+type PreviousReferences = NonNullable<document_d_exports.SectionPropertyChange["previousReferences"]>;
+declare const InvalidSectionReferenceHistoryError_base: import("better-result").TaggedErrorClass<"InvalidSectionReferenceHistoryError">;
+declare class InvalidSectionReferenceHistoryError extends InvalidSectionReferenceHistoryError_base<{
+  message: string;
+}> {}
+declare const parseSectionReferenceHistory: (change: XmlElement) => PreviousReferences | undefined;
+declare const serializeSectionReferenceHistory: (references: PreviousReferences | undefined) => string;
+declare const sectionReferenceSelection: (properties: document_d_exports.SectionProperties) => PreviousReferences;
+declare const sectionReferenceHistory: ({ previous, target }: {
+  previous: document_d_exports.SectionProperties;
+  target: document_d_exports.SectionProperties;
+}) => PreviousReferences | undefined;
+//#endregion
+export { InvalidSectionReferenceHistoryError, parseSectionReferenceHistory, sectionReferenceHistory, sectionReferenceSelection, serializeSectionReferenceHistory };

package/dist/docx/sectionReferenceHistory.js

@@ -0,0 +1,59 @@
+import { canonicalJson } from "../utils/canonicalJson.js";
+import { escapeXml } from "./serializer/xmlUtils.js";
+import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, findChildrenByNamespaceUri, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri } from "./xmlParser.js";
+import { TaggedError } from "better-result";
+//#region src/docx/sectionReferenceHistory.ts
+const SECTION_REFERENCE_HISTORY_NAMESPACE = "urn:stella:folio:section-reference-history:1";
+const HISTORY_NAMESPACES = /* @__PURE__ */ new Set([SECTION_REFERENCE_HISTORY_NAMESPACE]);
+var InvalidSectionReferenceHistoryError = class extends TaggedError("InvalidSectionReferenceHistoryError") {};
+const invalidHistory = () => {
+	throw new InvalidSectionReferenceHistoryError({ message: "Invalid section reference revision history." });
+};
+const parseSectionReferenceHistory = (change) => {
+	const histories = findChildrenByNamespaceUri(change, HISTORY_NAMESPACES, "previousReferences");
+	const history = histories.at(0);
+	if (!history) return void 0;
+	if (histories.length !== 1) return invalidHistory();
+	const headers = [];
+	const footers = [];
+	for (const child of getChildElements(history)) {
+		if (!WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "")) return invalidHistory();
+		const name = getLocalName(child.name);
+		if (name !== "headerReference" && name !== "footerReference") return invalidHistory();
+		const type = getAttributeByNamespaceUri(child, WORDPROCESSINGML_NAMESPACE_URIS, "type");
+		const rId = getAttributeByNamespaceUri(child, OFFICE_RELATIONSHIP_NAMESPACE_URIS, "id");
+		if (type !== "default" && type !== "first" && type !== "even" || !rId || rId.trim() !== rId) return invalidHistory();
+		const references = name === "headerReference" ? headers : footers;
+		if (references.some((reference) => reference.type === type)) return invalidHistory();
+		references.push({
+			type,
+			rId
+		});
+	}
+	return {
+		...headers.length > 0 && { headerReferences: headers },
+		...footers.length > 0 && { footerReferences: footers }
+	};
+};
+const serializeSectionReferenceHistory = (references) => {
+	if (references === void 0) return "";
+	const serializeReferences = (kind, values) => {
+		if (new Set(values.map(({ type }) => type)).size !== values.length) return invalidHistory();
+		return values.map(({ type, rId }) => {
+			if (!rId || rId.trim() !== rId) return invalidHistory();
+			return `<w:${kind}Reference w:type="${type}" r:id="${escapeXml(rId)}"/>`;
+		}).join("");
+	};
+	const content = serializeReferences("header", references.headerReferences ?? []) + serializeReferences("footer", references.footerReferences ?? []);
+	return `<frh:previousReferences xmlns:frh="${SECTION_REFERENCE_HISTORY_NAMESPACE}" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" mc:Ignorable="frh" mc:PreserveElements="frh:previousReferences">${content}</frh:previousReferences>`;
+};
+const sectionReferenceSelection = (properties) => ({
+	...properties.headerReferences !== void 0 && { headerReferences: properties.headerReferences },
+	...properties.footerReferences !== void 0 && { footerReferences: properties.footerReferences }
+});
+const sectionReferenceHistory = ({ previous, target }) => {
+	const before = sectionReferenceSelection(previous);
+	return canonicalJson(before) === canonicalJson(sectionReferenceSelection(target)) ? void 0 : before;
+};
+//#endregion
+export { InvalidSectionReferenceHistoryError, parseSectionReferenceHistory, sectionReferenceHistory, sectionReferenceSelection, serializeSectionReferenceHistory };