@stll/folio-core 0.43.0 → 0.45.0

package/dist/docx/builtInStyles.js

@@ -0,0 +1,239 @@
+import { BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME, resolveDefaultParagraphStyle } from "./defaultParagraphStyle.js";
+//#region src/docx/builtInStyles.ts
+/**
+* The tenth `w:outlineLvl` value. 17.3.1.20: "the val attribute … can be from
+* 0 to 9, where 9 specifically indicates that there is no outline level
+* specifically applied to this paragraph." It is a deliberate "not a heading",
+* not a tenth level. Every range test goes through
+* {@link isHeadingOutlineLevel} so the reserved value keeps one meaning across
+* the codebase.
+*
+* The same clause adds that an omitted element "is assumed to be 9". That
+* default cannot be applied to a *style* definition, because 17.7.1 tells
+* producers not to write a property "already been set by a previous level of
+* the style hierarchy": a document that names a style `heading 1` and omits
+* the level is inheriting the consumer's built-in definition, which carries
+* level 0. An absent level therefore means "unspecified, ask the name", and
+* only a written 9 means body text.
+*/
+const BODY_TEXT_OUTLINE_LEVEL = 9;
+/** The highest `w:outlineLvl` that still names a heading (outline level nine). */
+const MAX_HEADING_OUTLINE_LEVEL = 8;
+/** True when an outline level names a heading rather than body text. */
+const isHeadingOutlineLevel = (level) => typeof level === "number" && Number.isInteger(level) && level >= 0 && level <= MAX_HEADING_OUTLINE_LEVEL;
+/**
+* Compare style names the way producers actually write them. The corpus shows
+* both `heading 1` (Annex L, 94.8%) and `Heading 1` (5.2%), and LibreOffice
+* drops the space entirely (`Heading1`, `IntenseQuote`), so case and
+* whitespace are the tolerance. A name is otherwise matched whole: a style a
+* Czech template calls `Nadpis 1` stays a custom style.
+*/
+const normalizeStyleName = (name) => name.trim().toLowerCase().replace(/\s+/gu, "");
+/**
+* The `w:name` Word itself writes for each built-in, and therefore the
+* spelling every style table folio authors must use. One owner: a style set and
+* the classifier that reads it cannot drift apart if both name the same
+* constant.
+*
+* Word is not uniformly cased and guessing gets it wrong, so each value is the
+* spelling that dominates Microsoft Word output in the public corpus:
+* `footnote text` 375 against 49 `Footnote Text`, `footer` 1145 against 2,
+* `caption` 390 against 60 — but `Body Text` 424 against 2, `Title` 621
+* against 2, and the auto-generated linked character styles (`Footnote Text
+* Char` 248, `Endnote Text Char` 116) title-cased without exception.
+* {@link normalizeStyleName} makes matching tolerant of all of it; this map is
+* about what folio *writes*.
+*/
+const BUILT_IN_STYLE_NAME = {
+	/** 4,515 Word occurrences against 3 lowercase. */
+	normal: BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME,
+	bodyText: "Body Text",
+	title: "Title",
+	subtitle: "Subtitle",
+	quote: "Quote",
+	intenseQuote: "Intense Quote",
+	listParagraph: "List Paragraph",
+	tocHeading: "TOC Heading",
+	caption: "caption",
+	header: "header",
+	footer: "footer",
+	footnoteText: "footnote text",
+	commentReference: "annotation reference",
+	footnoteReference: "footnote reference",
+	footnoteTextChar: "Footnote Text Char",
+	endnoteText: "endnote text",
+	endnoteReference: "endnote reference",
+	endnoteTextChar: "Endnote Text Char",
+	hyperlink: "Hyperlink",
+	defaultParagraphFont: "Default Paragraph Font",
+	noList: "No List",
+	normalTable: "Normal Table",
+	tableGrid: "Table Grid"
+};
+/**
+* The name of a built-in heading, from its zero-based outline level.
+* Lowercase: 1,066 Word occurrences of `heading 1` against 13 `Heading 1`, and
+* Annex L writes the latent-style exceptions the same way.
+*/
+const builtInHeadingStyleName = (outlineLevel) => `heading ${outlineLevel + 1}`;
+/** The name of a built-in TOC entry style, from its one-based level (`toc 1`). */
+const builtInTableOfContentsStyleName = (level) => `toc ${level}`;
+/**
+* `heading 1`…`heading 9` against an already-normalised name. Word's built-in
+* names stop at nine, matching `w:outlineLvl`'s nine heading values, so
+* `Cmsor10` → `Címsor 10` is a user style rather than a tenth built-in.
+*/
+const BUILT_IN_HEADING_NAME = /^heading(?<level>[1-9])$/u;
+/** `toc 1`…`toc 9`, the styles a `TOC` field writes its entries in. */
+const BUILT_IN_TABLE_OF_CONTENTS_NAME = /^toc(?<level>[1-9])$/u;
+/**
+* The outline level a built-in heading *name* implies (zero-based, so
+* `heading 1` is 0), or undefined when the name is not a built-in heading.
+*/
+const headingOutlineLevelFromStyleName = (name) => {
+	if (name === void 0) return;
+	const level = BUILT_IN_HEADING_NAME.exec(normalizeStyleName(name))?.groups?.["level"];
+	return level === void 0 ? void 0 : Number.parseInt(level, 10) - 1;
+};
+/**
+* Every spelling a producer might write, mapped back to the canonical one, so
+* a caller compares against {@link BUILT_IN_STYLE_NAME} rather than against a
+* normalised form it would have to spell a second time.
+*/
+const CANONICAL_BY_NORMALIZED = new Map(Object.values(BUILT_IN_STYLE_NAME).map((name) => [normalizeStyleName(name), name]));
+const asBuiltInName = (normalized) => CANONICAL_BY_NORMALIZED.get(normalized);
+/**
+* The outline level a style chain sets: the style's own `w:outlineLvl`, else
+* the nearest ancestor's (17.7.1). `styleParser` already flattens `w:basedOn`
+* for a parsed package, but a style set built in memory carries the raw chain,
+* so the walk keeps both kinds of input on the same answer. `seen` guards the
+* circular `basedOn` a malformed package can contain.
+*/
+const inheritedOutlineLevel = (style, styleById) => {
+	const seen = /* @__PURE__ */ new Set();
+	let current = style;
+	while (current && !seen.has(current.styleId)) {
+		seen.add(current.styleId);
+		if (current.pPr?.outlineLevel !== void 0) return current.pPr.outlineLevel;
+		current = current.basedOn === void 0 ? void 0 : styleById.get(current.basedOn);
+	}
+};
+const createBuiltInStyleIndex = (styles, docDefaults) => {
+	const styleIdByHeadingLevel = /* @__PURE__ */ new Map();
+	const styleIdByTableOfContentsLevel = /* @__PURE__ */ new Map();
+	const styleIdByBuiltInName = /* @__PURE__ */ new Map();
+	const paragraphStyles = [];
+	const paragraphStyleById = /* @__PURE__ */ new Map();
+	const styleById = /* @__PURE__ */ new Map();
+	for (const style of styles) {
+		styleById.set(style.styleId, style);
+		if (style.type === "paragraph") {
+			paragraphStyles.push(style);
+			paragraphStyleById.set(style.styleId, style);
+		}
+	}
+	const docDefaultOutlineLevel = docDefaults?.pPr?.outlineLevel;
+	for (const style of paragraphStyles) {
+		if (style.name === void 0) continue;
+		const namedLevel = headingOutlineLevelFromStyleName(style.name);
+		const headingLevel = namedLevel === void 0 ? void 0 : inheritedOutlineLevel(style, styleById) ?? docDefaultOutlineLevel ?? namedLevel;
+		if (headingLevel !== void 0 && isHeadingOutlineLevel(headingLevel) && !styleIdByHeadingLevel.has(headingLevel)) {
+			styleIdByHeadingLevel.set(headingLevel, style.styleId);
+			continue;
+		}
+		const normalized = normalizeStyleName(style.name);
+		const tocLevel = BUILT_IN_TABLE_OF_CONTENTS_NAME.exec(normalized)?.groups?.["level"];
+		if (tocLevel !== void 0) {
+			const level = Number.parseInt(tocLevel, 10);
+			if (!styleIdByTableOfContentsLevel.has(level)) styleIdByTableOfContentsLevel.set(level, style.styleId);
+			continue;
+		}
+		const builtInName = asBuiltInName(normalized);
+		if (builtInName !== void 0 && !styleIdByBuiltInName.has(builtInName)) styleIdByBuiltInName.set(builtInName, style.styleId);
+	}
+	/**
+	* The style a paragraph actually resolves against. ECMA-376 17.7.2 layer 3
+	* is "the paragraph's own style chain", and a paragraph with no `w:pStyle`
+	* (or one naming a style the package never defines, or one naming a
+	* character style) takes the default paragraph style — the same fallback
+	* `StyleResolver` applies, so the model and the editor cannot drift apart.
+	*/
+	const defaultStyle = resolveDefaultParagraphStyle(paragraphStyles);
+	const styleFor = (styleId) => (styleId === null || styleId === void 0 ? void 0 : paragraphStyleById.get(styleId)) ?? defaultStyle;
+	const outlineLevelCache = /* @__PURE__ */ new Map();
+	return {
+		outlineLevelOf: (styleId) => {
+			if (outlineLevelCache.has(styleId)) return outlineLevelCache.get(styleId);
+			const style = styleFor(styleId);
+			const level = (style === void 0 ? void 0 : inheritedOutlineLevel(style, styleById)) ?? docDefaultOutlineLevel;
+			outlineLevelCache.set(styleId, level);
+			return level;
+		},
+		headingLevelFromNameOf: (styleId) => headingOutlineLevelFromStyleName(styleFor(styleId)?.name),
+		builtInNameOf: (styleId) => {
+			const name = styleFor(styleId)?.name;
+			return name === void 0 ? void 0 : asBuiltInName(normalizeStyleName(name));
+		},
+		undefinedBuiltInHeadingLevelOf: (styleId) => styleId === null || styleId === void 0 || paragraphStyleById.has(styleId) ? void 0 : headingOutlineLevelFromStyleName(styleId),
+		styleIdForHeadingLevel: (level) => styleIdByHeadingLevel.get(level),
+		styleIdForTableOfContentsLevel: (level) => styleIdByTableOfContentsLevel.get(level),
+		styleIdForBuiltInName: (name) => styleIdByBuiltInName.get(name)
+	};
+};
+/** An index over a document that defines no styles: every lookup misses. */
+const EMPTY_BUILT_IN_STYLE_INDEX = createBuiltInStyleIndex([]);
+/**
+* The heading level a paragraph carries, zero-based (`heading 1` is 0), or
+* undefined when it is not a heading.
+*
+* Precedence:
+*
+* 1. An effective outline level decides on its own, including
+*    {@link BODY_TEXT_OUTLINE_LEVEL}, which means "not a heading". A style
+*    named `heading 5` whose outline level is 0 is a level-1 heading; a style
+*    named `heading 3` reset to 9 is body text. The format gives the outline
+*    level to field calculation (17.3.1.20) and leaves the name to the UI
+*    (17.7.4.9), so the level is the one the document asserts.
+* 2. Only when no outline level is set anywhere does the built-in `w:name`
+*    decide — the style is then inheriting the consumer's own built-in
+*    definition, which supplies the level.
+* 3. Last resort, and only for a `w:pStyle` the package defines no style for:
+*    the id itself, read as the English built-in id. 17.7.4.17 makes a style
+*    without `w:customStyle` a built-in and lets an application recognise it
+*    "if the associated style ID is known", which is the one case where the id
+*    is all the information left. `defaultParagraphStyle.ts` keeps the same
+*    last tier for `Normal`. A document that defines its heading styles never
+*    reaches this, so it cannot override a name or an outline level — and a
+*    localized package never writes an English id to begin with.
+*
+* Two consequences of rule 1 are deliberate, not oversights.
+*
+* **An outline level on a style that is not a heading still makes a heading.**
+* The corpus has 680 such occurrences across 161 files, including `Title` at
+* level 0 (42×) and `Subtitle` at level 1 (23×), plus `H1`, `Sub-heading`,
+* `index heading` and a `DSTOC1-1`…`DSTOC8-8` family. Setting the level is how
+* a document asks for a paragraph to be outlined, and Word's navigation pane
+* and a `TOC \u` field both honour it, so folio does not second-guess a
+* document that asked. Suppressing `Title` here would mean folio deciding a
+* document's outline differs from Word's.
+*
+* **An outline level that disagrees with a built-in heading name wins.** 26
+* corpus styles do this (`heading 5` at level 0, `heading 3` at level 1, and
+* so on), all from non-Word producers or hand-authored fixtures. The format
+* gives the level to field calculation (17.3.1.20) and the name to the user
+* interface (17.7.4.9), so the level is the machine-readable claim and the
+* name is a label. This is the one rule below that was not confirmed against
+* Word itself.
+*/
+const resolveHeadingLevel = (paragraph, index) => {
+	const effective = paragraph.outlineLevel ?? index.outlineLevelOf(paragraph.styleId);
+	if (effective !== null && effective !== void 0) return isHeadingOutlineLevel(effective) ? effective : void 0;
+	return index.headingLevelFromNameOf(paragraph.styleId) ?? index.undefinedBuiltInHeadingLevelOf(paragraph.styleId);
+};
+/** True when the paragraph's style is Word's `Quote` or `Intense Quote`. */
+const isQuoteStyle = (styleId, index) => {
+	const name = index.builtInNameOf(styleId);
+	return name === BUILT_IN_STYLE_NAME.quote || name === BUILT_IN_STYLE_NAME.intenseQuote;
+};
+//#endregion
+export { BODY_TEXT_OUTLINE_LEVEL, BUILT_IN_STYLE_NAME, EMPTY_BUILT_IN_STYLE_INDEX, builtInHeadingStyleName, builtInTableOfContentsStyleName, createBuiltInStyleIndex, isHeadingOutlineLevel, isQuoteStyle, normalizeStyleName, resolveHeadingLevel };

