@stll/folio-core 0.43.0 → 0.44.0

package/dist/docx/parseContext.d.ts

@@ -0,0 +1,37 @@
+import { ParseWarning, ParseWarningCode } from "@stll/docx-core/model";
+//#region src/docx/parseContext.d.ts
+/** What a call site states; the collector supplies the rest. */
+type ParseWarningReport = {
+  code: ParseWarningCode;
+  /** The element as written, prefix included. */
+  element?: string;
+  /** The best position this part can name, e.g. `style "Heading1"`. */
+  at?: string;
+  /** The value folio declined to read, as written. */
+  value?: string;
+  /** Text passed through from another owner, for the pass-through codes. */
+  detail?: string;
+  /** How many occurrences this one report stands for; defaults to 1. */
+  count?: number;
+};
+type ParseContext = {
+  /** Record one normalisation applied to input folio accepted. */
+  warn: (report: ParseWarningReport) => void;
+  /** The same collector, reporting against another part or position. */
+  scoped: (location: {
+    part?: string;
+    at?: string;
+  }) => ParseContext;
+};
+type ParseWarningCollector = {
+  context: ParseContext;
+  /**
+   * Everything recorded, in the order it was recorded, followed by one entry
+   * per code whose occurrences ran past the cap. Deterministic: the same
+   * document yields the same list.
+   */
+  warnings: () => ParseWarning[];
+};
+declare const createParseWarningCollector: (part?: string) => ParseWarningCollector;
+//#endregion
+export { ParseContext, ParseWarningCollector, ParseWarningReport, createParseWarningCollector };

package/dist/docx/parseContext.js

@@ -0,0 +1,67 @@
+import { MAX_RETAINED_PARSE_WARNINGS_PER_CODE } from "@stll/docx-core/model";
+//#region src/docx/parseContext.ts
+/**
+* The channel a parser reports a normalisation through.
+*
+* Folio accepts input Word accepts, which means normalising at the parse
+* boundary rather than refusing. Every such decision has to be visible, and
+* before this the only place that could say so was `parseDocx` itself: the
+* leaf readers are pure functions with no way to report, so a value outside
+* `ST_OnOff` or a `w:type` outside `ST_HdrFtr` was normalised in silence.
+*
+* The context is an explicit parameter, never a module-level accumulator and
+* never async-local storage. Parsers stay re-entrant, a test can hand one in
+* and read what a single reader reported, and two documents parsed at once
+* cannot write into each other's list. The cost is a threaded argument, which
+* is also the thing that makes the reporting greppable.
+*/
+const PACKAGE_PART = "package";
+const createParseWarningCollector = (part = PACKAGE_PART) => {
+	const retained = [];
+	const retainedByCode = /* @__PURE__ */ new Map();
+	const suppressedByCode = /* @__PURE__ */ new Map();
+	const record = (location, report) => {
+		const count = report.count ?? 1;
+		const kept = retainedByCode.get(report.code) ?? 0;
+		if (kept >= MAX_RETAINED_PARSE_WARNINGS_PER_CODE) {
+			suppressedByCode.set(report.code, (suppressedByCode.get(report.code) ?? 0) + count);
+			return;
+		}
+		retainedByCode.set(report.code, kept + 1);
+		retained.push({
+			code: report.code,
+			location: {
+				...location,
+				...report.element === void 0 ? {} : { element: report.element },
+				...report.at === void 0 ? {} : { at: report.at }
+			},
+			...report.value === void 0 ? {} : { value: report.value },
+			...report.detail === void 0 ? {} : { detail: report.detail },
+			count
+		});
+	};
+	const contextAt = (location) => ({
+		warn: (report) => {
+			record(location, report);
+		},
+		scoped: (next) => {
+			const at = next.at ?? location.at;
+			return contextAt({
+				part: next.part ?? location.part,
+				...location.element === void 0 ? {} : { element: location.element },
+				...at === void 0 ? {} : { at }
+			});
+		}
+	});
+	return {
+		context: contextAt({ part }),
+		warnings: () => [...retained, ...[...suppressedByCode.entries()].sort(([left], [right]) => left < right ? -1 : 1).map(([code, count]) => ({
+			code,
+			location: { part },
+			count,
+			detail: `${String(count)} further occurrence(s) were counted but not retained.`
+		}))]
+	};
+};
+//#endregion
+export { createParseWarningCollector };

package/dist/docx/parseWarningMessage.d.ts

@@ -0,0 +1,6 @@
+import { ParseWarning } from "@stll/docx-core/model";
+//#region src/docx/parseWarningMessage.d.ts
+declare const formatParseWarning: (warning: ParseWarning) => string;
+declare const formatParseWarnings: (warnings: readonly ParseWarning[]) => string[];
+//#endregion
+export { formatParseWarning, formatParseWarnings };

