@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/docx/bookmarkParser.js

@@ -0,0 +1,246 @@
+import { getAttribute, parseNumericAttribute } from "./xmlParser.js";
+//#region src/docx/bookmarkParser.ts
+/**
+* Parse a bookmark start element (w:bookmarkStart)
+*
+* Extracts:
+* - id: Numeric identifier (required, matches with bookmarkEnd)
+* - name: Bookmark name (required, used by hyperlinks)
+* - colFirst: First column for table bookmarks (optional)
+* - colLast: Last column for table bookmarks (optional)
+*
+* @param node - The w:bookmarkStart XML element
+* @returns Parsed BookmarkStart object
+*/
+function parseBookmarkStart(node) {
+	const bookmark = {
+		type: "bookmarkStart",
+		id: parseNumericAttribute(node, "w", "id") ?? 0,
+		name: getAttribute(node, "w", "name") ?? ""
+	};
+	const colFirst = parseNumericAttribute(node, "w", "colFirst");
+	if (colFirst !== void 0) bookmark.colFirst = colFirst;
+	const colLast = parseNumericAttribute(node, "w", "colLast");
+	if (colLast !== void 0) bookmark.colLast = colLast;
+	return bookmark;
+}
+/**
+* Parse a bookmark end element (w:bookmarkEnd)
+*
+* Bookmark ends only contain an ID that matches the corresponding start marker.
+*
+* @param node - The w:bookmarkEnd XML element
+* @returns Parsed BookmarkEnd object
+*/
+function parseBookmarkEnd(node) {
+	return {
+		type: "bookmarkEnd",
+		id: parseNumericAttribute(node, "w", "id") ?? 0
+	};
+}
+/**
+* Create an empty bookmark map
+*/
+function createBookmarkMap() {
+	return {
+		byId: /* @__PURE__ */ new Map(),
+		byName: /* @__PURE__ */ new Map(),
+		bookmarks: []
+	};
+}
+/**
+* Add a bookmark to the map
+*
+* @param map - The bookmark map to update
+* @param bookmark - The bookmark start to add
+*/
+function addBookmark(map, bookmark) {
+	map.byId.set(bookmark.id, bookmark);
+	if (bookmark.name) map.byName.set(bookmark.name, bookmark);
+	map.bookmarks.push(bookmark);
+}
+/**
+* Get a bookmark by name (for resolving internal hyperlinks)
+*
+* @param map - The bookmark map to search
+* @param name - Bookmark name to find
+* @returns The BookmarkStart or undefined if not found
+*/
+function getBookmarkByName(map, name) {
+	return map.byName.get(name);
+}
+/**
+* Get a bookmark by ID (for matching start/end pairs)
+*
+* @param map - The bookmark map to search
+* @param id - Bookmark ID to find
+* @returns The BookmarkStart or undefined if not found
+*/
+function getBookmarkById(map, id) {
+	return map.byId.get(id);
+}
+/**
+* Check if a bookmark exists by name
+*
+* @param map - The bookmark map to search
+* @param name - Bookmark name to check
+* @returns true if bookmark exists
+*/
+function hasBookmark(map, name) {
+	return map.byName.has(name);
+}
+/**
+* Get all bookmark names in the document
+*
+* @param map - The bookmark map
+* @returns Array of bookmark names
+*/
+function getAllBookmarkNames(map) {
+	return Array.from(map.byName.keys());
+}
+/**
+* Check if a bookmark is a point bookmark (start and end at same location)
+*
+* Point bookmarks have no content between start and end markers.
+* This is commonly used for insertion points.
+*
+* @param start - The bookmark start
+* @param end - The bookmark end
+* @param contents - Content between them
+* @returns true if this is a point bookmark
+*/
+function isPointBookmark(start, end, contents) {
+	return start.id === end.id && contents.length === 0;
+}
+/**
+* Check if a bookmark is a table column bookmark
+*
+* Table bookmarks have colFirst and colLast attributes indicating
+* they span specific table columns.
+*
+* @param bookmark - The bookmark to check
+* @returns true if bookmark has column range info
+*/
+function isTableBookmark(bookmark) {
+	return bookmark.colFirst !== void 0 || bookmark.colLast !== void 0;
+}
+/**
+* Generate an internal hyperlink href from a bookmark name
+*
+* Internal hyperlinks use #anchor format.
+*
+* @param bookmarkName - The bookmark name to link to
+* @returns Href string (e.g., "#BookmarkName")
+*/
+function bookmarkToHref(bookmarkName) {
+	return `#${bookmarkName}`;
+}
+/**
+* Extract bookmark name from an internal hyperlink href
+*
+* @param href - The href string
+* @returns Bookmark name or null if not an internal link
+*/
+function hrefToBookmarkName(href) {
+	if (href.startsWith("#")) return href.slice(1);
+	return null;
+}
+/**
+* Check if a bookmark is a built-in Word bookmark
+*
+* Word uses certain reserved bookmark names for special purposes:
+* - _GoBack: Last editing position
+* - _Toc*: Table of contents entries
+* - _Ref*: Cross-reference anchors
+* - _Hlt*: Highlight ranges
+*
+* @param name - Bookmark name to check
+* @returns true if this is a built-in bookmark
+*/
+function isBuiltInBookmark(name) {
+	if (!name) return false;
+	if (name.startsWith("_")) return true;
+	return false;
+}
+/**
+* Check if a bookmark is a TOC entry bookmark
+*
+* @param name - Bookmark name to check
+* @returns true if bookmark is for TOC
+*/
+function isTocBookmark(name) {
+	return name.startsWith("_Toc");
+}
+/**
+* Check if a bookmark is a cross-reference anchor
+*
+* @param name - Bookmark name to check
+* @returns true if bookmark is for cross-reference
+*/
+function isRefBookmark(name) {
+	return name.startsWith("_Ref");
+}
+/**
+* Get bookmark type category
+*
+* @param name - Bookmark name
+* @returns Bookmark type
+*/
+function getBookmarkType(name) {
+	if (name === "_GoBack") return "goBack";
+	if (isTocBookmark(name)) return "toc";
+	if (isRefBookmark(name)) return "ref";
+	if (isBuiltInBookmark(name)) return "internal";
+	return "user";
+}
+/**
+* Validate that all bookmark starts have matching ends
+*
+* @param starts - Array of bookmark starts
+* @param ends - Array of bookmark ends
+* @returns Object with validation results
+*/
+function validateBookmarkPairs(starts, ends) {
+	const startIds = new Set(starts.map((s) => s.id));
+	const endIds = new Set(ends.map((e) => e.id));
+	const unmatchedStarts = starts.filter((s) => !endIds.has(s.id));
+	const unmatchedEnds = ends.filter((e) => !startIds.has(e.id));
+	return {
+		valid: unmatchedStarts.length === 0 && unmatchedEnds.length === 0,
+		unmatchedStarts,
+		unmatchedEnds
+	};
+}
+/**
+* Validate a bookmark name (for creating new bookmarks)
+*
+* Valid bookmark names:
+* - Cannot be empty
+* - Must start with a letter or underscore
+* - Can contain letters, digits, and underscores
+* - Cannot exceed 40 characters
+*
+* @param name - Name to validate
+* @returns Object with validation result and error message if invalid
+*/
+function validateBookmarkName(name) {
+	if (!name) return {
+		valid: false,
+		error: "Bookmark name cannot be empty"
+	};
+	if (name.length > 40) return {
+		valid: false,
+		error: "Bookmark name cannot exceed 40 characters"
+	};
+	if (!/^[a-zA-Z_]/u.test(name)) return {
+		valid: false,
+		error: "Bookmark name must start with a letter or underscore"
+	};
+	if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/u.test(name)) return {
+		valid: false,
+		error: "Bookmark name can only contain letters, digits, and underscores"
+	};
+	return { valid: true };
+}
+//#endregion
+export { addBookmark, bookmarkToHref, createBookmarkMap, getAllBookmarkNames, getBookmarkById, getBookmarkByName, getBookmarkType, hasBookmark, hrefToBookmarkName, isBuiltInBookmark, isPointBookmark, isRefBookmark, isTableBookmark, isTocBookmark, parseBookmarkEnd, parseBookmarkStart, validateBookmarkName, validateBookmarkPairs };

