@stll/folio-core 0.43.0 → 0.44.0

package/dist/docx/rezip.js

@@ -10,6 +10,7 @@ import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
 import { parseHeaderFooterType } from "./headerFooterRefParser.js";
 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 { isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries } from "./packageParts.js";
@@ -1389,6 +1390,42 @@ async function serializeNumberingIntoZip(doc, originalZip, newZip, compressionLe
 }
 const STYLES_PART_PATH = "word/styles.xml";
 const STYLES_CLOSE_ROOT = "</w:styles>";
+/**
+* The style table a package folio creates starts from: `docDefaults` and
+* `Normal`, and nothing else. A document that carries its own style table
+* replaces this part wholesale.
+*/
+const SEED_STYLES_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:docDefaults>
+    <w:rPrDefault>
+      <w:rPr>
+        <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>
+        <w:sz w:val="22"/>
+      </w:rPr>
+    </w:rPrDefault>
+    <w:pPrDefault>
+      <w:pPr>
+        <w:spacing w:after="200" w:line="276" w:lineRule="auto"/>
+      </w:pPr>
+    </w:pPrDefault>
+  </w:docDefaults>
+  <w:style w:type="paragraph" w:default="1" w:styleId="Normal">
+    <w:name w:val="Normal"/>
+  </w:style>
+</w:styles>`;
+/**
+* The seed part plus the reference styles this package's comments and notes
+* need. A document with no style table of its own never reaches
+* {@link styleDefinitionsToSerialize}, so without this its reference marks
+* would carry a `w:rStyle` naming nothing — the defect
+* `noteReferenceStyles.ts` exists to remove, on the one path that skips it.
+*/
+const seedStylesXmlWith = (missing) => {
+	if (missing.length === 0) return SEED_STYLES_XML;
+	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;
 /**
 * Append styles the model defines but the original `word/styles.xml` lacks.
@@ -1397,6 +1434,27 @@ const STYLE_ID_PATTERN = /<w:style\b[^>]*?\bw:styleId="(?<id>[^"]+)"/gu;
 * per-language clones a bilingual transform adds, are emitted before the root
 * close so paragraphs referencing them resolve on reopen.
 */
+/**
+* The styles to write into a package folio is authoring: the model's, plus any
+* reference character style the serializers are about to emit for this
+* package's comments and notes but the style table does not define. See
+* `noteReferenceStyles.ts` — the reference mark would otherwise carry a
+* `w:rStyle` pointing at nothing.
+*
+* Only for a package folio writes from scratch. Repacking a document someone
+* else authored preserves `word/styles.xml` byte for byte, and adding a
+* definition there would rewrite a part the user never edited: their document,
+* their style table, missing reference style included.
+*/
+const styleDefinitionsToSerialize = (doc) => {
+	const styles = doc.package.styles;
+	if (!styles) return;
+	const missing = missingNoteReferenceStyles(styles, noteReferenceNeeds(doc.package));
+	return missing.length === 0 ? styles : {
+		...styles,
+		styles: [...styles.styles, ...missing]
+	};
+};
 async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compressionLevel) {
 	const styles = doc.package.styles;
 	if (!styles || styles.styles.length === 0) return;
@@ -1578,25 +1636,7 @@ const createEmptyDocxZip = ({ creator, application }) => {
     </w:sectPr>
   </w:body>
 </w:document>`);
