@stll/folio-core 0.44.0 → 0.46.0

package/dist/docx/selectiveXmlPatch.js

@@ -1,3 +1,4 @@
+import { patchBreaksCommentRangeBalance } from "./commentRangeIntegrity.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, findAttributeByNamespaceUri, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
 //#region src/docx/selectiveXmlPatch.ts
@@ -237,10 +238,27 @@ function buildPatchedNoteXml(originalXml, serializedXml, changedIds) {
 	return spliceChangedParagraphs(originalXml, serializedXml, changedIds);
 }
 /**
+* Apply `splices` to `xml`, end-to-start so earlier offsets stay valid.
+*
+* Every selective patch is a splice, and every splice goes through here, so
+* the refusal below is a property of the operation rather than a check each
+* site has to remember. A patch rewrites the regions an edit touched and keeps
+* the rest of the part byte-for-byte, so it can write half a comment range:
+* invalid OOXML that anchors the comment to nothing. Answers null when it
+* would, leaving the caller to rewrite a wider region — ultimately the whole
+* part from the model, which is balanced with itself.
+*/
+const spliceXml = (xml, splices) => {
+	let result = xml;
+	for (const { start, end, newXml } of [...splices].toSorted((a, b) => b.start - a.start)) result = result.slice(0, start) + newXml + result.slice(end);
+	return patchBreaksCommentRangeBalance(xml, result) ? null : result;
+};
+/**
 * Replace each changed paragraph in `originalXml` with its re-serialized form
-* extracted from `serializedXml`, splicing end-to-start so earlier offsets stay
-* valid. Assumes safety has already been validated. Returns null if an offset
-* or extraction unexpectedly fails.
+* extracted from `serializedXml`. Assumes safety has already been validated.
+* Returns null if an offset or extraction unexpectedly fails, or if
+* {@link spliceXml} refuses the result; the caller then falls back to a full
+* repack, whose parts are all re-serialized from one model.
 */
 function spliceChangedParagraphs(originalXml, serializedXml, changedIds) {
 	const replacements = [];
@@ -255,10 +273,7 @@ function spliceChangedParagraphs(originalXml, serializedXml, changedIds) {
 			newXml
 		});
 	}