package/dist/docx/bookmarkPlacement.d.ts

@@ -0,0 +1,10 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/docx/bookmarkPlacement.d.ts
+type BookmarkMarker = document_d_exports.BookmarkStart | document_d_exports.BookmarkEnd;
+declare const appendBookmarkMarkerToLastParagraphInBlocks: (blocks: readonly document_d_exports.BlockContent[], marker: BookmarkMarker) => boolean;
+declare const prependBookmarkMarkersToFirstParagraphInBlocks: (blocks: readonly document_d_exports.BlockContent[], markers: readonly BookmarkMarker[]) => boolean;
+declare const appendBookmarkMarkerToLastParagraphInCells: (cells: readonly document_d_exports.TableCell[], marker: BookmarkMarker) => boolean;
+declare const prependBookmarkMarkersToFirstParagraphInCell: (cell: document_d_exports.TableCell, markers: readonly BookmarkMarker[]) => boolean;
+//#endregion
+export { BookmarkMarker, appendBookmarkMarkerToLastParagraphInBlocks, appendBookmarkMarkerToLastParagraphInCells, prependBookmarkMarkersToFirstParagraphInBlocks, prependBookmarkMarkersToFirstParagraphInCell };

package/dist/docx/bookmarkPlacement.js

@@ -0,0 +1,50 @@
+//#region src/docx/bookmarkPlacement.ts
+const appendBookmarkMarkerToLastParagraphInBlocks = (blocks, marker) => {
+	for (let index = blocks.length - 1; index >= 0; index -= 1) {
+		const block = blocks[index];
+		if (block && appendBookmarkMarkerToLastParagraph(block, marker)) return true;
+	}
+	return false;
+};
+const prependBookmarkMarkersToFirstParagraphInBlocks = (blocks, markers) => {
+	if (markers.length === 0) return true;
+	for (const block of blocks) if (prependBookmarkMarkersToFirstParagraph(block, markers)) return true;
+	return false;
+};
+const appendBookmarkMarkerToLastParagraphInCells = (cells, marker) => {
+	for (let index = cells.length - 1; index >= 0; index -= 1) {
+		const cell = cells[index];
+		if (cell && appendBookmarkMarkerToLastParagraphInBlocks(cell.content, marker)) return true;
+	}
+	return false;
+};
+const prependBookmarkMarkersToFirstParagraphInCell = (cell, markers) => prependBookmarkMarkersToFirstParagraphInBlocks(cell.content, markers);
+const appendBookmarkMarkerToLastParagraph = (block, marker) => {
+	if (block.type === "paragraph") {
+		block.content.push(marker);
+		return true;
+	}
+	if (block.type === "table") return appendBookmarkMarkerToLastParagraphInTable(block, marker);
+	return appendBookmarkMarkerToLastParagraphInBlocks(block.content, marker);
+};
+const appendBookmarkMarkerToLastParagraphInTable = (table, marker) => {
+	for (let rowIndex = table.rows.length - 1; rowIndex >= 0; rowIndex -= 1) {
+		const row = table.rows[rowIndex];
+		if (row && appendBookmarkMarkerToLastParagraphInCells(row.cells, marker)) return true;
+	}
+	return false;
+};
+const prependBookmarkMarkersToFirstParagraph = (block, markers) => {
+	if (block.type === "paragraph") {
+		block.content.unshift(...markers);
+		return true;
+	}
+	if (block.type === "table") return prependBookmarkMarkersToFirstParagraphInTable(block, markers);
+	return prependBookmarkMarkersToFirstParagraphInBlocks(block.content, markers);
+};
+const prependBookmarkMarkersToFirstParagraphInTable = (table, markers) => {
+	for (const row of table.rows) for (const cell of row.cells) if (prependBookmarkMarkersToFirstParagraphInCell(cell, markers)) return true;
+	return false;
+};
+//#endregion
+export { appendBookmarkMarkerToLastParagraphInBlocks, appendBookmarkMarkerToLastParagraphInCells, prependBookmarkMarkersToFirstParagraphInBlocks, prependBookmarkMarkersToFirstParagraphInCell };