package/dist/docx/parseWarningMessage.js

@@ -0,0 +1,44 @@
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
+//#region src/docx/parseWarningMessage.ts
+/**
+* The one place a parse warning becomes a sentence.
+*
+* `Document.warnings` is the string list hosts have always read, and it is now
+* rendered from `Document.parseWarnings` rather than written at the call site,
+* so a warning cannot say one thing in the structured list and another in the
+* prose. The map is total over the code union: a new code does not compile
+* until it has a message.
+*/
+const plural = (count, singular, pluralForm = `${singular}s`) => `${String(count)} ${count === 1 ? singular : pluralForm}`;
+/** The location suffix, omitted when the part is all we know. */
+const where = ({ location }) => {
+	if (location.at === void 0) return "";
+	return ` at ${location.at} in ${location.part}`;
+};
+const quoted = (value) => value === void 0 ? "" : ` "${value}"`;
+const PARSE_WARNING_MESSAGES = {
+	[PARSE_WARNING_CODES.packageDecrypted]: () => "Document was opened from password-protected storage; saving writes an unencrypted .docx file.",
+	[PARSE_WARNING_CODES.packageArchive]: (warning) => warning.detail ?? "The archive reader reported an issue.",
+	[PARSE_WARNING_CODES.documentPartMissing]: () => "No document.xml found in DOCX",
+	[PARSE_WARNING_CODES.documentModelIssue]: (warning) => warning.detail ?? "The document model reported an issue.",
+	[PARSE_WARNING_CODES.duplicateCommentId]: (warning) => `Dropped ${plural(warning.count, "comment")} repeating a w:id another comment already defines.`,
+	[PARSE_WARNING_CODES.missingCommentId]: (warning) => `Dropped ${plural(warning.count, "comment")} with no readable w:id.`,
+	[PARSE_WARNING_CODES.duplicateNoteId]: (warning) => `Dropped ${plural(warning.count, "note")} repeating a w:id another note already defines.`,
+	[PARSE_WARNING_CODES.danglingCommentReference]: (warning) => `Removed ${plural(warning.count, "dangling comment reference marker")} whose comments.xml entries are missing.`,
+	[PARSE_WARNING_CODES.unbalancedCommentRange]: (warning) => `Re-anchored ${plural(warning.count, "unbalanced comment range marker")} as point comments.`,
+	[PARSE_WARNING_CODES.danglingHeaderReference]: (warning) => `Removed ${plural(warning.count, "dangling header reference")} whose header parts are missing.`,
+	[PARSE_WARNING_CODES.danglingFooterReference]: (warning) => `Removed ${plural(warning.count, "dangling footer reference")} whose footer parts are missing.`,
+	[PARSE_WARNING_CODES.danglingRelationshipId]: (warning) => `Left relationship id${quoted(warning.value)} unresolved${where(warning)}; the part defines no such relationship.`,
+	[PARSE_WARNING_CODES.unnumberedParagraph]: (warning) => `Unnumbered ${plural(warning.count, "paragraph")} whose numbering definitions are missing.`,
+	[PARSE_WARNING_CODES.unnumberedStyle]: (warning) => `Unnumbered style${quoted(warning.value)} whose numbering definition is missing.`,
+	[PARSE_WARNING_CODES.unbalancedMoveRange]: (warning) => `Removed ${plural(warning.count, "unbalanced tracked move range marker")}.`,
+	[PARSE_WARNING_CODES.headerFooterTypeOutsideEnum]: (warning) => `Read header/footer type${quoted(warning.value)} as "default"${where(warning)}; ST_HdrFtr is even, default or first.`,
+	[PARSE_WARNING_CODES.unrecognisedOnOffValue]: (warning) => `Ignored on/off value${quoted(warning.value)}${where(warning)}; ST_OnOff is 1, 0, true, false, on or off.`,
+	[PARSE_WARNING_CODES.borderWithoutValue]: (warning) => `Read a border with no w:val${where(warning)} as having no border style.`,
+	[PARSE_WARNING_CODES.styleSetDuplicateStyleId]: (warning) => `Dropped a style repeating the id${quoted(warning.value)} another style in the set already defines.`,
+	[PARSE_WARNING_CODES.styleSetInitialStyleMissing]: (warning) => `The style set names initial paragraph style${quoted(warning.value)}, which it does not contain; used the set's default instead${where(warning)}.`
+};
+const formatParseWarning = (warning) => PARSE_WARNING_MESSAGES[warning.code](warning);
+const formatParseWarnings = (warnings) => warnings.map(formatParseWarning);
+//#endregion
+export { formatParseWarning, formatParseWarnings };

package/dist/docx/parser.js