-	replacements.sort((a, b) => b.start - a.start);
-	let result = originalXml;
-	for (const { start, end, newXml } of replacements) result = result.slice(0, start) + newXml + result.slice(end);
-	return result;
+	return spliceXml(originalXml, replacements);
 }
 /**
 * Depth-count the end of the element that opens at `start` (an `<openLiteral…>`
@@ -424,11 +439,6 @@ const collectChangedNoteParaIds = (baselineXml, currentXml) => {
 	}
 	return changed;
 };
-const replaceRanges = (xml, replacements) => {
-	let result = xml;
-	for (const { start, end, newXml } of [...replacements].toSorted((a, b) => b.start - a.start)) result = result.slice(0, start) + newXml + result.slice(end);
-	return result;
-};
 /**
 * Patch an existing note part from its model serialization.
 *
@@ -440,56 +450,79 @@ const replaceRanges = (xml, replacements) => {
 * notes, and unaffected equal-shape paragraphs remain byte-exact.
 * `replacementXml` also supplies synthesized automatic note-reference marks,
 * which the parsed model intentionally omits.
+*
+* A comment can be anchored on a note's own text, so its range spans that
+* note's paragraphs and an edit inside the span moves a range half from one
+* paragraph to another. Replacing only the dirty paragraph then drops the half
+* it held and leaves the other standing, so {@link spliceXml} refuses the
+* result and the changed notes are rewritten whole instead — model content on
+* both sides of the range, with every other note still byte-exact.
 */
 function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, replacementXml, elementName, changedParaIds }) {
 	const currentElements = collectNoteElementSyntax(serializedXml, elementName);
 	const originalElements = collectNoteElementSyntax(originalXml, elementName);
 	const replacementElements = collectNoteElementSyntax(replacementXml, elementName);
 	const replacementXmlnsDeclarations = collectXmlnsFromOpeningTag(replacementXml);
-	const ordinalReplacements = [];
+	const paragraphSplices = [];
+	/** The same edits at note granularity, should the paragraph splices be refused. */
+	const noteSplices = [];
 	const serializedParaIds = collectParaIds(serializedXml);
 	const effectiveChangedParaIds = changedParaIds ?? collectChangedNoteParaIds(baselineXml, serializedXml);
 	const unroutedChangedParaIds = new Set([...effectiveChangedParaIds].filter((paraId) => serializedParaIds.has(paraId)));
 	for (const [id, currentSyntaxEntries] of currentElements) {
 		const originalSyntaxEntries = originalElements.get(id);
 		const replacementSyntaxEntries = replacementElements.get(id);
-		if (currentSyntaxEntries.length !== 1 || originalSyntaxEntries?.length !== 1 || replacementSyntaxEntries?.length !== 1) return null;
+		if (currentSyntaxEntries.length !== 1 || originalSyntaxEntries?.length !== 1 || replacementSyntaxEntries?.length !== 1) return {
+			type: "refused",
+			reason: "unroutable-paragraph"
+		};
 		const currentSyntax = currentSyntaxEntries[0];
 		const originalSyntax = originalSyntaxEntries[0];
 		const replacementSyntax = replacementSyntaxEntries[0];
-		if (!currentSyntax || !originalSyntax || !replacementSyntax) return null;
+		if (!currentSyntax || !originalSyntax || !replacementSyntax) return {
+			type: "refused",
+			reason: "unroutable-paragraph"
+		};
 		const currentNote = extractNoteElement(serializedXml, currentSyntax, id);
 		const originalOffsets = findNoteElement(originalXml, originalSyntax, id);
 		const replacementNote = extractNoteElement(replacementXml, replacementSyntax, id);
-		if (!currentNote || !originalOffsets || !replacementNote) return null;
+		if (!currentNote || !originalOffsets || !replacementNote) return {
+			type: "refused",
+			reason: "unroutable-paragraph"
+		};
 		const originalNote = originalXml.slice(originalOffsets.start, originalOffsets.end);
 		const currentParagraphs = paragraphRanges(currentNote, currentSyntax.elementPrefix);
 		const originalParagraphs = paragraphRanges(originalNote, originalSyntax.elementPrefix);
 		const replacementParagraphs = paragraphRanges(replacementNote, replacementSyntax.elementPrefix);
 		const noteChangedParaIds = [...collectParaIds(currentNote).keys()].filter((paraId) => unroutedChangedParaIds.has(paraId));
 		if (noteChangedParaIds.length === 0) continue;
+		const wholeNoteSplice = {
+			start: originalOffsets.start,
+			end: originalOffsets.end,
+			newXml: rewriteWordprocessingPrefixes(replacementNote, {
+				source: replacementSyntax,
+				target: originalSyntax,
+				sourceXmlnsDeclarations: replacementXmlnsDeclarations
+			})
+		};
+		noteSplices.push(wholeNoteSplice);
 		if (currentParagraphs.length !== originalParagraphs.length || currentParagraphs.length !== replacementParagraphs.length) {
 			for (const paraId of noteChangedParaIds) unroutedChangedParaIds.delete(paraId);
-			ordinalReplacements.push({
-				start: originalOffsets.start,
-				end: originalOffsets.end,
-				newXml: rewriteWordprocessingPrefixes(replacementNote, {
-					source: replacementSyntax,
-					target: originalSyntax,
-					sourceXmlnsDeclarations: replacementXmlnsDeclarations
-				})
-			});
+			paragraphSplices.push(wholeNoteSplice);
 			continue;
 		}
 		for (let index = 0; index < currentParagraphs.length; index++) {
 			const currentRange = currentParagraphs[index];
 			const originalRange = originalParagraphs[index];
 			const replacementRange = replacementParagraphs[index];
-			if (!currentRange || !originalRange || !replacementRange) return null;
+			if (!currentRange || !originalRange || !replacementRange) return {
+				type: "refused",
+				reason: "unroutable-paragraph"
+			};
 			const routedIds = [...collectParaIds(currentNote.slice(currentRange.start, currentRange.end)).keys()].filter((paraId) => unroutedChangedParaIds.has(paraId));
 			if (routedIds.length === 0) continue;
 			for (const paraId of routedIds) unroutedChangedParaIds.delete(paraId);
-			ordinalReplacements.push({
+			paragraphSplices.push({
 				start: originalOffsets.start + originalRange.start,
 				end: originalOffsets.start + originalRange.end,
 				newXml: rewriteWordprocessingPrefixes(replacementNote.slice(replacementRange.start, replacementRange.end), {
@@ -500,8 +533,23 @@ function buildPatchedNotePartXml({ originalXml, baselineXml, serializedXml, repl
 			});
 		}
 	}
-	if (unroutedChangedParaIds.size > 0) return null;
-	return replaceRanges(originalXml, ordinalReplacements);
+	if (unroutedChangedParaIds.size > 0) return {
+		type: "refused",
+		reason: "unroutable-paragraph"
+	};
+	const patched = spliceXml(originalXml, paragraphSplices);
+	if (patched !== null) return {
+		type: "patched",
+		xml: patched
+	};
+	const wholeNotes = spliceXml(originalXml, noteSplices);
+	return wholeNotes === null ? {
+		type: "refused",
+		reason: "comment-range-balance"
+	} : {
+		type: "patched",
+		xml: wholeNotes
+	};
 }
 /**
 * The full range of the first `<openLiteral …>…</closeTag>` element, or null.
@@ -695,17 +743,19 @@ function restoreLevelNumFmts(originalDefXml, currentDefXml) {
 			...collectXmlnsFromOpeningTag(origLevel)
 		});
 		else replacement = reconstructCustomNumFmt(currentWidth);
-		const restoredLevel = curLevel.slice(0, synthetic.index) + replacement + curLevel.slice(synthetic.index + synthetic[0].length);
+		const restoredLevel = spliceXml(curLevel, [{
+			start: synthetic.index,
+			end: synthetic.index + synthetic[0].length,
+			newXml: replacement
+		}]);
+		if (restoredLevel === null) continue;
 		replacements.push({
 			start: curOffsets.start,
 			end: curOffsets.end,
 			newXml: restoredLevel
 		});
 	}
-	replacements.sort((a, b) => b.start - a.start);
-	let result = currentDefXml;
-	for (const { start, end, newXml } of replacements) result = result.slice(0, start) + newXml + result.slice(end);
-	return result;
+	return spliceXml(currentDefXml, replacements) ?? currentDefXml;
 }
 /**
 * Build a patched `word/numbering.xml` by splicing the changed `w:abstractNum` /
@@ -733,10 +783,7 @@ function buildPatchedNumberingXml(originalXml, currentXml, changed) {
 		return true;
 	};
 	if (!collect("abstractNum", changed.abstractNums) || !collect("num", changed.nums)) return null;
-	replacements.sort((a, b) => b.start - a.start);
-	let result = originalXml;
-	for (const { start, end, newXml } of replacements) result = result.slice(0, start) + newXml + result.slice(end);
-	return result;
+	return spliceXml(originalXml, replacements);
 }
 /**
 * Numbering definitions present in `currentXml` (the model's serialization)
@@ -872,4 +919,4 @@ function escapeRegExp(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 //#endregion
-export { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, validatePatchSafety };
+export { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNotePartXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNoteParaIds, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, patchNumberingDefinitions, spliceXml, validatePatchSafety };

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 (shadow !== void 0) attrs.push(`w:shadow="${shadow ? "1" : "0"}"`);
+	if (frame !== void 0) attrs.push(`w:frame="${frame ? "1" : "0"}"`);
+	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 };