@stll/folio-core 0.44.0 → 0.45.0

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

@@ -18,7 +18,7 @@ type ExhaustiveBorder = document_d_exports.ExhaustiveFields<document_d_exports.B
  *
  * `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 };

package/dist/docx/serializer/commentSerializer.js

@@ -1,8 +1,9 @@
 import { deterministicHexId } from "../../utils/hexId.js";
+import { commentThreadParaId } from "../commentThreadKey.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
 import { serializeTextFormatting } from "./textFormattingSerializer.js";
-import { escapeXml } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/commentSerializer.ts
 /**
 * Comment Serializer
@@ -26,9 +27,9 @@ function serializeParagraphWithAnnotationRef(paragraph, formatting) {
 	return xml.replace(/^<w:p(?=[\s>])[^>]*>/u, (openingTag) => `${openingTag}${annotationReference}`);
 }
 function serializeComment(comment) {
-	const attrs = [`w:id="${comment.id}"`, `w:author="${escapeXml(comment.author)}"`];
-	if (comment.initials !== void 0) attrs.push(`w:initials="${escapeXml(comment.initials)}"`);
-	if (comment.date) attrs.push(`w:date="${escapeXml(comment.date)}"`);
+	const attrs = [`w:id="${comment.id}"`, `w:author="${escapeXmlAttribute(comment.author)}"`];
+	if (comment.initials !== void 0) attrs.push(`w:initials="${escapeXmlAttribute(comment.initials)}"`);
+	if (comment.date) attrs.push(`w:date="${escapeXmlAttribute(comment.date)}"`);
 	let xml = `<w:comment ${attrs.join(" ")}>`;
 	if (comment.content.length > 0) {
 		xml += serializeParagraphWithAnnotationRef(comment.content[0], comment.annotationReferenceFormatting);
@@ -61,46 +62,6 @@ 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
-* comment — leaving the previous file in place would otherwise re-emit
-* the orphaned comment threads on every save.
-*/
-function serializeComments(comments, sourceBindings) {
-	const body = commentPartOrder(comments).map((comment) => serializeComment(comment)).join("");
-	return XML_DECLARATION + serializePartElement({
-		partPath: "word/comments.xml",
-		rootName: "w:comments",
-		baselinePrefixes: COMMENTS_BASELINE_PREFIXES,
-		sourceBindings,
-		body
-	});
-}
-/** The `w14:paraId` Word threads a comment by: its LAST paragraph's paraId. */
-function commentThreadParaId(comment) {
-	return comment.content?.at(-1)?.paraId;
-}
-/**
 * The ids of comments that need a `commentsExtended.xml` entry: a reply, a
 * reply's parent (the thread root), or any comment carrying a resolved state.
 * A plain top-level comment set yields an empty set, so no part is written.
@@ -121,29 +82,71 @@ const commentPlainText = (comment) => {
 	return text;
 };
 /**
-* 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.
+* 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.
 */
-function ensureThreadedCommentParaIds(comments) {
-	const threaded = threadedCommentIds(comments);
-	if (threaded.size === 0) return;
+const planCommentParts = (comments) => {
+	const byId = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const comment of comments) {
+		if (byId.has(comment.id)) continue;
+		byId.set(comment.id, comment);
+		order.push(comment.id);
+	}
+	const planned = [...byId.values()];
+	const threadedIds = threadedCommentIds(planned);
 	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 commentPartOrder(comments)) {
-		if (!threaded.has(comment.id)) continue;
+	for (const comment of planned) for (const paragraph of comment.content ?? []) if (paragraph.paraId) used.add(paragraph.paraId.toUpperCase());
+	const threadParaIdById = /* @__PURE__ */ new Map();
+	for (const id of order) {
+		const comment = byId.get(id);
+		const existing = commentThreadParaId((comment.content ?? []).map(({ paraId }) => paraId));
+		if (existing) {
+			threadParaIdById.set(id, existing);
+			continue;
+		}
 		const last = (comment.content ?? []).at(-1);
-		if (!last || last.paraId) continue;
-		let paraId = deterministicHexId(`comment:${comment.id}:${commentPlainText(comment)}`);
-		for (let salt = 1; used.has(paraId.toUpperCase()); salt++) paraId = deterministicHexId(`comment:${comment.id}:${salt}`);
-		used.add(paraId.toUpperCase());
-		last.paraId = paraId;
+		if (!threadedIds.has(id) || !last) continue;
+		let minted = deterministicHexId(`comment:${id}:${commentPlainText(comment)}`);
+		for (let salt = 1; used.has(minted.toUpperCase()); salt++) minted = deterministicHexId(`comment:${id}:${salt}`);
+		used.add(minted.toUpperCase());
+		last.paraId = minted;
+		threadParaIdById.set(id, minted);
 	}
+	return {
+		order,
+		byId,
+		threadParaIdById,
+		threadedIds
+	};
+};
+/**
+* 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.
+*/
+function serializeComments({ order, byId }, sourceBindings) {
+	let body = "";
+	for (const id of order) body += serializeComment(byId.get(id));
+	return XML_DECLARATION + serializePartElement({
+		partPath: "word/comments.xml",
+		rootName: "w:comments",
+		baselinePrefixes: COMMENTS_BASELINE_PREFIXES,
+		sourceBindings,
+		body
+	});
 }
 /**
 * Build the `commentsExtended.xml` entries for the comments that participate in
@@ -152,29 +155,23 @@ function ensureThreadedCommentParaIds(comments) {
 * leave any existing part untouched — a plain top-level comment set gets no
 * `commentsExtended.xml`, matching how Word omits it.
 *
-* A `w15:commentEx` keys on the comment's LAST paragraph paraId; a reply's
-* `w15:paraIdParent` points at its parent comment's last-paragraph paraId. Ids
-* are guaranteed present by {@link ensureThreadedCommentParaIds}; the `!paraId`
-* skip is a last-ditch safety for a malformed model.
+* A `w15:commentEx` keys on the comment's thread paraId; a reply's
+* `w15:paraIdParent` on its parent's. Both come from the plan, so a reply and
+* its parent name each other by `w:id` right up to the attribute.
 */
-function buildCommentExtendedEntries(comments) {
-	const threaded = threadedCommentIds(comments);
-	if (threaded.size === 0) return null;
-	const paraIdByCommentId = /* @__PURE__ */ new Map();
-	for (const comment of comments) {
-		const paraId = commentThreadParaId(comment);
-		if (paraId) paraIdByCommentId.set(comment.id, paraId);
-	}
+function buildCommentExtendedEntries({ order, byId, threadParaIdById, threadedIds }) {
+	if (threadedIds.size === 0) return null;
 	const entries = [];
-	for (const comment of commentPartOrder(comments)) {
-		if (!threaded.has(comment.id)) continue;
-		const paraId = paraIdByCommentId.get(comment.id);
+	for (const id of order) {
+		if (!threadedIds.has(id)) continue;
+		const paraId = threadParaIdById.get(id);
 		if (!paraId) continue;
-		const parentParaId = comment.parentId !== void 0 ? paraIdByCommentId.get(comment.parentId) : void 0;
+		const { parentId, done } = byId.get(id);
+		const parentParaId = parentId !== void 0 ? threadParaIdById.get(parentId) : void 0;
 		entries.push({
 			paraId,
 			...parentParaId !== void 0 ? { paraIdParent: parentParaId } : {},
-			done: comment.done ?? false
+			done: done ?? false
 		});
 	}
 	return entries.length > 0 ? entries : null;
@@ -185,12 +182,12 @@ function buildCommentExtendedEntries(comments) {
 * {@link buildCommentExtendedEntries}). This is the part that makes Word render
 * a comment as a REPLY rather than a separate top-level thread.
 */
-function serializeCommentsExtended(comments) {
-	const entries = buildCommentExtendedEntries(comments);
+function serializeCommentsExtended(plan) {
+	const entries = buildCommentExtendedEntries(plan);
 	if (!entries) return null;
 	const body = entries.map((entry) => {
-		const parentAttr = entry.paraIdParent !== void 0 ? ` w15:paraIdParent="${escapeXml(entry.paraIdParent)}"` : "";
-		return `<w15:commentEx w15:paraId="${escapeXml(entry.paraId)}"${parentAttr} w15:done="${entry.done ? "1" : "0"}"/>`;
+		const parentAttr = entry.paraIdParent !== void 0 ? ` w15:paraIdParent="${escapeXmlAttribute(entry.paraIdParent)}"` : "";
+		return `<w15:commentEx w15:paraId="${escapeXmlAttribute(entry.paraId)}"${parentAttr} w15:done="${entry.done ? "1" : "0"}"/>`;
 	}).join("");
 	return XML_DECLARATION + serializePartElement({
 		partPath: "word/commentsExtended.xml",
@@ -201,4 +198,4 @@ function serializeCommentsExtended(comments) {
 	});
 }
 //#endregion
-export { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended };
+export { planCommentParts, serializeComments, serializeCommentsExtended };

package/dist/docx/serializer/fontTableSerializer.js

@@ -1,5 +1,5 @@
 import { serializePartElement } from "./partNamespaces.js";
-import { escapeXml } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/fontTableSerializer.ts
 const serializeFontTableXml = (fontTable) => "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n" + serializePartElement({
 	partPath: "word/fontTable.xml",
@@ -10,20 +10,20 @@ const serializeFontTableXml = (fontTable) => "<?xml version=\"1.0\" encoding=\"U
 });
 const serializeFont = (font) => {
 	const parts = [];
-	if (font.altName) parts.push(`<w:altName w:val="${escapeXml(font.altName)}"/>`);
-	if (font.panose1) parts.push(`<w:panose1 w:val="${escapeXml(font.panose1)}"/>`);
-	if (font.charset) parts.push(`<w:charset w:val="${escapeXml(font.charset)}"/>`);
+	if (font.altName) parts.push(`<w:altName w:val="${escapeXmlAttribute(font.altName)}"/>`);
+	if (font.panose1) parts.push(`<w:panose1 w:val="${escapeXmlAttribute(font.panose1)}"/>`);
+	if (font.charset) parts.push(`<w:charset w:val="${escapeXmlAttribute(font.charset)}"/>`);
 	if (font.family) parts.push(`<w:family w:val="${font.family}"/>`);
 	if (font.pitch) parts.push(`<w:pitch w:val="${font.pitch}"/>`);
 	if (font.sig) {
 		const attrs = [];
 		for (const [key, value] of Object.entries(font.sig)) {
 			if (value === void 0) continue;
-			attrs.push(`w:${key}="${escapeXml(value)}"`);
+			attrs.push(`w:${key}="${escapeXmlAttribute(value)}"`);
 		}
 		if (attrs.length > 0) parts.push(`<w:sig ${attrs.join(" ")}/>`);
 	}
-	return `<w:font w:name="${escapeXml(font.name)}">${parts.join("")}</w:font>`;
+	return `<w:font w:name="${escapeXmlAttribute(font.name)}">${parts.join("")}</w:font>`;
 };
 //#endregion
 export { serializeFontTableXml };

package/dist/docx/serializer/headerFooterSerializer.js

@@ -7,7 +7,7 @@ import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
 import { serializeTable } from "./tableSerializer.js";
-import { escapeXml } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/headerFooterSerializer.ts
 const HEADER_FOOTER_BASELINE_PREFIXES = [
 	"wpc",
@@ -85,7 +85,7 @@ function serializeRawWatermarkIntoHost({ hostXml, rawWatermarkXml }) {
 	if (!rawHost || getLocalName(rawHost.name ?? "") !== "p") return rawWatermarkXml;
 	const watermarkContent = (rawHost.elements ?? []).filter((child) => child.type === "element" && getLocalName(child.name ?? "") !== "pPr").map((child) => captureVerbatimXml(child)).join("");
 	if (!watermarkContent) return rawWatermarkXml;
-	const namespaceAttributes = Object.entries(rawHost.attributes ?? {}).filter(([name, value]) => value !== void 0 && (name === "xmlns" || name.startsWith("xmlns:"))).map(([name, value]) => ` ${name}="${escapeXml(String(value))}"`).join("");
+	const namespaceAttributes = Object.entries(rawHost.attributes ?? {}).filter(([name, value]) => value !== void 0 && (name === "xmlns" || name.startsWith("xmlns:"))).map(([name, value]) => ` ${name}="${escapeXmlAttribute(String(value))}"`).join("");
 	return hostXml.replace(/^<w:p(?=[\s>])/u, `<w:p${namespaceAttributes}`).replace("</w:p>", `${watermarkContent}</w:p>`);
 }
 function serializeWatermarkParagraph(hf) {
@@ -101,15 +101,15 @@ function synthesizeTextWatermark(watermark) {
 	const rotation = watermark.diagonal === false ? 0 : 315;
 	const fillcolor = watermark.color && watermark.color !== "auto" ? `#${watermark.color}` : "#C0C0C0";
 	const fontFamily = watermark.font ?? "Calibri";