package/dist/docx/bulletMarkers.d.ts

@@ -0,0 +1,4 @@
+//#region src/docx/bulletMarkers.d.ts
+declare const convertBulletToUnicode: (bulletChar: string) => string;
+//#endregion
+export { convertBulletToUnicode };

package/dist/docx/bulletMarkers.js

@@ -0,0 +1,42 @@
+//#region src/docx/bulletMarkers.ts
+const SYMBOL_BULLET_MAP = {
+	183: "•",
+	111: "○",
+	167: "■",
+	252: "✓",
+	110: "■",
+	113: "○",
+	117: "◆",
+	118: "❖",
+	168: "✓",
+	251: "✓",
+	254: "✓",
+	61623: "•",
+	61550: "■",
+	61551: "○",
+	61607: "■",
+	61692: "✓",
+	8226: "•",
+	9679: "●",
+	9675: "○",
+	9632: "■",
+	9633: "□",
+	9670: "◆",
+	9671: "◇",
+	8211: "–",
+	8212: "—",
+	62: ">",
+	45: "-"
+};
+const convertBulletToUnicode = (bulletChar) => {
+	if (!bulletChar || bulletChar.trim() === "") return "•";
+	const charCode = bulletChar.codePointAt(0);
+	if (charCode === void 0) return "•";
+	const mapped = SYMBOL_BULLET_MAP[charCode];
+	if (mapped !== void 0) return mapped;
+	if (charCode >= 57344 && charCode <= 63743) return "•";
+	if (charCode < 32 || charCode >= 127 && charCode < 160) return "•";
+	return bulletChar;
+};
+//#endregion
+export { convertBulletToUnicode };