@@ -1,35 +1,39 @@
 import { toArrayBuffer } from "../utils/docxInput.js";
 import { loadFontsWithMapping } from "../utils/fontLoader.js";
 import { MAX_PACKAGE_TIFF_PIXELS, convertTiffToPngDataUrl, isTiffMimeType } from "../utils/tiffConverter.js";
-import { normalizeCommentIds } from "./commentIdNormalization.js";
+import { DUPLICATE_COMMENT_ID_WARNING, normalizeCommentIds } from "./commentIdNormalization.js";
 import { parseComments } from "./commentParser.js";
-import { normalizeCommentReferences } from "./commentReferenceNormalization.js";
+import { DANGLING_COMMENT_REFERENCE_WARNING, UNBALANCED_COMMENT_RANGE_WARNING, normalizeCommentReferences } from "./commentReferenceNormalization.js";
 import { detectDocxConformanceClass } from "./conformance.js";
 import { parseCoreProperties } from "./corePropertiesParser.js";
+import { countDanglingRelationshipReferences } from "./danglingRelationshipReferences.js";
 import { extractAllTemplateVariables, parseDocumentBody } from "./documentParser.js";
 import { normalizeDrawingIds } from "./drawingIdNormalization.js";
 import { DocxEncryptionError } from "./encryption/errors.js";
 import { parseFontTable } from "./fontTableParser.js";
 import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
 import { parseFooter, parseHeader } from "./headerFooterParser.js";
-import { normalizeHeaderFooterReferences } from "./headerFooterReferenceNormalization.js";
+import { DANGLING_FOOTER_REFERENCE_WARNING, DANGLING_HEADER_REFERENCE_WARNING, normalizeHeaderFooterReferences } from "./headerFooterReferenceNormalization.js";
 import { assignHeaderFooterVerbatimXml, refreshHeaderFooterVerbatimFingerprint } from "./headerFooterVerbatim.js";
 import { extractMetafileRaster, isMetafileMimeType } from "./metafileRaster.js";
 import { renderEmfSvg } from "./metafileSvg.js";
 import { DocxModelValidationError, formatDocumentModelIssues, validateFolioDocumentModel } from "./modelValidation.js";
 import { parseNumbering } from "./numberingParser.js";
-import { normalizeNumberingReferences, normalizeStyleNumberingReferences } from "./numberingReferenceNormalization.js";
+import { UNNUMBERED_PARAGRAPH_WARNING, UNNUMBERED_STYLE_WARNING, normalizeNumberingReferences, normalizeStyleNumberingReferences } from "./numberingReferenceNormalization.js";
 import { assignDocumentParagraphPropertySourceContract } from "./paragraphPropertySource.js";
+import { createParseWarningCollector } from "./parseContext.js";
+import { formatParseWarnings } from "./parseWarningMessage.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
 import { normalizeRenderedPageBreakHints } from "./renderedPageBreakNormalization.js";
 import { parseSettings } from "./settingsParser.js";
 import { parseStylesPackage } from "./styleParser.js";
 import { applyThemeFontLang, parseTheme } from "./themeParser.js";
-import { normalizeTrackedMoveRanges } from "./trackedMoveRangeNormalization.js";
+import { UNBALANCED_MOVE_RANGE_WARNING, normalizeTrackedMoveRanges } from "./trackedMoveRangeNormalization.js";
 import { getMediaMimeType, mediaToDataUrl, unzipDocx } from "./unzip.js";
 import { enforcePackageVmlPreviewBudget } from "./vmlPreview.js";
 import { FOLIO_XML_RESOURCE_LIMITS } from "./xmlResourceLimits.js";
 import { TaggedError } from "better-result";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/parser.ts
 /**
 * Main Parser Orchestrator - Unified parseDocx function
@@ -70,7 +74,7 @@ const sha256Hex = async (buffer) => {
 async function parseDocx(input, options = {}) {
 	const buffer = input instanceof ArrayBuffer ? input : await toArrayBuffer(input);
 	const { onProgress = () => {}, preloadFonts = true, parseHeadersFooters = true, parseNotes = true, detectVariables = true, password, unzipLimits, mediaResolver } = options;
-	const warnings = [];
+	const { context: parseContext, warnings: collectedWarnings } = createParseWarningCollector();
 	try {
 		const timeStage = (_name, fn) => fn();
 		const timeStageAsync = async (_name, fn) => await fn();
@@ -81,8 +85,11 @@ async function parseDocx(input, options = {}) {
 			password,
 			extractAllXml: false
 		}));
-		if (raw.wasEncrypted) warnings.push("Document was opened from password-protected storage; saving writes an unencrypted .docx file.");
-		warnings.push(...raw.warnings);
+		if (raw.wasEncrypted) parseContext.warn({ code: PARSE_WARNING_CODES.packageDecrypted });
+		for (const message of raw.warnings) parseContext.warn({
+			code: PARSE_WARNING_CODES.packageArchive,
+			detail: message
+		});
 		onProgress("Extracted DOCX", 10);
 		onProgress("Parsing relationships...", 10);
 		const rels = timeStage("relationships", () => raw.documentRels ? parseRelationships(raw.documentRels) : /* @__PURE__ */ new Map());
