@stll/folio-core 0.54.2 → 0.56.0

package/dist/docx/selectiveSave.js

@@ -7,7 +7,7 @@ import { parseNumbering } from "./numberingParser.js";
 import { normalizeImportedNumericIds } from "./numericIdNormalization.js";
 import { isUnsafePackagePath } from "./packageParts.js";
 import { RELATIONSHIP_TYPES } from "./relsParser.js";
-import { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_PART_LOWER, addCommentsExtendedOverride, addCommentsExtendedRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, updateCoreProperties, withoutAttachedTemplate } from "./rezip.js";
+import { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_PART_LOWER, addCommentsExtendedOverride, addCommentsExtendedRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedHyperlinkBindings, hasUnmaterializedInlineResources, planAddedStyles, publishCanonicalImageResources, updateCoreProperties, withoutAttachedTemplate } from "./rezip.js";
 import "./selectiveSaveFlags.js";
 import { buildPatchedDocumentXml, buildPatchedNoteXml, collectAddedNumberingDefs, collectParaIds, patchNumberingDefinitions } from "./selectiveXmlPatch.js";
 import { planCommentParts, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
@@ -17,6 +17,7 @@ import { serializeNumberingXml } from "./serializer/numberingSerializer.js";
 import { readRootNamespaceBindings } from "./serializer/partNamespaces.js";
 import { buildStructuralDocumentPatch } from "./structuralXmlPatch.js";
 import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
+import { writeZipPart } from "@stll/docx-core/zip";
 //#region src/docx/selectiveSave.ts
 /**
 * Splice edited footnote/endnote paragraphs into their parts and return the
@@ -203,6 +204,7 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 	const commentPlan = planCommentParts(comments);
 	try {
 		const zip = await (await import("jszip")).default.loadAsync(originalBuffer);
+		if (await hasUnmaterializedHyperlinkBindings(doc, zip)) return null;
 		for (const [path, file] of Object.entries(zip.files)) if (!file.dir && isUnsafePackagePath(path)) return null;
 		if (originalBuffer !== doc.originalBuffer) {
 			const sourceParts = /* @__PURE__ */ new Map();
@@ -211,14 +213,27 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 				if (file.dir || !lowerPath.startsWith("word/") || !lowerPath.endsWith(".xml")) continue;
 				sourceParts.set(path, await file.async("text"));
 			}
-			for (const [path, xml] of normalizeImportedNumericIds(sourceParts)) if (xml !== sourceParts.get(path)) zip.file(path, xml);
+			for (const [path, xml] of normalizeImportedNumericIds(sourceParts)) if (xml !== sourceParts.get(path)) writeZipPart({
+				zip,
+				path,
+				data: xml
+			});
 		}
