@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/sectionParser.js

@@ -1,10 +1,13 @@
+import { NO_MODELLED_ATTRIBUTES, attributeRemainder } from "./attributeRemainder.js";
 import { parseBorderSpec } from "./borderParser.js";
+import { CAPTURE, dispatchChildren, keptUnless, sequencePositions } from "./containerChildren.js";
 import { parseFooterReference, parseHeaderReference } from "./headerFooterRefParser.js";
 import { parseEndnoteProperties, parseFootnoteProperties } from "./notePropertiesParser.js";
-import { NumberFormatSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
+import { NumberFormatSchema, TextDirectionSchema, narrowEnum } from "./parserEnums.js";
 import { parseSectionReferenceHistory } from "./sectionReferenceHistory.js";
+import { parseThemeColorAttribute } from "./themeColorAttribute.js";
 import { parsePropertyChangeInfo } from "./trackedChangeInfo.js";
-import { findChild, findChildren, getAttribute, getChildElements, getLocalName, parseBooleanElement, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
+import { findChild, findChildren, getAttribute, parseBooleanElement, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
 //#region src/docx/sectionParser.ts
 /**
 * Sanity cap on `w:cols/@w:num`. Word's column picker tops out well below
@@ -18,37 +21,6 @@ const MAX_SECTION_COLUMNS = 45;
 * ruler tick generators, which are sized off the page dimensions.
 */
 const MAX_PAGE_DIMENSION_TWIPS = 31680;
-const serializedSectionPropertyChildNames = /* @__PURE__ */ new Set([
-	"headerReference",
-	"footerReference",
-	"footnotePr",
-	"footnoteColumns",
-	"endnotePr",
-	"type",
-	"pgSz",
-	"pgMar",
-	"paperSrc",
-	"pgBorders",
-	"background",
-	"lnNumType",
-	"pgNumType",
-	"cols",
-	"formProt",
-	"vAlign",
-	"noEndnote",
-	"titlePg",
-	"textDirection",
-	"bidi",
-	"rtlGutter",
-	"docGrid",
-	"printerSettings",
-	"sectPrChange"
-]);
-const unserializedSectionPropertyChildNames = Symbol("unserializedSectionPropertyChildNames");
-function getUnserializedSectionPropertyChildNames(props) {
-	const descriptor = Object.getOwnPropertyDescriptor(props, unserializedSectionPropertyChildNames);
-	return Array.isArray(descriptor?.value) ? descriptor.value : void 0;
-}
 /**
 * Parse page orientation
 */
@@ -84,23 +56,6 @@ function parseVerticalAlign(align) {
 		default: return;
 	}
 }
-function parseTextDirection(val) {
-	switch (val) {
-		case "lrTb":
-		case "tbRl":
-		case "btLr":
-		case "lrTbV":
-		case "tbRlV":
-		case "tbLrV":
-		case "tb":
-		case "rl":
-		case "lr":
-		case "tbV":
-		case "rlV":
-		case "lrV": return val;
-		default: return;
-	}
-}
 /**
 * Parse line number restart type
 */
@@ -121,201 +76,249 @@ function parseLineNumberRestart(restart) {
 function parseSectionProperties(sectPr, context) {
 	const props = {};
 	if (!sectPr) return props;
-	const unhandledChildNames = getChildElements(sectPr).map((child) => getLocalName(child.name ?? "")).filter((name) => !serializedSectionPropertyChildNames.has(name));
-	const addUnhandledChildName = (name) => {
-		if (!unhandledChildNames.includes(name)) unhandledChildNames.push(name);
-	};
-	const pgSz = findChild(sectPr, "w", "pgSz");
-	if (pgSz) {
-		const w = parseNumericAttribute(pgSz, "w", "w");
-		if (w !== void 0) props.pageWidth = Math.min(w, MAX_PAGE_DIMENSION_TWIPS);
-		const h = parseNumericAttribute(pgSz, "w", "h");
-		if (h !== void 0) props.pageHeight = Math.min(h, MAX_PAGE_DIMENSION_TWIPS);
-		const orientation = parseOrientation(getAttribute(pgSz, "w", "orient"));
-		if (orientation) props.orientation = orientation;
-	}
-	const pgMar = findChild(sectPr, "w", "pgMar");
-	if (pgMar) {
-		const top = parseNumericAttribute(pgMar, "w", "top");
-		if (top !== void 0) props.marginTop = top;
-		const bottom = parseNumericAttribute(pgMar, "w", "bottom");
-		if (bottom !== void 0) props.marginBottom = bottom;
-		const left = parseNumericAttribute(pgMar, "w", "left");
-		if (left !== void 0) props.marginLeft = left;
-		const right = parseNumericAttribute(pgMar, "w", "right");
-		if (right !== void 0) props.marginRight = right;
-		const header = parseNumericAttribute(pgMar, "w", "header");
-		if (header !== void 0) props.headerDistance = header;
-		const footer = parseNumericAttribute(pgMar, "w", "footer");
-		if (footer !== void 0) props.footerDistance = footer;
-		const gutter = parseNumericAttribute(pgMar, "w", "gutter");
-		if (gutter !== void 0) props.gutter = gutter;
-	}
-	const cols = findChild(sectPr, "w", "cols");
-	if (cols) {
-		const num = parseNumericAttribute(cols, "w", "num");
-		if (num !== void 0) props.columnCount = Math.min(num, MAX_SECTION_COLUMNS);
-		const space = parseNumericAttribute(cols, "w", "space");
-		if (space !== void 0) props.columnSpace = space;
-		const equalWidth = parseOnOffAttribute(cols, "w", "equalWidth");
-		if (equalWidth !== void 0) props.equalWidth = equalWidth;
-		if (parseOnOffAttribute(cols, "w", "sep") === true) props.separator = true;
-		const colElements = findChildren(cols, "w", "col");
-		if (colElements.length > 0) {
-			props.columns = [];
-			for (const colEl of colElements) {
-				const column = {};
-				const colWidth = parseNumericAttribute(colEl, "w", "w");
-				if (colWidth !== void 0) column.width = colWidth;
-				const colSpace = parseNumericAttribute(colEl, "w", "space");
-				if (colSpace !== void 0) column.space = colSpace;
-				props.columns.push(column);
+	const headerRefs = [];
+	const footerRefs = [];
+	const propertyChanges = [];
+	const preserved = dispatchChildren({
+		element: sectPr,
+		container: "section-properties",
+		handlers: {
+			headerReference: (child) => {
+				const reference = parseHeaderReference(child, context);
+				if (reference) headerRefs.push(reference);
+			},
+			footerReference: (child) => {
+				const reference = parseFooterReference(child, context);
+				if (reference) footerRefs.push(reference);
+			},
+			footnotePr: (child) => {
+				const footnotePr = parseFootnoteProperties(child);
+				if (Object.keys(footnotePr).length > 0) {
+					props.footnotePr = footnotePr;
+					return;
+				}
+				return CAPTURE;
+			},
+			endnotePr: (child) => {
+				const endnotePr = parseEndnoteProperties(child);
+				if (Object.keys(endnotePr).length > 0) {
+					props.endnotePr = endnotePr;
+					return;
+				}
+				return CAPTURE;
+			},
+			type: (child) => {
+				const sectionStart = parseSectionStart(getAttribute(child, "w", "val"));
+				if (sectionStart) props.sectionStart = sectionStart;
+				return keptUnless(sectionStart !== void 0);
+			},
+			pgSz: (child) => {
+				const width = parseNumericAttribute(child, "w", "w");
+				if (width !== void 0) props.pageWidth = Math.min(width, MAX_PAGE_DIMENSION_TWIPS);
+				const height = parseNumericAttribute(child, "w", "h");
+				if (height !== void 0) props.pageHeight = Math.min(height, MAX_PAGE_DIMENSION_TWIPS);
+				const orientation = parseOrientation(getAttribute(child, "w", "orient"));
+				if (orientation) props.orientation = orientation;
+				return keptUnless(width !== void 0 || height !== void 0 || orientation !== void 0);
+			},
+			pgMar: (child) => {
+				const margins = [
+					["top", "marginTop"],
+					["bottom", "marginBottom"],
+					["left", "marginLeft"],
+					["right", "marginRight"],
+					["header", "headerDistance"],
+					["footer", "footerDistance"],
+					["gutter", "gutter"]
+				];
+				let taken = false;
+				for (const [attribute, field] of margins) {
+					const value = parseNumericAttribute(child, "w", attribute);
+					if (value !== void 0) {
+						props[field] = value;
+						taken = true;
+					}
+				}
+				return keptUnless(taken);
+			},
+			paperSrc: (child) => {
+				const first = parseNumericAttribute(child, "w", "first");
+				if (first !== void 0) props.paperSrcFirst = first;
+				const other = parseNumericAttribute(child, "w", "other");
+				if (other !== void 0) props.paperSrcOther = other;
+				return keptUnless(first !== void 0 || other !== void 0);
+			},
+			pgBorders: (child) => keptUnless(readPageBorders(props, child, context)),
+			lnNumType: (child) => {
+				const lineNumbers = {};
+				for (const [attribute, field] of [
+					["start", "start"],
+					["countBy", "countBy"],
+					["distance", "distance"]
+				]) {
+					const value = parseNumericAttribute(child, "w", attribute);
+					if (value !== void 0) lineNumbers[field] = value;
+				}
+				const restart = parseLineNumberRestart(getAttribute(child, "w", "restart"));
+				if (restart) lineNumbers.restart = restart;
+				if (Object.keys(lineNumbers).length === 0) return CAPTURE;
+				props.lineNumbers = lineNumbers;
+			},
+			pgNumType: (child) => {
+				const pageNumbering = {};
+				const format = narrowEnum(getAttribute(child, "w", "fmt"), NumberFormatSchema);
+				if (format) pageNumbering.format = format;
+				const start = parseNumericAttribute(child, "w", "start");
+				if (start !== void 0) pageNumbering.start = start;
+				const chapterStyle = parseNumericAttribute(child, "w", "chapStyle");
+				if (chapterStyle !== void 0) pageNumbering.chapterStyle = chapterStyle;
+				const chapterSeparator = getAttribute(child, "w", "chapSep");
+				if (chapterSeparator) pageNumbering.chapterSeparator = chapterSeparator;
+				if (Object.keys(pageNumbering).length === 0) return CAPTURE;
+				props.pageNumbering = pageNumbering;
+			},
+			cols: (child) => keptUnless(readColumns(props, child)),
+			formProt: (child) => {
+				props.formProtection = parseBooleanElement(child, "w", context);
+			},
+			vAlign: (child) => {
+				const verticalAlign = parseVerticalAlign(getAttribute(child, "w", "val"));
+				if (verticalAlign) props.verticalAlign = verticalAlign;
+				return keptUnless(verticalAlign !== void 0);
+			},
+			noEndnote: (child) => {
+				props.noEndnote = parseBooleanElement(child, "w", context);
+			},
+			titlePg: (child) => {
+				props.titlePg = parseBooleanElement(child, "w", context);
+			},
+			textDirection: (child) => {
+				const textDirection = narrowEnum(getAttribute(child, "w", "val"), TextDirectionSchema);
+				if (textDirection) props.textDirection = textDirection;
+				return keptUnless(textDirection !== void 0);
+			},
+			bidi: (child) => {
+				props.bidi = parseBooleanElement(child, "w", context);
+			},
+			rtlGutter: (child) => {
+				props.rtlGutter = parseBooleanElement(child, "w", context);
+			},
+			docGrid: (child) => {
+				const docGrid = {};
+				const gridType = getAttribute(child, "w", "type");
+				if (gridType === "default" || gridType === "lines" || gridType === "linesAndChars" || gridType === "snapToChars") docGrid.type = gridType;
+				const linePitch = parseNumericAttribute(child, "w", "linePitch");
+				if (linePitch !== void 0) docGrid.linePitch = linePitch;
+				const charSpace = parseNumericAttribute(child, "w", "charSpace");
+				if (charSpace !== void 0) docGrid.charSpace = charSpace;
+				props.docGrid = docGrid;
+			},
+			printerSettings: (child) => {
+				const relationshipId = getAttribute(child, "r", "id");
+				if (relationshipId) props.printerSettingsRelationshipId = relationshipId;
+				return keptUnless(Boolean(relationshipId));
+			},
+			sectPrChange: (child) => {
+				const previousSectPr = findChild(child, "w", "sectPr");
+				const change = {
+					type: "sectionPropertyChange",
+					info: parsePropertyChangeInfo(child)
+				};
+				if (previousSectPr) change.previousProperties = parseSectionProperties(previousSectPr);
+				const previousReferences = parseSectionReferenceHistory(child);
+				if (previousReferences !== void 0) change.previousReferences = previousReferences;
+				propertyChanges.push(change);
+			}
+		},
+		capturePosition: sequencePositions("section-properties", sectPr),
+		undeclared: {
+			background: (child) => keptUnless(readBackground(props, child, context)),
+			evenAndOddHeaders: (child) => {
+				props.evenAndOddHeaders = parseBooleanElement(child, "w", context);
+			},
+			footnoteColumns: (child) => {
+				const columns = parseNumericAttribute(child, "w", "val");
+				if (columns !== void 0) props.footnoteColumns = columns;
+				return keptUnless(columns !== void 0);
 			}
-			if (props.columnCount === void 0) props.columnCount = colElements.length;
 		}
-	}
-	const typeEl = findChild(sectPr, "w", "type");
-	if (typeEl) {
-		const sectionStart = parseSectionStart(getAttribute(typeEl, "w", "val"));
-		if (sectionStart) props.sectionStart = sectionStart;
-	}
-	const vAlign = findChild(sectPr, "w", "vAlign");
-	if (vAlign) {
-		const verticalAlign = parseVerticalAlign(getAttribute(vAlign, "w", "val"));
-		if (verticalAlign) props.verticalAlign = verticalAlign;
-	}
-	const textDirection = findChild(sectPr, "w", "textDirection");
-	if (textDirection) {
-		const textDirectionValue = parseTextDirection(getAttribute(textDirection, "w", "val"));
-		if (textDirectionValue) props.textDirection = textDirectionValue;
-		else addUnhandledChildName("textDirection");
-	}
-	const bidi = findChild(sectPr, "w", "bidi");
-	if (bidi) props.bidi = parseBooleanElement(bidi, "w", context);
-	const headerRefs = findChildren(sectPr, "w", "headerReference").flatMap((el) => parseHeaderReference(el, context) ?? []);
+	});
+	if (preserved) props.preserved = preserved;
 	if (headerRefs.length > 0) props.headerReferences = headerRefs;
-	const footerRefs = findChildren(sectPr, "w", "footerReference").flatMap((el) => parseFooterReference(el, context) ?? []);
 	if (footerRefs.length > 0) props.footerReferences = footerRefs;
-	const titlePg = findChild(sectPr, "w", "titlePg");
-	if (titlePg) props.titlePg = parseBooleanElement(titlePg, "w", context);
-	const evenAndOddHeaders = findChild(sectPr, "w", "evenAndOddHeaders");
-	if (evenAndOddHeaders) props.evenAndOddHeaders = parseBooleanElement(evenAndOddHeaders, "w", context);
-	const lnNumType = findChild(sectPr, "w", "lnNumType");
-	if (lnNumType) {
-		props.lineNumbers = {};
-		const start = parseNumericAttribute(lnNumType, "w", "start");
-		if (start !== void 0) props.lineNumbers.start = start;
-		const countBy = parseNumericAttribute(lnNumType, "w", "countBy");
-		if (countBy !== void 0) props.lineNumbers.countBy = countBy;
-		const distance = parseNumericAttribute(lnNumType, "w", "distance");
-		if (distance !== void 0) props.lineNumbers.distance = distance;
-		const restartValue = parseLineNumberRestart(getAttribute(lnNumType, "w", "restart"));
-		if (restartValue) props.lineNumbers.restart = restartValue;
-	}
-	const pgNumType = findChild(sectPr, "w", "pgNumType");
-	if (pgNumType) {
-		const pageNumbering = {};
-		const format = narrowEnum(getAttribute(pgNumType, "w", "fmt"), NumberFormatSchema);
-		if (format) pageNumbering.format = format;
-		const start = parseNumericAttribute(pgNumType, "w", "start");
-		if (start !== void 0) pageNumbering.start = start;
-		const chapterStyle = parseNumericAttribute(pgNumType, "w", "chapStyle");
-		if (chapterStyle !== void 0) pageNumbering.chapterStyle = chapterStyle;
-		const chapterSeparator = getAttribute(pgNumType, "w", "chapSep");
-		if (chapterSeparator) pageNumbering.chapterSeparator = chapterSeparator;
-		if (Object.keys(pageNumbering).length > 0) props.pageNumbering = pageNumbering;
-	}
-	const pgBorders = findChild(sectPr, "w", "pgBorders");
-	if (pgBorders) {
-		props.pageBorders = {};
-		const topBorder = parseBorderSpec(findChild(pgBorders, "w", "top"), context);
-		if (topBorder) props.pageBorders.top = topBorder;
-		const bottomBorder = parseBorderSpec(findChild(pgBorders, "w", "bottom"), context);
-		if (bottomBorder) props.pageBorders.bottom = bottomBorder;
-		const leftBorder = parseBorderSpec(findChild(pgBorders, "w", "left"), context);
-		if (leftBorder) props.pageBorders.left = leftBorder;
-		const rightBorder = parseBorderSpec(findChild(pgBorders, "w", "right"), context);
-		if (rightBorder) props.pageBorders.right = rightBorder;
-		const display = getAttribute(pgBorders, "w", "display");
-		if (display === "allPages" || display === "firstPage" || display === "notFirstPage") props.pageBorders.display = display;
-		const offsetFrom = getAttribute(pgBorders, "w", "offsetFrom");
-		if (offsetFrom === "page" || offsetFrom === "text") props.pageBorders.offsetFrom = offsetFrom;
-		const zOrder = getAttribute(pgBorders, "w", "zOrder");
-		if (zOrder === "front" || zOrder === "back") props.pageBorders.zOrder = zOrder;
-	}
-	const background = findChild(sectPr, "w", "background");
-	if (background) {
-		props.background = {};
-		const colorVal = getAttribute(background, "w", "color");
-		if (colorVal && colorVal !== "auto") props.background.color = { rgb: colorVal };
-		const backgroundThemeColor = narrowEnum(getAttribute(background, "w", "themeColor"), ThemeColorSlotSchema);
-		if (backgroundThemeColor) props.background.themeColor = backgroundThemeColor;
-		const themeTint = getAttribute(background, "w", "themeTint");
-		if (themeTint) props.background.themeTint = themeTint;
-		const themeShade = getAttribute(background, "w", "themeShade");
-		if (themeShade) props.background.themeShade = themeShade;
-	}
-	const footnotePr = findChild(sectPr, "w", "footnotePr");
-	if (footnotePr) {
-		const fnProps = parseFootnoteProperties(footnotePr);
-		if (Object.keys(fnProps).length > 0) props.footnotePr = fnProps;
-	}
-	const footnoteColumns = findChild(sectPr, "w15", "footnoteColumns");
-	if (footnoteColumns) {
-		const columns = parseNumericAttribute(footnoteColumns, "w", "val");
-		if (columns !== void 0) props.footnoteColumns = columns;
-	}
-	const endnotePr = findChild(sectPr, "w", "endnotePr");
-	if (endnotePr) {
-		const enProps = parseEndnoteProperties(endnotePr);
-		if (Object.keys(enProps).length > 0) props.endnotePr = enProps;
-	}
-	const formProt = findChild(sectPr, "w", "formProt");
-	if (formProt) props.formProtection = parseBooleanElement(formProt, "w", context);
-	const noEndnote = findChild(sectPr, "w", "noEndnote");
-	if (noEndnote) props.noEndnote = parseBooleanElement(noEndnote, "w", context);
-	const rtlGutter = findChild(sectPr, "w", "rtlGutter");
-	if (rtlGutter) props.rtlGutter = parseBooleanElement(rtlGutter, "w", context);
-	const docGrid = findChild(sectPr, "w", "docGrid");
-	if (docGrid) {
-		props.docGrid = {};
-		const gridType = getAttribute(docGrid, "w", "type");
-		if (gridType === "default" || gridType === "lines" || gridType === "linesAndChars" || gridType === "snapToChars") props.docGrid.type = gridType;
-		const linePitch = parseNumericAttribute(docGrid, "w", "linePitch");
-		if (linePitch !== void 0) props.docGrid.linePitch = linePitch;
-		const charSpace = parseNumericAttribute(docGrid, "w", "charSpace");
-		if (charSpace !== void 0) props.docGrid.charSpace = charSpace;
-	}
-	const paperSrc = findChild(sectPr, "w", "paperSrc");
-	if (paperSrc) {
-		const first = parseNumericAttribute(paperSrc, "w", "first");
-		if (first !== void 0) props.paperSrcFirst = first;
-		const other = parseNumericAttribute(paperSrc, "w", "other");
-		if (other !== void 0) props.paperSrcOther = other;
-	}
-	const printerSettings = findChild(sectPr, "w", "printerSettings");
-	if (printerSettings) {
-		const relationshipId = getAttribute(printerSettings, "r", "id");
-		if (relationshipId) props.printerSettingsRelationshipId = relationshipId;
-	}
-	const propertyChanges = findChildren(sectPr, "w", "sectPrChange").map((changeElement) => {
-		const previousSectPr = findChild(changeElement, "w", "sectPr");
-		const change = {
-			type: "sectionPropertyChange",
-			info: parsePropertyChangeInfo(changeElement)
-		};
-		if (previousSectPr) change.previousProperties = parseSectionProperties(previousSectPr);
-		const previousReferences = parseSectionReferenceHistory(changeElement);
-		if (previousReferences !== void 0) change.previousReferences = previousReferences;
-		return change;
-	});
 	if (propertyChanges.length > 0) props.propertyChanges = propertyChanges;
-	Object.defineProperty(props, unserializedSectionPropertyChildNames, {
-		enumerable: true,
-		value: unhandledChildNames
+	const remainder = attributeRemainder({
+		element: sectPr,
+		modelled: NO_MODELLED_ATTRIBUTES
 	});
+	if (remainder) props.preservedAttributes = remainder;
 	return props;
 }
+/** `w:cols`, into the four scalars and the per-column list. Did it state anything? */
+function readColumns(props, cols) {
+	const num = parseNumericAttribute(cols, "w", "num");
+	if (num !== void 0) props.columnCount = Math.min(num, MAX_SECTION_COLUMNS);
+	const space = parseNumericAttribute(cols, "w", "space");
+	if (space !== void 0) props.columnSpace = space;
+	const equalWidth = parseOnOffAttribute(cols, "w", "equalWidth");
+	if (equalWidth !== void 0) props.equalWidth = equalWidth;
+	const separator = parseOnOffAttribute(cols, "w", "sep");
+	if (separator !== void 0) props.separator = separator;
+	const colElements = findChildren(cols, "w", "col");
+	if (colElements.length > 0) {
+		props.columns = colElements.map((colEl) => {
+			const column = {};
+			const colWidth = parseNumericAttribute(colEl, "w", "w");
+			if (colWidth !== void 0) column.width = colWidth;
+			const colSpace = parseNumericAttribute(colEl, "w", "space");
+			if (colSpace !== void 0) column.space = colSpace;
+			return column;
+		});
+		if (props.columnCount === void 0) props.columnCount = colElements.length;
+	}
+	return num !== void 0 || space !== void 0 || equalWidth !== void 0 || separator !== void 0 || colElements.length > 0;
+}
+/** `w:pgBorders`, into the four sides and the three placement attributes. */
+function readPageBorders(props, pgBorders, context) {
+	const pageBorders = {};
+	for (const side of [
+		"top",
+		"bottom",
+		"left",
+		"right"
+	]) {
+		const border = parseBorderSpec(findChild(pgBorders, "w", side), context);
+		if (border) pageBorders[side] = border;
+	}
+	const display = getAttribute(pgBorders, "w", "display");
+	if (display === "allPages" || display === "firstPage" || display === "notFirstPage") pageBorders.display = display;
+	const offsetFrom = getAttribute(pgBorders, "w", "offsetFrom");
+	if (offsetFrom === "page" || offsetFrom === "text") pageBorders.offsetFrom = offsetFrom;
+	const zOrder = getAttribute(pgBorders, "w", "zOrder");
+	if (zOrder === "front" || zOrder === "back") pageBorders.zOrder = zOrder;
+	if (Object.keys(pageBorders).length === 0) return false;
+	props.pageBorders = pageBorders;
+	return true;
+}
+/** `w:background`, the page colour a producer wrote on the section. */
+function readBackground(props, background, context) {
+	const pageBackground = {};
+	const colorVal = getAttribute(background, "w", "color");
+	if (colorVal && colorVal !== "auto") pageBackground.color = { rgb: colorVal };
+	const backgroundThemeColor = parseThemeColorAttribute({
+		raw: getAttribute(background, "w", "themeColor"),
+		element: background.name ?? "w:background",
+		context
+	});
+	if (backgroundThemeColor !== void 0) pageBackground.themeColor = backgroundThemeColor;
+	const themeTint = getAttribute(background, "w", "themeTint");
+	if (themeTint) pageBackground.themeTint = themeTint;
+	const themeShade = getAttribute(background, "w", "themeShade");
+	if (themeShade) pageBackground.themeShade = themeShade;
+	if (Object.keys(pageBackground).length === 0) return false;
+	props.background = pageBackground;
+	return true;
+}
 /**
 * Get page width in pixels (96 DPI)
 *
@@ -489,4 +492,4 @@ function mergeSectionProperties(base, override) {
 	return result;
 }
 //#endregion
-export { getColumnCount, getContentHeightPixels, getContentWidthPixels, getDefaultSectionProperties, getMarginsPixels, getPageHeightPixels, getPageWidthPixels, getUnserializedSectionPropertyChildNames, hasDifferentFirstPage, hasDifferentOddEven, hasLineNumbers, hasPageBorders, isLandscape, mergeSectionProperties, parseSectionProperties };
+export { getColumnCount, getContentHeightPixels, getContentWidthPixels, getDefaultSectionProperties, getMarginsPixels, getPageHeightPixels, getPageWidthPixels, hasDifferentFirstPage, hasDifferentOddEven, hasLineNumbers, hasPageBorders, isLandscape, mergeSectionProperties, parseSectionProperties };

package/dist/docx/selectiveSave.js

@@ -199,7 +199,8 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 			const docXmlFile = zip.file("word/document.xml");
 			if (!docXmlFile) return null;
 			const originalDocXml = await docXmlFile.async("text");
-			const bodyParaIds = collectParaIds(originalDocXml);
+			const serializedDocXml = serializeDocument(doc, readRootNamespaceBindings(originalDocXml));
+			const bodyParaIds = collectParaIds(serializedDocXml);
 			const bodyChangedIds = /* @__PURE__ */ new Set();
 			const noteCandidateIds = /* @__PURE__ */ new Set();
 			for (const id of changedParaIds) if (bodyParaIds.has(id)) bodyChangedIds.add(id);
@@ -209,7 +210,7 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 				if (unrouted === null || unrouted.size > 0) return null;
 			}
 			if (bodyChangedIds.size > 0) {
-				const patchedDocXml = buildPatchedDocumentXml(originalDocXml, serializeDocument(doc, readRootNamespaceBindings(originalDocXml)), bodyChangedIds);
+				const patchedDocXml = buildPatchedDocumentXml(originalDocXml, serializedDocXml, bodyChangedIds);
 				if (!patchedDocXml) return null;
 				updates.set("word/document.xml", patchedDocXml);
 			}

package/dist/docx/selectiveXmlPatch.d.ts

@@ -54,6 +54,24 @@ type ParagraphOffsets = {
  * function would return null.
  */
 declare function buildParagraphOffsetIndex(xml: string): Map<string, ParagraphOffsets>;
+/** One `<w:p>` of a part: its byte range and the paraId its open tag carries. */
+type ScannedParagraph = ParagraphOffsets & {
+  paraId: string | undefined;
+};
+/**
+ * Every `<w:p>` element of `xml`, in the document order of its opening tags,
+ * with the `w14:paraId` that tag carries.
+ *
+ * Document order is what makes the array an ordinal space: the *n*th entry of
+ * the source part and the *n*th entry of the model's serialization name the
+ * same paragraph, which is the only way to address a paragraph the producer
+ * gave no id. A `<w:p>` nested inside another (inside `mc:AlternateContent`,
+ * a text box) is one entry of its own, exactly as
+ * {@link countParagraphElements} counts it, so the two never disagree about
+ * what an ordinal is. An unterminated paragraph keeps `end === start`: it
+ * occupies its ordinal but no splice can be built from it.
+ */
+declare function scanParagraphs(xml: string): ScannedParagraph[];
 /**
  * Count <w:p> elements in an XML string (top-level paragraph count).
  * Counts opening <w:p tags that are NOT self-closing.
@@ -81,7 +99,8 @@ type PatchSafetyOptions = {
  * Validate that a selective patch can be safely applied.
  *
  * Checks:
- * - All changed paraIds exist in original XML (exactly once)
+ * - Every changed paraId routes to one region of the original XML, by its
+ *   authored id or, when the producer wrote none, by its paragraph ordinal
  * - All changed paraIds exist in serialized XML (exactly once)
  * - Paragraph count matches between original and serialized (unless disabled)
  */
@@ -109,6 +128,24 @@ declare function buildPatchedDocumentXml(originalXml: string, serializedXml: str
  * the caller can fall back to preserving the original part verbatim.
  */
 declare function buildPatchedNoteXml(originalXml: string, serializedXml: string, changedIds: Set<string>): string | null;
+/** One region of a part replaced by re-serialized XML. */
+type XmlSplice = {
+  start: number;
+  end: number;
+  newXml: string;
+};
+/**
+ * Apply `splices` to `xml`, end-to-start so earlier offsets stay valid.
+ *
+ * Every selective patch is a splice, and every splice goes through here, so
+ * the refusal below is a property of the operation rather than a check each
+ * site has to remember. A patch rewrites the regions an edit touched and keeps
+ * the rest of the part byte-for-byte, so it can write half a comment range:
+ * invalid OOXML that anchors the comment to nothing. Answers null when it
+ * would, leaving the caller to rewrite a wider region — ultimately the whole
+ * part from the model, which is balanced with itself.
+ */
+declare const spliceXml: (xml: string, splices: readonly XmlSplice[]) => string | null;
 type NoteElementName = "footnote" | "endnote";
 declare const collectChangedNoteParaIds: (baselineXml: string, currentXml: string) => Set<string>;
 type BuildPatchedNotePartXmlOptions = {
@@ -119,6 +156,25 @@ type BuildPatchedNotePartXmlOptions = {
   elementName: NoteElementName;
   changedParaIds?: ReadonlySet<string>;
 };
+/** Why a note part could not be patched; see {@link NotePartPatch}. */
+type NotePartPatchRefusal =
+/** A note element, or a changed paragraph, was missing or ambiguous. */
+"unroutable-paragraph" |
+/** Even rewriting whole notes would leave a comment range with one half. */
+"comment-range-balance";
+/**
+ * What patching a note part produced. `refused` is not a failure to serialize:
+ * the caller writes the part from the model instead, the note-part reading of
+ * the fall back to a full repack the document story takes when its own splice
+ * is refused.
+ */
+type NotePartPatch = {
+  type: "patched";
+  xml: string;
+} | {
+  type: "refused";
+  reason: NotePartPatchRefusal;
+};
 /**
  * Patch an existing note part from its model serialization.
  *
@@ -130,8 +186,15 @@ type BuildPatchedNotePartXmlOptions = {
  * notes, and unaffected equal-shape paragraphs remain byte-exact.
  * `replacementXml` also supplies synthesized automatic note-reference marks,
  * which the parsed model intentionally omits.
+ *
+ * A comment can be anchored on a note's own text, so its range spans that
+ * note's paragraphs and an edit inside the span moves a range half from one
+ * paragraph to another. Replacing only the dirty paragraph then drops the half
+ * it held and leaves the other standing, so {@link spliceXml} refuses the
+ * result and the changed notes are rewritten whole instead — model content on
+ * both sides of the range, with every other note still byte-exact.
  */
-declare function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }: BuildPatchedNotePartXmlOptions): string | null;
+declare function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }: BuildPatchedNotePartXmlOptions): NotePartPatch;
 type ChangedNumberingDefs = {
   abstractNums: Set<string>;
   nums: Set<string>;
@@ -178,4 +241,4 @@ declare const patchNumberingDefinitions: ({ originalXml, baselineXml, currentXml
  */
 declare function appendNumberingDefs(xml: string, currentXml: string, added: ChangedNumberingDefs): string | null;
 //#endregion
-export { ChangedNumberingDefs, ParagraphOffsets, PatchSafetyOptions, PatchValidationResult, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, validatePatchSafety };
+export { ChangedNumberingDefs, NotePartPatch, NotePartPatchRefusal, ParagraphOffsets, PatchSafetyOptions, PatchValidationResult, ScannedParagraph, XmlSplice, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, scanParagraphs, spliceXml, validatePatchSafety };