@@ -114,8 +121,8 @@ async function parseDocx(input, options = {}) {
 		onProgress("Parsing document body...", 40);
 		let documentBody = { content: [] };
 		timeStage("documentBody", () => {
-			if (raw.documentXml) documentBody = parseDocumentBody(raw.documentXml, styles, theme, numbering, rels, media);
-			else warnings.push("No document.xml found in DOCX");
+			if (raw.documentXml) documentBody = parseDocumentBody(raw.documentXml, styles, theme, numbering, rels, media, parseContext.scoped({ part: "word/document.xml" }));
+			else parseContext.warn({ code: PARSE_WARNING_CODES.documentPartMissing });
 		});
 		onProgress("Parsed document body", 55);
 		let headers;
@@ -131,15 +138,19 @@ async function parseDocx(input, options = {}) {
 		let endnotes;
 		if (parseNotes) {
 			onProgress("Parsing footnotes/endnotes...", 65);
-			const notes = timeStage("footnotesEndnotes", () => parseNotesContent(raw, styles, theme, numbering, rels, media));
+			const notes = timeStage("footnotesEndnotes", () => parseNotesContent(raw, styles, theme, numbering, rels, media, parseContext));
 			footnotes = notes.footnotes;
 			endnotes = notes.endnotes;
 			onProgress("Parsed footnotes/endnotes", 75);
 		} else onProgress("Skipping footnotes/endnotes", 75);
 		onProgress("Parsing comments...", 75);
-		const comments = timeStage("comments", () => parseComments(raw.commentsXml, styles, theme, rels, media, raw.commentsExtensibleXml, raw.commentsExtendedXml));
+		const commentsContext = parseContext.scoped({ part: "word/comments.xml" });
+		const comments = timeStage("comments", () => parseComments(raw.commentsXml, styles, theme, rels, media, raw.commentsExtensibleXml, raw.commentsExtendedXml, commentsContext));
 		const commentIdNormalization = normalizeCommentIds(comments);
-		if (commentIdNormalization.droppedDuplicateComments > 0) warnings.push(`Dropped ${commentIdNormalization.droppedDuplicateComments} comment(s) repeating a w:id another comment already defines.`);
+		if (commentIdNormalization.droppedDuplicateComments > 0) commentsContext.warn({
+			code: DUPLICATE_COMMENT_ID_WARNING,
+			count: commentIdNormalization.droppedDuplicateComments
+		});
 		if (comments.length > 0) documentBody.comments = comments;
 		normalizeDrawingIds({
 			documentBody,
@@ -165,15 +176,27 @@ async function parseDocx(input, options = {}) {
 			...footnotes !== void 0 ? { footnotes } : {},
 			...endnotes !== void 0 ? { endnotes } : {}
 		});
-		if (commentReferenceNormalization.removedDanglingReferences > 0) warnings.push(`Removed ${commentReferenceNormalization.removedDanglingReferences} dangling comment reference marker(s) whose comments.xml entries are missing.`);
-		if (commentReferenceNormalization.reanchoredUnbalancedRanges > 0) warnings.push(`Re-anchored ${commentReferenceNormalization.reanchoredUnbalancedRanges} unbalanced comment range marker(s) as point comments.`);
+		if (commentReferenceNormalization.removedDanglingReferences > 0) parseContext.warn({
+			code: DANGLING_COMMENT_REFERENCE_WARNING,
+			count: commentReferenceNormalization.removedDanglingReferences
+		});
+		if (commentReferenceNormalization.reanchoredUnbalancedRanges > 0) parseContext.warn({
+			code: UNBALANCED_COMMENT_RANGE_WARNING,
+			count: commentReferenceNormalization.reanchoredUnbalancedRanges
+		});
 		const headerFooterReferenceNormalization = normalizeHeaderFooterReferences({
 			documentBody,
 			...headers !== void 0 ? { headers } : {},
 			...footers !== void 0 ? { footers } : {}
 		});
-		if (headerFooterReferenceNormalization.removedDanglingHeaderReferences > 0) warnings.push(`Removed ${headerFooterReferenceNormalization.removedDanglingHeaderReferences} dangling header reference(s) whose header parts are missing.`);
-		if (headerFooterReferenceNormalization.removedDanglingFooterReferences > 0) warnings.push(`Removed ${headerFooterReferenceNormalization.removedDanglingFooterReferences} dangling footer reference(s) whose footer parts are missing.`);
+		if (headerFooterReferenceNormalization.removedDanglingHeaderReferences > 0) parseContext.warn({
+			code: DANGLING_HEADER_REFERENCE_WARNING,
+			count: headerFooterReferenceNormalization.removedDanglingHeaderReferences
+		});
+		if (headerFooterReferenceNormalization.removedDanglingFooterReferences > 0) parseContext.warn({
+			code: DANGLING_FOOTER_REFERENCE_WARNING,
+			count: headerFooterReferenceNormalization.removedDanglingFooterReferences
+		});
 		const numberingReferenceNormalization = normalizeNumberingReferences({
 			documentBody,
 			numbering,
@@ -182,12 +205,33 @@ async function parseDocx(input, options = {}) {
 			...footnotes !== void 0 ? { footnotes } : {},
 			...endnotes !== void 0 ? { endnotes } : {}
 		});
-		if (numberingReferenceNormalization.unnumberedDanglingReferences > 0) warnings.push(`Unnumbered ${numberingReferenceNormalization.unnumberedDanglingReferences} paragraph(s) whose numbering definitions are missing.`);
+		if (numberingReferenceNormalization.unnumberedDanglingReferences > 0) parseContext.warn({
+			code: UNNUMBERED_PARAGRAPH_WARNING,
+			count: numberingReferenceNormalization.unnumberedDanglingReferences
+		});
 		const styleNumberingNormalization = normalizeStyleNumberingReferences({
 			styles: styleDefinitions?.styles ?? [],
 			numbering
 		});
-		for (const styleId of styleNumberingNormalization.unnumberedStyleIds) warnings.push(`Unnumbered style "${styleId}" whose numbering definition is missing.`);
+		for (const styleId of styleNumberingNormalization.unnumberedStyleIds) parseContext.warn({
+			code: UNNUMBERED_STYLE_WARNING,
+			value: styleId,
+			at: `style "${styleId}"`
+		});
+		const danglingReferences = countDanglingRelationshipReferences({
+			content: documentBody.content,
+			relationships: rels
+		});
+		if (danglingReferences.drawings > 0) parseContext.warn({
+			code: PARSE_WARNING_CODES.danglingRelationshipId,
+			element: "w:drawing",
+			count: danglingReferences.drawings
+		});
+		if (danglingReferences.hyperlinks > 0) parseContext.warn({
+			code: PARSE_WARNING_CODES.danglingRelationshipId,
+			element: "w:hyperlink",
+			count: danglingReferences.hyperlinks
+		});
 		const trackedMoveRangeNormalization = normalizeTrackedMoveRanges({
 			documentBody,
 			...headers !== void 0 ? { headers } : {},
@@ -195,7 +239,10 @@ async function parseDocx(input, options = {}) {
 			...footnotes !== void 0 ? { footnotes } : {},
 			...endnotes !== void 0 ? { endnotes } : {}
 		});
-		if (trackedMoveRangeNormalization.removedUnbalancedMoveRangeMarkers > 0) warnings.push(`Removed ${trackedMoveRangeNormalization.removedUnbalancedMoveRangeMarkers} unbalanced tracked move range marker(s).`);
+		if (trackedMoveRangeNormalization.removedUnbalancedMoveRangeMarkers > 0) parseContext.warn({
+			code: UNBALANCED_MOVE_RANGE_WARNING,
+			count: trackedMoveRangeNormalization.removedUnbalancedMoveRangeMarkers
+		});
 		let templateVariables;
 		if (detectVariables) {
 			onProgress("Detecting template variables...", 75);
@@ -238,8 +285,15 @@ async function parseDocx(input, options = {}) {
 		const validation = validateFolioDocumentModel(document);
 		const parsedCompleteModel = parseHeadersFooters && parseNotes;
 		if (!validation.valid && parsedCompleteModel) throw new DocxModelValidationError("Parsed DOCX produced an invalid document model", validation.issues);
-		warnings.push(...formatDocumentModelIssues(validation.issues));
-		if (warnings.length > 0) document.warnings = warnings;
+		for (const issue of formatDocumentModelIssues(validation.issues)) parseContext.warn({
+			code: PARSE_WARNING_CODES.documentModelIssue,
+			detail: issue
+		});
+		const parseWarnings = collectedWarnings();
+		if (parseWarnings.length > 0) {
+			document.parseWarnings = parseWarnings;
+			document.warnings = formatParseWarnings(parseWarnings);
+		}
 		onProgress("Complete", 100);
 		return document;
 	} catch (error) {
@@ -418,7 +472,7 @@ function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media) {
 		if (headerXml) {
 			const headerRelsPath = getRelationshipsPathForPart(partPath);
 			const headerRelsXml = getMapCaseInsensitive(raw.allXml, headerRelsPath);
-			const headerRels = headerRelsXml ? parseRelationships(headerRelsXml) : rels;
+			const headerRels = headerRelsXml ? parseRelationships(headerRelsXml) : /* @__PURE__ */ new Map();
 			const header = parseHeader(headerXml, "default", styles, theme, numbering, headerRels, media);
 			const watermark = header.watermark;
 			if (watermark?.kind === "picture") {
@@ -437,7 +491,7 @@ function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media) {
 		if (footerXml) {
 			const footerRelsPath = getRelationshipsPathForPart(partPath);
 			const footerRelsXml = getMapCaseInsensitive(raw.allXml, footerRelsPath);
-			const footer = parseFooter(footerXml, "default", styles, theme, numbering, footerRelsXml ? parseRelationships(footerRelsXml) : rels, media);
+			const footer = parseFooter(footerXml, "default", styles, theme, numbering, footerRelsXml ? parseRelationships(footerRelsXml) : /* @__PURE__ */ new Map(), media);
 			footers.set(rId, footer);
 		}
 	}
@@ -449,13 +503,13 @@ function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media) {
 /**
 * Parse footnotes and endnotes from raw content
 */
-function parseNotesContent(raw, styles, theme, numbering, rels, media) {
+function parseNotesContent(raw, styles, theme, numbering, rels, media, context) {
 	const relsForNotePart = (partPath) => {
 		const xml = getMapCaseInsensitive(raw.allXml, getRelationshipsPathForPart(partPath));
 		return xml ? parseRelationships(xml) : rels;
 	};
-	const footnoteMap = parseFootnotes(raw.footnotesXml, styles, theme, numbering, relsForNotePart("word/footnotes.xml"), media);
-	const endnoteMap = parseEndnotes(raw.endnotesXml, styles, theme, numbering, relsForNotePart("word/endnotes.xml"), media);
+	const footnoteMap = parseFootnotes(raw.footnotesXml, styles, theme, numbering, relsForNotePart("word/footnotes.xml"), media, context?.scoped({ part: "word/footnotes.xml" }));
+	const endnoteMap = parseEndnotes(raw.endnotesXml, styles, theme, numbering, relsForNotePart("word/endnotes.xml"), media, context?.scoped({ part: "word/endnotes.xml" }));
 	return {
 		footnotes: footnoteMap.getNormalFootnotes(),
 		endnotes: endnoteMap.getNormalEndnotes()

package/dist/docx/relsParser.d.ts

@@ -107,21 +107,38 @@ declare function getHeaders(map: document_d_exports.RelationshipMap): document_d
  */
 declare function getFooters(map: document_d_exports.RelationshipMap): document_d_exports.Relationship[];
 /**
- * Resolve a relationship ID to a target path
+ * What a relationship id names.
+ *
+ * The three cases are kept apart because collapsing any of them into a string
+ * turns absence into a lookup key: an id the author never wrote, an id whose
+ * target the package no longer holds, and an id that resolves are different
+ * facts, and only the last one may be read as a part.
+ */
+type RelationshipResolution = {
+  status: "resolved";
+  relationship: document_d_exports.Relationship;
+} | {
+  status: "absent";
+} | {
+  status: "dangling";
+  id: string;
+};
+/**
+ * Resolve a relationship id against a relationship map.
  *
- * @param map - RelationshipMap to search
- * @param rId - Relationship ID (e.g., "rId1")
- * @returns Target path or undefined if not found
+ * The only sanctioned way to turn an `r:id`, `r:embed` or `r:link` into a part.
+ * An empty attribute is absence, not an id: `ST_RelationshipId` is an NCName,
+ * so `""` can never name a relationship, and no map can hold it as a key.
  */
-declare function resolveTarget(map: document_d_exports.RelationshipMap, rId: string): string | undefined;
+declare function resolveRelationshipId(map: document_d_exports.RelationshipMap | null | undefined, rId: string | undefined): RelationshipResolution;
 /**
- * Resolve a relationship ID to a full relationship
+ * Resolve a relationship id and require it to name a relationship of one type.
  *
- * @param map - RelationshipMap to search
- * @param rId - Relationship ID (e.g., "rId1")
- * @returns Relationship or undefined if not found
+ * A reference of the wrong type is reported as dangling: the part it names
+ * exists, but not as the thing the reference asked for, and reading it anyway
+ * is how a missing image comes back as `styles.xml`.
  */
-declare function resolveRelationship(map: document_d_exports.RelationshipMap, rId: string): document_d_exports.Relationship | undefined;
+declare function resolveRelationshipIdOfType(map: document_d_exports.RelationshipMap | null | undefined, rId: string | undefined, type: document_d_exports.RelationshipType): RelationshipResolution;
 /**
  * Resolve a relative target path to an absolute path within the DOCX
  *
@@ -158,4 +175,4 @@ declare function parsePackageRelationships(relsXml: string): document_d_exports.
  */
 declare function formatRelationships(map: document_d_exports.RelationshipMap): string;
 //#endregion
-export { RELATIONSHIP_TYPES, filterByType, formatRelationships, getFooters, getHeaders, getHyperlinks, getImages, getRelationshipTypeName, isExternalHyperlink, isFooterRelationship, isHeaderRelationship, isImageRelationship, parseDocumentRelationships, parsePackageRelationships, parseRelationships, resolveRelationship, resolveRelativePath, resolveTarget };
+export { RELATIONSHIP_TYPES, RelationshipResolution, filterByType, formatRelationships, getFooters, getHeaders, getHyperlinks, getImages, getRelationshipTypeName, isExternalHyperlink, isFooterRelationship, isHeaderRelationship, isImageRelationship, parseDocumentRelationships, parsePackageRelationships, parseRelationships, resolveRelationshipId, resolveRelationshipIdOfType, resolveRelativePath };

package/dist/docx/relsParser.js

@@ -155,24 +155,37 @@ function getFooters(map) {
 	return filterByType(map, RELATIONSHIP_TYPES.footer);
 }
 /**
-* Resolve a relationship ID to a target path
+* Resolve a relationship id against a relationship map.
 *
-* @param map - RelationshipMap to search
-* @param rId - Relationship ID (e.g., "rId1")
-* @returns Target path or undefined if not found
+* The only sanctioned way to turn an `r:id`, `r:embed` or `r:link` into a part.
+* An empty attribute is absence, not an id: `ST_RelationshipId` is an NCName,
+* so `""` can never name a relationship, and no map can hold it as a key.
 */
-function resolveTarget(map, rId) {
-	return map.get(rId)?.target;
+function resolveRelationshipId(map, rId) {
+	if (rId === void 0 || rId.length === 0) return { status: "absent" };
+	const relationship = map?.get(rId);
+	return relationship === void 0 ? {
+		status: "dangling",
+		id: rId
+	} : {
+		status: "resolved",
+		relationship
+	};
 }
 /**
-* Resolve a relationship ID to a full relationship
+* Resolve a relationship id and require it to name a relationship of one type.
 *
-* @param map - RelationshipMap to search
-* @param rId - Relationship ID (e.g., "rId1")
-* @returns Relationship or undefined if not found
+* A reference of the wrong type is reported as dangling: the part it names
+* exists, but not as the thing the reference asked for, and reading it anyway
+* is how a missing image comes back as `styles.xml`.
 */
-function resolveRelationship(map, rId) {
-	return map.get(rId);
+function resolveRelationshipIdOfType(map, rId, type) {
+	const resolved = resolveRelationshipId(map, rId);
+	if (resolved.status !== "resolved" || resolved.relationship.type === type) return resolved;
+	return {
+		status: "dangling",
+		id: resolved.relationship.id
+	};
 }
 /**
 * Resolve a relative target path to an absolute path within the DOCX
@@ -232,4 +245,4 @@ function formatRelationships(map) {
 	return lines.join("\n");
 }
 //#endregion
-export { RELATIONSHIP_TYPES, filterByType, formatRelationships, getFooters, getHeaders, getHyperlinks, getImages, getRelationshipTypeName, isExternalHyperlink, isFooterRelationship, isHeaderRelationship, isImageRelationship, parseDocumentRelationships, parsePackageRelationships, parseRelationships, resolveRelationship, resolveRelativePath, resolveTarget };
+export { RELATIONSHIP_TYPES, filterByType, formatRelationships, getFooters, getHeaders, getHyperlinks, getImages, getRelationshipTypeName, isExternalHyperlink, isFooterRelationship, isHeaderRelationship, isImageRelationship, parseDocumentRelationships, parsePackageRelationships, parseRelationships, resolveRelationshipId, resolveRelationshipIdOfType, resolveRelativePath };

package/dist/docx/revisionIdNormalization.js

@@ -31,16 +31,79 @@ const REVISION_ELEMENT_NAMES = /* @__PURE__ */ new Set([
 	"trPrChange"
 ]);
 const REVISION_ELEMENT_CANDIDATE = new RegExp(`<(?:[^\\s<>/:]+:)?(?:${[...REVISION_ELEMENT_NAMES].join("|")})(?:[\\s/>])`, "u");
-const revisionAttribute = (element) => {
-	if (!element.name || !WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "") || !REVISION_ELEMENT_NAMES.has(getLocalName(element.name))) return null;
+/**
+* The rest of the annotation id space.
+*
+* A comment, a bookmark, a protected range and a tracked change all draw their
+* `w:id` from one space: Word allocates from a single counter, which is why a
+* package carrying several kinds almost never repeats a value across them. So
+* an id this pass mints must avoid these as well, or a renumbered `w:ins`
+* lands on a live comment.
+*
+* They are only ever reserved, never claimed. A comment id legitimately
+* appears four times (`w:comment`, both range markers and the reference) and a
+* bookmark id twice, so feeding them to the uniqueness machinery would reject
+* a package Word wrote. Their pairing is also why they are not revision
+* elements: renumbering one end of a range would unpair it.
+*/
+const ANNOTATION_ELEMENT_NAMES = /* @__PURE__ */ new Set([
+	"bookmarkEnd",
+	"bookmarkStart",
+	"comment",
+	"commentRangeEnd",
+	"commentRangeStart",
+	"commentReference",
+	"customXmlDelRangeEnd",
+	"customXmlDelRangeStart",
+	"customXmlInsRangeEnd",
+	"customXmlInsRangeStart",
+	"customXmlMoveFromRangeEnd",
+	"customXmlMoveFromRangeStart",
+	"customXmlMoveToRangeEnd",
+	"customXmlMoveToRangeStart",
+	"moveFromRangeEnd",
+	"moveFromRangeStart",
+	"moveToRangeEnd",
+	"moveToRangeStart",
+	"permEnd",
+	"permStart"
+]);
+const ANNOTATION_ELEMENT_CANDIDATE = new RegExp(`<(?:[^\\s<>/:]+:)?(?:${[...ANNOTATION_ELEMENT_NAMES].join("|")})(?:[\\s/>])`, "u");
+const ID_KINDS = {
+	revision: "revision",
+	annotation: "annotation"
+};
+/** One lookup for both halves of the space, so an element is classified once. */
+const ID_KIND_BY_ELEMENT_NAME = new Map([...[...REVISION_ELEMENT_NAMES].map((name) => [name, ID_KINDS.revision]), ...[...ANNOTATION_ELEMENT_NAMES].map((name) => [name, ID_KINDS.annotation])]);
+/**
+* An element's `w:id` and which half of the annotation space it belongs to.
+*
+* One classifier rather than two, because it runs on every element of every
+* scanned part: resolving the namespace and the local name twice to ask two
+* questions measured 18% on a 17.6 MiB package.
+*
+* `w:permStart` types its id as a string, so a protected range named
+* `everyone` yields nothing. That is correct: a value the allocator can never
+* mint is not one it has to avoid.
+*/
+const identifiedElement = (element) => {
+	if (!element.name || !WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "")) return null;
+	const localName = getLocalName(element.name);
+	const kind = ID_KIND_BY_ELEMENT_NAME.get(localName);
+	if (kind === void 0) return null;
 	const attribute = findAttributeByNamespaceUri(element, WORDPROCESSINGML_NAMESPACE_URIS, "id");
 	if (!attribute) return null;
 	const id = Number(attribute.value);
 	return Number.isSafeInteger(id) && id >= 0 ? {
+		kind,
 		name: attribute.name,
 		id
 	} : null;
 };
+const revisionAttribute = (element) => {
+	const identified = identifiedElement(element);
+	return identified?.kind === ID_KINDS.revision ? identified : null;
+};
 /**
 * Keep physical tracked-change element ids unique across a package.
 *
@@ -57,11 +120,10 @@ const normalizeRevisionIdsInXmlParts = (parts) => {
 		assertXmlResourceLimits(xml);
 		const ids = [];
 		if (rewriteStreamingXmlDecimalAttributes(xml, (element) => {
-			const attribute = revisionAttribute(element);
-			if (attribute) {
-				ids.push(attribute.id);
-				reserved.add(attribute.id);
-			}
+			const identified = identifiedElement(element);
+			if (identified === null) return null;
+			if (identified.kind === ID_KINDS.revision) ids.push(identified.id);
+			reserved.add(identified.id);
 			return null;
 		}).status === "unsupported") throw new XmlResourceLimitError({
 			message: `Revision-id normalization could not safely scan ${path}`,
@@ -73,6 +135,18 @@ const normalizeRevisionIdsInXmlParts = (parts) => {
 	const firstSeen = /* @__PURE__ */ new Set();
 	for (const [path, ids] of occurrencesByPath) for (const id of ids) if (firstSeen.has(id)) repeatedPaths.add(path);
 	else firstSeen.add(id);
+	if (repeatedPaths.size > 0) for (const [path, xml] of parts) {
+		if (occurrencesByPath.has(path) || !ANNOTATION_ELEMENT_CANDIDATE.test(xml)) continue;
+		assertXmlResourceLimits(xml);
+		if (rewriteStreamingXmlDecimalAttributes(xml, (element) => {
+			const identified = identifiedElement(element);
+			if (identified !== null) reserved.add(identified.id);
+			return null;
+		}).status === "unsupported") throw new XmlResourceLimitError({
+			message: `Revision-id normalization could not safely scan ${path}`,
+			limit: "syntax"
+		});
+	}
 	let nextId = 0;
 	const allocate = () => {
 		while (reserved.has(nextId)) nextId += 1;