package/dist/docx/commentIdNormalization.d.ts

@@ -1,8 +1,10 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/commentIdNormalization.d.ts
+/** The code this normalisation is reported under, owned here, not at the caller. */
+declare const DUPLICATE_COMMENT_ID_WARNING: "duplicate-comment-id";
 type NormalizeCommentIdsResult = {
   droppedDuplicateComments: number;
 };
 declare const normalizeCommentIds: (comments: document_d_exports.Comment[]) => NormalizeCommentIdsResult;
 //#endregion
-export { NormalizeCommentIdsResult, normalizeCommentIds };
+export { DUPLICATE_COMMENT_ID_WARNING, NormalizeCommentIdsResult, normalizeCommentIds };

package/dist/docx/commentIdNormalization.js

@@ -1,4 +1,21 @@
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/commentIdNormalization.ts
+/**
+* One comment per `w:id`, because that is all the body can address.
+*
+* `w:commentReference`, `w:commentRangeStart` and `w:commentRangeEnd` name a
+* comment by its `w:id`, so two `w:comment` elements sharing an id make every
+* marker that names it ambiguous. Word opens such a package and resolves each
+* marker to the first definition, so folio keeps the first and drops the rest:
+* no marker can address a later one, and re-numbering it would invent a
+* comment nothing anchors. Microsoft's own conformance corpus ships a file
+* that does this.
+*
+* Reply links survive unchanged. `w15:paraIdParent` resolves to a comment id
+* before this runs, and that id still belongs to the definition that stayed.
+*/
+/** The code this normalisation is reported under, owned here, not at the caller. */
+const DUPLICATE_COMMENT_ID_WARNING = PARSE_WARNING_CODES.duplicateCommentId;
 const normalizeCommentIds = (comments) => {
 	const seen = /* @__PURE__ */ new Set();
 	let kept = 0;
@@ -13,4 +30,4 @@ const normalizeCommentIds = (comments) => {
 	return { droppedDuplicateComments };
 };
 //#endregion
-export { normalizeCommentIds };
+export { DUPLICATE_COMMENT_ID_WARNING, normalizeCommentIds };

package/dist/docx/commentParser.d.ts

@@ -1,5 +1,6 @@
 import { document_d_exports } from "../types/document.js";
 import { StyleMap } from "./styleParser.js";
+import { ParseContext } from "./parseContext.js";
 //#region src/docx/commentParser.d.ts
 type CommentExtendedInfo = {
   parentParaId?: string;
@@ -28,6 +29,6 @@ declare function parseCommentsExtended(xml: string): Map<string, CommentExtended
  * 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[];
+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, context?: ParseContext): document_d_exports.Comment[];
 //#endregion
 export { CommentExtendedInfo, parseComments, parseCommentsExtended };

package/dist/docx/commentParser.js

@@ -1,9 +1,51 @@
+import { commentThreadParaId } from "./commentThreadKey.js";
 import { parseParagraph } from "./paragraphParser.js";
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
 import { parseRunProperties } from "./runParser.js";
-import { findChild, getAttribute, getChildElements, getLocalName, parseXml } from "./xmlParser.js";
+import { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, parseOnOffValue, parseXml } from "./xmlParser.js";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/commentParser.ts
+/**
+* Comment Parser - Parse comments.xml, commentsExtensible.xml, and
+* commentsExtended.xml.
+*
+* - `comments.xml` (w) carries the comment author, local date, and body.
+* - `commentsExtensible.xml` (w16cex, Word 2016+) carries reliable UTC
+*   timestamps via `w16cex:dateUtc` — Word's `w:date` is local time
+*   without an offset and so is ambiguous.
+* - `commentsExtended.xml` (w15, Word 2013+) carries reply-thread
+*   parent links via `w15:paraIdParent` and the resolved/done state
+*   via `w15:done`. Cross-referenced via the `w14:paraId` on
+*   `w:comment` and the matching `w15:paraId` on `w15:commentEx`.
+*
+* OOXML Reference:
+* - Comments: w:comments
+* - Comment: w:comment (w:id, w:author, w:date, w:initials, w14:paraId)
+* - Comment content: child w:p elements
+*/
+/** The whole lexical form of `ST_DecimalNumber`: an optional sign and digits. */
+const DECIMAL_NUMBER = /^[+-]?\d+$/u;
 const DEFAULT_ANNOTATION_REFERENCE_STYLE_ID = "CommentReference";
+/**
+* The namespaces a paraId may be written in: Word 2010 and Word 2012 wordml.
+*
+* Resolved by URI rather than by prefix, because the value is a thread key: an
+* unrelated `vendor:paraId` picked up by local name alone would key a comment
+* to the wrong thread and carry that thread's date, parent and resolved state.
+*/
+const PARA_ID_NAMESPACE_URIS = /* @__PURE__ */ new Set([NAMESPACES.w14, NAMESPACES.w15]);
+/**
+* A paraId join key, wherever an exporter writes it: on `w:comment` or `w:p`.
+*
+* One reading for both, so the wrapper and the paragraphs cannot come to
+* disagree about what counts as a key. The literal reads are the fallback for
+* a part that writes a conventional prefix without binding it, which no URI
+* lookup can resolve.
+*/
+const paraIdAttribute = (element) => {
+	const raw = getAttributeByNamespaceUri(element, PARA_ID_NAMESPACE_URIS, "paraId") ?? element.attributes?.["w14:paraId"] ?? element.attributes?.["w15:paraId"] ?? getAttributeByNamespaceUri(element, WORDPROCESSINGML_NAMESPACE_URIS, "paraId") ?? element.attributes?.["w:paraId"];
+	return raw === null || raw === void 0 ? void 0 : String(raw);
+};
 const normalizeAnnotationReferenceFormatting = (formatting) => {
 	if (formatting?.styleId === DEFAULT_ANNOTATION_REFERENCE_STYLE_ID && Object.keys(formatting).length === 1) return;
 	return formatting;
@@ -35,7 +77,8 @@ function parseCommentsExtensible(xml) {
 		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 key = paraId === null || paraId === void 0 ? null : String(paraId).toUpperCase();
+		if (key && dateUtc && !dateUtcByParaId.has(key)) dateUtcByParaId.set(key, String(dateUtc));
 	}
 	return dateUtcByParaId;
 }
@@ -61,15 +104,14 @@ function parseCommentsExtended(xml) {
 		if ((child.name?.replace(/^.*:/u, "") ?? "") !== "commentEx") continue;
 		const paraId = getAttribute(child, "w15", "paraId") ?? child.attributes?.["w15:paraId"];
 		if (!paraId) continue;
+		const key = String(paraId).toUpperCase();
+		if (infoByParaId.has(key)) 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);
+		if (doneAttr !== void 0) info.done = parseOnOffValue(String(doneAttr).toLowerCase()) ?? false;
+		infoByParaId.set(key, info);
 	}
 	return infoByParaId;
 }