-	const text = escapeXml(watermark.text);
-	return `<w:p><w:r><w:pict><v:shape id="PowerPlusWaterMarkObject1" type="#_x0000_t136" style="position:absolute;margin-left:0;margin-top:0;width:415pt;height:207pt;rotation:${rotation};z-index:-251658240;mso-position-horizontal:center;mso-position-horizontal-relative:margin;mso-position-vertical:center;mso-position-vertical-relative:margin" fillcolor="${fillcolor}" stroked="f">${watermark.opacity !== void 0 ? `<v:fill opacity="${watermark.opacity}"/>` : ""}<v:textpath style="font-family:&quot;${escapeXml(fontFamily)}&quot;;font-size:1pt" string="${text}"/></v:shape></w:pict></w:r></w:p>`;
+	const text = escapeXmlAttribute(watermark.text);
+	return `<w:p><w:r><w:pict><v:shape id="PowerPlusWaterMarkObject1" type="#_x0000_t136" style="position:absolute;margin-left:0;margin-top:0;width:415pt;height:207pt;rotation:${rotation};z-index:-251658240;mso-position-horizontal:center;mso-position-horizontal-relative:margin;mso-position-vertical:center;mso-position-vertical-relative:margin" fillcolor="${fillcolor}" stroked="f">${watermark.opacity !== void 0 ? `<v:fill opacity="${watermark.opacity}"/>` : ""}<v:textpath style="font-family:&quot;${escapeXmlAttribute(fontFamily)}&quot;;font-size:1pt" string="${text}"/></v:shape></w:pict></w:r></w:p>`;
 }
 const PICTURE_WATERMARK_DEFAULT_WIDTH_PT = 415;
 const PICTURE_WATERMARK_DEFAULT_HEIGHT_PT = 207;
 const PICTURE_WATERMARK_WASHOUT_GAIN = "19661f";
 const PICTURE_WATERMARK_WASHOUT_BLACKLEVEL = "22938f";
 function synthesizePictureWatermark(watermark) {
-	const rId = escapeXml(watermark.imageRId);
+	const rId = escapeXmlAttribute(watermark.imageRId);
 	return `<w:p><w:r><w:pict><v:shape id="WordPictureWatermark1" type="#_x0000_t75" style="position:absolute;margin-left:0;margin-top:0;width:${watermark.scale === void 0 ? watermark.widthPt ?? PICTURE_WATERMARK_DEFAULT_WIDTH_PT : PICTURE_WATERMARK_DEFAULT_WIDTH_PT * watermark.scale}pt;height:${watermark.scale === void 0 ? watermark.heightPt ?? PICTURE_WATERMARK_DEFAULT_HEIGHT_PT : PICTURE_WATERMARK_DEFAULT_HEIGHT_PT * watermark.scale}pt;z-index:-251658240;mso-position-horizontal:center;mso-position-horizontal-relative:margin;mso-position-vertical:center;mso-position-vertical-relative:margin"><v:imagedata r:id="${rId}" o:title=""${watermark.washout === false ? "" : ` gain="${PICTURE_WATERMARK_WASHOUT_GAIN}" blacklevel="${PICTURE_WATERMARK_WASHOUT_BLACKLEVEL}"`}/></v:shape></w:pict></w:r></w:p>`;
 }
 //#endregion

