@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/rezip.js

@@ -12,9 +12,10 @@ import { assertValidFolioDocumentModel } from "./modelValidation.js";
 import { isNewDataUrlDrawing } from "./newImage.js";
 import { missingNoteReferenceStyles, noteReferenceNeeds } from "./noteReferenceStyles.js";
 import { parseNumbering } from "./numberingParser.js";
-import { isNumberingReference } from "./numberingReference.js";
+import { paragraphNumberingReferenceId as paragraphNumberingReferenceId$1 } from "./numberingReference.js";
 import { isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries } from "./packageParts.js";
 import { normalizeParaIdRangeInXmlParts } from "./paraIdRangeNormalization.js";
+import { BLOCK_TREE_DESCENT, visitBlockTreeRecords } from "./paragraphTraversal.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
 import { removeResolvedHeaderFooterParts } from "./removeHeaderFooterParts.js";
 import { normalizeRevisionIdsInXmlParts } from "./revisionIdNormalization.js";
@@ -29,10 +30,11 @@ import { readRootNamespaceBindings } from "./serializer/partNamespaces.js";
 import { serializeSettingsXml } from "./serializer/settingsSerializer.js";
 import { serializeStyle, serializeStylesXml } from "./serializer/stylesSerializer.js";
 import { serializeThemeXml } from "./serializer/themeSerializer.js";
-import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, matchesName, parseXml, parseXmlDocument } from "./xmlParser.js";
+import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, findChild, findChildByNamespaceUri, findChildrenByNamespaceUri, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, matchesName, parseXml, parseXmlDocument } from "./xmlParser.js";
 import { assertXmlResourceLimits } from "./xmlResourceLimits.js";
-import { panic } from "better-result";
+import { TaggedError, panic } from "better-result";
 import { escapeXmlAttribute, escapeXmlText, validateDocxPackage } from "@stll/docx-core";
+import { mintRelationshipId } from "@stll/docx-core/model";
 import JSZip from "jszip";
 //#region src/docx/rezip.ts
 /**
@@ -65,10 +67,34 @@ import JSZip from "jszip";
 * - word/_rels/document.xml.rels - Document relationships (preserved)
 * - docProps/* - Document properties (preserved)
 */
