@stll/folio-core 0.54.2 → 0.56.0

package/dist/docx/runConsolidator.d.ts

@@ -1,62 +1,6 @@
 import { document_d_exports } from "../types/document.js";
+import { formattingEquals, isTextOnlyRun, runsMergeable } from "@stll/docx-core/ops";
 //#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: 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)
- */
-declare function isTextOnlyRun(run: document_d_exports.Run): boolean;
-/**
- * Check if a run can be merged with another run
- * 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
  *
@@ -93,4 +37,4 @@ declare function getConsolidationStats(originalParagraphs: document_d_exports.Pa
   reductionPercentage: number;
 };
 //#endregion
-export { canMergeRun, consolidateParagraph, consolidateParagraphContent, consolidateRuns, countRuns, formattingEquals, getConsolidationStats, isTextOnlyRun, runsMergeable };
+export { consolidateParagraph, consolidateParagraphContent, consolidateRuns, countRuns, formattingEquals, getConsolidationStats, isTextOnlyRun, runsMergeable };

package/dist/docx/runConsolidator.js

@@ -1,180 +1,8 @@
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
 import { runHoldsPayload } from "./runPayload.js";
+import { formattingEquals, isTextOnlyRun, mergeRunContent, runsMergeable, runsMergeable as runsMergeable$1 } from "@stll/docx-core/ops";
 //#region src/docx/runConsolidator.ts
 /**
-* Check if two TextFormatting objects are equivalent
-*
-* Uses deep comparison of all properties to determine if runs
-* can be merged without losing formatting information.
-*/
-function formattingEquals(a, b) {
-	if (!a && !b) return true;
-	if (!a || !b) return false;
-	if (a.bold !== b.bold) return false;
-	if (a.boldCs !== b.boldCs) return false;
-	if (a.italic !== b.italic) return false;
-	if (a.italicCs !== b.italicCs) return false;
-	if (a.strike !== b.strike) return false;
-	if (a.doubleStrike !== b.doubleStrike) return false;
-	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;
-	if (a.shadow !== b.shadow) return false;
-	if (a.rtl !== b.rtl) return false;
-	if (a.cs !== b.cs) return false;
-	if (a.fontSize !== b.fontSize) return false;
-	if (a.fontSizeCs !== b.fontSizeCs) return false;
-	if (a.spacing !== b.spacing) return false;
-	if (a.position !== b.position) return false;
-	if (a.scale !== b.scale) return false;
-	if (a.kerning !== b.kerning) return false;
-	if (a.vertAlign !== b.vertAlign) return false;
-	if (a.highlight !== b.highlight) return false;
-	if (a.effect !== b.effect) return false;
-	if (a.emphasisMark !== b.emphasisMark) return false;
-	if (a.styleId !== b.styleId) return false;
-	if (!underlineEquals(a.underline, b.underline)) return false;
-	if (!colorEquals(a.color, b.color)) return false;
-	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;
-}
-/**
-* Compare underline settings
-*/
-function underlineEquals(a, b) {
-	if (!a && !b) return true;
-	if (!a || !b) return false;
-	if (a.style !== b.style) return false;
-	return colorEquals(a.color, b.color);
-}
-/**
-* Compare color values
-*/
-function colorEquals(a, b) {
-	if (!a && !b) return true;
-	if (!a || !b) return false;
-	return a.rgb === b.rgb && a.auto === b.auto && a.themeColor === b.themeColor && a.themeTint === b.themeTint && a.themeShade === b.themeShade;
-}
-/**
-* Compare shading properties
-*/
-function shadingEquals(a, b) {
-	if (!a && !b) return true;
-	if (!a || !b) return false;
-	if (a.pattern !== b.pattern) return false;
-	if (!colorEquals(a.color, b.color)) return false;
-	if (!colorEquals(a.fill, b.fill)) return false;
-	return true;
-}
-/**
-* Compare font family settings
-*/
-function fontFamilyEquals(a, b) {
-	if (!a && !b) return true;
-	if (!a || !b) return false;
-	return a.ascii === b.ascii && a.hAnsi === b.hAnsi && a.eastAsia === b.eastAsia && a.cs === b.cs && a.asciiTheme === b.asciiTheme && a.hAnsiTheme === b.hAnsiTheme && a.eastAsiaTheme === b.eastAsiaTheme && a.csTheme === b.csTheme;
-}
-/**
-* Check if a run contains only text content
-* (runs with special content like images, fields, etc. should not be merged)
-*/
-function isTextOnlyRun(run) {
-	return run.content.every((c) => c.type === "text" || c.type === "softHyphen" || c.type === "noBreakHyphen");
-}
-/**
-* Check if run content can be merged (simple text types)
-*/
-function isMergeableContent(content) {
-	return content.type === "text" || content.type === "softHyphen" || content.type === "noBreakHyphen";
-}
-/**
-* Check if a run can be merged with another run
-* Runs with breaks, tabs, images, fields, etc. act as merge boundaries
-*/
-function canMergeRun(run) {
-	if (run.propertyChanges && run.propertyChanges.length > 0) return false;
-	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) {
-	const result = [];
-	for (const c of content1) result.push(c);
-	const lastText = result.at(-1);
-	const firstText = content2[0];
-	if (lastText?.type === "text" && firstText?.type === "text") {
-		result[result.length - 1] = {
-			type: "text",
-			text: lastText.text + firstText.text
-		};
-		for (let i = 1; i < content2.length; i++) result.push(content2[i]);
-	} else for (const c of content2) result.push(c);
-	return result;
-}
-/**
 * Consolidate an array of runs by merging consecutive runs with identical formatting
 *
 * @param runs - Array of runs to consolidate
@@ -200,7 +28,7 @@ function consolidateRuns(runs) {
 			};
 			continue;
 		}
-		if (runsMergeable(current, run)) current = {
+		if (runsMergeable$1(current, run)) current = {
 			...current,
 			content: mergeRunContent(current.content, run.content)
 		};
@@ -276,4 +104,4 @@ function getConsolidationStats(originalParagraphs, consolidatedParagraphs) {
 	};
 }
 //#endregion
-export { canMergeRun, consolidateParagraph, consolidateParagraphContent, consolidateRuns, countRuns, formattingEquals, getConsolidationStats, isTextOnlyRun, runsMergeable };
+export { consolidateParagraph, consolidateParagraphContent, consolidateRuns, countRuns, formattingEquals, getConsolidationStats, isTextOnlyRun, runsMergeable };

package/dist/docx/runParser.d.ts

@@ -60,7 +60,8 @@ declare const isBaselineVertAlign: (vertAlign: document_d_exports.TextFormatting
  * it beat are not kept.
  *
  * 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.
+ * means the owner carried no `w:rPr`, or a paragraph-mark carrier contained
+ * only metadata owned by the paragraph. An authored empty set remains {}.
  */
 declare function parseRunProperties(rPr: XmlElement | null, theme: document_d_exports.Theme | null, owner: RunPropertyOwner): document_d_exports.TextFormatting | undefined;
 /**

package/dist/docx/runParser.js

@@ -9,6 +9,7 @@ import { imageRawXmlFingerprint } from "./imageRawXml.js";
 import { EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, TextEffectSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
 import { preserveRunChild } from "./preservedRunContent.js";
 import { standalonePreviewLedger } from "./previewBudget.js";
+import { parseBoundaryJoins } from "./reviewResolutionProvenance.js";
 import { parseShading } from "./shadingParser.js";
 import { captureShapeAlternateContent } from "./shapeAlternateContent.js";
 import { parseShapeFromDrawing, shouldPreserveRawShapeDrawing } from "./shapeParser.js";
@@ -22,6 +23,25 @@ import { WORDPROCESSINGML_NAMESPACE_URIS, cloneWithXmlnsDeclarations, findAllDee
 import { DRAWING_RAW_XML_MODES } from "@stll/docx-core/model";
 //#region src/docx/runParser.ts
 /**
+* Run Parser - Parse text runs (w:r) with complete formatting
+*
+* A run is a contiguous region of text with the same character formatting.
+* Runs can contain:
+* - Text (w:t)
+* - Tabs (w:tab)
+* - Line breaks (w:br)
+* - Symbols (w:sym)
+* - Footnote/endnote references
+* - Field characters
+* - Drawings/images (w:drawing)
+* - And more...
+*
+* OOXML Reference:
+* - Run: w:r
+* - Run properties: w:rPr
+* - Text content: w:t
+*/
+/**
 * Sanity cap on `w:lang` `@w:val`/`@w:eastAsia`/`@w:bidi` tag length. BCP-47
 * tags top out well under this; a hostile/corrupt tag here would drive the
 * hyphenation dictionary lookup and segmenter cache keying with an
@@ -81,6 +101,11 @@ const OWNED_BY_A_SIBLING_RECORD = {
 		reader: "runParser#parseRun"
 	}) },
 	paragraphMark: {
+		specVanish: ownedElsewhere({
+			container: "run-properties",
+			child: "specVanish",
+			reader: "paragraphProperties#parseParagraphProperties"
+		}),
 		ins: ownedElsewhere({
 			container: "run-properties",
 			child: "ins",
@@ -354,7 +379,6 @@ const RUN_PROPERTY_HANDLERS = {
 	},
 	paragraphMark: {
 		...RUN_PROPERTY_BASE_HANDLERS,
-		specVanish: readLastOccurrenceOnly(() => void 0),
 		...OWNED_BY_A_SIBLING_RECORD.paragraphMark
 	},
 	standalone: {
@@ -386,7 +410,8 @@ const RUN_PROPERTY_HANDLERS = {
 * it beat are not kept.
 *
 * 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.
+* means the owner carried no `w:rPr`, or a paragraph-mark carrier contained
+* only metadata owned by the paragraph. An authored empty set remains {}.
 */
 function parseRunProperties(rPr, theme, owner) {
 	if (!rPr) return;
@@ -403,6 +428,8 @@ function parseRunProperties(rPr, theme, owner) {
 		}
 	});
 	if (preserved) formatting.preserved = preserved;