@@ -81,30 +123,33 @@ function parseCommentsExtended(xml) {
 * 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) {
+function parseComments(commentsXml, styles, theme, rels, media, commentsExtensibleXml, commentsExtendedXml, context) {
 	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 parsed = [];
 	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 rawId = getAttribute(child, "w", "id");
+		const id = rawId !== null && DECIMAL_NUMBER.test(rawId) ? Number.parseInt(rawId, 10) : NaN;
+		if (Number.isNaN(id)) {
+			context?.warn({
+				code: PARSE_WARNING_CODES.missingCommentId,
+				element: "w:comment",
+				...rawId === null ? {} : { value: rawId }
+			});
+			continue;
+		}
 		const rawAuthor = getAttribute(child, "w", "author");
 		const author = parseCommentAuthor(rawAuthor);
 		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 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;
@@ -120,33 +165,26 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 			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 } : {},
+				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/commentReferenceNormalization.d.ts

@@ -1,5 +1,8 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/commentReferenceNormalization.d.ts
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+declare const DANGLING_COMMENT_REFERENCE_WARNING: "dangling-comment-reference";
+declare const UNBALANCED_COMMENT_RANGE_WARNING: "unbalanced-comment-range";
 type NormalizeCommentReferencesInput = {
   documentBody: document_d_exports.DocumentBody;
   comments: readonly document_d_exports.Comment[];
@@ -14,4 +17,4 @@ type NormalizeCommentReferencesResult = {
 };
 declare const normalizeCommentReferences: ({ documentBody, comments, headers, footers, footnotes, endnotes }: NormalizeCommentReferencesInput) => NormalizeCommentReferencesResult;
 //#endregion
-export { normalizeCommentReferences };
+export { DANGLING_COMMENT_REFERENCE_WARNING, UNBALANCED_COMMENT_RANGE_WARNING, normalizeCommentReferences };

package/dist/docx/commentReferenceNormalization.js

@@ -1,24 +1,31 @@
+import { InlineContentRemovals, visitInlineContentSlots } from "./paragraphTraversal.js";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/commentReferenceNormalization.ts
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+const DANGLING_COMMENT_REFERENCE_WARNING = PARSE_WARNING_CODES.danglingCommentReference;
+const UNBALANCED_COMMENT_RANGE_WARNING = PARSE_WARNING_CODES.unbalancedCommentRange;
 const normalizeCommentReferences = ({ documentBody, comments, headers, footers, footnotes, endnotes }) => {
 	const validCommentIds = new Set(comments.map((comment) => comment.id));
 	const rangeMarkers = [];
+	const dangling = new InlineContentRemovals();
 	let removedDanglingReferences = 0;
 	const normalizeParagraph = (paragraph) => {
-		const nextContent = [];
-		for (const content of paragraph.content) {
-			if (isCommentMarker(content) && !validCommentIds.has(content.id)) {
+		visitInlineContentSlots(paragraph, ({ content, index, item }) => {
+			if (isCommentMarker(item) && !validCommentIds.has(item.id)) {
+				dangling.mark({
+					content,
+					index
+				});
 				removedDanglingReferences += 1;
-				continue;
+				return;
 			}
-			nextContent.push(content);
-			if (isCommentRangeMarker(content)) rangeMarkers.push({
-				content: nextContent,
-				index: nextContent.length - 1,
-				id: content.id,
-				type: content.type
+			if (isCommentRangeMarker(item)) rangeMarkers.push({
+				content,
+				index,
+				id: item.id,
+				type: item.type
 			});
-		}
-		paragraph.content = nextContent;
+		});
 	};
 	const normalizeTable = (table) => {
 		for (const row of table.rows) for (const cell of row.cells) normalizeBlocks(cell.content);
@@ -43,9 +50,11 @@ const normalizeCommentReferences = ({ documentBody, comments, headers, footers,
 	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);
+	const reanchoredUnbalancedRanges = reanchorUnbalancedCommentRanges(rangeMarkers);
+	dangling.apply();
 	return {
 		removedDanglingReferences,
-		reanchoredUnbalancedRanges: reanchorUnbalancedCommentRanges(rangeMarkers)
+		reanchoredUnbalancedRanges
 	};
 };
 const reanchorUnbalancedCommentRanges = (rangeMarkers) => {
@@ -94,4 +103,4 @@ const reanchorCommentRangeMarker = (marker) => {
 const isCommentMarker = (content) => content.type === "commentRangeStart" || content.type === "commentRangeEnd" || content.type === "commentReference";
 const isCommentRangeMarker = (content) => content.type === "commentRangeStart" || content.type === "commentRangeEnd";
 //#endregion
-export { normalizeCommentReferences };
+export { DANGLING_COMMENT_REFERENCE_WARNING, UNBALANCED_COMMENT_RANGE_WARNING, normalizeCommentReferences };

package/dist/docx/commentThreadKey.d.ts

@@ -0,0 +1,18 @@
+//#region src/docx/commentThreadKey.d.ts
+/**
+ * The one rule for "which `w14:paraId` a comment is threaded by".
+ *
+ * `w15:commentEx/@w15:paraId` and `w15:paraIdParent` name a comment through the
+ * `w14:paraId` of its LAST paragraph, never through its `w:id`. Files in the
+ * wild leave that paragraph's id off and carry one on an earlier paragraph, so
+ * the rule folio reads by is the last paragraph that carries an id.
+ *
+ * The rule has two readers over two representations: the parser applies it to
+ * the `w:p` children of a `w:comment`, the serializer to the model's
+ * `Comment.content`. They must not drift — a save that keyed on a different
+ * paragraph than the parse would write a `commentsExtended.xml` whose entries
+ * belong to other comments — so both call this instead of restating it.
+ */
+declare const commentThreadParaId: (paragraphParaIds: Iterable<string | null | undefined>) => string | undefined;
+//#endregion
+export { commentThreadParaId };

package/dist/docx/commentThreadKey.js

@@ -0,0 +1,22 @@
+//#region src/docx/commentThreadKey.ts
+/**
+* The one rule for "which `w14:paraId` a comment is threaded by".
+*
+* `w15:commentEx/@w15:paraId` and `w15:paraIdParent` name a comment through the
+* `w14:paraId` of its LAST paragraph, never through its `w:id`. Files in the
+* wild leave that paragraph's id off and carry one on an earlier paragraph, so
+* the rule folio reads by is the last paragraph that carries an id.
+*
+* The rule has two readers over two representations: the parser applies it to
+* the `w:p` children of a `w:comment`, the serializer to the model's
+* `Comment.content`. They must not drift — a save that keyed on a different
+* paragraph than the parse would write a `commentsExtended.xml` whose entries
+* belong to other comments — so both call this instead of restating it.
+*/
+const commentThreadParaId = (paragraphParaIds) => {
+	let key;
+	for (const paraId of paragraphParaIds) if (paraId) key = paraId;
+	return key;
+};
+//#endregion
+export { commentThreadParaId };

package/dist/docx/danglingRelationshipReferences.d.ts

@@ -0,0 +1,15 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/danglingRelationshipReferences.d.ts
+type DanglingRelationshipReferences = {
+  /** Drawings whose `r:embed` names no relationship. */
+  drawings: number;
+  /** Hyperlinks whose `r:id` names no relationship. */
+  hyperlinks: number;
+};
+type CountDanglingRelationshipReferencesOptions = {
+  content: readonly document_d_exports.BlockContent[];
+  relationships: document_d_exports.RelationshipMap | undefined;
+};
+declare const countDanglingRelationshipReferences: ({ content, relationships }: CountDanglingRelationshipReferencesOptions) => DanglingRelationshipReferences;
+//#endregion
+export { DanglingRelationshipReferences, countDanglingRelationshipReferences };

package/dist/docx/danglingRelationshipReferences.js

@@ -0,0 +1,30 @@
+import { resolveRelationshipId } from "./relsParser.js";
+//#region src/docx/danglingRelationshipReferences.ts
+const countDanglingRelationshipReferences = ({ content, relationships }) => {
+	const counts = {
+		drawings: 0,
+		hyperlinks: 0
+	};
+	const isDangling = (rId) => resolveRelationshipId(relationships, rId).status === "dangling";
+	const visitBlocks = (blocks) => {
+		for (const block of blocks) {
+			if (block.type === "table") {
+				for (const row of block.rows) for (const cell of row.cells) visitBlocks(cell.content);
+				continue;
+			}
+			if (block.type !== "paragraph") continue;
+			for (const item of block.content) {
+				if (item.type === "hyperlink") {
+					if (isDangling(item.rId)) counts.hyperlinks += 1;
+					continue;
+				}
+				if (item.type !== "run") continue;
+				for (const child of item.content) if (child.type === "drawing" && isDangling(child.image.rId)) counts.drawings += 1;
+			}
+		}
+	};
+	visitBlocks(content);
+	return counts;
+};
+//#endregion
+export { countDanglingRelationshipReferences };