@stll/folio-core 0.43.0 → 0.45.0

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/sectionReferenceHistory.js

@@ -1,7 +1,7 @@
 import { canonicalJson } from "../utils/canonicalJson.js";
-import { escapeXml } from "./serializer/xmlUtils.js";
 import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, findChildrenByNamespaceUri, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri } from "./xmlParser.js";
 import { TaggedError } from "better-result";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/sectionReferenceHistory.ts
 const SECTION_REFERENCE_HISTORY_NAMESPACE = "urn:stella:folio:section-reference-history:1";
 const HISTORY_NAMESPACES = /* @__PURE__ */ new Set([SECTION_REFERENCE_HISTORY_NAMESPACE]);
@@ -41,7 +41,7 @@ const serializeSectionReferenceHistory = (references) => {
 		if (new Set(values.map(({ type }) => type)).size !== values.length) return invalidHistory();
 		return values.map(({ type, rId }) => {
 			if (!rId || rId.trim() !== rId) return invalidHistory();
-			return `<w:${kind}Reference w:type="${type}" r:id="${escapeXml(rId)}"/>`;
+			return `<w:${kind}Reference w:type="${type}" r:id="${escapeXmlAttribute(rId)}"/>`;
 		}).join("");
 	};
 	const content = serializeReferences("header", references.headerReferences ?? []) + serializeReferences("footer", references.footerReferences ?? []);

package/dist/docx/selectiveSave.js

@@ -8,7 +8,7 @@ import { RELATIONSHIP_TYPES } from "./relsParser.js";
 import { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_PART_LOWER, addCommentsExtendedOverride, addCommentsExtendedRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, updateCoreProperties, withoutAttachedTemplate } from "./rezip.js";
 import "./selectiveSaveFlags.js";
 import { buildPatchedDocumentXml, buildPatchedNoteXml, collectParaIds, patchNumberingDefinitions } from "./selectiveXmlPatch.js";