-	zip.file("word/styles.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
-  <w:docDefaults>
-    <w:rPrDefault>
-      <w:rPr>
-        <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>
-        <w:sz w:val="22"/>
-      </w:rPr>
-    </w:rPrDefault>
-    <w:pPrDefault>
-      <w:pPr>
-        <w:spacing w:after="200" w:line="276" w:lineRule="auto"/>
-      </w:pPr>
-    </w:pPrDefault>
-  </w:docDefaults>
-  <w:style w:type="paragraph" w:default="1" w:styleId="Normal">
-    <w:name w:val="Normal"/>
-  </w:style>
-</w:styles>`);
+	zip.file(STYLES_PART_PATH, SEED_STYLES_XML);
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	const creatorElement = creator === void 0 ? "" : `\n  <dc:creator>${escapeXml(creator)}</dc:creator>`;
 	zip.file("docProps/core.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
@@ -1647,10 +1687,11 @@ const createDocumentSeedZip = async (doc, properties) => {
 	const relationships = ["<Relationship Id=\"rId1\" Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles\" Target=\"styles.xml\"/>"];
 	const overrides = [];
 	let nextRelationshipId = 2;
-	if (doc.package.styles) {
+	const styleDefinitions = styleDefinitionsToSerialize(doc);
+	if (styleDefinitions) {
 		assertStyleNumberingReferences(doc);
-		zip.file("word/styles.xml", serializeStylesXml(doc.package.styles));
-	}
+		zip.file(STYLES_PART_PATH, serializeStylesXml(styleDefinitions));
+	} else zip.file(STYLES_PART_PATH, seedStylesXmlWith(missingNoteReferenceStyles(void 0, noteReferenceNeeds(doc.package))));
 	const numbering = doc.package.numbering;
 	if (numbering && (numbering.abstractNums.length > 0 || numbering.nums.length > 0)) {
 		zip.file("word/numbering.xml", serializeNumberingXml(numbering));

package/dist/docx/runConsolidator.js

@@ -114,8 +114,7 @@ function mergeRunContent(content1, content2) {
 	if (lastText?.type === "text" && firstText?.type === "text") {
 		result[result.length - 1] = {
 			type: "text",
-			text: lastText.text + firstText.text,
-			...lastText.preserveSpace || firstText.preserveSpace ? { preserveSpace: true } : {}
+			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);

package/dist/docx/runParser.d.ts

@@ -2,6 +2,13 @@ import { document_d_exports } from "../types/document.js";
 import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/runParser.d.ts
+/**
+ * `w:vertAlign` `baseline` is the reserved value that means "no vertical
+ * offset", not a third offset beside `superscript` and `subscript`. It is
+ * answered here because this module reads the slot, so a consumer deciding
+ * whether a run sits on the baseline cannot drift from how it was parsed.
+ */
+declare const isBaselineVertAlign: (vertAlign: document_d_exports.TextFormatting["vertAlign"]) => boolean;
 /**
  * Parse run formatting properties (w:rPr)
  *
@@ -74,4 +81,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, parseRun, parseRunProperties };
+export { getFieldCharType, getImages, getRunText, hasContent, hasFieldChar, hasImage, isBaselineVertAlign, parseRun, parseRunProperties };

package/dist/docx/runParser.js

@@ -1,18 +1,17 @@
-import { isValidHexColor } from "../utils/colorResolver.js";
 import { parseHorizontalScalePercent } from "../utils/horizontalScale.js";
 import { parseDiagramPreview } from "./diagramPreview.js";
 import { isGroupDrawing, parseGroupDrawing } from "./groupDrawingParser.js";
 import { parseImage } from "./imageParser.js";
 import { imageRawXmlFingerprint } from "./imageRawXml.js";
-import { EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, ShadingPatternSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
+import { EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
+import { parseShading } from "./shadingParser.js";
 import { parseShapeFromDrawing, shouldPreserveRawShapeDrawing } from "./shapeParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
-import { requiresXmlSpacePreserve } from "./textWhitespace.js";
 import { resolveThemeFontRef } from "./themeParser.js";
 import { parsePropertyChangeInfo } from "./trackedChangeInfo.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { parseVmlImageContent, shouldPreserveRawVmlPict } from "./vmlImageParser.js";
-import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, selectAlternateContentBranch } from "./xmlParser.js";
+import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, parseOnOffAttribute, selectAlternateContentBranch } from "./xmlParser.js";
 import { DRAWING_RAW_XML_MODES } from "@stll/docx-core/model";
 //#region src/docx/runParser.ts
 /**
@@ -36,31 +35,6 @@ function parseColorValue(rgb, themeColor, themeTint, themeShade) {
 	if (themeShade) color.themeShade = themeShade;
 	return color;
 }
-/**
-* Parse shading properties (w:shd)
-*/
-function parseShadingProperties(shd) {
-	if (!shd) return;
-	const props = {};
-	const color = getAttribute(shd, "w", "color");
-	if (color === "auto") props.color = { auto: true };
-	else if (color && isValidHexColor(color)) props.color = { rgb: color };
-	const fill = getAttribute(shd, "w", "fill");
-	if (fill === "auto") props.fill = { auto: true };
-	else if (fill && isValidHexColor(fill)) props.fill = { rgb: fill };
-	const validatedThemeFill = narrowEnum(getAttribute(shd, "w", "themeFill"), ThemeColorSlotSchema);
-	if (validatedThemeFill) {
-		if (!props.fill) props.fill = {};
-		props.fill.themeColor = validatedThemeFill;
-	}
-	const themeFillTint = getAttribute(shd, "w", "themeFillTint");
-	if (themeFillTint && props.fill) props.fill.themeTint = themeFillTint;
-	const themeFillShade = getAttribute(shd, "w", "themeFillShade");
-	if (themeFillShade && props.fill) props.fill.themeShade = themeFillShade;
-	const pattern = narrowEnum(getAttribute(shd, "w", "val"), ShadingPatternSchema);
-	if (pattern) props.pattern = pattern;
-	return Object.keys(props).length > 0 ? props : void 0;
-}
 function collectFirstRunPropertyChildren(rPr) {
 	const children = {};
 	for (const child of rPr.elements ?? []) {
@@ -167,6 +141,13 @@ function collectFirstRunPropertyChildren(rPr) {
 	return children;
 }
 /**
+* `w:vertAlign` `baseline` is the reserved value that means "no vertical
+* offset", not a third offset beside `superscript` and `subscript`. It is
+* answered here because this module reads the slot, so a consumer deciding
+* whether a run sits on the baseline cannot drift from how it was parsed.
+*/
+const isBaselineVertAlign = (vertAlign) => vertAlign === "baseline";
+/**
 * Parse run formatting properties (w:rPr)
 *
 * Handles ALL rPr properties:
@@ -231,7 +212,7 @@ function parseRunProperties(rPr, theme, _styles) {
 	}
 	const shd = propertyChildren.shd;
 	if (shd) {
-		const shadingResult = parseShadingProperties(shd);
+		const shadingResult = parseShading(shd);
 		if (shadingResult) formatting.shading = shadingResult;
 	}
 	const sz = propertyChildren.sz;
@@ -370,14 +351,10 @@ function parseRunPropertyChanges(rPr, theme, styles, currentFormatting) {
 * Parse text content (w:t)
 */
 function parseTextContent(element) {
-	const text = getTextContent(element);
-	const preserveSpace = getAttribute(element, "xml", "space") === "preserve" || requiresXmlSpacePreserve(text);
-	const content = {
+	return {
 		type: "text",
-		text
+		text: getTextContent(element)
 	};
-	if (preserveSpace) content.preserveSpace = true;
-	return content;
 }
 /**
 * Parse tab element (w:tab)
@@ -442,8 +419,8 @@ function parseEndnoteReference(element) {
 */
 function parseFieldChar(element) {
 	const fldCharType = getAttribute(element, "w", "fldCharType");
-	const fldLock = getAttribute(element, "w", "fldLock") === "true" || getAttribute(element, "w", "fldLock") === "1";
-	const dirty = getAttribute(element, "w", "dirty") === "true" || getAttribute(element, "w", "dirty") === "1";
+	const fldLock = parseOnOffAttribute(element, "w", "fldLock") === true;
+	const dirty = parseOnOffAttribute(element, "w", "dirty") === true;
 	let charType = "begin";
 	if (fldCharType === "separate") charType = "separate";
 	else if (fldCharType === "end") charType = "end";
@@ -473,15 +450,14 @@ function parseInstrText(element) {
 * Wrap raw XML the model cannot project at all.
 *
 * `DrawingContent` always carries an `Image`, so preservation-only content
-* gets a placeholder one: the empty `rId` marks it as backed by no
-* relationship, which keeps `classifyDrawingSafety` and the serializer on the
-* replay path instead of regenerating DrawingML from the placeholder.
+* gets a placeholder one. It names no relationship, which keeps
+* `classifyDrawingSafety` and the serializer on the replay path instead of
+* regenerating DrawingML from the placeholder.
 */
 const preserveOnlyDrawing = (rawXml) => ({
 	type: "drawing",
 	image: {
 		type: "image",
-		rId: "",
 		size: {
 			width: 0,
 			height: 0
@@ -530,13 +506,19 @@ function parseDrawingContent(element, rels, media) {
 	};
 	const image = parseImage(element, rels ?? void 0, media ?? void 0);
 	if (!image) return null;
-	const drawing = {
+	const rawXml = captureVerbatimXml(element);
+	if (image.rId === void 0) return {
+		type: "drawing",
+		image,
+		rawXml,
+		rawXmlMode: DRAWING_RAW_XML_MODES.PRESERVE_ONLY
+	};
+	return {
 		type: "drawing",
-		image
+		image,
+		rawXml,
+		rawImageFingerprint: imageRawXmlFingerprint(image)
 	};
-	drawing.rawXml = captureVerbatimXml(element);
-	drawing.rawImageFingerprint = imageRawXmlFingerprint(image);
-	return drawing;
 }
 /**
 * Parse all content within a run element
@@ -750,4 +732,4 @@ function getFieldCharType(run) {
 	return run.content.find((c) => c.type === "fieldChar")?.charType ?? null;
 }
 //#endregion
-export { getFieldCharType, getImages, getRunText, hasContent, hasFieldChar, hasImage, parseRun, parseRunProperties };
+export { getFieldCharType, getImages, getRunText, hasContent, hasFieldChar, hasImage, isBaselineVertAlign, parseRun, parseRunProperties };

package/dist/docx/sectionParser.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../types/document.js";
+import { ParseContext } from "./parseContext.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/sectionParser.d.ts
 declare function getUnserializedSectionPropertyChildNames(props: document_d_exports.SectionProperties): readonly string[] | undefined;
@@ -8,7 +9,7 @@ declare function getUnserializedSectionPropertyChildNames(props: document_d_expo
  * @param sectPr - The w:sectPr element
  * @returns SectionProperties object
  */
-declare function parseSectionProperties(sectPr: XmlElement | null): document_d_exports.SectionProperties;
+declare function parseSectionProperties(sectPr: XmlElement | null, context?: ParseContext): document_d_exports.SectionProperties;
 /**
  * Get page width in pixels (96 DPI)
  *

package/dist/docx/sectionParser.js

@@ -1,9 +1,10 @@
+import { parseBorderSpec } from "./borderParser.js";
 import { parseFooterReference, parseHeaderReference } from "./headerFooterRefParser.js";
 import { parseEndnoteProperties, parseFootnoteProperties } from "./notePropertiesParser.js";
-import { BorderStyleSchema, NumberFormatSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
+import { NumberFormatSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
 import { parseSectionReferenceHistory } from "./sectionReferenceHistory.js";
 import { parsePropertyChangeInfo } from "./trackedChangeInfo.js";
-import { findChild, findChildren, getAttribute, getChildElements, getLocalName, parseBooleanElement, parseNumericAttribute } from "./xmlParser.js";
+import { findChild, findChildren, getAttribute, getChildElements, getLocalName, 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
@@ -49,49 +50,6 @@ function getUnserializedSectionPropertyChildNames(props) {
 	return Array.isArray(descriptor?.value) ? descriptor.value : void 0;
 }
 /**
-* Parse a color element/attribute for page borders/background
-*/
-function parseColorValue(colorStr, themeColor, themeTint, themeShade) {
-	if (!colorStr && !themeColor) return;
-	const color = {};
-	if (colorStr && colorStr !== "auto") color.rgb = colorStr;
-	else if (colorStr === "auto") color.auto = true;
-	const validatedThemeColor = narrowEnum(themeColor, ThemeColorSlotSchema);
-	if (validatedThemeColor) color.themeColor = validatedThemeColor;
-	if (themeTint) color.themeTint = themeTint;
-	if (themeShade) color.themeShade = themeShade;
-	return Object.keys(color).length > 0 ? color : void 0;
-}
-/**
-* Parse a border element for page borders
-*/
-function parseBorderSpec(element) {
-	if (!element) return;
-	const rawStyle = getAttribute(element, "w", "val") ?? "none";
-	const border = { style: narrowEnum(rawStyle, BorderStyleSchema) ?? rawStyle };
-	const sz = parseNumericAttribute(element, "w", "sz");
-	if (sz !== void 0) border.size = sz;
-	const space = parseNumericAttribute(element, "w", "space");
-	if (space !== void 0) border.space = space;
-	const color = parseColorValue(getAttribute(element, "w", "color"), getAttribute(element, "w", "themeColor"), getAttribute(element, "w", "themeTint"), getAttribute(element, "w", "themeShade"));
-	if (color) border.color = color;
-	const shadow = getAttribute(element, "w", "shadow");
-	if (shadow === "1" || shadow === "true") border.shadow = true;
-	const frame = getAttribute(element, "w", "frame");
-	if (frame === "1" || frame === "true") border.frame = true;
-	const artRelationshipId = getAttribute(element, "w", "id")?.trim();
-	if (artRelationshipId) border.artRelationshipId = artRelationshipId;
-	const topLeftArtRelationshipId = getAttribute(element, "w", "topLeft")?.trim();
-	if (topLeftArtRelationshipId) border.topLeftArtRelationshipId = topLeftArtRelationshipId;
-	const topRightArtRelationshipId = getAttribute(element, "w", "topRight")?.trim();
-	if (topRightArtRelationshipId) border.topRightArtRelationshipId = topRightArtRelationshipId;
-	const bottomLeftArtRelationshipId = getAttribute(element, "w", "bottomLeft")?.trim();
-	if (bottomLeftArtRelationshipId) border.bottomLeftArtRelationshipId = bottomLeftArtRelationshipId;
-	const bottomRightArtRelationshipId = getAttribute(element, "w", "bottomRight")?.trim();
-	if (bottomRightArtRelationshipId) border.bottomRightArtRelationshipId = bottomRightArtRelationshipId;
-	return border;
-}
-/**
 * Parse page orientation
 */
 function parseOrientation(orient) {
@@ -160,7 +118,7 @@ function parseLineNumberRestart(restart) {
 * @param sectPr - The w:sectPr element
 * @returns SectionProperties object
 */
-function parseSectionProperties(sectPr) {
+function parseSectionProperties(sectPr, context) {
 	const props = {};
 	if (!sectPr) return props;
 	const unhandledChildNames = getChildElements(sectPr).map((child) => getLocalName(child.name ?? "")).filter((name) => !serializedSectionPropertyChildNames.has(name));
@@ -199,11 +157,9 @@ function parseSectionProperties(sectPr) {
 		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 = getAttribute(cols, "w", "equalWidth");
-		if (equalWidth === "1" || equalWidth === "true") props.equalWidth = true;
-		else if (equalWidth === "0" || equalWidth === "false") props.equalWidth = false;
-		const sep = getAttribute(cols, "w", "sep");
-		if (sep === "1" || sep === "true") props.separator = true;
+		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 = [];
@@ -235,15 +191,15 @@ function parseSectionProperties(sectPr) {
 		else addUnhandledChildName("textDirection");
 	}
 	const bidi = findChild(sectPr, "w", "bidi");
-	if (bidi) props.bidi = parseBooleanElement(bidi);
-	const headerRefs = findChildren(sectPr, "w", "headerReference");
-	if (headerRefs.length > 0) props.headerReferences = headerRefs.map((el) => parseHeaderReference(el));
-	const footerRefs = findChildren(sectPr, "w", "footerReference");
-	if (footerRefs.length > 0) props.footerReferences = footerRefs.map((el) => parseFooterReference(el));
+	if (bidi) props.bidi = parseBooleanElement(bidi, "w", context);
+	const headerRefs = findChildren(sectPr, "w", "headerReference").flatMap((el) => parseHeaderReference(el, context) ?? []);
+	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);
+	if (titlePg) props.titlePg = parseBooleanElement(titlePg, "w", context);
 	const evenAndOddHeaders = findChild(sectPr, "w", "evenAndOddHeaders");
-	if (evenAndOddHeaders) props.evenAndOddHeaders = parseBooleanElement(evenAndOddHeaders);
+	if (evenAndOddHeaders) props.evenAndOddHeaders = parseBooleanElement(evenAndOddHeaders, "w", context);
 	const lnNumType = findChild(sectPr, "w", "lnNumType");
 	if (lnNumType) {
 		props.lineNumbers = {};
@@ -272,13 +228,13 @@ function parseSectionProperties(sectPr) {
 	const pgBorders = findChild(sectPr, "w", "pgBorders");
 	if (pgBorders) {
 		props.pageBorders = {};
-		const topBorder = parseBorderSpec(findChild(pgBorders, "w", "top"));
+		const topBorder = parseBorderSpec(findChild(pgBorders, "w", "top"), context);
 		if (topBorder) props.pageBorders.top = topBorder;
-		const bottomBorder = parseBorderSpec(findChild(pgBorders, "w", "bottom"));
+		const bottomBorder = parseBorderSpec(findChild(pgBorders, "w", "bottom"), context);
 		if (bottomBorder) props.pageBorders.bottom = bottomBorder;
-		const leftBorder = parseBorderSpec(findChild(pgBorders, "w", "left"));
+		const leftBorder = parseBorderSpec(findChild(pgBorders, "w", "left"), context);
 		if (leftBorder) props.pageBorders.left = leftBorder;
-		const rightBorder = parseBorderSpec(findChild(pgBorders, "w", "right"));
+		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;
@@ -315,11 +271,11 @@ function parseSectionProperties(sectPr) {
 		if (Object.keys(enProps).length > 0) props.endnotePr = enProps;
 	}
 	const formProt = findChild(sectPr, "w", "formProt");
-	if (formProt) props.formProtection = parseBooleanElement(formProt);
+	if (formProt) props.formProtection = parseBooleanElement(formProt, "w", context);
 	const noEndnote = findChild(sectPr, "w", "noEndnote");
-	if (noEndnote) props.noEndnote = parseBooleanElement(noEndnote);
+	if (noEndnote) props.noEndnote = parseBooleanElement(noEndnote, "w", context);
 	const rtlGutter = findChild(sectPr, "w", "rtlGutter");
-	if (rtlGutter) props.rtlGutter = parseBooleanElement(rtlGutter);
+	if (rtlGutter) props.rtlGutter = parseBooleanElement(rtlGutter, "w", context);
 	const docGrid = findChild(sectPr, "w", "docGrid");
 	if (docGrid) {
 		props.docGrid = {};

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

@@ -1,8 +1,7 @@
 import { document_d_exports } from "../../types/document.js";
 //#region src/docx/serializer/borderSerializer.d.ts
-type ExhaustiveFields<Source, Classified extends keyof Source> = Exclude<keyof Source, Classified> extends never ? Source : never;
 type ClassifiedBorderField = "style" | "color" | "size" | "space" | "shadow" | "frame" | "artRelationshipId" | "topLeftArtRelationshipId" | "topRightArtRelationshipId" | "bottomLeftArtRelationshipId" | "bottomRightArtRelationshipId";
-type ExhaustiveBorder = ExhaustiveFields<document_d_exports.BorderSpec, ClassifiedBorderField>;
+type ExhaustiveBorder = document_d_exports.ExhaustiveFields<document_d_exports.BorderSpec, ClassifiedBorderField>;
 /**
  * Serialize a single border element (`<w:top .../>`, `<w:left .../>`, ...).
  *

package/dist/docx/serializer/commentSerializer.js

@@ -61,6 +61,25 @@ const COMMENTS_EXTENDED_BASELINE_PREFIXES = [
 ];
 const XML_DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n";
 /**
+* The order every comment part is written in: top-level comments, then replies.
+*
+* `word/comments.xml` has always been written this way, and the order matters
+* beyond that one part: the save rewrites comments.xml, so the next parse hands
+* the model back in exactly this order. Any other part built by walking the
+* same array — `word/commentsExtended.xml`, and the paraId minting both parts
+* key on — has to walk it in the same order, or the first save writes a part
+* whose order the second save cannot reproduce and saving is not a fixed point.
+*/
+const commentPartOrder = (comments) => {
+	const topLevel = [];
+	const replies = [];
+	for (const comment of comments) {
+		const { parentId } = comment;
+		(parentId === null || parentId === void 0 ? topLevel : replies).push(comment);
+	}
+	return [...topLevel, ...replies];
+};
+/**
 * Serialize comments array to comments.xml content. Returns a valid empty
 * `<w:comments/>` document for an empty array so callers can overwrite an
 * existing `word/comments.xml` part when the editor has removed the last
@@ -68,13 +87,7 @@ const XML_DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"y
 * the orphaned comment threads on every save.
 */
 function serializeComments(comments, sourceBindings) {
-	const topLevel = [];
-	const replies = [];
-	for (const c of comments) {
-		const { parentId } = c;
-		(parentId === null || parentId === void 0 ? topLevel : replies).push(c);
-	}
-	const body = topLevel.map((comment) => serializeComment(comment)).join("") + replies.map((reply) => serializeComment(reply)).join("");
+	const body = commentPartOrder(comments).map((comment) => serializeComment(comment)).join("");
 	return XML_DECLARATION + serializePartElement({
 		partPath: "word/comments.xml",
 		rootName: "w:comments",
@@ -122,7 +135,7 @@ function ensureThreadedCommentParaIds(comments) {
 	if (threaded.size === 0) return;
 	const used = /* @__PURE__ */ new Set();
 	for (const comment of comments) for (const paragraph of comment.content ?? []) if (paragraph.paraId) used.add(paragraph.paraId.toUpperCase());
-	for (const comment of comments) {
+	for (const comment of commentPartOrder(comments)) {
 		if (!threaded.has(comment.id)) continue;
 		const last = (comment.content ?? []).at(-1);
 		if (!last || last.paraId) continue;
@@ -153,7 +166,7 @@ function buildCommentExtendedEntries(comments) {
 		if (paraId) paraIdByCommentId.set(comment.id, paraId);
 	}
 	const entries = [];
-	for (const comment of comments) {
+	for (const comment of commentPartOrder(comments)) {
 		if (!threaded.has(comment.id)) continue;
 		const paraId = paraIdByCommentId.get(comment.id);
 		if (!paraId) continue;

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

@@ -47,10 +47,6 @@ declare function getDocumentParagraphCount(doc: document_d_exports.Document): nu
  * Get table count in document
  */
 declare function getDocumentTableCount(doc: document_d_exports.Document): number;
-/**
- * Get plain text from document (for comparison/debugging)
- */
-declare function getDocumentPlainText(doc: document_d_exports.Document): string;
 /**
  * Create an empty document
  */
@@ -63,4 +59,4 @@ declare function createSimpleDocument(paragraphs: {
   styleId?: string;
 }[]): document_d_exports.Document;
 //#endregion
-export { createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentPlainText, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };
+export { createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };

package/dist/docx/serializer/documentSerializer.js

@@ -1,3 +1,4 @@
+import { withBlockRangeMarkers } from "../blockRangeMarkers.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
@@ -40,6 +41,10 @@ const DOCUMENT_BASELINE_PREFIXES = [
 * Serialize a single block content item (paragraph, table, or block-level SDT).
 */
 function serializeBlockContent(block) {
+	return withBlockRangeMarkers(block, serializeBlockBody(block));
+}
+/** The block itself, without the range markers that stood around it. */
+function serializeBlockBody(block) {
 	if (block.type === "paragraph") return serializeParagraph(block);
 	if (block.type === "table") return serializeTable(block, serializeParagraph);
 	return serializeBlockSdt(block, serializeBlockContent);
@@ -127,21 +132,6 @@ function getDocumentTableCount(doc) {
 	return doc.package.document.content.filter((b) => b.type === "table").length;
 }
 /**
-* Get plain text from document (for comparison/debugging)
-*/
-function getDocumentPlainText(doc) {
-	const texts = [];
-	for (const block of doc.package.document.content) if (block.type === "paragraph") {
-		for (const content of block.content) if (content.type === "run") {
-			for (const item of content.content) if (item.type === "text") texts.push(item.text);
-			else if (item.type === "tab") texts.push("	");
-			else if (item.type === "break") texts.push("\n");
-		}
-		texts.push("\n");
-	}
-	return texts.join("");
-}
-/**
 * Create an empty document
 */
 function createEmptyDocument() {
@@ -164,4 +154,4 @@ function createSimpleDocument(paragraphs) {
 	})) } } };
 }
 //#endregion
-export { createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentPlainText, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };
+export { createEmptyDocument, createSimpleDocument, getDocumentContentCount, getDocumentParagraphCount, getDocumentTableCount, hasDocumentContent, hasDocumentSections, hasSectionProperties, serializeDocument, serializeDocumentBody, serializeDocumentBodyElement };

package/dist/docx/serializer/headerFooterSerializer.js

@@ -1,3 +1,4 @@
+import { withBlockRangeMarkers } from "../blockRangeMarkers.js";
 import { canReplayHeaderFooterVerbatim, getHeaderFooterVerbatimXml } from "../headerFooterVerbatim.js";
 import { isEmptyParagraph } from "../paragraphParser.js";
 import { captureVerbatimXml } from "../verbatimCapture.js";
@@ -36,6 +37,10 @@ const HEADER_FOOTER_BASELINE_PREFIXES = [
 * header/footer.
 */
 function serializeBlock(block) {
+	return withBlockRangeMarkers(block, serializeBlockBody(block));
+}
+/** The block itself, without the range markers that stood around it. */
+function serializeBlockBody(block) {
 	if (block.type === "paragraph") return serializeParagraph(block);
 	if (block.type === "table") return serializeTable(block, serializeParagraph);
 	return serializeBlockSdt(block, serializeBlock);

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

@@ -0,0 +1,8 @@
+import { document_d_exports } from "../../types/document.js";
+//#region src/docx/serializer/markupRangeAttributes.d.ts
+declare const markupRangeAttributes: (marker: document_d_exports.MarkupRangeMarker) => string[];
+declare const bookmarkRangeAttributes: (marker: document_d_exports.BookmarkRangeMarker) => string[];
+/** `w:author` is required, so it is always written; `w:date` only when known. */
+declare const moveBookmarkAttributes: (marker: document_d_exports.MoveBookmarkMarker) => string[];
+//#endregion
+export { bookmarkRangeAttributes, markupRangeAttributes, moveBookmarkAttributes };

package/dist/docx/serializer/markupRangeAttributes.js

@@ -0,0 +1,24 @@
+import { escapeXml } from "./xmlUtils.js";
+//#region src/docx/serializer/markupRangeAttributes.ts
+const attribute = (name, value) => `${name}="${escapeXml(String(value))}"`;
+const markupRangeAttributes = (marker) => {
+	const attributes = [attribute("w:id", marker.id)];
+	if (marker.displacedByCustomXml !== void 0) attributes.push(attribute("w:displacedByCustomXml", marker.displacedByCustomXml));
+	return attributes;
+};
+const bookmarkRangeAttributes = (marker) => {
+	const attributes = markupRangeAttributes(marker);
+	if (marker.colFirst !== void 0) attributes.push(attribute("w:colFirst", marker.colFirst));
+	if (marker.colLast !== void 0) attributes.push(attribute("w:colLast", marker.colLast));
+	attributes.push(attribute("w:name", marker.name));
+	return attributes;
+};
+/** `w:author` is required, so it is always written; `w:date` only when known. */
+const moveBookmarkAttributes = (marker) => {
+	const attributes = bookmarkRangeAttributes(marker);
+	attributes.push(attribute("w:author", marker.author.trim() || "Unknown"));
+	if (marker.date !== void 0 && marker.date.trim().length > 0) attributes.push(attribute("w:date", marker.date.trim()));
+	return attributes;
+};
+//#endregion
+export { bookmarkRangeAttributes, markupRangeAttributes, moveBookmarkAttributes };