@stll/folio-core 0.43.0 → 0.44.0

package/dist/docx/builtInStyles.d.ts

@@ -0,0 +1,165 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/builtInStyles.d.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.
+ */
+declare const BODY_TEXT_OUTLINE_LEVEL = 9;
+/** True when an outline level names a heading rather than body text. */
+declare const isHeadingOutlineLevel: (level: number | null | undefined) => level is number;
+/**
+ * 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.
+ */
+declare const normalizeStyleName: (name: string) => string;
+/**
+ * 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*.
+ */
+declare const BUILT_IN_STYLE_NAME: {
+  /** 4,515 Word occurrences against 3 lowercase. */
+  readonly normal: "Normal";
+  readonly bodyText: "Body Text";
+  readonly title: "Title";
+  readonly subtitle: "Subtitle";
+  readonly quote: "Quote";
+  readonly intenseQuote: "Intense Quote";
+  readonly listParagraph: "List Paragraph";
+  readonly tocHeading: "TOC Heading";
+  readonly caption: "caption";
+  readonly header: "header";
+  readonly footer: "footer";
+  readonly footnoteText: "footnote text";
+  readonly commentReference: "annotation reference";
+  readonly footnoteReference: "footnote reference";
+  readonly footnoteTextChar: "Footnote Text Char";
+  readonly endnoteText: "endnote text";
+  readonly endnoteReference: "endnote reference";
+  readonly endnoteTextChar: "Endnote Text Char";
+  readonly hyperlink: "Hyperlink";
+  readonly defaultParagraphFont: "Default Paragraph Font";
+  readonly noList: "No List";
+  readonly normalTable: "Normal Table";
+  readonly tableGrid: "Table Grid";
+};
+type BuiltInStyleName = (typeof BUILT_IN_STYLE_NAME)[keyof typeof BUILT_IN_STYLE_NAME];
+/**
+ * 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.
+ */
+declare const builtInHeadingStyleName: (outlineLevel: number) => string;
+/** The name of a built-in TOC entry style, from its one-based level (`toc 1`). */
+declare const builtInTableOfContentsStyleName: (level: number) => string;
+/**
+ * A document's styles indexed by what they *are* rather than by what they are
+ * called. Built once per document: the consumers below classify every
+ * paragraph, and rebuilding the maps per paragraph would make each of them
+ * quadratic.
+ */
+type BuiltInStyleIndex = {
+  /** The style's effective `w:outlineLvl`, including 9, or undefined. */
+  outlineLevelOf: (styleId: string | null | undefined) => number | undefined;
+  /** The zero-based level a built-in heading *name* implies, or undefined. */
+  headingLevelFromNameOf: (styleId: string | null | undefined) => number | undefined;
+  /** The built-in this style is, by name, or undefined for a custom style. */
+  builtInNameOf: (styleId: string | null | undefined) => BuiltInStyleName | undefined;
+  /**
+   * The level an English built-in heading *id* implies, and only when the
+   * package defines no style under it. See {@link resolveHeadingLevel} tier 3.
+   */
+  undefinedBuiltInHeadingLevelOf: (styleId: string | null | undefined) => number | undefined;
+  /** The document's style id for a built-in heading level (zero-based). */
+  styleIdForHeadingLevel: (level: number) => string | undefined;
+  /** The document's style id for a built-in TOC entry level (one-based, `toc 1`). */
+  styleIdForTableOfContentsLevel: (level: number) => string | undefined;
+  /** The document's style id for a named built-in, e.g. `TOC Heading`. */
+  styleIdForBuiltInName: (name: BuiltInStyleName) => string | undefined;
+};
+declare const createBuiltInStyleIndex: (styles: Iterable<document_d_exports.Style>, docDefaults?: document_d_exports.DocDefaults | undefined) => BuiltInStyleIndex;
+/** An index over a document that defines no styles: every lookup misses. */
+declare const EMPTY_BUILT_IN_STYLE_INDEX: BuiltInStyleIndex;
+/**
+ * What a consumer knows about a paragraph: its style id and whatever
+ * `w:outlineLvl` applies to it. The ProseMirror `outlineLevel` attr already
+ * holds direct-else-style resolution, so passing it here agrees with passing
+ * direct formatting from the DOCX model.
+ */
+type ParagraphOutlineSource = {
+  styleId?: string | null | undefined;
+  outlineLevel?: number | null | undefined;
+};
+/**
+ * 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.
+ */
+declare const resolveHeadingLevel: (paragraph: ParagraphOutlineSource, index: BuiltInStyleIndex) => number | undefined;
+/** True when the paragraph's style is Word's `Quote` or `Intense Quote`. */
+declare const isQuoteStyle: (styleId: string | null | undefined, index: BuiltInStyleIndex) => boolean;
+//#endregion
+export { BODY_TEXT_OUTLINE_LEVEL, BUILT_IN_STYLE_NAME, BuiltInStyleIndex, EMPTY_BUILT_IN_STYLE_INDEX, ParagraphOutlineSource, builtInHeadingStyleName, builtInTableOfContentsStyleName, createBuiltInStyleIndex, isHeadingOutlineLevel, isQuoteStyle, normalizeStyleName, resolveHeadingLevel };

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,8 +1,29 @@
 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 { findChild, getAttribute, 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";
 const normalizeAnnotationReferenceFormatting = (formatting) => {
 	if (formatting?.styleId === DEFAULT_ANNOTATION_REFERENCE_STYLE_ID && Object.keys(formatting).length === 1) return;
@@ -65,10 +86,7 @@ function parseCommentsExtended(xml) {
 		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";
-		}
+		if (doneAttr !== void 0) info.done = parseOnOffValue(String(doneAttr).toLowerCase()) ?? false;
 		infoByParaId.set(String(paraId).toUpperCase(), info);
 	}
 	return infoByParaId;
@@ -81,7 +99,7 @@ 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();
@@ -92,7 +110,16 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 	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");

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/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 };