@stll/folio-core 0.44.0 → 0.46.0

package/dist/docx/attributeRemainder.js

@@ -0,0 +1,65 @@
+import { OOXML_NAMESPACES } from "./serializer/partNamespaces.js";
+import { getLocalName, resolveAttributeNamespaceUri } from "./xmlParser.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
+//#region src/docx/attributeRemainder.ts
+/** Namespace URI to the prefix a rebuilt part binds for it. */
+const CANONICAL_PREFIX = new Map(Object.entries(OOXML_NAMESPACES).map(([prefix, { uri }]) => [uri, prefix]));
+/**
+* The modelled set of an element whose serializer writes no attribute at all.
+*
+* `w:r`, `w:tr` and `w:sectPr` are rebuilt as bare start tags, so everything
+* their source wrote is the remainder. Named rather than spelled `new Set()`
+* at each call site, so the claim is visible and one place has to change when
+* one of them gains a modelled attribute.
+*/
+const NO_MODELLED_ATTRIBUTES = /* @__PURE__ */ new Set();
+/**
+* Every attribute on the element the model has no field for.
+*
+* @returns the remainder, or `undefined` when the parser read them all — an
+*   empty list is never written, so a fully modelled element stays identical
+*   in the model.
+*/
+const attributeRemainder = ({ element, modelled }) => {
+	const attributes = element.attributes;
+	if (!attributes) return;
+	const remainder = [];
+	for (const [spelling, value] of Object.entries(attributes)) {
+		if (value === void 0 || spelling === "xmlns" || spelling.startsWith("xmlns:")) continue;
+		const name = getLocalName(spelling);
+		if (modelled.has(name)) continue;
+		const namespace = resolveAttributeNamespaceUri(element, spelling);
+		if (namespace !== void 0 && !CANONICAL_PREFIX.has(namespace)) continue;
+		remainder.push({
+			...namespace === void 0 ? {} : { namespace },
+			name,
+			value: String(value)
+		});
+	}
+	return remainder.length === 0 ? void 0 : remainder;
+};
+/** The name a fragment such as `w14:paraId="1F2E"` writes. */
+const spelledName = (fragment) => fragment.slice(0, fragment.indexOf("="));
+/**
+* The element's attributes, modelled first and the remainder after them.
+*
+* @param modelled the fragments the serializer is about to emit, already
+*   spelled — they win a collision, because the model is the editable copy
+* @returns the fragments to write, so an element with neither writes nothing
+*/
+const serializePreservedAttributes = (modelled, preserved) => {
+	if (preserved === void 0 || preserved.length === 0) return [...modelled];
+	const written = new Set(modelled.map(spelledName));
+	const fragments = [...modelled];
+	for (const { namespace, name, value } of preserved) {
+		const prefix = namespace === void 0 ? void 0 : CANONICAL_PREFIX.get(namespace);
+		if (namespace !== void 0 && prefix === void 0) continue;
+		const spelling = prefix === void 0 ? name : `${prefix}:${name}`;
+		if (written.has(spelling)) continue;
+		written.add(spelling);
+		fragments.push(`${spelling}="${escapeXmlAttribute(value)}"`);
+	}
+	return fragments;
+};
+//#endregion
+export { NO_MODELLED_ATTRIBUTES, attributeRemainder, serializePreservedAttributes };

package/dist/docx/blockContentParser.d.ts