+		if (options.bodyAuthority === "canonical") await publishCanonicalImageResources({
+			document: doc,
+			zip,
+			compressionLevel: 6
+		});
 		const updates = /* @__PURE__ */ new Map();
 		if (changedParaIds.size > 0 || structuralChange) {
 			const docXmlFile = zip.file("word/document.xml");
 			if (!docXmlFile) return null;
 			const originalDocXml = await docXmlFile.async("text");
-			const serializedDocXml = serializeDocument(doc, readRootNamespaceBindings(originalDocXml));
+			const serializedDocXml = serializeDocument(doc, readRootNamespaceBindings(originalDocXml), {
+				xml: originalDocXml,
+				bodyAuthority: options.bodyAuthority,
+				onDiagnostic: options.onDiagnostic
+			});
 			const bodyParaIds = collectParaIds(serializedDocXml);
 			const originalBodyParaIds = structuralChange ? collectParaIds(originalDocXml) : void 0;
 			if (structuralChange && doc.package.numbering) {
@@ -268,7 +283,24 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 		}
 		if (!await patchCommentsExtended(zip, commentPlan, updates)) return null;
 		if (!await patchNumberingPart(zip, doc, updates)) return null;
-		for (const [path, xml] of await collectHeaderFooterUpdates(doc, zip)) updates.set(path, xml);
+		const styles = await planAddedStyles(doc, zip);
+		switch (styles.type) {
+			case "unchanged": break;
+			case "patch":
+				updates.set(styles.path, styles.xml);
+				break;
+			case "materialize":
+				options.onDiagnostic?.({
+					type: "selectiveSaveRefused",
+					part: "word/styles.xml"
+				});
+				return null;
+			default: return styles;
+		}
+		for (const [path, xml] of await collectHeaderFooterUpdates(doc, {
+			sourceZip: zip,
+			onDiagnostic: options.onDiagnostic
+		})) updates.set(path, xml);
 		await queueSettingsUpdates(zip, updates);
 		const corePropsFile = zip.file("docProps/core.xml");
 		if (corePropsFile) {

package/dist/docx/selectiveXmlPatch.d.ts

@@ -1,11 +1,5 @@
+import { XmlElement } from "./xmlParser.js";
 //#region src/docx/selectiveXmlPatch.d.ts
-/**
- * Selective XML Patch Module
- *
- * Patches only changed paragraphs in document.xml, preserving
- * unchanged content byte-for-byte. Uses string offset tracking
- * with proper tag depth counting (not regex) to handle nested elements.
- */
 /**
  * Whether `char` ends an element's tag name in XML — a whitespace separator
  * (space, tab, CR, or LF, all valid before attributes per XML 1.0 §3.1), the
@@ -170,6 +164,20 @@ type XmlSplice = {
  * end, so its original offsets cannot be applied to the resulting string.
  */
 declare const spliceXml: (xml: string, splices: readonly XmlSplice[]) => string | null;
+/**
+ * A paragraph splice cannot change the owning part's root declarations. Refuse
+ * fragments that inherit a prefix from the serialized root when the source
+ * root does not bind that prefix to the same URI; the caller can then use the
+ * full serializer, which owns the root namespace set.
+ */
+type SpliceNamespaceOptions = {
+  originalXml: string;
+  serializedXml: string;
+  fragments: readonly string[];
+  originalRoot?: XmlElement;
+  serializedRoot?: XmlElement;
+};
+declare const spliceSupportsRootNamespaces: ({ originalXml, serializedXml, fragments, originalRoot, serializedRoot }: SpliceNamespaceOptions) => boolean;
 type NoteElementName = "footnote" | "endnote";
 declare const collectChangedNoteParaIds: (baselineXml: string, currentXml: string) => Set<string>;
 type BuildPatchedNotePartXmlOptions = {
@@ -265,4 +273,4 @@ declare const patchNumberingDefinitions: ({ originalXml, baselineXml, currentXml
  */
 declare function appendNumberingDefs(xml: string, currentXml: string, added: ChangedNumberingDefs): string | null;
 //#endregion
-export { ChangedNumberingDefs, NotePartPatch, NotePartPatchRefusal, ParagraphContainer, ParagraphOffsets, PatchValidationResult, ScannedParagraph, XmlSplice, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, scanParagraphs, spliceXml, validatePatchSafety };
+export { ChangedNumberingDefs, NotePartPatch, NotePartPatchRefusal, ParagraphContainer, ParagraphOffsets, PatchValidationResult, ScannedParagraph, XmlSplice, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, scanParagraphs, spliceSupportsRootNamespaces, spliceXml, validatePatchSafety };

package/dist/docx/selectiveXmlPatch.js

@@ -1,8 +1,10 @@
 import { patchBreaksCommentRangeBalance } from "./commentRangeIntegrity.js";
 import { resolveParagraphIdentities } from "./paraIdAttribute.js";
+import { readRootNamespaceBindings } from "./serializer/partNamespaces.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";
+import { resolveNamespaceUri } from "./xmlNamespaceContext.js";
+import { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, findAttributeByNamespaceUri, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
 //#region src/docx/selectiveXmlPatch.ts
 /**
 * Selective XML Patch Module
@@ -33,7 +35,7 @@ function isXmlNameBoundary(char) {
 */
 function findParagraphOffsets(xml, paraId) {
 	const escaped = escapeRegExp(paraId);
-	const pattern = new RegExp(`<w:p[\\s][^>]*w14:paraId="${escaped}"`, "gu");
+	const pattern = new RegExp(`<w:p[\\s][^>]*w14:paraId\\s*=\\s*(["'])${escaped}\\1`, "gu");
 	const matches = [];
 	let match;
 	while ((match = pattern.exec(xml)) !== null) matches.push(match.index);
@@ -189,7 +191,7 @@ function scanParagraphs(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"];
+		const paraId = /\bw14:paraId\s*=\s*(?<quote>["'])(?<id>[^"']+)\k<quote>/u.exec(openTag)?.groups?.["id"];
 		const container = {
 			inFallback: depth.fallback > 0,
 			inAlternateContent: depth.alternateContent > 0,
@@ -234,7 +236,7 @@ function countParagraphElements(xml) {
 */
 function collectParaIds(xml) {
 	const ids = /* @__PURE__ */ new Map();
-	const pattern = /w14:paraId="(?<id>[^"]+)"/gu;
+	const pattern = /w14:paraId\s*=\s*(?<quote>["'])(?<id>[^"']+)\k<quote>/gu;
 	let match;
 	while ((match = pattern.exec(xml)) !== null) {
 		const id = match.groups["id"];
@@ -243,7 +245,7 @@ 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;
+const MINTED_PARA_ID_ATTRIBUTE = /\sw14:(paraId|textId)="[^"]*"/gu;
 /**
 * The replacement for a paragraph whose source open tag carries no paraId.
 *
@@ -260,7 +262,9 @@ const MINTED_PARA_ID_ATTRIBUTE = /\sw14:(?:para|text)Id="[^"]*"/gu;
 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);
+	return paragraphXml.slice(0, tagEnd + 1).replace(MINTED_PARA_ID_ATTRIBUTE, (attribute, name) => {
+		return new RegExp(`\\bw14:${name}\\s*=\\s*(["'])[^"']*\\1`, "u").test(sourceOpenTag) ? attribute : "";
+	}) + paragraphXml.slice(tagEnd + 1);
 };
 const storyOf = ({ textBoxDepth }) => textBoxDepth > 0 ? "text-box" : "main";
 const sameContainer = (a, b) => a.inAlternateContent === b.inAlternateContent && a.textBoxDepth === b.textBoxDepth && a.tableDepth === b.tableDepth;
@@ -425,6 +429,14 @@ const routeChangedParagraphs = (originalXml, serializedXml, changedIds) => {
 			newXml: authored ? newXml : withoutMintedIds(newXml, sourceXml)
 		});
 	}
+	if (!spliceSupportsRootNamespaces({
+		originalXml,
+		serializedXml,
+		fragments: splices.map(({ newXml }) => newXml)
+	})) return {
+		type: "refused",
+		reason: "root-namespace-requirements-changed"
+	};
 	const candidate = spliceXml(originalXml, splices);
 	if (candidate === null) return {
 		type: "refused",
@@ -514,6 +526,68 @@ const spliceXml = (xml, splices) => {
 	}
 	return patchBreaksCommentRangeBalance(xml, result) ? null : result;
 };
+const spliceSupportsRootNamespaces = ({ originalXml, serializedXml, fragments, originalRoot, serializedRoot }) => {
+	const original = originalRoot ?? parseXmlDocument(originalXml);
+	const serialized = serializedRoot ?? parseXmlDocument(serializedXml);
+	if (!original || !serialized) return false;
+	const originalBindings = readRootNamespaceBindings(originalXml);
+	const serializedBindings = readRootNamespaceBindings(serializedXml);
+	const mcNamespace = /* @__PURE__ */ new Set([NAMESPACES.mc]);
+	const ignorableUris = (root) => {
+		const uris = /* @__PURE__ */ new Set();
+		for (const prefix of (getAttributeByNamespaceUri(root, mcNamespace, "Ignorable") ?? "").split(/\s+/u).filter(Boolean)) {
+			const uri = resolveNamespaceUri(root.namespaceScope, prefix);
+			if (uri) uris.add(uri);
+		}
+		return uris;
+	};
+	const originalNamespaceUses = /* @__PURE__ */ new Set();
+	const collectSourceNamespaces = (element) => {
+		const uri = getNamespaceUri(element);
+		if (uri) originalNamespaceUses.add(uri);
+		for (const attribute of Object.keys(element.attributes ?? {})) {
+			if (attribute === "xmlns" || attribute.startsWith("xmlns:")) continue;
+			const prefix = getNamespacePrefix(attribute);
+			const attributeUri = prefix ? resolveNamespaceUri(element.namespaceScope, prefix) : void 0;
+			if (attributeUri) originalNamespaceUses.add(attributeUri);
+		}
+		for (const child of element.elements ?? []) collectSourceNamespaces(child);
+	};
+	collectSourceNamespaces(original);
+	const originalIgnorable = ignorableUris(original);
+	const serializedIgnorable = ignorableUris(serialized);
+	const inheritedPrefixes = /* @__PURE__ */ new Set();
+	const visit = (element, ancestorIgnorableUris) => {
+		const localIgnorableUris = new Set(ancestorIgnorableUris);
+		for (const uri of ignorableUris(element)) localIgnorableUris.add(uri);
+		const requirePrefix = (prefix) => {
+			const localUri = resolveNamespaceUri(element.namespaceScope, prefix);
+			if (!localUri) inheritedPrefixes.add(prefix);
+			const uri = localUri ?? serializedBindings.get(prefix);
+			if (!uri) return false;
+			return !serializedIgnorable.has(uri) || originalNamespaceUses.has(uri) || originalIgnorable.has(uri) || localIgnorableUris.has(uri);
+		};
+		const namePrefix = element.name?.split(":").at(0);
+		if (namePrefix && namePrefix !== element.name && !requirePrefix(namePrefix)) return false;
+		for (const attribute of Object.keys(element.attributes ?? {})) {
+			if (attribute === "xmlns" || attribute.startsWith("xmlns:")) continue;
+			const prefix = attribute.split(":").at(0);
+			if (prefix && prefix !== attribute && !requirePrefix(prefix)) return false;
+		}
+		for (const child of element.elements ?? []) if (!visit(child, localIgnorableUris)) return false;
+		return true;
+	};
+	for (const fragment of fragments) {
+		const parsed = parseXmlDocument(fragment);
+		if (!parsed) return false;
+		if (!visit(parsed, /* @__PURE__ */ new Set())) return false;
+	}
+	for (const prefix of inheritedPrefixes) {
+		const serializedUri = serializedBindings.get(prefix);
+		if (serializedUri === void 0 || originalBindings.get(prefix) !== serializedUri) return false;
+	}
+	return true;
+};
 /**
 * Depth-count the end of the element that opens at `start` (an `<openLiteral…>`
 * offset), returning its full range. Nested same-name opens increment depth;
@@ -1269,4 +1343,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, scanParagraphs, spliceXml, validatePatchSafety };
+export { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, scanParagraphs, spliceSupportsRootNamespaces, spliceXml, validatePatchSafety };

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

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../../types/document.js";
+import { SaveDiagnosticOptions } from "../saveDiagnostics.js";
 //#region src/docx/serializer/documentSerializer.d.ts
 /**
  * Serialize a DocumentBody to document.xml body content
@@ -15,7 +16,13 @@ declare function serializeDocumentBody(body: document_d_exports.DocumentBody): s
  *   prefix only the source document bound keeps its URI
  * @returns Complete XML string for document.xml
  */
-declare function serializeDocument(doc: document_d_exports.Document, sourceBindings?: ReadonlyMap<string, string>): string;
+type DocumentBodyAuthorityOptions = {
+  /** Canonical saves preserve trusted source blocks; default saves serialize the model. */
+  bodyAuthority?: "canonical" | "model" | undefined;
+};
+declare function serializeDocument(doc: document_d_exports.Document, sourceBindings?: ReadonlyMap<string, string>, source?: SaveDiagnosticOptions & DocumentBodyAuthorityOptions & {
+  xml?: string | undefined;
+}): string;
 /**
  * Serialize just the document body (useful for partial updates)
  *
@@ -59,4 +66,4 @@ declare function createSimpleDocument(paragraphs: {
   styleId?: string;
 }[]): document_d_exports.Document;
 //#endregion
-export { createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };
+export { DocumentBodyAuthorityOptions, createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };

package/dist/docx/serializer/documentSerializer.js

@@ -1,3 +1,5 @@
+import { getDocumentSourceBaseline } from "../headerFooterVerbatim.js";
+import { buildDocumentBlockReplay, canReplayDocumentSource } from "../storyBlockReplay.js";
 import { serializeBlockCustomXml } from "./blockCustomXmlSerializer.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeBookmarkMarker } from "./markupRangeAttributes.js";
@@ -84,24 +86,41 @@ function serializeDocumentBody(body) {
 	if (body.finalSectionProperties) parts.push(serializeSectionProperties(body.finalSectionProperties));
 	return parts.join("");
 }
-/**
-* Serialize a complete Document to valid document.xml
-*
-* @param doc - The document to serialize
-* @param sourceBindings - Root `xmlns:*` of the part being replaced, so a
-*   prefix only the source document bound keeps its URI
-* @returns Complete XML string for document.xml
-*/
-function serializeDocument(doc, sourceBindings) {
+const replayableDocumentSources = /* @__PURE__ */ new WeakMap();
+function serializeDocument(doc, sourceBindings, source) {
 	resetAutoIdCounter();
+	const baseline = source?.bodyAuthority === "canonical" ? getDocumentSourceBaseline(doc) : { type: "missing" };
+	const sourceMatches = baseline.type === "captured" && (source?.xml === void 0 || source.xml === baseline.xml);
+	if (baseline.type === "captured" && sourceMatches && JSON.stringify(doc.package.document) === baseline.fingerprint) {
+		if (replayableDocumentSources.get(baseline.body) === baseline.xml) return baseline.xml;
+		if (canReplayDocumentSource(baseline.xml, baseline.body)) {
+			replayableDocumentSources.set(baseline.body, baseline.xml);
+			return baseline.xml;
+		}
+	}
 	const body = serializeDocumentBackground(doc.package.document.background) + `<w:body>${serializeDocumentBody(doc.package.document)}</w:body>`;
-	return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>" + serializePartElement({
+	const serializedXml = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>" + serializePartElement({
 		partPath: "word/document.xml",
 		rootName: "w:document",
 		baselinePrefixes: DOCUMENT_BASELINE_PREFIXES,
 		sourceBindings,
 		body
 	});
+	if (baseline.type === "missing") return serializedXml;
+	if (baseline.type === "captured" && sourceMatches) {
+		const replay = buildDocumentBlockReplay({
+			sourceXml: baseline.xml,
+			baseline: baseline.body,
+			current: doc.package.document,
+			serializedXml
+		});
+		if (replay !== null) return replay;
+	}
+	source?.onDiagnostic?.({
+		type: "sourceReplayMismatch",
+		part: "word/document.xml"
+	});
+	return serializedXml;
 }
 /**
 * Serialize just the document body (useful for partial updates)

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

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../../types/document.js";
+import { SaveDiagnosticOptions } from "../saveDiagnostics.js";
 import { SourcePart } from "./partNamespaces.js";
 //#region src/docx/serializer/headerFooterSerializer.d.ts
 /**
@@ -9,6 +10,9 @@ import { SourcePart } from "./partNamespaces.js";
  *   document bound keeps its URI
  * @returns Complete XML string for header*.xml or footer*.xml
  */
-declare function serializeHeaderFooter(hf: document_d_exports.HeaderFooter, source?: SourcePart): string;
+type HeaderFooterSerializeOptions = SourcePart & SaveDiagnosticOptions & {
+  originalBuffer?: ArrayBuffer | undefined;
+};
+declare function serializeHeaderFooter(hf: document_d_exports.HeaderFooter, source?: HeaderFooterSerializeOptions): string;
 //#endregion
 export { serializeHeaderFooter };

package/dist/docx/serializer/headerFooterSerializer.js

@@ -1,5 +1,6 @@
-import { canReplayHeaderFooterVerbatim, getHeaderFooterVerbatimXml } from "../headerFooterVerbatim.js";
+import { canReplayHeaderFooterBlocks, canReplayHeaderFooterVerbatim, getHeaderFooterSourceBaseline, getHeaderFooterVerbatimXml } from "../headerFooterVerbatim.js";
 import { isEmptyParagraph } from "../paragraphParser.js";
+import { buildStoryBlockReplay } from "../storyBlockReplay.js";
 import { captureVerbatimXml } from "../verbatimCapture.js";
 import { getLocalName, parseXmlDocument } from "../xmlParser.js";
 import { serializeBlockCustomXml } from "./blockCustomXmlSerializer.js";
@@ -49,17 +50,14 @@ function serializeBlock(block) {
 		default: return block;
 	}
 }
-/**
-* Serialize a HeaderFooter object to valid OOXML XML
-*
-* @param hf - HeaderFooter object to serialize
-* @param source - The part being replaced, so a prefix only the source
-*   document bound keeps its URI
-* @returns Complete XML string for header*.xml or footer*.xml
-*/
 function serializeHeaderFooter(hf, source) {
+	const baseline = getHeaderFooterSourceBaseline(hf, source?.originalBuffer);
+	if (baseline.type === "mismatch") source?.onDiagnostic?.({
+		type: "sourceReplayMismatch",
+		part: source.path
+	});
 	const verbatim = getHeaderFooterVerbatimXml(hf);
-	if (verbatim && canReplayHeaderFooterVerbatim(hf)) return verbatim;
+	if (baseline.type === "captured" && verbatim && canReplayHeaderFooterVerbatim(hf)) return verbatim;
 	const rootTag = hf.type === "header" ? "w:hdr" : "w:ftr";
 	const watermarkXml = serializeWatermarkParagraph(hf);
 	const watermarkInsertIndex = hf.watermarkBlockIndex !== void 0 ? Math.max(0, Math.min(hf.watermarkBlockIndex, hf.content.length)) : 0;
@@ -75,13 +73,23 @@ function serializeHeaderFooter(hf, source) {
 		});
 		contentXml = blocksXml.slice(0, watermarkInsertIndex).join("") + (mergesIntoRetainedHost ? "" : watermarkXml) + blocksXml.slice(watermarkInsertIndex).join("");
 	} else contentXml = blocksXml.join("");
-	return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({
+	const serializedXml = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({
 		partPath: source?.path ?? `word/${hf.type}.xml`,
 		rootName: rootTag,
 		baselinePrefixes: HEADER_FOOTER_BASELINE_PREFIXES,
 		sourceBindings: source?.bindings,
 		body: contentXml
 	});
+	if (baseline.type === "captured" && verbatim && canReplayHeaderFooterBlocks(hf, baseline.content)) {
+		const replayed = buildStoryBlockReplay({
+			sourceXml: verbatim,
+			baselineContent: baseline.content,
+			currentContent: hf.content,
+			serializedXml
+		});
+		if (replayed !== null) return replayed;
+	}
+	return serializedXml;
 }
 function serializeRawWatermarkIntoHost({ hostXml, rawWatermarkXml }) {
 	const rawHost = parseXmlDocument(rawWatermarkXml);

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

@@ -16,9 +16,9 @@ declare function serializeFootnotes(footnotes: readonly document_d_exports.Footn
 declare function serializeEndnotes(endnotes: readonly document_d_exports.Endnote[]): string;
 /** Serialize a brand-new footnote part, including Word's required separators
  * and the automatic reference mark at the start of every normal note. */
-declare function serializeNewFootnotesPart(footnotes: readonly document_d_exports.Footnote[]): string;
+declare function serializeNewFootnotesPart(footnotes: readonly document_d_exports.Footnote[], document?: document_d_exports.Document): string;
 /** Serialize a brand-new endnote part, including Word's required separators
  * and the automatic reference mark at the start of every normal note. */
-declare function serializeNewEndnotesPart(endnotes: readonly document_d_exports.Endnote[]): string;
+declare function serializeNewEndnotesPart(endnotes: readonly document_d_exports.Endnote[], document?: document_d_exports.Document): string;
 //#endregion
 export { serializeEndnotes, serializeFootnotes, serializeNewEndnotesPart, serializeNewFootnotesPart };

package/dist/docx/serializer/noteSerializer.js

@@ -1,9 +1,11 @@
+import { hasNoteReferenceMark } from "../noteReferenceMark.js";
 import { serializeBlockCustomXml } from "./blockCustomXmlSerializer.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeBookmarkMarker } from "./markupRangeAttributes.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
 import { serializeTable } from "./tableSerializer.js";
+import { noteUsesCustomMark } from "@stll/docx-core/ops";
 //#region src/docx/serializer/noteSerializer.ts
 const NOTE_BASELINE_PREFIXES = [
 	"wpc",
@@ -66,8 +68,9 @@ const NOTE_SEPARATOR_BODY = "<w:p><w:pPr><w:spacing w:after=\"0\" w:line=\"240\"
 function serializeRequiredNoteSeparators(elementName) {
 	return `<w:${elementName} w:type="separator" w:id="-1">${NOTE_SEPARATOR_BODY}<w:r><w:separator/></w:r></w:p></w:${elementName}><w:${elementName} w:type="continuationSeparator" w:id="0">${NOTE_SEPARATOR_BODY}<w:r><w:continuationSeparator/></w:r></w:p></w:${elementName}>`;
 }
-function insertNoteReferenceMark(xml, elementName) {
-	if (new RegExp(`<(?:[\\w.-]+:)?${elementName}Ref[\\s/>]`, "u").test(xml)) return xml;
+function insertNoteReferenceMark({ xml, elementName, note, customMark }) {
+	if (customMark) return xml;
+	if (hasNoteReferenceMark(elementName, note.content)) return xml;
 	const paragraphOpen = /<w:p(?=[\s>])[^>]*>/u.exec(xml);
 	if (!paragraphOpen) return `${`<w:p><w:r><w:rPr><w:rStyle w:val="${elementName === "footnote" ? "FootnoteReference" : "EndnoteReference"}"/></w:rPr><w:${elementName}Ref/></w:r></w:p>`}${xml}`;
 	const paragraphStart = paragraphOpen.index + paragraphOpen[0].length;
@@ -77,8 +80,13 @@ function insertNoteReferenceMark(xml, elementName) {
 	const referenceRun = `<w:r><w:rPr><w:rStyle w:val="${elementName === "footnote" ? "FootnoteReference" : "EndnoteReference"}"/></w:rPr><w:${elementName}Ref/></w:r>`;
 	return `${xml.slice(0, insertAt)}${referenceRun}${xml.slice(insertAt)}`;
 }
-function serializeNewNotePart(elementName, notes) {
-	const serializedNotes = notes.map((note) => insertNoteReferenceMark(serializeNote(elementName, note), elementName)).join("");
+function serializeNewNotePart({ elementName, notes, document }) {
+	const serializedNotes = notes.map((note) => insertNoteReferenceMark({
+		xml: serializeNote(elementName, note),
+		elementName,
+		note,
+		customMark: document ? noteUsesCustomMark(document, note) : false
+	})).join("");
 	return serializeNotePart(elementName, serializeRequiredNoteSeparators(elementName) + serializedNotes);
 }
 /**
@@ -101,13 +109,21 @@ function serializeEndnotes(endnotes) {
 }
 /** Serialize a brand-new footnote part, including Word's required separators
 * and the automatic reference mark at the start of every normal note. */
-function serializeNewFootnotesPart(footnotes) {
-	return serializeNewNotePart("footnote", footnotes);
+function serializeNewFootnotesPart(footnotes, document) {
+	return serializeNewNotePart({
+		elementName: "footnote",
+		notes: footnotes,
+		...document ? { document } : {}
+	});
 }
 /** Serialize a brand-new endnote part, including Word's required separators
 * and the automatic reference mark at the start of every normal note. */
-function serializeNewEndnotesPart(endnotes) {
-	return serializeNewNotePart("endnote", endnotes);
+function serializeNewEndnotesPart(endnotes, document) {
+	return serializeNewNotePart({
+		elementName: "endnote",
+		notes: endnotes,
+		...document ? { document } : {}
+	});
 }
 //#endregion
 export { serializeEndnotes, serializeFootnotes, serializeNewEndnotesPart, serializeNewFootnotesPart };

package/dist/docx/serializer/paragraphSerializer.js

@@ -2,7 +2,9 @@ import { modelParagraphFormattingEmission, serializeParagraphPropertySet } from
 import { serializePreservedAttributes } from "../attributeRemainder.js";
 import { CONTAINER_CHILDREN } from "../containerChildren.gen.js";
 import { fieldStateAttributes } from "../fieldState.js";
+import { serializeEmptyMarkProperties } from "../paragraphMarkPropertyPresence.js";
 import { getParagraphPropertySource, paragraphPropertySourceMatchesEmission } from "../paragraphPropertySource.js";
+import { ReviewResolutionProvenanceError, paragraphMarkResolutionJoinAttributes, serializeParagraphMarkResolutionJoin, serializeResolutionJoins } from "../reviewResolutionProvenance.js";
 import { DATE_UTC_ATTRIBUTE } from "../trackedChangeInfo.js";
 import { toTransitionalNamespaceUri } from "../transitionalSpelling.js";
 import { captureVerbatimXml, createCapturedXmlSanitizer } from "../verbatimCapture.js";
@@ -20,11 +22,22 @@ import { PARAGRAPH_MARK_CHANGE_KINDS } from "@stll/docx-core/model";
 import { SEQUENCE_CHILDREN } from "@stll/docx-core/schema";
 //#region src/docx/serializer/paragraphSerializer.ts
 /**
+* Paragraph Serializer - Serialize paragraphs to OOXML XML
+*
+* Converts Paragraph objects back to <w:p> XML format for DOCX files.
+* Handles all paragraph properties and child content (runs, hyperlinks, fields, bookmarks).
+*
+* OOXML Reference:
+* - Paragraph: w:p
+* - Paragraph properties: w:pPr
+* - Runs, hyperlinks, bookmarks, fields as child elements
+*/
+/**
 * Serialize paragraph formatting properties to w:pPr XML
 */
 function serializeParagraphMarkChange(mark) {
 	const attrs = serializeTrackedChangeAttributes(mark.info);
-	return `<w:${mark.kind} ${attrs}/>`;
+	return `<w:${mark.kind} ${attrs}${serializeParagraphMarkResolutionJoin(mark)}/>`;
 }
 const RESERVED_PARAGRAPH_PROPERTY_CHILDREN = /* @__PURE__ */ new Set(["pPrChange", "sectPr"]);
 /**
@@ -212,7 +225,10 @@ const withTrailingParagraphPropertyChildren = (sourceXml, children) => {
 const withParagraphMarkChange = (sourceXml, mark) => {
 	const root = parseXml(sourceXml, OOXML_NAMESPACE_SCOPE).elements?.at(0);
 	if (!root || root.type !== "element") panic("A validated paragraph-property capture could not be parsed for composition");
-	const attributes = trackedChangeAttributeRecord(mark.info);
+	const attributes = {
+		...trackedChangeAttributeRecord(mark.info),
+		...paragraphMarkResolutionJoinAttributes(mark)
+	};
 	const markElement = cloneElement(root, {
 		name: `w:${mark.kind}`,
 		attributes,
@@ -339,6 +355,20 @@ function serializeComplexField(field) {
 	parts.push(`<w:r>${rPrXml}<w:fldChar w:fldCharType="end"/></w:r>`);
 	return parts.join("");
 }
+var UnrepresentableTrackedCaptureError = class extends TaggedError("UnrepresentableTrackedCaptureError") {};
+/**
+* Preserved markup inside a removal. Markup captured from a removal already
+* spells its text as deleted text. Markup captured outside one and put under
+* a removal afterwards does not: plain runs are respelled here, as a deleted
+* run is. A folded list-number capture that cannot be respelled is refused,
+* rather than written as live text inside the removal.
+*/
+function serializeRemovedPreservedInline(item) {
+	if (!/<w:(?:t|instrText)[\s>]/u.test(item.xml)) return item.xml;
+	if (/^<w:r[\s>]/u.test(item.xml) && !/<w:(?:drawing|pict|object)\b|<mc:AlternateContent\b/u.test(item.xml)) return rewriteRunTextAsDeleted(item.xml);
+	if (item.foldedListNumber) throw new UnrepresentableTrackedCaptureError({ message: "A folded list-number field holds markup that cannot be written as deleted content." });
+	return item.xml;
+}
 var UnrepresentableTrackedSimpleFieldError = class extends TaggedError("UnrepresentableTrackedSimpleFieldError") {};
 /** A revision can contain run-level field characters, but not `w:fldSimple`. */
 function serializeTrackedSimpleField(field) {
@@ -429,7 +459,12 @@ function trackedChangeTag(change) {
 	}
 }
 function serializeTrackedChange(tag, change) {
-	const attrs = serializeTrackedChangeAttributes(change.info);
+	if (change.resolutionJoins !== void 0 && change.content.some((item) => item.type === "hyperlink")) throw new ReviewResolutionProvenanceError({
+		attribute: "resolutionJoins",
+		reason: "unrepresentable",
+		message: "Tracked-resolution provenance cannot be repartitioned across serialized hyperlinks."
+	});
+	const attrs = serializeTrackedChangeAttributes(change.info) + serializeResolutionJoins(change.resolutionJoins);
 	const disposition = tag === "del" || tag === "moveFrom" ? "removed" : "kept";
 	const serializeContentRun = (run) => serializeInlineRun(run, disposition);
 	const serializeWrappedItem = (item) => {
@@ -451,7 +486,7 @@ function serializeTrackedChange(tag, change) {
 			case "moveFromRangeEnd": return `<w:moveFromRangeEnd ${markupRangeAttributes(item).join(" ")}/>`;
 			case "moveToRangeStart": return serializeMoveRangeStart("moveToRangeStart", item);
 			case "moveToRangeEnd": return `<w:moveToRangeEnd ${markupRangeAttributes(item).join(" ")}/>`;
-			case "preservedInline": return item.xml;
+			case "preservedInline": return disposition === "removed" ? serializeRemovedPreservedInline(item) : item.xml;
 			case "inlineWrapper":
 			case "inlineSdt": return serializeParagraphContent(item, disposition);
 			default: return item;
@@ -574,6 +609,8 @@ function serializeParagraph(paragraph) {
 	if (paragraph.paraId) attrs.push(`w14:paraId="${escapeXmlAttribute(paragraph.paraId)}"`);
 	if (paragraph.textId) attrs.push(`w14:textId="${escapeXmlAttribute(paragraph.textId)}"`);
 	if (paragraph.reviewCarrier) attrs.push(`folio:reviewCarrier="${paragraph.reviewCarrier}"`);
+	const emptyMarkProperties = serializeEmptyMarkProperties(paragraph);
+	if (emptyMarkProperties !== void 0) attrs.push(emptyMarkProperties);
 	const written = serializePreservedAttributes(attrs, paragraph.preservedAttributes);
 	const attrsStr = written.length > 0 ? ` ${written.join(" ")}` : "";
 	parts.push(serializeParagraphFormattingWithOptions(paragraph.formatting, {

package/dist/docx/serializer/partNamespaces.js

@@ -1,3 +1,4 @@
+import { FOLIO_REVIEW_HISTORY_NAMESPACE } from "../reviewHistoryNamespace.js";
 import { toTransitionalNamespaceUri } from "../transitionalSpelling.js";
 import { TaggedError } from "better-result";
 import { assertValidOoxmlNumericIds, escapeXmlAttribute } from "@stll/docx-core";
@@ -144,7 +145,7 @@ const OOXML_NAMESPACES = {
 		ignorable: true
 	},
 	folio: {
-		uri: "urn:stella:folio:review-history:1",
+		uri: FOLIO_REVIEW_HISTORY_NAMESPACE,
 		ignorable: true
 	},
 	wpg: {

package/dist/docx/serializer/runSerializer.js

@@ -7,6 +7,7 @@ import { serializeGraphicFrameLocks } from "../graphicFrameLocks.js";
 import { DECORATIVE_EXTENSION_URI, DECORATIVE_NAMESPACE } from "../imageParser.js";
 import { canReplayEditableImageRawXml } from "../imageRawXml.js";
 import { serializeNonVisualDrawingNames } from "../nonVisualDrawingProps.js";
+import { serializeBoundaryJoins } from "../reviewResolutionProvenance.js";
 import { runHoldsPayload } from "../runPayload.js";
 import { replayableShapeAlternateContent } from "../shapeAlternateContent.js";
 import { requiredWrapPolygon, serializeWrapPolygon } from "../wrapPolygon.js";
@@ -51,7 +52,7 @@ function getUniqueId(id) {
 }
 function serializeRunPropertyChange(change) {
 	const previousRPrXml = serializeTextFormatting(change.previousFormatting) || "<w:rPr/>";
-	return `<w:rPrChange ${serializeTrackedChangeAttributes(change.info)}>${previousRPrXml}</w:rPrChange>`;
+	return `<w:rPrChange ${serializeTrackedChangeAttributes(change.info)}${serializeBoundaryJoins(change.boundaryJoins)}>${previousRPrXml}</w:rPrChange>`;
 }
 function serializeRunProperties(formatting, propertyChanges) {
 	const propertyChange = getSingularRunPropertyChange(propertyChanges);
@@ -537,6 +538,7 @@ function serializeRunContent(content) {
 		case "symbol": return serializeSymbolContent(content);
 		case "footnoteRef":
 		case "endnoteRef": return serializeNoteReference(content);
+		case "noteMarker": return content.kind === "footnote" ? "<w:footnoteRef/>" : "<w:endnoteRef/>";
 		case "fieldChar": return serializeFieldChar(content);
 		case "instrText": return serializeInstrText(content);
 		case "softHyphen": return serializeSoftHyphen(content);