package/dist/docx/commentParser.d.ts

@@ -0,0 +1,34 @@
+import { document_d_exports } from "../types/document.js";
+import { StyleMap } from "./styleParser.js";
+
+//#region src/docx/commentParser.d.ts
+type CommentExtendedInfo = {
+  parentParaId?: string;
+  done?: boolean;
+};
+/**
+ * Build a lookup from paraId → reply-thread info from
+ * commentsExtended.xml. The XML structure is:
+ *
+ * ```xml
+ * <w15:commentsEx>
+ *   <w15:commentEx w15:paraId="..." w15:done="0"/>
+ *   <w15:commentEx w15:paraId="..." w15:paraIdParent="..." w15:done="1"/>
+ * </w15:commentsEx>
+ * ```
+ *
+ * `w15:paraIdParent` points at the parent thread's paraId; `w15:done`
+ * (`"1"` / `"true"`) marks the thread resolved.
+ */
+declare function parseCommentsExtended(xml: string): Map<string, CommentExtendedInfo>;
+/**
+ * Parse comments.xml into an array of Comment objects.
+ *
+ * If `commentsExtensibleXml` is provided, UTC timestamps are
+ * cross-referenced via paraId and preferred over the ambiguous w:date
+ * local time. If `commentsExtendedXml` is provided, reply-thread
+ * parent links (`parentId`) and resolved state (`done`) are populated.
+ */
+declare function parseComments(commentsXml: string | null, styles: StyleMap | null, theme: document_d_exports.Theme | null, rels: document_d_exports.RelationshipMap, media: Map<string, document_d_exports.MediaFile>, commentsExtensibleXml?: string | null, commentsExtendedXml?: string | null): document_d_exports.Comment[];
+//#endregion
+export { CommentExtendedInfo, parseComments, parseCommentsExtended };

package/dist/docx/commentParser.js