package/dist/docx/serializer/markupRangeAttributes.js

@@ -1,6 +1,6 @@
-import { escapeXml } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/markupRangeAttributes.ts
-const attribute = (name, value) => `${name}="${escapeXml(String(value))}"`;
+const attribute = (name, value) => `${name}="${escapeXmlAttribute(String(value))}"`;
 const markupRangeAttributes = (marker) => {
 	const attributes = [attribute("w:id", marker.id)];
 	if (marker.displacedByCustomXml !== void 0) attributes.push(attribute("w:displacedByCustomXml", marker.displacedByCustomXml));

package/dist/docx/serializer/numberingSerializer.js

@@ -1,6 +1,7 @@
 import { serializePartElement } from "./partNamespaces.js";
 import { serializeTextFormatting } from "./textFormattingSerializer.js";
-import { escapeXml, intAttr } from "./xmlUtils.js";
+import { intAttr } from "./xmlUtils.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/serializer/numberingSerializer.ts
 /**
 * Serialize a level's paragraph properties — the modeled subset is indentation
@@ -36,11 +37,11 @@ function serializeLevelParagraphProps(pPr) {
 function serializeLevel(level) {
 	const parts = [];
 	if (level.start !== void 0) parts.push(`<w:start w:val="${intAttr(level.start)}"/>`);
-	parts.push(`<w:numFmt w:val="${escapeXml(level.numFmt)}"/>`);
+	parts.push(`<w:numFmt w:val="${escapeXmlAttribute(level.numFmt)}"/>`);
 	if (level.lvlRestart !== void 0) parts.push(`<w:lvlRestart w:val="${intAttr(level.lvlRestart)}"/>`);
 	if (level.isLgl) parts.push("<w:isLgl/>");
 	if (level.suffix) parts.push(`<w:suff w:val="${level.suffix}"/>`);
-	parts.push(`<w:lvlText w:val="${escapeXml(level.lvlText)}"/>`);
+	parts.push(`<w:lvlText w:val="${escapeXmlAttribute(level.lvlText)}"/>`);
 	if (level.legacy) {
 		const legacyAttrs = [`w:legacy="${level.legacy.legacy ? 1 : 0}"`];
 		if (level.legacy.legacySpace !== void 0) legacyAttrs.push(`w:legacySpace="${intAttr(level.legacy.legacySpace)}"`);
@@ -60,9 +61,9 @@ function serializeLevel(level) {
 function serializeAbstractNum(abstractNum) {
 	const parts = [];
 	if (abstractNum.multiLevelType) parts.push(`<w:multiLevelType w:val="${abstractNum.multiLevelType}"/>`);
-	if (abstractNum.name !== void 0) parts.push(`<w:name w:val="${escapeXml(abstractNum.name)}"/>`);
-	if (abstractNum.styleLink !== void 0) parts.push(`<w:styleLink w:val="${escapeXml(abstractNum.styleLink)}"/>`);
-	if (abstractNum.numStyleLink !== void 0) parts.push(`<w:numStyleLink w:val="${escapeXml(abstractNum.numStyleLink)}"/>`);
+	if (abstractNum.name !== void 0) parts.push(`<w:name w:val="${escapeXmlAttribute(abstractNum.name)}"/>`);
+	if (abstractNum.styleLink !== void 0) parts.push(`<w:styleLink w:val="${escapeXmlAttribute(abstractNum.styleLink)}"/>`);
+	if (abstractNum.numStyleLink !== void 0) parts.push(`<w:numStyleLink w:val="${escapeXmlAttribute(abstractNum.numStyleLink)}"/>`);
 	const levels = [...abstractNum.levels].sort((a, b) => a.ilvl - b.ilvl);
 	for (const level of levels) parts.push(serializeLevel(level));
 	return `<w:abstractNum w:abstractNumId="${intAttr(abstractNum.abstractNumId)}">${parts.join("")}</w:abstractNum>`;