@@ -1,7 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
-import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
 //#region src/docx/blockContentParser.d.ts
 type ParseBlockContentOptions = {
   inHeaderFooter?: boolean;

package/dist/docx/blockContentParser.js

@@ -1,7 +1,7 @@
-import { attachPendingRangeMarkers, attachTrailingRangeMarkers, isBlockRangeMarker } from "./blockRangeMarkers.js";
 import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
 import { appendBookmarkMarkerToLastParagraphInBlocks, prependBookmarkMarkersToFirstParagraphInBlocks } from "./bookmarkPlacement.js";
 import { convertBulletToUnicode } from "./bulletMarkers.js";
+import { CAPTURE, OWNED_ELSEWHERE, dispatchChildren, withPreservedChildren } from "./containerChildren.js";
 import { isNumberingReference } from "./numberingReference.js";
 import { formatOoxmlCounter } from "./ooxmlCounterFormatter.js";
 import { parseParagraph } from "./paragraphParser.js";
@@ -9,7 +9,7 @@ import { enrichParagraphTextBoxes } from "./paragraphTextBoxEnrichment.js";
 import { parseSdtProperties } from "./sdtProperties.js";
 import { parseTable } from "./tableParser.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
-import { findChild, getChildElements, getLocalName, mergeXmlnsDeclarations, selectAlternateContentBranch } from "./xmlParser.js";
+import { findChild, getLocalName, mergeXmlnsDeclarations, selectAlternateContentBranch } from "./xmlParser.js";
 //#region src/docx/blockContentParser.ts
 const computeListMarker = (paragraph, { numbering, listCounters, abstractCounters, restartedNumIds, previousList }) => {
 	const listRendering = paragraph.listRendering;
@@ -104,72 +104,100 @@ const parseBlockContent = (parent, styles, theme, numbering, rels, media, option
 	}
 });
 const parseBlockContentWithState = (parent, styles, theme, numbering, rels, media, state) => {
-	const content = [];
-	const children = getChildElements(parent);
+	const modelled = [];
 	const pendingBookmarkMarkers = [];
-	const pendingRangeMarkers = [];
-	for (const child of children) {
-		const localName = getLocalName(child.name ?? "");
-		if (localName === "p") {
-			const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, state.options);
-			prependPendingBookmarkMarkers(paragraph, pendingBookmarkMarkers);
-			enrichParagraphTextBoxes(paragraph, child, styles, theme, numbering, rels, media, parseTable);
-			computeListMarker(paragraph, {
-				numbering,
-				listCounters: state.listCounters,
-				abstractCounters: state.abstractCounters,
-				restartedNumIds: state.restartedNumIds,
-				previousList: state.previousList
-			});
-			attachPendingRangeMarkers(paragraph, pendingRangeMarkers);
-			content.push(paragraph);
-			continue;
-		}
-		if (localName === "tbl") {
-			const table = parseTable(child, styles, theme, numbering, rels, media, state.options);
-			if (!table) continue;
-			if (prependBookmarkMarkersToFirstParagraphInBlocks([table], pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
-			attachPendingRangeMarkers(table, pendingRangeMarkers);
-			content.push(table);
-			continue;
-		}
-		if (localName === "sdt") {
-			const sdtPr = findChild(child, "w", "sdtPr");
-			const sdtEndPr = findChild(child, "w", "sdtEndPr");
-			const sdtContent = findChild(child, "w", "sdtContent");
-			const properties = parseSdtProperties(sdtPr, sdtEndPr);
-			const captured = captureSdtSiblingMarkers(child);
-			if (captured.before.length > 0) properties.rawSdtChildrenBeforeContent = captured.before;
-			if (captured.after.length > 0) properties.rawSdtChildrenAfterContent = captured.after;
-			const blockSdt = {
-				type: "blockSdt",
-				properties,
-				content: sdtContent ? parseBlockContentWithState(sdtContent, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), sdtContent)) : []
-			};
-			if (prependBookmarkMarkersToFirstParagraphInBlocks(blockSdt.content, pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
-			attachPendingRangeMarkers(blockSdt, pendingRangeMarkers);
-			content.push(blockSdt);
-			continue;
-		}
-		if (localName === "AlternateContent") {
+	const content = withPreservedChildren(modelled, dispatchChildren({
+		element: parent,
+		container: "block-content",
+		modelledCount: () => modelled.length,
+		undeclared: { AlternateContent: (child) => {
 			const selectedBranch = selectAlternateContentBranch(child);
-			if (selectedBranch) content.push(...parseBlockContentWithState(selectedBranch, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), selectedBranch)));
-			continue;
+			if (!selectedBranch) return;
+			modelled.push(...parseBlockContentWithState(selectedBranch, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), selectedBranch)));
+		} },
+		handlers: {
+			p: (child) => {
+				const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, state.options);
+				prependPendingBookmarkMarkers(paragraph, pendingBookmarkMarkers);
+				enrichParagraphTextBoxes(paragraph, child, styles, theme, numbering, rels, media, parseTable);
+				computeListMarker(paragraph, {
+					numbering,
+					listCounters: state.listCounters,
+					abstractCounters: state.abstractCounters,
+					restartedNumIds: state.restartedNumIds,
+					previousList: state.previousList
+				});
+				modelled.push(paragraph);
+			},
+			tbl: (child) => {
+				const table = parseTable(child, styles, theme, numbering, rels, media, state.options);
+				if (!table) return;
+				if (prependBookmarkMarkersToFirstParagraphInBlocks([table], pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
+				modelled.push(table);
+			},
+			sdt: (child) => {
+				const blockSdt = parseBlockSdt(child, styles, theme, numbering, rels, media, state);
+				if (prependBookmarkMarkersToFirstParagraphInBlocks(blockSdt.content, pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
+				modelled.push(blockSdt);
+			},
+			bookmarkStart: (child) => {
+				collectBookmarkMarker(child, "bookmarkStart", modelled, pendingBookmarkMarkers);
+			},
+			bookmarkEnd: (child) => {
+				collectBookmarkMarker(child, "bookmarkEnd", modelled, pendingBookmarkMarkers);
+			},
+			sectPr: OWNED_ELSEWHERE,
+			tcPr: OWNED_ELSEWHERE,
+			altChunk: CAPTURE,
+			commentRangeEnd: CAPTURE,
+			commentRangeStart: CAPTURE,
+			customXml: CAPTURE,
+			customXmlDelRangeEnd: CAPTURE,
+			customXmlDelRangeStart: CAPTURE,
+			customXmlInsRangeEnd: CAPTURE,
+			customXmlInsRangeStart: CAPTURE,
+			customXmlMoveFromRangeEnd: CAPTURE,
+			customXmlMoveFromRangeStart: CAPTURE,
+			customXmlMoveToRangeEnd: CAPTURE,
+			customXmlMoveToRangeStart: CAPTURE,
+			del: CAPTURE,
+			ins: CAPTURE,
+			moveFrom: CAPTURE,
+			moveFromRangeEnd: CAPTURE,
+			moveFromRangeStart: CAPTURE,
+			moveTo: CAPTURE,
+			moveToRangeEnd: CAPTURE,
+			moveToRangeStart: CAPTURE,
+			permEnd: CAPTURE,
+			permStart: CAPTURE,
+			proofErr: CAPTURE
 		}
-		if (localName === "bookmarkStart" || localName === "bookmarkEnd") {
-			const marker = parseBookmarkMarker(child, localName);
-			if (!appendBookmarkMarkerToLastParagraphInBlocks(content, marker)) pendingBookmarkMarkers.push(marker);
-			continue;
-		}
-		if (isBlockRangeMarker(localName)) pendingRangeMarkers.push(captureVerbatimXml(child));
-	}
+	}), (xml) => ({
+		type: "preservedBlock",
+		xml
+	}));
 	if (pendingBookmarkMarkers.length > 0) content.push({
 		type: "paragraph",
 		content: [...pendingBookmarkMarkers]
 	});
-	attachTrailingRangeMarkers(content, pendingRangeMarkers);
 	return content;
 };
+const parseBlockSdt = (child, styles, theme, numbering, rels, media, state) => {
+	const sdtContent = findChild(child, "w", "sdtContent");
+	const properties = parseSdtProperties(findChild(child, "w", "sdtPr"), findChild(child, "w", "sdtEndPr"));
+	const captured = captureSdtSiblingMarkers(child);
+	if (captured.before.length > 0) properties.rawSdtChildrenBeforeContent = captured.before;
+	if (captured.after.length > 0) properties.rawSdtChildrenAfterContent = captured.after;
+	return {
+		type: "blockSdt",
+		properties,
+		content: sdtContent ? parseBlockContentWithState(sdtContent, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), sdtContent)) : []
+	};
+};
+const collectBookmarkMarker = (child, localName, content, pending) => {
+	const marker = localName === "bookmarkStart" ? parseBookmarkStart(child) : parseBookmarkEnd(child);
+	if (!appendBookmarkMarkerToLastParagraphInBlocks(content, marker)) pending.push(marker);
+};
 /**
 * Walk a `<w:sdt>` element's direct children and return the verbatim XML
 * for every child that is NOT `<w:sdtPr>`, `<w:sdtEndPr>`, or
@@ -202,10 +230,6 @@ const captureSdtSiblingMarkers = (sdt) => {
 		after: afterParts.join("")
 	};
 };
-const parseBookmarkMarker = (child, localName) => {
-	if (localName === "bookmarkStart") return parseBookmarkStart(child);
-	return parseBookmarkEnd(child);
-};
 const prependPendingBookmarkMarkers = (paragraph, pendingBookmarkMarkers) => {
 	if (pendingBookmarkMarkers.length === 0) return;
 	paragraph.content.unshift(...pendingBookmarkMarkers);

package/dist/docx/blockPlainText.d.ts

@@ -1,8 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/blockPlainText.d.ts
-type PlainTextBlock = document_d_exports.Paragraph | document_d_exports.Table | document_d_exports.BlockSdt;
 /** One entry per block, so callers can join or count lines as they need. */