@@ -0,0 +1,127 @@
+import { findChild, getAttribute, getChildElements, parseXml } from "./xmlParser.js";
+import { parseParagraph } from "./paragraphParser.js";
+//#region src/docx/commentParser.ts
+/**
+* Build a lookup from paraId → dateUtc from commentsExtensible.xml
+*
+* The XML structure is:
+* <w16cex:commentsExtensible>
+*   <w16cex:comment w16cex:paraId="..." w16cex:dateUtc="2024-02-10T14:30:45Z"/>
+* </w16cex:commentsExtensible>
+*/
+function parseCommentsExtensible(xml) {
+	const dateUtcByParaId = /* @__PURE__ */ new Map();
+	const root = parseXml(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));
+	}
+	return dateUtcByParaId;
+}
+/**
+* Build a lookup from paraId → reply-thread info from
+* commentsExtended.xml. The XML structure is:
+*
+* ```xml
+* <w15:commentsEx>
+*   <w15:commentEx w15:paraId="..." w15:done="0"/>
+*   <w15:commentEx w15:paraId="..." w15:paraIdParent="..." w15:done="1"/>
+* </w15:commentsEx>
+* ```
+*
+* `w15:paraIdParent` points at the parent thread's paraId; `w15:done`
+* (`"1"` / `"true"`) marks the thread resolved.
+*/
+function parseCommentsExtended(xml) {
+	const infoByParaId = /* @__PURE__ */ new Map();
+	const root = parseXml(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"];
+		if (!paraId) continue;
+		const parentParaId = getAttribute(child, "w15", "paraIdParent") ?? child.attributes?.["w15:paraIdParent"];
+		const doneAttr = getAttribute(child, "w15", "done") ?? child.attributes?.["w15:done"];
+		const info = {};
+		if (parentParaId) info.parentParaId = String(parentParaId).toUpperCase();
+		if (doneAttr !== void 0) {
+			const v = String(doneAttr).toLowerCase();
+			info.done = v === "1" || v === "true";
+		}
+		infoByParaId.set(String(paraId).toUpperCase(), info);
+	}
+	return infoByParaId;
+}
+/**
+* Parse comments.xml into an array of Comment objects.
+*
+* If `commentsExtensibleXml` is provided, UTC timestamps are
+* cross-referenced via paraId and preferred over the ambiguous w:date
+* local time. If `commentsExtendedXml` is provided, reply-thread
+* parent links (`parentId`) and resolved state (`done`) are populated.
+*/
+function parseComments(commentsXml, styles, theme, rels, media, commentsExtensibleXml, commentsExtendedXml) {
+	if (!commentsXml) return [];
+	const root = parseXml(commentsXml);
+	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 commentIdByParaId = /* @__PURE__ */ new Map();
+	const paraIdByCommentIndex = /* @__PURE__ */ new Map();
+	for (const child of children) {
+		if ((child.name?.replace(/^.*:/u, "") ?? "") !== "comment") continue;
+		const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
+		const author = getAttribute(child, "w", "author") ?? "Unknown";
+		const rawInitials = getAttribute(child, "w", "initials");
+		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 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 = [];
+		for (const contentChild of getChildElements(child)) if ((contentChild.name?.replace(/^.*:/u, "") ?? "") === "p") {
+			const paragraph = parseParagraph(contentChild, styles, theme, null, rels, media);
+			paragraphs.push(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 } : {},
+			content: paragraphs
+		});
+	}
+	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
+		};
+	}
+	return comments;
+}
+//#endregion
+export { parseComments, parseCommentsExtended };

package/dist/docx/commentReferenceNormalization.d.ts

@@ -0,0 +1,25 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/docx/commentReferenceNormalization.d.ts
+type NormalizeCommentReferencesInput = {
+  documentBody: document_d_exports.DocumentBody;
+  comments: readonly document_d_exports.Comment[];
+  headers?: Map<string, document_d_exports.HeaderFooter>;
+  footers?: Map<string, document_d_exports.HeaderFooter>;
+  footnotes?: readonly document_d_exports.Footnote[];
+  endnotes?: readonly document_d_exports.Endnote[];
+};
+type NormalizeCommentReferencesResult = {
+  removedDanglingReferences: number;
+  reanchoredUnbalancedRanges: number;
+};
+declare const normalizeCommentReferences: ({
+  documentBody,
+  comments,
+  headers,
+  footers,
+  footnotes,
+  endnotes
+}: NormalizeCommentReferencesInput) => NormalizeCommentReferencesResult;
+//#endregion
+export { normalizeCommentReferences };

package/dist/docx/commentReferenceNormalization.js