+	const children = getChildElements(rPr);
+	if (owner === RUN_PROPERTY_OWNERS.paragraphMark && Object.keys(formatting).length === 0 && children.length > 0 && children.every((child) => WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "") && Object.hasOwn(OWNED_BY_A_SIBLING_RECORD.paragraphMark, getLocalName(child.name)))) return;
 	return formatting;
 }
 function parseRunPropertyChanges(rPr, theme, currentFormatting) {
@@ -413,6 +440,8 @@ function parseRunPropertyChanges(rPr, theme, currentFormatting) {
 			type: "runPropertyChange",
 			info: parsePropertyChangeInfo(changeElement)
 		};
+		const boundaryJoins = parseBoundaryJoins(changeElement);
+		if (boundaryJoins !== void 0) change.boundaryJoins = boundaryJoins;
 		const previousFormatting = parseRunProperties(previousRPr, theme, RUN_PROPERTY_OWNERS.standalone);
 		if (previousFormatting) change.previousFormatting = previousFormatting;
 		if (currentFormatting) change.currentFormatting = currentFormatting;
@@ -602,130 +631,141 @@ function parseDrawingContent(element, rels, media, previews) {
 function parseRunContents(runElement, rels, media, previews, rootXmlns = {}) {
 	const contents = [];
 	const children = getChildElements(runElement);
-	for (const child of children) switch (getLocalName(child.name)) {
-		case "t":
-			contents.push(parseTextContent(child));
-			break;
-		case "tab":
-			contents.push(parseTabContent());
-			break;
-		case "ptab":
-			contents.push(parsePositionalTabContent(child));
-			break;
-		case "br":
-			contents.push(parseBreakContent(child));
-			break;
-		case "sym":
-			contents.push(parseSymbolContent(child));
-			break;
-		case "footnoteReference":
-			contents.push(parseFootnoteReference(child));
-			break;
-		case "endnoteReference":
-			contents.push(parseEndnoteReference(child));
-			break;
-		case "fldChar":
-			contents.push(parseFieldChar(child));
-			break;
-		case "instrText":
-			contents.push(parseInstrText(child));
-			break;
-		case "softHyphen":
-			contents.push({ type: "softHyphen" });
-			break;
-		case "noBreakHyphen":
-			contents.push({ type: "noBreakHyphen" });
-			break;
-		case "drawing": {
-			const drawing = parseDrawingContent(child, rels, media, previews);
-			if (drawing) contents.push(drawing);
-			break;
-		}
-		case "pict": {
-			const vmlDrawing = parseVmlImageContent(child, rels, media, previews, rootXmlns);
-			if (vmlDrawing) {
-				contents.push(vmlDrawing);
+	for (const child of children) {
+		const localName = getLocalName(child.name);
+		switch (localName) {
+			case "t":
+				contents.push(parseTextContent(child));
+				break;
+			case "tab":
+				contents.push(parseTabContent());
+				break;
+			case "ptab":
+				contents.push(parsePositionalTabContent(child));
+				break;
+			case "br":
+				contents.push(parseBreakContent(child));
+				break;
+			case "sym":
+				contents.push(parseSymbolContent(child));
+				break;
+			case "footnoteReference":
+				contents.push(parseFootnoteReference(child));
+				break;
+			case "endnoteReference":
+				contents.push(parseEndnoteReference(child));
+				break;
+			case "footnoteRef":
+			case "endnoteRef":
+				if (WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "")) contents.push({
+					type: "noteMarker",
+					kind: localName === "footnoteRef" ? "footnote" : "endnote"
+				});
+				else contents.push(preserveRunChild(child));
+				break;
+			case "fldChar":
+				contents.push(parseFieldChar(child));
+				break;
+			case "instrText":
+				contents.push(parseInstrText(child));
+				break;
+			case "softHyphen":
+				contents.push({ type: "softHyphen" });
+				break;
+			case "noBreakHyphen":
+				contents.push({ type: "noBreakHyphen" });
+				break;
+			case "drawing": {
+				const drawing = parseDrawingContent(child, rels, media, previews);
+				if (drawing) contents.push(drawing);
 				break;
 			}
-			if (shouldPreserveRawVmlPict(child)) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
-			break;
-		}
-		case "object": {
-			const objectPreview = parseVmlImageContent(child, rels, media, previews, rootXmlns);
-			contents.push(objectPreview ?? preserveRunChild(child));
-			break;
-		}
-		case "rPr": break;
-		case "commentReference": break;
-		case "lastRenderedPageBreak":
-			contents.push({ type: "renderedPageBreak" });
-			break;
-		case "cr":
-			contents.push({
-				type: "break",
-				sourceElement: "cr"
-			});
-			break;
-		case "AlternateContent": {
-			const alternateChildren = getChildElements(child);
-			const choiceEl = alternateChildren.find((el) => getLocalName(el.name) === "Choice");
-			const fallbackEl = alternateChildren.find((el) => getLocalName(el.name) === "Fallback");
-			const contentsBeforeAlternate = contents.length;
-			const choiceTextBoxDrawing = choiceEl ? getChildElements(choiceEl).find((element) => getLocalName(element.name) === "drawing" && isTextBoxDrawing(element)) : void 0;
-			const groupedChoiceDrawing = choiceEl ? getChildElements(choiceEl).find((element) => getLocalName(element.name) === "drawing" && findAllDeep(element, "wpg", "wgp").length > 0) : void 0;
-			if (groupedChoiceDrawing) {
-				const groupedDrawing = parseDrawingContent(groupedChoiceDrawing, rels, media, previews);
-				if (groupedDrawing?.type === "drawing" && groupedDrawing.rawXmlMode === DRAWING_RAW_XML_MODES.PREVIEW_ONLY && groupedDrawing.image.src) {
-					contents.push({
-						...groupedDrawing,
-						rawXml: captureVerbatimXml(child)
-					});
+			case "pict": {
+				const vmlDrawing = parseVmlImageContent(child, rels, media, previews, rootXmlns);
+				if (vmlDrawing) {
+					contents.push(vmlDrawing);
 					break;
 				}
+				if (shouldPreserveRawVmlPict(child)) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
+				break;
 			}
-			const fallbackPict = fallbackEl ? getChildElements(fallbackEl).find((el) => getLocalName(el.name) === "pict") : void 0;
-			const fallbackVml = fallbackPict && !choiceTextBoxDrawing ? parseVmlImageContent(fallbackPict, rels, media, previews, rootXmlns) : null;
-			if (fallbackVml?.image.src) {
-				fallbackVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
-				contents.push(fallbackVml);
+			case "object": {
+				const objectPreview = parseVmlImageContent(child, rels, media, previews, rootXmlns);
+				contents.push(objectPreview ?? preserveRunChild(child));
 				break;
 			}
-			const targetEl = selectAlternateContentBranch(child);
-			if (targetEl) for (const innerChild of getChildElements(targetEl)) {
-				const innerName = getLocalName(innerChild.name);
-				if (innerName === "drawing") {
-					const innerDrawing = parseDrawingContent(innerChild, rels, media, previews);
-					if (innerDrawing) {
-						if (innerDrawing.type === "drawing" && (innerDrawing.rawXml !== void 0 || !innerDrawing.image.src)) innerDrawing.rawXml = captureVerbatimXml(child);
-						if (innerDrawing.type === "shape") {
-							const alternateContent = captureShapeAlternateContent({
-								shape: innerDrawing.shape,
-								alternateContent: child,
-								branch: targetEl,
-								drawing: innerChild
-							});
-							if (alternateContent) innerDrawing.alternateContent = alternateContent;
-						}
-						contents.push(innerDrawing);
-					}
-				} else if (innerName === "pict") {
-					const innerVml = parseVmlImageContent(innerChild, rels, media, previews, rootXmlns);
-					if (innerVml) {
-						innerVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
-						contents.push(innerVml);
+			case "rPr": break;
+			case "commentReference": break;
+			case "lastRenderedPageBreak":
+				contents.push({ type: "renderedPageBreak" });
+				break;
+			case "cr":
+				contents.push({
+					type: "break",
+					sourceElement: "cr"
+				});
+				break;
+			case "AlternateContent": {
+				const alternateChildren = getChildElements(child);
+				const choiceEl = alternateChildren.find((el) => getLocalName(el.name) === "Choice");
+				const fallbackEl = alternateChildren.find((el) => getLocalName(el.name) === "Fallback");
+				const contentsBeforeAlternate = contents.length;
+				const choiceTextBoxDrawing = choiceEl ? getChildElements(choiceEl).find((element) => getLocalName(element.name) === "drawing" && isTextBoxDrawing(element)) : void 0;
+				const groupedChoiceDrawing = choiceEl ? getChildElements(choiceEl).find((element) => getLocalName(element.name) === "drawing" && findAllDeep(element, "wpg", "wgp").length > 0) : void 0;
+				if (groupedChoiceDrawing) {
+					const groupedDrawing = parseDrawingContent(groupedChoiceDrawing, rels, media, previews);
+					if (groupedDrawing?.type === "drawing" && groupedDrawing.rawXmlMode === DRAWING_RAW_XML_MODES.PREVIEW_ONLY && groupedDrawing.image.src) {
+						contents.push({
+							...groupedDrawing,
+							rawXml: captureVerbatimXml(child)
+						});
+						break;
 					}
-				} else contents.push(...parseRunContents({
-					...targetEl,
-					elements: [innerChild]
-				}, rels, media, previews, rootXmlns));
+				}
+				const fallbackPict = fallbackEl ? getChildElements(fallbackEl).find((el) => getLocalName(el.name) === "pict") : void 0;
+				const fallbackVml = fallbackPict && !choiceTextBoxDrawing ? parseVmlImageContent(fallbackPict, rels, media, previews, rootXmlns) : null;
+				if (fallbackVml?.image.src) {
+					fallbackVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
+					contents.push(fallbackVml);
+					break;
+				}
+				const targetEl = selectAlternateContentBranch(child);
+				if (targetEl) for (const innerChild of getChildElements(targetEl)) {
+					const innerName = getLocalName(innerChild.name);
+					if (innerName === "drawing") {
+						const innerDrawing = parseDrawingContent(innerChild, rels, media, previews);
+						if (innerDrawing) {
+							if (innerDrawing.type === "drawing" && (innerDrawing.rawXml !== void 0 || !innerDrawing.image.src)) innerDrawing.rawXml = captureVerbatimXml(child);
+							if (innerDrawing.type === "shape") {
+								const alternateContent = captureShapeAlternateContent({
+									shape: innerDrawing.shape,
+									alternateContent: child,
+									branch: targetEl,
+									drawing: innerChild
+								});
+								if (alternateContent) innerDrawing.alternateContent = alternateContent;
+							}
+							contents.push(innerDrawing);
+						}
+					} else if (innerName === "pict") {
+						const innerVml = parseVmlImageContent(innerChild, rels, media, previews, rootXmlns);
+						if (innerVml) {
+							innerVml.rawXml = captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns));
+							contents.push(innerVml);
+						}
+					} else contents.push(...parseRunContents({
+						...targetEl,
+						elements: [innerChild]
+					}, rels, media, previews, rootXmlns));
+				}
+				const hasTextBoxBranch = [choiceEl, fallbackEl].some((branch) => getChildElements(branch).some((element) => getLocalName(element.name) === "drawing" && isTextBoxDrawing(element)));
+				if (contents.length === contentsBeforeAlternate && !hasTextBoxBranch) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
+				break;
 			}
-			const hasTextBoxBranch = [choiceEl, fallbackEl].some((branch) => getChildElements(branch).some((element) => getLocalName(element.name) === "drawing" && isTextBoxDrawing(element)));
-			if (contents.length === contentsBeforeAlternate && !hasTextBoxBranch) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
-			break;
+			default:
+				contents.push(preserveRunChild(child));
+				break;
 		}
-		default:
-			contents.push(preserveRunChild(child));
-			break;
 	}
 	return contents;
 }

package/dist/docx/saveDiagnostics.d.ts

@@ -0,0 +1,22 @@
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+//#region src/docx/saveDiagnostics.d.ts
+/** Save diagnostics describe fidelity fallbacks without including document content. */
+type SaveDiagnostic = {
+  type: "sourceReplayMismatch";
+  part: string;
+} | {
+  type: "selectiveSaveRefused";
+  part: string;
+} | {
+  type: "sourceReplayUnavailable";
+  part: string;
+} | {
+  type: "canonicalResourceReplacement";
+  gap: typeof CANONICAL_GAP.resourceReplacement;
+  part: string;
+};
+type SaveDiagnosticOptions = {
+  onDiagnostic?: ((diagnostic: SaveDiagnostic) => void) | undefined;
+};
+//#endregion
+export { SaveDiagnostic, SaveDiagnosticOptions };

package/dist/docx/selectiveSave.d.ts

@@ -1,6 +1,8 @@
 import { document_d_exports } from "../types/document.js";
+import { SaveDiagnosticOptions } from "./saveDiagnostics.js";
+import { DocumentBodyAuthorityOptions } from "./serializer/documentSerializer.js";
 //#region src/docx/selectiveSave.d.ts
-type SelectiveSaveOptions = {
+type SelectiveSaveOptions = SaveDiagnosticOptions & DocumentBodyAuthorityOptions & {
   /** Changed paragraph IDs to selectively patch */
   changedParaIds: Set<string>;
   /** Whether paragraph membership, order, or block structure changed. */