-declare const collectBlockTexts: (blocks: readonly PlainTextBlock[]) => string[];
-declare const blockPlainText: (blocks: readonly PlainTextBlock[]) => string;
+declare const collectBlockTexts: (blocks: readonly document_d_exports.BlockContent[]) => string[];
+declare const blockPlainText: (blocks: readonly document_d_exports.BlockContent[]) => string;
 //#endregion
-export { PlainTextBlock, blockPlainText, collectBlockTexts };
+export { blockPlainText, collectBlockTexts };

package/dist/docx/blockPlainText.js

@@ -31,6 +31,7 @@ const collectBlockTexts = (blocks) => {
 		case "blockSdt":
 			texts.push(...collectBlockTexts(block.content));
 			break;
+		case "preservedBlock": break;
 		default: panic(`Unsupported block in plain-text extraction: ${JSON.stringify(block)}`);
 	}
 	return texts;

package/dist/docx/bookmarkPlacement.js

@@ -25,6 +25,7 @@ const appendBookmarkMarkerToLastParagraph = (block, marker) => {
 		return true;
 	}
 	if (block.type === "table") return appendBookmarkMarkerToLastParagraphInTable(block, marker);
+	if (block.type === "preservedBlock") return false;
 	return appendBookmarkMarkerToLastParagraphInBlocks(block.content, marker);
 };
 const appendBookmarkMarkerToLastParagraphInTable = (table, marker) => {
@@ -40,6 +41,7 @@ const prependBookmarkMarkersToFirstParagraph = (block, markers) => {
 		return true;
 	}
 	if (block.type === "table") return prependBookmarkMarkersToFirstParagraphInTable(block, markers);
+	if (block.type === "preservedBlock") return false;
 	return prependBookmarkMarkersToFirstParagraphInBlocks(block.content, markers);
 };
 const prependBookmarkMarkersToFirstParagraphInTable = (table, markers) => {

package/dist/docx/borderParser.js

@@ -55,15 +55,15 @@ function parseBorderSpec(border, context) {
 	if (shadow !== void 0) spec.shadow = shadow;
 	const frame = parseOnOffAttribute(border, "w", "frame");
 	if (frame !== void 0) spec.frame = frame;
-	const artRelationshipId = getAttribute(border, "w", "id")?.trim();
+	const artRelationshipId = getAttribute(border, "r", "id")?.trim();
 	if (artRelationshipId) spec.artRelationshipId = artRelationshipId;
-	const topLeftArtRelationshipId = getAttribute(border, "w", "topLeft")?.trim();
+	const topLeftArtRelationshipId = getAttribute(border, "r", "topLeft")?.trim();
 	if (topLeftArtRelationshipId) spec.topLeftArtRelationshipId = topLeftArtRelationshipId;
-	const topRightArtRelationshipId = getAttribute(border, "w", "topRight")?.trim();
+	const topRightArtRelationshipId = getAttribute(border, "r", "topRight")?.trim();
 	if (topRightArtRelationshipId) spec.topRightArtRelationshipId = topRightArtRelationshipId;
-	const bottomLeftArtRelationshipId = getAttribute(border, "w", "bottomLeft")?.trim();
+	const bottomLeftArtRelationshipId = getAttribute(border, "r", "bottomLeft")?.trim();
 	if (bottomLeftArtRelationshipId) spec.bottomLeftArtRelationshipId = bottomLeftArtRelationshipId;
-	const bottomRightArtRelationshipId = getAttribute(border, "w", "bottomRight")?.trim();
+	const bottomRightArtRelationshipId = getAttribute(border, "r", "bottomRight")?.trim();
 	if (bottomRightArtRelationshipId) spec.bottomRightArtRelationshipId = bottomRightArtRelationshipId;
 	return spec;
 }

package/dist/docx/commentAnchorIndex.d.ts

@@ -0,0 +1,30 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/commentAnchorIndex.d.ts
+type CommentMarkerSlot = {
+  /** The inline-content array the marker sits in, so a caller can splice it. */
+  content: document_d_exports.ParagraphContent[];
+  index: number;
+  item: Extract<document_d_exports.ParagraphContent, {
+    type: "commentRangeStart";
+  } | {
+    type: "commentRangeEnd";
+  } | {
+    type: "commentReference";
+  }>;
+};
+declare const visitCommentMarkers: (blocks: readonly document_d_exports.BlockContent[], visit: (slot: CommentMarkerSlot) => void) => void;
+/**
+ * Comments that open a range anywhere in these blocks.
+ *
+ * A `commentReference` whose id is absent has no highlight of its own — the
+ * point-comment shape the model's `CommentReference` documents — and only that
+ * one needs its mark anchored onto neighbouring text. Anchoring one whose range
+ * exists stretches that range to wherever the reference sits, which is how a
+ * comment on one word came back covering the rest of the sentence. The range
+ * and the reference need not share a paragraph, so the question is asked of the
+ * whole story: a reference that trails the end of a range three paragraphs back
+ * is still not a point comment.
+ */
+declare const rangedCommentIds: (blocks: readonly document_d_exports.BlockContent[]) => ReadonlySet<number>;
+//#endregion
+export { CommentMarkerSlot, rangedCommentIds, visitCommentMarkers };

package/dist/docx/commentAnchorIndex.js

@@ -0,0 +1,50 @@
+import { visitInlineContentSlots } from "./paragraphTraversal.js";
+//#region src/docx/commentAnchorIndex.ts
+const visitCommentMarkers = (blocks, visit) => {
+	const visitParagraph = (paragraph) => {
+		visitInlineContentSlots(paragraph, ({ content, index, item }) => {
+			if (item.type === "commentRangeStart" || item.type === "commentRangeEnd" || item.type === "commentReference") visit({
+				content,
+				index,
+				item
+			});
+		});
+	};
+	const visitBlock = (block) => {
+		if (block.type === "paragraph") {
+			visitParagraph(block);
+			return;
+		}
+		if (block.type === "table") {
+			for (const row of block.rows) for (const cell of row.cells) visitBlocks(cell.content);
+			return;
+		}
+		if (block.type === "preservedBlock") return;
+		visitBlocks(block.content);
+	};
+	const visitBlocks = (nested) => {
+		for (const block of nested) visitBlock(block);
+	};
+	visitBlocks(blocks);
+};
+/**
+* Comments that open a range anywhere in these blocks.
+*
+* A `commentReference` whose id is absent has no highlight of its own — the
+* point-comment shape the model's `CommentReference` documents — and only that
+* one needs its mark anchored onto neighbouring text. Anchoring one whose range
+* exists stretches that range to wherever the reference sits, which is how a
+* comment on one word came back covering the rest of the sentence. The range
+* and the reference need not share a paragraph, so the question is asked of the
+* whole story: a reference that trails the end of a range three paragraphs back
+* is still not a point comment.
+*/
+const rangedCommentIds = (blocks) => {
+	const ids = /* @__PURE__ */ new Set();
+	visitCommentMarkers(blocks, ({ item }) => {
+		if (item.type === "commentRangeStart") ids.add(item.id);
+	});
+	return ids;
+};
+//#endregion
+export { rangedCommentIds, visitCommentMarkers };

package/dist/docx/commentParser.d.ts

@@ -1,6 +1,6 @@
 import { document_d_exports } from "../types/document.js";
-import { StyleMap } from "./styleParser.js";
 import { ParseContext } from "./parseContext.js";
+import { StyleMap } from "./styleParser.js";
 //#region src/docx/commentParser.d.ts
 type CommentExtendedInfo = {
   parentParaId?: string;

package/dist/docx/commentParser.js

@@ -1,7 +1,10 @@
+import { commentThreadParaId } from "./commentThreadKey.js";
+import { CAPTURE, dispatchChildren } from "./containerChildren.js";
+import { PARA_ID_NAMESPACE_URIS, paraIdAttribute, paraIdParentAttribute } from "./paraIdAttribute.js";
 import { parseParagraph } from "./paragraphParser.js";
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
 import { parseRunProperties } from "./runParser.js";
-import { findChild, getAttribute, getChildElements, getLocalName, parseOnOffValue, parseXml } from "./xmlParser.js";
+import { findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, parseOnOffValue, parseXml } from "./xmlParser.js";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/commentParser.ts
 /**
@@ -36,7 +39,7 @@ const normalizeFirstCommentParagraph = (paragraphElement, paragraph, theme) => {
 	const annotationReferenceFormatting = normalizeAnnotationReferenceFormatting(runProperties ? parseRunProperties(runProperties, theme) : void 0);
 	const firstParsedContent = paragraph.content.at(0);
 	return {
-		paragraph: firstParsedContent?.type === "run" && firstParsedContent.content.length === 0 ? cloneParagraphWithPropertySource(paragraph, { content: paragraph.content.slice(1) }) : paragraph,
+		paragraph: firstParsedContent?.type === "run" && firstParsedContent.content.every((item) => item.type === "preservedXml" && item.text === "") ? cloneParagraphWithPropertySource(paragraph, { content: paragraph.content.slice(1) }) : paragraph,
 		...annotationReferenceFormatting !== void 0 ? { annotationReferenceFormatting } : {}
 	};
 };
@@ -54,9 +57,10 @@ function parseCommentsExtensible(xml) {
 	const container = findChild(root, "w16cex", "commentsExtensible") ?? root;
 	for (const child of getChildElements(container)) {
 		if ((child.name?.replace(/^.*:/u, "") ?? "") !== "comment") continue;
-		const paraId = getAttribute(child, "w16cex", "paraId") ?? getAttribute(child, "w15", "paraId") ?? child.attributes?.["w16cex:paraId"] ?? child.attributes?.["w15:paraId"];
-		const dateUtc = getAttribute(child, "w16cex", "dateUtc") ?? getAttribute(child, "w15", "dateUtc") ?? child.attributes?.["w16cex:dateUtc"] ?? child.attributes?.["w15:dateUtc"];
-		if (paraId && dateUtc) dateUtcByParaId.set(String(paraId).toUpperCase(), String(dateUtc));
+		const paraId = paraIdAttribute(child);
+		const dateUtc = getAttributeByNamespaceUri(child, PARA_ID_NAMESPACE_URIS, "dateUtc") ?? child.attributes?.["w16cex:dateUtc"] ?? child.attributes?.["w15:dateUtc"];
+		const key = paraId === void 0 ? null : paraId.toUpperCase();
+		if (key && dateUtc && !dateUtcByParaId.has(key)) dateUtcByParaId.set(key, String(dateUtc));
 	}
 	return dateUtcByParaId;
 }
@@ -80,14 +84,16 @@ function parseCommentsExtended(xml) {
 	const container = findChild(root, "w15", "commentsEx") ?? root;
 	for (const child of getChildElements(container)) {
 		if ((child.name?.replace(/^.*:/u, "") ?? "") !== "commentEx") continue;
-		const paraId = getAttribute(child, "w15", "paraId") ?? child.attributes?.["w15:paraId"];
+		const paraId = paraIdAttribute(child);
 		if (!paraId) continue;
-		const parentParaId = getAttribute(child, "w15", "paraIdParent") ?? child.attributes?.["w15:paraIdParent"];
+		const key = paraId.toUpperCase();
+		if (infoByParaId.has(key)) continue;
+		const parentParaId = paraIdParentAttribute(child);
 		const doneAttr = getAttribute(child, "w15", "done") ?? child.attributes?.["w15:done"];
 		const info = {};
 		if (parentParaId) info.parentParaId = String(parentParaId).toUpperCase();
 		if (doneAttr !== void 0) info.done = parseOnOffValue(String(doneAttr).toLowerCase()) ?? false;
-		infoByParaId.set(String(paraId).toUpperCase(), info);
+		infoByParaId.set(key, info);
 	}
 	return infoByParaId;
 }
@@ -105,9 +111,8 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 	const dateUtcByParaId = commentsExtensibleXml ? parseCommentsExtensible(commentsExtensibleXml) : /* @__PURE__ */ new Map();
 	const extendedByParaId = commentsExtendedXml ? parseCommentsExtended(commentsExtendedXml) : /* @__PURE__ */ new Map();
 	const children = getChildElements(findChild(root, "w", "comments") ?? root);
-	const comments = [];
+	const parsed = [];
 	const commentIdByParaId = /* @__PURE__ */ new Map();
-	const paraIdByCommentIndex = /* @__PURE__ */ new Map();
 	for (const child of children) {
 		if ((child.name?.replace(/^.*:/u, "") ?? "") !== "comment") continue;
 		const rawId = getAttribute(child, "w", "id");
@@ -126,54 +131,77 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 		const initials = rawInitials !== null ? String(rawInitials) : void 0;
 		const rawDate = getAttribute(child, "w", "date");
 		const localDate = rawDate !== null ? String(rawDate) : void 0;
-		let rawParaId = getAttribute(child, "w14", "paraId") ?? child.attributes?.["w14:paraId"] ?? getAttribute(child, "w15", "paraId") ?? child.attributes?.["w15:paraId"] ?? getAttribute(child, "w", "paraId");
-		if (!rawParaId) for (const sub of getChildElements(child)) {
-			if ((sub.name?.replace(/^.*:/u, "") ?? "") !== "p") continue;
-			const subParaId = getAttribute(sub, "w14", "paraId") ?? sub.attributes?.["w14:paraId"] ?? getAttribute(sub, "w15", "paraId") ?? sub.attributes?.["w15:paraId"] ?? getAttribute(sub, "w", "paraId");
-			if (subParaId) rawParaId = subParaId;
-		}
+		const rawParaId = paraIdAttribute(child) ?? commentThreadParaId(getChildElements(child).filter((sub) => (sub.name?.replace(/^.*:/u, "") ?? "") === "p").map(paraIdAttribute));
 		const paraId = rawParaId ? String(rawParaId).toUpperCase() : null;
 		const date = (paraId ? dateUtcByParaId.get(paraId) : void 0) ?? localDate;
 		const done = (paraId ? extendedByParaId.get(paraId) : void 0)?.done;
 		const paragraphs = [];
 		let annotationReferenceFormatting;
-		for (const contentChild of getChildElements(child)) if ((contentChild.name?.replace(/^.*:/u, "") ?? "") === "p") {
-			const paragraph = parseParagraph(contentChild, styles, theme, null, rels, media);
-			if (paragraphs.length > 0) {
-				paragraphs.push(paragraph);
-				continue;
+		const preserved = dispatchChildren({
+			element: child,
+			container: "w:comment",
+			modelledCount: () => paragraphs.length,
+			handlers: {
+				p: (contentChild) => {
+					const paragraph = parseParagraph(contentChild, styles, theme, null, rels, media);
+					if (paragraphs.length > 0) {
+						paragraphs.push(paragraph);
+						return;
+					}
+					const normalized = normalizeFirstCommentParagraph(contentChild, paragraph, theme);
+					annotationReferenceFormatting = normalized.annotationReferenceFormatting;
+					paragraphs.push(normalized.paragraph);
+				},
+				altChunk: CAPTURE,
+				bookmarkEnd: CAPTURE,
+				bookmarkStart: CAPTURE,
+				commentRangeEnd: CAPTURE,
+				commentRangeStart: CAPTURE,
+				customXml: CAPTURE,
+				customXmlDelRangeEnd: CAPTURE,
+				customXmlDelRangeStart: CAPTURE,
+				customXmlInsRangeEnd: CAPTURE,
+				customXmlInsRangeStart: CAPTURE,
+				customXmlMoveFromRangeEnd: CAPTURE,
+				customXmlMoveFromRangeStart: CAPTURE,
+				customXmlMoveToRangeEnd: CAPTURE,
+				customXmlMoveToRangeStart: CAPTURE,
+				del: CAPTURE,
+				ins: CAPTURE,
+				moveFrom: CAPTURE,
+				moveFromRangeEnd: CAPTURE,
+				moveFromRangeStart: CAPTURE,
+				moveTo: CAPTURE,
+				moveToRangeEnd: CAPTURE,
+				moveToRangeStart: CAPTURE,
+				permEnd: CAPTURE,
+				permStart: CAPTURE,
+				proofErr: CAPTURE,
+				sdt: CAPTURE,
+				tbl: CAPTURE
 			}
-			const normalized = normalizeFirstCommentParagraph(contentChild, paragraph, theme);
-			annotationReferenceFormatting = normalized.annotationReferenceFormatting;
-			paragraphs.push(normalized.paragraph);
-		}
-		const commentIndex = comments.length;
-		if (paraId) {
-			commentIdByParaId.set(paraId, id);
-			paraIdByCommentIndex.set(commentIndex, paraId);
-		}
-		comments.push({
-			id,
-			author,
-			...initials !== void 0 ? { initials } : {},
-			...date !== void 0 ? { date } : {},
-			...done !== void 0 ? { done } : {},
-			...annotationReferenceFormatting !== void 0 ? { annotationReferenceFormatting } : {},
-			content: paragraphs
+		});
+		if (paraId && !commentIdByParaId.has(paraId)) commentIdByParaId.set(paraId, id);
+		parsed.push({
+			comment: {
+				id,
+				author,
+				...initials !== void 0 ? { initials } : {},
+				...date !== void 0 ? { date } : {},
+				...done !== void 0 ? { done } : {},
+				...annotationReferenceFormatting !== void 0 ? { annotationReferenceFormatting } : {},
+				...preserved !== void 0 ? { preserved } : {},
+				content: paragraphs
+			},
+			threadParaId: paraId
 		});
 	}
-	for (let i = 0; i < comments.length; i++) {
-		const comment = comments[i];
-		if (!comment) continue;
-		const paraId = paraIdByCommentIndex.get(i);
-		if (!paraId) continue;
-		const parentParaId = extendedByParaId.get(paraId)?.parentParaId;
-		if (!parentParaId) continue;
-		const parentId = commentIdByParaId.get(parentParaId);
-		if (parentId !== void 0 && parentId !== comment.id) comments[i] = {
-			...comment,
-			parentId
-		};
+	const comments = [];
+	for (const { comment, threadParaId } of parsed) {
+		const parentParaId = threadParaId ? extendedByParaId.get(threadParaId)?.parentParaId : void 0;
+		const parentId = parentParaId ? commentIdByParaId.get(parentParaId) : void 0;
+		if (parentId !== void 0 && parentId !== comment.id) comment.parentId = parentId;
+		comments.push(comment);
 	}
 	return comments;
 }

package/dist/docx/commentRangeIntegrity.d.ts

@@ -1,5 +1,20 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/commentRangeIntegrity.d.ts
+/**
+ * Comment ids whose range is not a start followed by an end in this story's
+ * XML. Either half alone is invalid OOXML and anchors nothing: Word shows no
+ * comment for a range that never opens.
+ */
+declare const unbalancedCommentRangeIds: (xml: string) => Set<string>;
+/**
+ * Whether rewriting `originalXml` into `patchedXml` left a comment range with
+ * only one half. A save patches the paragraphs an edit touched and keeps the
+ * rest of the part byte-for-byte, so an edit that moves a range's only start
+ * out of a patched paragraph and into an untouched one writes an end with no
+ * start. Ranges the source already had unbalanced are not this save's doing
+ * and stay tolerated.
+ */
+declare const patchBreaksCommentRangeBalance: (originalXml: string, patchedXml: string) => boolean;
 declare const withoutOrphanCommentRanges: (doc: document_d_exports.Document) => document_d_exports.Document;
 //#endregion
-export { withoutOrphanCommentRanges };
+export { patchBreaksCommentRangeBalance, unbalancedCommentRangeIds, withoutOrphanCommentRanges };