@@ -0,0 +1,97 @@
+//#region src/docx/commentReferenceNormalization.ts
+const normalizeCommentReferences = ({ documentBody, comments, headers, footers, footnotes, endnotes }) => {
+	const validCommentIds = new Set(comments.map((comment) => comment.id));
+	const rangeMarkers = [];
+	let removedDanglingReferences = 0;
+	const normalizeParagraph = (paragraph) => {
+		const nextContent = [];
+		for (const content of paragraph.content) {
+			if (isCommentMarker(content) && !validCommentIds.has(content.id)) {
+				removedDanglingReferences += 1;
+				continue;
+			}
+			nextContent.push(content);
+			if (isCommentRangeMarker(content)) rangeMarkers.push({
+				content: nextContent,
+				index: nextContent.length - 1,
+				id: content.id,
+				type: content.type
+			});
+		}
+		paragraph.content = nextContent;
+	};
+	const normalizeTable = (table) => {
+		for (const row of table.rows) for (const cell of row.cells) normalizeBlocks(cell.content);
+	};
+	const normalizeBlock = (block) => {
+		if (block.type === "paragraph") {
+			normalizeParagraph(block);
+			return;
+		}
+		if (block.type === "table") {
+			normalizeTable(block);
+			return;
+		}
+		normalizeBlocks(block.content);
+	};
+	const normalizeBlocks = (blocks) => {
+		for (const block of blocks) normalizeBlock(block);
+	};
+	normalizeBlocks(documentBody.content);
+	for (const header of headers?.values() ?? []) normalizeBlocks(header.content);
+	for (const footer of footers?.values() ?? []) normalizeBlocks(footer.content);
+	for (const footnote of footnotes ?? []) normalizeBlocks(footnote.content);
+	for (const endnote of endnotes ?? []) normalizeBlocks(endnote.content);
+	for (const comment of comments) for (const paragraph of comment.content) normalizeParagraph(paragraph);
+	return {
+		removedDanglingReferences,
+		reanchoredUnbalancedRanges: reanchorUnbalancedCommentRanges(rangeMarkers)
+	};
+};
+const reanchorUnbalancedCommentRanges = (rangeMarkers) => {
+	const byId = /* @__PURE__ */ new Map();
+	for (const marker of rangeMarkers) {
+		const markers = byId.get(marker.id);
+		if (markers) {
+			markers.push(marker);
+			continue;
+		}
+		byId.set(marker.id, [marker]);
+	}
+	let reanchoredCount = 0;
+	for (const markers of byId.values()) {
+		let openStart = null;
+		for (const marker of markers) {
+			if (marker.type === "commentRangeStart") {
+				if (openStart) {
+					reanchorCommentRangeMarker(marker);
+					reanchoredCount += 1;
+					continue;
+				}
+				openStart = marker;
+				continue;
+			}
+			if (!openStart) {
+				reanchorCommentRangeMarker(marker);
+				reanchoredCount += 1;
+				continue;
+			}
+			openStart = null;
+		}
+		if (openStart) {
+			reanchorCommentRangeMarker(openStart);
+			reanchoredCount += 1;
+		}
+	}
+	return reanchoredCount;
+};
+const reanchorCommentRangeMarker = (marker) => {
+	marker.content[marker.index] = {
+		type: "commentReference",
+		id: marker.id
+	};
+};
+const isCommentMarker = (content) => content.type === "commentRangeStart" || content.type === "commentRangeEnd" || content.type === "commentReference";
+const isCommentRangeMarker = (content) => content.type === "commentRangeStart" || content.type === "commentRangeEnd";
+//#endregion
+export { normalizeCommentReferences };

package/dist/docx/commentReplyMarkers.d.ts

@@ -0,0 +1,20 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/docx/commentReplyMarkers.d.ts
+/**
+ * Synthesize reply range markers into a document model in place, so every
+ * reply comment picks up its parent's anchor before `document.xml` is
+ * serialized. Idempotent and safe to call on both save paths. Returns the
+ * number of markers injected.
+ */
+declare const applyReplyThreadMarkers: (doc: document_d_exports.Document) => number;
+/**
+ * Whether the model holds a reply comment that has no anchor of its own yet —
+ * i.e. one that still needs {@link applyReplyThreadMarkers} to run. The
+ * selective-save path uses this to bail to a full repack, which is the path
+ * that owns marker synthesis (selective only patches individually-changed
+ * paragraphs, so it cannot add a reply's markers to the parent's paragraph).
+ */
+declare const hasUnsynthesizedReplyRanges: (doc: document_d_exports.Document) => boolean;
+//#endregion
+export { applyReplyThreadMarkers, hasUnsynthesizedReplyRanges };