-var DocxPackageFidelityError = class extends Error {
+var DocxPackageFidelityError = class extends TaggedError("DocxPackageFidelityError") {
 	constructor(message) {
-		super(message);
-		this.name = "DocxPackageFidelityError";
+		super({ message });
+	}
+};
+/**
+* Raised when a save would write a section the editor never authored.
+*
+* Two paragraphs holding the *same* `SectionProperties` object are one
+* section's two halves, not two sections: ProseMirror copies a node's attrs
+* when a command splits it, and the object is passed through by reference and
+* never cloned, so identity is what tells a copy from a second authored break.
+* The paragraph is named because the count alone does not say which of them the
+* save invented.
+*/
+var DocxDuplicateSectionCarrierError = class extends DocxPackageFidelityError {
+	/** The `w:paraId` of the duplicate carrier, when the package gave it one. */
+	paraId;
+	/** Its position among the paragraph-level carriers, in document order. */
+	carrierIndex;
+	/** The position of the carrier it duplicates. */
+	duplicatesCarrierIndex;
+	constructor(options) {
+		super(`Full DOCX repack would add a section: paragraph-level w:sectPr carrier ${options.carrierIndex}${options.paraId === null ? "" : ` (w:paraId ${options.paraId})`} holds the same section record as carrier ${options.duplicatesCarrierIndex}.`);
+		this.name = "DocxDuplicateSectionCarrierError";
+		this.paraId = options.paraId;
+		this.carrierIndex = options.carrierIndex;
+		this.duplicatesCarrierIndex = options.duplicatesCarrierIndex;
 	}
 };
 /**
@@ -136,12 +162,55 @@ const consumeReferenceCount = (counts, key) => {
 	counts.set(key, count - 1);
 	return true;
 };
+/** Every paragraph the model says a section ends at, in document order. */
+const sectionCarrierParagraphs = (doc) => {
+	const carriers = [];
+	visitBlockTreeRecords(doc.package.document.content, (record) => {
+		if (record.type === "paragraph" && record.sectionProperties !== void 0) carriers.push(record);
+		return BLOCK_TREE_DESCENT.descend;
+	});
+	return carriers;
+};
+/**
+* Every serialized section has exactly one model record, and vice versa.
+*
+* A split paragraph's duplicated `w:sectPr` is a section nobody added,
+* repeating the real one's `w:rsidSect` and claiming its revision history too.
+* Two carriers over one record are therefore invalid regardless of whether a
+* separate deletion makes the total section count rise, fall, or stay equal.
+*
+* The count is a separate invariant: `serializeSectionProperties` fails closed
+* to `""` for a record holding settings it cannot write, so carrier uniqueness
+* alone does not prove the package states the sections the model holds.
+*/
+const assertSectionCarriersMatchModel = ({ doc, serializedSectionCount }) => {
+	const carriers = sectionCarrierParagraphs(doc);
+	const firstHolder = /* @__PURE__ */ new Map();
+	for (const [index, paragraph] of carriers.entries()) {
+		const record = paragraph.sectionProperties;
+		const duplicates = firstHolder.get(record);
+		if (duplicates !== void 0) throw new DocxDuplicateSectionCarrierError({
+			paraId: paragraph.paraId ?? null,
+			carrierIndex: index,
+			duplicatesCarrierIndex: duplicates
+		});
+		firstHolder.set(record, index);
+	}
+	const finalSectionProperties = doc.package.document.finalSectionProperties;
+	if (finalSectionProperties !== void 0 && firstHolder.has(finalSectionProperties)) throw new DocxPackageFidelityError("Full DOCX repack would write the final section record from a paragraph carrier twice.");
+	const modelSectionCount = carriers.length + (finalSectionProperties === void 0 ? 0 : 1);
+	if (serializedSectionCount !== modelSectionCount) throw new DocxPackageFidelityError(`Full DOCX repack would write ${serializedSectionCount} sections where the editor holds ${modelSectionCount}.`);
+};
 function assertDocumentPackageFidelity({ originalDocumentXml, serializedDocumentXml, doc, sectionEndpointRemoval, sectionReferenceRemovals = [] }) {
 	const originalSectionCount = countDocumentSections(originalDocumentXml);
 	const serializedSectionCount = countDocumentSections(serializedDocumentXml);
 	const trackedRemovedSectionCount = sectionEndpointRemoval ? sectionEndpointRemoval.sourceParagraphEndpointCount - sectionEndpointRemoval.expectedParagraphEndpointCount : 0;
 	const exactTrackedSectionRemoval = trackedRemovedSectionCount > 0 && originalSectionCount - trackedRemovedSectionCount === serializedSectionCount && serializedSectionCount < originalSectionCount;
 	if (serializedSectionCount < originalSectionCount && !exactTrackedSectionRemoval) throw new DocxPackageFidelityError("Full DOCX repack would drop section properties. Use selective patching instead.");
+	assertSectionCarriersMatchModel({
+		doc,
+		serializedSectionCount
+	});
 	const serializedReferenceCounts = /* @__PURE__ */ new Map();
 	for (const reference of extractHeaderFooterReferences(serializedDocumentXml)) incrementReferenceCount(serializedReferenceCounts, headerFooterReferenceKey(reference));
 	const removedReferenceCounts = /* @__PURE__ */ new Map();
@@ -390,7 +459,7 @@ async function processNewImages(parts, zip, compressionLevel) {
 			maxImageNum++;
 			maxId++;
 			const mediaPath = `word/media/${`image${maxImageNum}.${extension}`}`;
-			const newRId = `rId${maxId}`;
+			const newRId = mintRelationshipId(maxId);
 			zip.file(mediaPath, data, {
 				compression: "DEFLATE",
 				compressionOptions: { level: compressionLevel }
@@ -443,6 +512,7 @@ function collectHyperlinksWithoutRId(blocks) {
 				break;
 			case "simpleField":
 			case "inlineSdt":
+			case "inlineWrapper":
 			case "insertion":
 			case "deletion":
 			case "moveFrom":
@@ -454,7 +524,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 hyperlinks.push(...collectHyperlinksWithoutRId(block.content));
+	else if (block.type === "blockSdt") hyperlinks.push(...collectHyperlinksWithoutRId(block.content));
 	return hyperlinks;
 }
 /** The selective save boundary must use the same resource census as full repack. */
@@ -1425,7 +1495,26 @@ const seedStylesXmlWith = (missing) => {
 	const rootClose = SEED_STYLES_XML.lastIndexOf(STYLES_CLOSE_ROOT);
 	return SEED_STYLES_XML.slice(0, rootClose) + missing.map(serializeStyle).join("") + SEED_STYLES_XML.slice(rootClose);
 };
-const STYLE_ID_PATTERN = /<w:style\b[^>]*?\bw:styleId="(?<id>[^"]+)"/gu;
+/**
+* The style ids `word/styles.xml` already defines.
+*
+* Read by parsing the part, because the model holds the *decoded* id and the
+* part holds its XML spelling: `w:styleId='Body A'` is single-quoted,
+* `w:styleId="Header &amp; Footer"` is escaped, and either may sit behind an
+* attribute value containing `>`. A reader that misses one of those reports a
+* style the part already defines as missing, and
+* {@link serializeAddedStylesIntoZip} appends it — on every save, for ever.
+*/
+const definedStyleIds = (stylesXml) => {
+	const root = parseXml(stylesXml);
+	const styles = findChildByNamespaceUri(root, WORDPROCESSINGML_NAMESPACE_URIS, "styles") ?? root;
+	const ids = /* @__PURE__ */ new Set();
+	for (const style of findChildrenByNamespaceUri(styles, WORDPROCESSINGML_NAMESPACE_URIS, "style")) {
+		const id = getAttributeByNamespaceUri(style, WORDPROCESSINGML_NAMESPACE_URIS, "styleId") ?? style.attributes?.["w:styleId"];
+		if (id !== void 0 && id !== null && id !== "") ids.add(String(id));
+	}
+	return ids;
+};
 /**
 * Append styles the model defines but the original `word/styles.xml` lacks.
 * Existing styles stay byte-exact (edits to them are not written here, the
@@ -1471,9 +1560,13 @@ async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compression
 		});
 		return;
 	}
-	const existing = /* @__PURE__ */ new Set();
-	for (const match of originalXml.matchAll(STYLE_ID_PATTERN)) existing.add(match.groups["id"]);
-	const added = styles.styles.filter((style) => !existing.has(style.styleId));
+	const existing = new Set(definedStyleIds(originalXml));
+	const added = [];
+	for (const style of styles.styles) {
+		if (existing.has(style.styleId)) continue;
+		existing.add(style.styleId);
+		added.push(style);
+	}
 	if (added.length === 0) return;
 	const patched = originalXml.slice(0, rootClose) + added.map(serializeStyle).join("") + originalXml.slice(rootClose);
 	newZip.file(file.name, patched, {
@@ -1481,28 +1574,60 @@ async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compression
 		compressionOptions: { level: compressionLevel }
 	});
 }
+/**
+* The XML to write for a patched note part, or null to keep the original.
+*
+* A refusal over comment-range balance is not a failure to serialize: the
+* splice was too narrow to keep a comment's range whole, so the part is
+* written from the model, which is balanced with itself and with the
+* `document.xml` this repack rewrites beside it. Word's required separator
+* notes come back synthesized rather than byte-exact, the price of keeping the
+* comment anchored to the text it was written about. Any other refusal means a
+* changed paragraph could not be located in the part at all, which no wider
+* rewrite fixes.
+*/
+const notePartXmlFor = ({ patch, originalXml, replacementXml, hasDirtyParagraph, elementName, partName }) => {
+	const keepOriginal = () => {
+		if (hasDirtyParagraph) throw new DocxPackageFidelityError(`Cannot serialize changed ${elementName} paragraphs into ${partName}`);
+		return null;
+	};
+	switch (patch.type) {
+		case "patched": return patch.xml === originalXml ? keepOriginal() : patch.xml;
+		case "refused": switch (patch.reason) {
+			case "comment-range-balance": return replacementXml;
+			case "unroutable-paragraph": return keepOriginal();
+			default: {
+				const unreachable = patch.reason;
+				return panic("Unhandled note-part patch refusal", { reason: unreachable });
+			}
+		}
+		default: return panic("Unhandled note-part patch", { patch });
+	}
+};
 async function patchNotePartIntoZip({ conventionalLowerPath, currentXml, replacementXml, baselineFrom, elementName, changedNoteParaIds, originalZip, newZip, compressionLevel }) {
 	const file = findNotePartEntry(originalZip, conventionalLowerPath);
 	if (!file) return;
 	const originalXml = await file.async("text");
 	const baselineXml = baselineFrom(originalXml);
 	const effectiveChangedNoteParaIds = changedNoteParaIds ?? collectChangedNoteParaIds(baselineXml, currentXml);
-	const patched = buildPatchedNotePartXml({
+	const currentParaIds = collectParaIds(currentXml);
+	const patchedXml = notePartXmlFor({
+		patch: buildPatchedNotePartXml({
+			originalXml,
+			baselineXml,
+			serializedXml: currentXml,
+			replacementXml,
+			elementName,
+			changedParaIds: effectiveChangedNoteParaIds
+		}),
 		originalXml,
-		baselineXml,
-		serializedXml: currentXml,
 		replacementXml,
+		hasDirtyParagraph: [...effectiveChangedNoteParaIds].some((paraId) => currentParaIds.has(paraId)),
 		elementName,
-		changedParaIds: effectiveChangedNoteParaIds
+		partName: file.name
 	});
-	const currentParaIds = collectParaIds(currentXml);
-	const hasDirtyParagraph = [...effectiveChangedNoteParaIds].some((paraId) => currentParaIds.has(paraId));
-	if (patched === null || hasDirtyParagraph && patched === originalXml) {
-		if (hasDirtyParagraph) throw new DocxPackageFidelityError(`Cannot serialize changed ${elementName} paragraphs into ${file.name}`);
-		return;
-	}
-	if (patched === originalXml) return;
-	newZip.file(file.name, patched, {
+	if (patchedXml === null || patchedXml === originalXml) return;
+	newZip.file(file.name, patchedXml, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});
@@ -1741,8 +1866,8 @@ const overrideXml = (partName, contentType) => `<Override PartName="${partName}"
 const assertStyleNumberingReferences = (doc) => {
 	const referenced = /* @__PURE__ */ new Set();
 	for (const style of doc.package.styles?.styles ?? []) {
-		const numId = style.pPr?.numPr?.numId;
-		if (isNumberingReference(numId)) referenced.add(numId);
+		const numId = paragraphNumberingReferenceId$1(style.pPr?.numPr);
+		if (numId !== void 0) referenced.add(numId);
 	}
 	if (referenced.size === 0) return;
 	const available = new Map(doc.package.numbering?.nums.map((numbering) => [numbering.numId, numbering]) ?? []);
@@ -1754,4 +1879,4 @@ const assertStyleNumberingReferences = (doc) => {
 	}
 };
 //#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, hasUnmaterializedInlineResources, 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, DocxDuplicateSectionCarrierError, 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/runConsolidator.d.ts

@@ -1,12 +1,21 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/runConsolidator.d.ts
+/**
+ * Every `TextFormatting` field, named so the comparison below is total.
+ *
+ * A field this comparison forgets is a field one of two merged runs loses,
+ * silently and at parse time. Naming them turns a field added to the model
+ * without a comparison into a compile error rather than a fidelity defect.
+ */
+type ComparedTextFormattingField = "bold" | "boldCs" | "italic" | "italicCs" | "underline" | "strike" | "doubleStrike" | "vertAlign" | "smallCaps" | "allCaps" | "hidden" | "noProof" | "color" | "highlight" | "shading" | "fontSize" | "fontSizeCs" | "fontFamily" | "language" | "spacing" | "position" | "scale" | "kerning" | "effect" | "emphasisMark" | "emboss" | "imprint" | "outline" | "shadow" | "rtl" | "cs" | "styleId" | "preserved";
+type ComparedTextFormatting = document_d_exports.ExhaustiveFields<document_d_exports.TextFormatting, ComparedTextFormattingField>;
 /**
  * Check if two TextFormatting objects are equivalent
  *
  * Uses deep comparison of all properties to determine if runs
  * can be merged without losing formatting information.
  */
-declare function formattingEquals(a: document_d_exports.TextFormatting | undefined, b: document_d_exports.TextFormatting | undefined): boolean;
+declare function formattingEquals(a: ComparedTextFormatting | undefined, b: ComparedTextFormatting | undefined): boolean;
 /**
  * Check if a run contains only text content
  * (runs with special content like images, fields, etc. should not be merged)
@@ -17,6 +26,37 @@ declare function isTextOnlyRun(run: document_d_exports.Run): boolean;
  * Runs with breaks, tabs, images, fields, etc. act as merge boundaries
  */
 declare function canMergeRun(run: document_d_exports.Run): boolean;
+/**
+ * Every `Run` field, named by what a merge does with it.
+ *
+ * The merged run is the survivor spread whole, so a field added to the model
+ * is carried over from one side by default. Naming each one here forces the
+ * next field to state whether that default is right before it can compile.
+ */
+type MergeDecidedRunField =
+/** Identical for every run. */
+"type" |
+/** Concatenated; see {@link mergeRunContent}. */
+"content" |
+/** Must be equal, and the survivor keeps it. */
+"formatting" |
+/** Must be equal, and the survivor keeps it. */
+"preservedAttributes" |
+/** Refuses the merge outright; see {@link canMergeRun}. */
+"propertyChanges";
+type MergeDecidedRun = document_d_exports.ExhaustiveFields<document_d_exports.Run, MergeDecidedRunField>;
+/**
+ * May two adjacent runs become one?
+ *
+ * Every consolidation site asks this one question, because a merge that any
+ * one site decides differently is a merge the next parse undoes. A run holds
+ * three records a merged run can hold only one of: its typed formatting, the
+ * attributes `w:r` carried that the model has no field for, and the `w:rPr`
+ * children no reader took a value from. Merging two runs that disagree on any
+ * of them discards the loser's copy, which is how both runs' `w:rsid*` used to
+ * vanish at parse time — before the editor, before any gate could see it.
+ */
+declare function runsMergeable(a: MergeDecidedRun, b: MergeDecidedRun): boolean;
 /**
  * Consolidate an array of runs by merging consecutive runs with identical formatting
  *
@@ -53,4 +93,4 @@ declare function getConsolidationStats(originalParagraphs: document_d_exports.Pa
   reductionPercentage: number;
 };
 //#endregion
-export { canMergeRun, consolidateParagraph, consolidateParagraphContent, consolidateRuns, countRuns, formattingEquals, getConsolidationStats, isTextOnlyRun };
+export { canMergeRun, consolidateParagraph, consolidateParagraphContent, consolidateRuns, countRuns, formattingEquals, getConsolidationStats, isTextOnlyRun, runsMergeable };

package/dist/docx/runConsolidator.js

@@ -1,4 +1,5 @@
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
+import { runHoldsPayload } from "./runPayload.js";
 //#region src/docx/runConsolidator.ts
 /**
 * Check if two TextFormatting objects are equivalent
@@ -18,6 +19,7 @@ function formattingEquals(a, b) {
 	if (a.smallCaps !== b.smallCaps) return false;
 	if (a.allCaps !== b.allCaps) return false;
 	if (a.hidden !== b.hidden) return false;
+	if (a.noProof !== b.noProof) return false;
 	if (a.emboss !== b.emboss) return false;
 	if (a.imprint !== b.imprint) return false;
 	if (a.outline !== b.outline) return false;
@@ -40,8 +42,46 @@ function formattingEquals(a, b) {
 	if (!shadingEquals(a.shading, b.shading)) return false;
 	if (!fontFamilyEquals(a.fontFamily, b.fontFamily)) return false;
 	if (!languageEquals(a.language, b.language)) return false;
+	if (!preservedMarkupEquals(a.preserved, b.preserved)) return false;
 	return true;
 }
+/**
+* Compare two verbatim sinks position by position.
+*
+* The sink is ordered — by `index`, then by source order within an index — and
+* the order is what puts the markup back between the same modelled siblings,
+* so equality is by sequence, not by set.
+*/
+function preservedMarkupEquals(a, b) {
+	const left = a?.children ?? [];
+	const right = b?.children ?? [];
+	if (left.length !== right.length) return false;
+	return left.every(({ index, xml }, position) => {
+		const other = right[position];
+		return other !== void 0 && other.index === index && other.xml === xml;
+	});
+}
+/**
+* Compare two attribute remainders as sets.
+*
+* An element cannot carry one expanded name twice, so (namespace, name) orders
+* a remainder totally and the sorted keys compare exactly. Order is a set
+* comparison rather than a sequence one because attribute order in XML says
+* nothing: two runs that spelled the same attributes in a different order
+* carry the same remainder and may still become one run.
+*/
+function preservedAttributesEqual(a, b) {
+	const left = canonicalRemainderKeys(a);
+	const right = canonicalRemainderKeys(b);
+	return left.length === right.length && left.every((key, index) => key === right[index]);
+}
+/** `\u0000` cannot appear in an XML name, namespace URI or attribute value. */
+const REMAINDER_KEY_SEPARATOR = "\0";
+const canonicalRemainderKeys = (attributes) => (attributes ?? []).map(({ namespace, name, value }) => [
+	namespace ?? "",
+	name,
+	value
+].join(REMAINDER_KEY_SEPARATOR)).sort();
 function languageEquals(a, b) {
 	return a?.val === b?.val && a?.eastAsia === b?.eastAsia && a?.bidi === b?.bidi;
 }
@@ -100,10 +140,24 @@ function isMergeableContent(content) {
 */
 function canMergeRun(run) {
 	if (run.propertyChanges && run.propertyChanges.length > 0) return false;
-	if (run.content.length === 0) return true;
+	if (!runHoldsPayload(run)) return false;
 	return run.content.every(isMergeableContent);
 }
 /**
+* May two adjacent runs become one?
+*
+* Every consolidation site asks this one question, because a merge that any
+* one site decides differently is a merge the next parse undoes. A run holds
+* three records a merged run can hold only one of: its typed formatting, the
+* attributes `w:r` carried that the model has no field for, and the `w:rPr`
+* children no reader took a value from. Merging two runs that disagree on any
+* of them discards the loser's copy, which is how both runs' `w:rsid*` used to
+* vanish at parse time — before the editor, before any gate could see it.
+*/
+function runsMergeable(a, b) {
+	return canMergeRun(a) && canMergeRun(b) && formattingEquals(a.formatting, b.formatting) && preservedAttributesEqual(a.preservedAttributes, b.preservedAttributes);
+}
+/**
 * Merge the content of two runs into a single content array
 */
 function mergeRunContent(content1, content2) {
@@ -131,11 +185,12 @@ function consolidateRuns(runs) {
 	const result = [];
 	let current = null;
 	for (const run of runs) {
-		if (run.content.length === 0) {
+		if (!runHoldsPayload(run)) {
 			if (current !== null) {
 				result.push(current);
 				current = null;
 			}
+			result.push(run);
 			continue;
 		}
 		if (current === null) {
@@ -145,9 +200,8 @@ function consolidateRuns(runs) {
 			};
 			continue;
 		}
-		if (canMergeRun(current) && canMergeRun(run) && formattingEquals(current.formatting, run.formatting)) current = {
-			type: "run",
-			...current.formatting !== void 0 ? { formatting: current.formatting } : {},
+		if (runsMergeable(current, run)) current = {
+			...current,
 			content: mergeRunContent(current.content, run.content)
 		};
 		else {
@@ -222,4 +276,4 @@ function getConsolidationStats(originalParagraphs, consolidatedParagraphs) {
 	};
 }
 //#endregion
-export { canMergeRun, consolidateParagraph, consolidateParagraphContent, consolidateRuns, countRuns, formattingEquals, getConsolidationStats, isTextOnlyRun };
+export { canMergeRun, consolidateParagraph, consolidateParagraphContent, consolidateRuns, countRuns, formattingEquals, getConsolidationStats, isTextOnlyRun, runsMergeable };

package/dist/docx/runParser.d.ts

@@ -1,7 +1,33 @@
 import { document_d_exports } from "../types/document.js";
-import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
 //#region src/docx/runParser.d.ts
+/**
+ * Which record beside this `w:rPr` reads children out of it.
+ *
+ * The four owners of a run property set share one handler map, because they
+ * share one content model: `CT_RPr` is `EG_RPrBase` plus `w:rPrChange`, and
+ * `CT_ParaRPr` opens that with `EG_ParaRPrTrackChanges`. They differ only in
+ * which children a *sibling* record has already claimed, and a child claimed
+ * twice is written twice. Naming the owner states that once, at the call site
+ * that knows it, instead of leaving it to whichever reader ran first.
+ */
+declare const RUN_PROPERTY_OWNERS: {
+  /** A `w:r`'s own properties: `Run.propertyChanges` reads the `w:rPrChange`. */
+  readonly run: "run";
+  /**
+   * `w:pPr/w:rPr`. The paragraph's record reads the mark's revision
+   * (`ParagraphMarkChange`) and its `w:specVanish`
+   * (`ParagraphFormatting.runInWithNext`).
+   */
+  readonly paragraphMark: "paragraphMark";
+  /**
+   * A style, a numbering level, a comment's reference mark, the snapshot
+   * inside a `w:rPrChange`: nothing beside it reads any of its children.
+   */
+  readonly standalone: "standalone";
+};
+type RunPropertyOwner = (typeof RUN_PROPERTY_OWNERS)[keyof typeof RUN_PROPERTY_OWNERS];
 /**
  * `w:vertAlign` `baseline` is the reserved value that means "no vertical
  * offset", not a third offset beside `superscript` and `subscript`. It is
@@ -10,34 +36,44 @@ import { XmlElement } from "./xmlParser.js";
  */
 declare const isBaselineVertAlign: (vertAlign: document_d_exports.TextFormatting["vertAlign"]) => boolean;
 /**
- * Parse run formatting properties (w:rPr)
+ * The one reader of a run property set (`w:rPr`).
+ *
+ * Every owner reads through here — a run, the paragraph mark, a style, a
+ * numbering level, a comment's reference mark and the snapshot inside either
+ * kind of `w:rPrChange` — so none of them can grow its own idea of which
+ * children exist, which values it admits, or which of two statements of one
+ * property wins. The style parser used to keep a copy of this function, and
+ * the copies had drifted on all three.
+ *
+ * Every child the content model declares carries a decision: a handler that
+ * reads it into {@link TextFormatting}, `ownedElsewhere` when the owner's
+ * sibling record reads it, or `CAPTURE` for markup folio models nothing for.
+ * A handler that looked and took nothing answers `CAPTURE` as well — `<w:sz/>`
+ * states no size and `<w:highlight w:val="chartreuse"/>` states a value the
+ * reader's enumeration does not admit, and neither can be decided by the
+ * child's name. What no reader took goes to `TextFormatting.preserved` at its
+ * schema ordinal, so a rebuild puts it back between the same two siblings.
+ *
+ * A property stated twice resolves to the last statement; see
+ * {@link readLastOccurrenceOnly} for the evidence and for why the statements
+ * it beat are not kept.
  *
- * Handles ALL rPr properties:
- * - w:b (bold), w:i (italic), w:u (underline with style)
- * - w:strike (strikethrough), w:dstrike (double strike)
- * - w:vertAlign (superscript/subscript)
- * - w:smallCaps, w:caps (capitalization)
- * - w:highlight (text highlight color)
- * - w:shd (character shading)
- * - w:color (text color with theme resolution)
- * - w:sz (font size in half-points)
- * - w:rFonts (font family with theme resolution)
- * - w:spacing (character spacing)
- * - w:effect (text effects)
- * - And more...
+ * An element that states nothing at all still yields a record: `undefined` here
+ * means the owner carried no `w:rPr`, never that the one it carried was empty.
  */
-declare function parseRunProperties(rPr: XmlElement | null, theme: document_d_exports.Theme | null, _styles?: StyleMap): document_d_exports.TextFormatting | undefined;
+declare function parseRunProperties(rPr: XmlElement | null, theme: document_d_exports.Theme | null, owner: RunPropertyOwner): document_d_exports.TextFormatting | undefined;
 /**
  * Parse a run element (w:r)
  *
  * @param node - The w:r XML element
- * @param styles - Style map for resolving style references
+ * @param _styles - Unread: a run's properties are parsed as the source wrote
+ *   them, and style resolution happens above this parser
  * @param theme - Theme for resolving theme colors/fonts
  * @param rels - Relationship map for resolving image references
  * @param media - Media files map for image data
  * @returns Parsed Run object
  */
-declare function parseRun(node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null, rootXmlns?: Record<string, string>): document_d_exports.Run;
+declare function parseRun(node: XmlElement, _styles: StyleMap | null, theme: document_d_exports.Theme | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null, rootXmlns?: Record<string, string>): document_d_exports.Run;
 /**
  * Get plain text from a run
  *
@@ -81,4 +117,4 @@ declare function hasFieldChar(run: document_d_exports.Run): boolean;
  */
 declare function getFieldCharType(run: document_d_exports.Run): "begin" | "separate" | "end" | null;
 //#endregion
-export { getFieldCharType, getImages, getRunText, hasContent, hasFieldChar, hasImage, isBaselineVertAlign, parseRun, parseRunProperties };
+export { RUN_PROPERTY_OWNERS, RunPropertyOwner, getFieldCharType, getImages, getRunText, hasContent, hasFieldChar, hasImage, isBaselineVertAlign, parseRun, parseRunProperties };