-import { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
+import { planCommentParts, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
 import { serializeDocument } from "./serializer/documentSerializer.js";
 import { serializeEndnotes, serializeFootnotes } from "./serializer/noteSerializer.js";
 import { serializeNumberingXml } from "./serializer/numberingSerializer.js";
@@ -84,8 +84,8 @@ const commentsExtendedInfoEqual = (a, b) => {
 * - Threading changed: write the part and ensure its override + relationship,
 *   bailing if the packaging files needed to wire it are absent.
 */
-async function patchCommentsExtended(zip, comments, updates) {
-	const desiredXml = serializeCommentsExtended(comments);
+async function patchCommentsExtended(zip, plan, updates) {
+	const desiredXml = serializeCommentsExtended(plan);
 	const existing = findZipEntryCaseInsensitive(zip, COMMENTS_EXTENDED_PART_LOWER);
 	if (!desiredXml) return existing === null;
 	const baselineInfo = existing ? parseCommentsExtended(await existing.async("text")) : /* @__PURE__ */ new Map();
@@ -190,6 +190,7 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 	if (!validateFolioDocumentModel(doc).valid) return null;
 	const comments = doc.package.document.comments ?? [];
 	const hasComments = comments.length > 0;
+	const commentPlan = planCommentParts(comments);
 	try {
 		const zip = await (await import("jszip")).default.loadAsync(originalBuffer);
 		for (const [path, file] of Object.entries(zip.files)) if (!file.dir && isUnsafePackagePath(path)) return null;
@@ -215,9 +216,8 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 		}
 		const sourceCommentsFile = zip.file("word/comments.xml");
 		if (hasComments || sourceCommentsFile) {
-			ensureThreadedCommentParaIds(comments);
 			const sourceBindings = sourceCommentsFile ? readRootNamespaceBindings(await sourceCommentsFile.async("text")) : void 0;
-			updates.set("word/comments.xml", serializeComments(comments, sourceBindings));
+			updates.set("word/comments.xml", serializeComments(commentPlan, sourceBindings));
 		}
 		if (hasComments) {
 			const ctFile = zip.file("[Content_Types].xml");
@@ -235,7 +235,7 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 				}
 			}
 		}
-		if (!await patchCommentsExtended(zip, comments, updates)) return null;
+		if (!await patchCommentsExtended(zip, commentPlan, updates)) return null;
 		await patchNumberingPart(zip, doc, updates);
 		for (const [path, xml] of await collectHeaderFooterUpdates(doc, zip)) updates.set(path, xml);
 		await queueSettingsUpdates(zip, updates);

package/dist/docx/serializer/blockSdtSerializer.js

@@ -1,24 +1,39 @@
 import { reconcileRawSdtPr } from "../sdtPropertiesPatch.js";
 import { isSingleWellFormedElement } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/blockSdtSerializer.ts
-function escapeXmlAttr(value) {
-	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
-}
+/**
+* Block-level SDT serializer.
+*
+* Replays `<w:sdtPr>` (and `<w:sdtEndPr>` when present) verbatim from the
+* `rawPropertiesXml` / `rawEndPropertiesXml` strings captured by the parser.
+* That keeps OOXML element order intact (`CT_SdtPr` is an `xsd:sequence`,
+* ECMA-376 §17.5.2) and round-trips unmodeled features — `w:dataBinding`,
+* `w15:repeatingSection`, `@lastValue`, custom XML mappings — without us
+* having to enumerate them.
+*
+* If a `BlockSdt` was constructed programmatically (no parsed snapshot to
+* replay), fall back to a minimal projection from the modeled fields so the
+* result is still a valid `<w:sdt>`.
+*
+* Sharing the helper between the document body and the header/footer
+* serializers keeps body↔HF parity in one place.
+*/
 function serializeFallbackSdtPr(props) {
 	const parts = [];
 	if (props.id !== void 0) parts.push(`<w:id w:val="${props.id}"/>`);
-	if (props.alias) parts.push(`<w:alias w:val="${escapeXmlAttr(props.alias)}"/>`);
-	if (props.tag) parts.push(`<w:tag w:val="${escapeXmlAttr(props.tag)}"/>`);
+	if (props.alias) parts.push(`<w:alias w:val="${escapeXmlAttribute(props.alias)}"/>`);
+	if (props.tag) parts.push(`<w:tag w:val="${escapeXmlAttribute(props.tag)}"/>`);
 	if (props.lock) parts.push(`<w:lock w:val="${props.lock}"/>`);
-	if (props.placeholder) parts.push(`<w:placeholder><w:docPart w:val="${escapeXmlAttr(props.placeholder)}"/></w:placeholder>`);
+	if (props.placeholder) parts.push(`<w:placeholder><w:docPart w:val="${escapeXmlAttribute(props.placeholder)}"/></w:placeholder>`);
 	if (props.showingPlaceholder) parts.push("<w:showingPlcHdr/>");
 	switch (props.sdtType) {
 		case "plainText":
 			parts.push("<w:text/>");
 			break;
 		case "date": {
-			const fullDateAttr = props.dateValueISO ? ` w:fullDate="${escapeXmlAttr(props.dateValueISO)}"` : "";
-			const formatChild = props.dateFormat ? `<w:dateFormat w:val="${escapeXmlAttr(props.dateFormat)}"/>` : "";
+			const fullDateAttr = props.dateValueISO ? ` w:fullDate="${escapeXmlAttribute(props.dateValueISO)}"` : "";
+			const formatChild = props.dateFormat ? `<w:dateFormat w:val="${escapeXmlAttribute(props.dateFormat)}"/>` : "";
 			if (fullDateAttr || formatChild) parts.push(`<w:date${fullDateAttr}>${formatChild}</w:date>`);
 			else parts.push("<w:date/>");
 			break;
@@ -26,7 +41,7 @@ function serializeFallbackSdtPr(props) {
 		case "dropdown":
 		case "comboBox": {
 			const tag = props.sdtType === "dropdown" ? "w:dropDownList" : "w:comboBox";
-			const items = (props.listItems ?? []).map((item) => `<w:listItem w:displayText="${escapeXmlAttr(item.displayText)}" w:value="${escapeXmlAttr(item.value)}"/>`).join("");
+			const items = (props.listItems ?? []).map((item) => `<w:listItem w:displayText="${escapeXmlAttribute(item.displayText)}" w:value="${escapeXmlAttribute(item.value)}"/>`).join("");
 			parts.push(`<${tag}>${items}</${tag}>`);
 			break;
 		}
@@ -48,25 +63,22 @@ function serializeFallbackSdtPr(props) {
 	}
 	return `<w:sdtPr>${parts.join("")}</w:sdtPr>`;
 }
+/**
+* `properties.dropdownLastValue` is the only record of what was selected.
+*
+* The XSD default of `@w:lastValue` is the empty string, so "never selected",
+* "cleared" and "selected" are three distinguishable states, and the body's
+* display text is evidence for none of them: it is equally the placeholder of
+* a dropdown nobody has touched, and a displayText shared by two list items
+* picks the wrong sibling. The parser records the authored `@w:lastValue` and
+* `setContentControlValue` records a pick; what neither wrote is no selection.
+*
+* `""` is a value a producer can author (`<w:listItem w:value=""/>`), so
+* presence is the test, not truthiness.
+*/
 function extractDropdownLastValue(blockSdt) {
 	if (blockSdt.properties.sdtType !== "dropdown" && blockSdt.properties.sdtType !== "comboBox") return;
-	const modeled = blockSdt.properties.dropdownLastValue;
-	if (modeled !== void 0) return modeled;
-	if (blockSdt.properties.rawPropertiesXml !== void 0) return;
-	const firstBlock = blockSdt.content[0];
-	if (!firstBlock || firstBlock.type !== "paragraph") return;
-	const parts = [];
-	for (const child of firstBlock.content) if (child.type === "run") {
-		for (const item of child.content) if (item.type === "text") parts.push(item.text);
-	}
-	const text = parts.join("");
-	if (text.length === 0) return;
-	const items = blockSdt.properties.listItems;
-	if (items) {
-		const match = items.find((item) => item.displayText === text);
-		if (match) return match.value;
-	}
-	return text;
+	return blockSdt.properties.dropdownLastValue;
 }
 function extractDateFullDate(blockSdt) {
 	if (blockSdt.properties.sdtType !== "date") return;

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 .../>`, ...).
  *
@@ -19,7 +18,7 @@ type ExhaustiveBorder = ExhaustiveFields<document_d_exports.BorderSpec, Classifi
  *
  * `style` and the color values come straight from the parsed DOCX (the parser
  * casts `w:val`/`w:color` without validating the enum), so they are
- * untrusted and are `escapeXml`'d before re-entering XML attributes; for valid
+ * untrusted and are `escapeXmlAttribute`'d before re-entering XML attributes; for valid
  * documents these are enum/hex values, so escaping is a no-op.
  */
 declare function serializeBorder(input: ExhaustiveBorder | undefined, elementName: string): string;

package/dist/docx/serializer/borderSerializer.js

@@ -1,4 +1,5 @@
-import { escapeXml, intAttr } from "./xmlUtils.js";
+import { intAttr } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/borderSerializer.ts
 /**
 * Serialize a single border element (`<w:top .../>`, `<w:left .../>`, ...).
@@ -16,30 +17,30 @@ import { escapeXml, intAttr } from "./xmlUtils.js";
 *
 * `style` and the color values come straight from the parsed DOCX (the parser
 * casts `w:val`/`w:color` without validating the enum), so they are
-* untrusted and are `escapeXml`'d before re-entering XML attributes; for valid
+* untrusted and are `escapeXmlAttribute`'d before re-entering XML attributes; for valid
 * documents these are enum/hex values, so escaping is a no-op.
 */
 function serializeBorder(input, elementName) {
 	if (!input) return "";
 	const { style, color, size, space, shadow, frame, artRelationshipId, topLeftArtRelationshipId, topRightArtRelationshipId, bottomLeftArtRelationshipId, bottomRightArtRelationshipId } = input;
-	const attrs = [`w:val="${escapeXml(style)}"`];
+	const attrs = [`w:val="${escapeXmlAttribute(style)}"`];
 	if (size !== void 0) attrs.push(`w:sz="${intAttr(size)}"`);
 	if (space !== void 0) attrs.push(`w:space="${intAttr(space)}"`);
 	if (color) {
 		const { auto, rgb, themeColor, themeTint, themeShade } = color;
 		if (auto) attrs.push("w:color=\"auto\"");
-		else if (rgb) attrs.push(`w:color="${escapeXml(rgb)}"`);
-		if (themeColor) attrs.push(`w:themeColor="${escapeXml(themeColor)}"`);
-		if (themeTint) attrs.push(`w:themeTint="${escapeXml(themeTint)}"`);
-		if (themeShade) attrs.push(`w:themeShade="${escapeXml(themeShade)}"`);
+		else if (rgb) attrs.push(`w:color="${escapeXmlAttribute(rgb)}"`);
+		if (themeColor) attrs.push(`w:themeColor="${escapeXmlAttribute(themeColor)}"`);
+		if (themeTint) attrs.push(`w:themeTint="${escapeXmlAttribute(themeTint)}"`);
+		if (themeShade) attrs.push(`w:themeShade="${escapeXmlAttribute(themeShade)}"`);
 	}
 	if (shadow) attrs.push("w:shadow=\"true\"");
 	if (frame) attrs.push("w:frame=\"true\"");
-	if (artRelationshipId) attrs.push(`w:id="${escapeXml(artRelationshipId)}"`);
-	if (topLeftArtRelationshipId) attrs.push(`w:topLeft="${escapeXml(topLeftArtRelationshipId)}"`);
-	if (topRightArtRelationshipId) attrs.push(`w:topRight="${escapeXml(topRightArtRelationshipId)}"`);
-	if (bottomLeftArtRelationshipId) attrs.push(`w:bottomLeft="${escapeXml(bottomLeftArtRelationshipId)}"`);
-	if (bottomRightArtRelationshipId) attrs.push(`w:bottomRight="${escapeXml(bottomRightArtRelationshipId)}"`);
+	if (artRelationshipId) attrs.push(`r:id="${escapeXmlAttribute(artRelationshipId)}"`);
+	if (topLeftArtRelationshipId) attrs.push(`r:topLeft="${escapeXmlAttribute(topLeftArtRelationshipId)}"`);
+	if (topRightArtRelationshipId) attrs.push(`r:topRight="${escapeXmlAttribute(topRightArtRelationshipId)}"`);
+	if (bottomLeftArtRelationshipId) attrs.push(`r:bottomLeft="${escapeXmlAttribute(bottomLeftArtRelationshipId)}"`);
+	if (bottomRightArtRelationshipId) attrs.push(`r:bottomRight="${escapeXmlAttribute(bottomRightArtRelationshipId)}"`);
 	return `<w:${elementName} ${attrs.join(" ")}/>`;
 }
 //#endregion

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

@@ -1,30 +1,55 @@
 import { Comment } from "../../types/content.js";
 //#region src/docx/serializer/commentSerializer.d.ts
 /**
- * Serialize comments array to comments.xml content. Returns a valid empty
- * `<w:comments/>` document for an empty array so callers can overwrite an
+ * What every comment part is written from: one ordered list of comment ids, and
+ * the facts each id carries.
+ *
+ * `word/comments.xml` and `word/commentsExtended.xml` describe the same
+ * comments and have to agree about which is which. They agreed by each walking
+ * the `Comment[]` they were handed and pairing entries up by position, so any
+ * disagreement about order — one part reordered, the other not — silently moved
+ * a comment's thread link, resolved state and paraId onto a different comment.
+ * Positions cannot disagree if neither part has one: both walk `order` and look
+ * every fact up by `w:id`, the only identity the package itself has.
+ */
+type CommentPartPlan = {
+  /** The `w:id`s to write, in order, each exactly once. */
+  readonly order: readonly number[];
+  readonly byId: ReadonlyMap<number, Comment>;
+  /** The `w14:paraId` each comment is threaded by, minted where the model had none. */
+  readonly threadParaIdById: ReadonlyMap<number, string>;
+  /** The comments needing a `commentsExtended.xml` entry: replies, their parents, resolved comments. */
+  readonly threadedIds: ReadonlySet<number>;
+};
+/**
+ * Plan both comment parts from the model, in the model's own order.
+ *
+ * The order is the document's: the order `word/comments.xml` listed the
+ * comments in is the order it is written back in, so a save neither reshuffles
+ * a reviewer's threads nor hands the next parse a different `comments[]` than
+ * the one it read.
+ *
+ * Planning also mints the `w14:paraId` a thread needs when the model has none —
+ * a comment written in the editor has no Word-authored id, and without one the
+ * `commentsExtended.xml` link would be dropped. Minting is deterministic
+ * (comment id and text derived) so repeated saves mint the same id, and it
+ * happens here rather than at each call site because both parts must see it.
+ */
+declare const planCommentParts: (comments: readonly Comment[]) => CommentPartPlan;
+/**
+ * Serialize a comment plan to comments.xml content. Returns a valid empty
+ * `<w:comments/>` document for an empty plan so callers can overwrite an
  * existing `word/comments.xml` part when the editor has removed the last
  * comment — leaving the previous file in place would otherwise re-emit
  * the orphaned comment threads on every save.
  */
-declare function serializeComments(comments: Comment[], sourceBindings?: ReadonlyMap<string, string>): string;
-/**
- * Assign a deterministic `w14:paraId` to the LAST paragraph of every comment
- * that needs a commentsExtended entry (a reply, a reply's parent, or a resolved
- * comment) but has none. A document authored or loaded without comment paraIds
- * would otherwise have no stable key to thread through commentsExtended.xml, and
- * the thread link would be silently dropped. Word-authored ids are preserved;
- * only threaded, id-less paragraphs are filled. Deterministic (content- and
- * id-derived) so repeated saves mint the SAME id. MUST run before serializing
- * BOTH comments.xml and commentsExtended.xml so the two reference the same id.
- */
-declare function ensureThreadedCommentParaIds(comments: readonly Comment[]): void;
+declare function serializeComments({ order, byId }: CommentPartPlan, sourceBindings?: ReadonlyMap<string, string>): string;
 /**
  * Serialize `commentsExtended.xml` (`w15:commentsEx`) for reply threading and
  * resolved state, or `null` when no comment needs an entry (see
  * {@link buildCommentExtendedEntries}). This is the part that makes Word render
  * a comment as a REPLY rather than a separate top-level thread.
  */
-declare function serializeCommentsExtended(comments: readonly Comment[]): string | null;
+declare function serializeCommentsExtended(plan: CommentPartPlan): string | null;
 //#endregion
-export { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended };
+export { CommentPartPlan, planCommentParts, serializeComments, serializeCommentsExtended };