@stll/folio-core 0.42.0 → 0.44.0

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

package/dist/docx/defaultParagraphStyle.d.ts

@@ -0,0 +1,39 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/defaultParagraphStyle.d.ts
+/** The name Word's built-in default paragraph style always carries in the file. */
+declare const BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME = "Normal";
+/** The id English Word gives it, kept as the last resort for the reverse case. */
+declare const BUILT_IN_DEFAULT_PARAGRAPH_STYLE_ID = "Normal";
+/**
+ * The formatting Word's default template gives Normal: 8pt (160 twips) after
+ * spacing, 1.08x line spacing.
+ *
+ * A package that declares neither a default paragraph style nor `w:docDefaults`
+ * renders as though it declared this, so anything that mints the missing
+ * default has to mint the formatting with it.
+ */
+declare const BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING: {
+  spaceAfter: number;
+  lineSpacing: number;
+  lineSpacingRule: "auto";
+};
+type MintDefaultParagraphStyleOptions = {
+  takenStyleIds: ReadonlySet<string>;
+  /** Whether the source declared `w:docDefaults`, which the set carries over. */
+  hasDocDefaults: boolean;
+};
+/**
+ * The default paragraph style a set needs when its source declared none.
+ *
+ * The id only has to be free, because the set is what defines it. The
+ * formatting has to be the built-in template's whenever the source had no
+ * `w:docDefaults`, because that is what the source itself rendered as: a
+ * consumer applies its built-in Normal only where no default paragraph style
+ * exists, and this minted style is one. Where the source did declare
+ * `w:docDefaults`, the set carries them and they remain authoritative, so the
+ * minted style states nothing.
+ */
+declare const mintDefaultParagraphStyle: ({ takenStyleIds, hasDocDefaults }: MintDefaultParagraphStyleOptions) => document_d_exports.Style;
+declare const resolveDefaultParagraphStyle: (styles: Iterable<document_d_exports.Style>) => document_d_exports.Style | undefined;
+//#endregion
+export { BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING, BUILT_IN_DEFAULT_PARAGRAPH_STYLE_ID, BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME, mintDefaultParagraphStyle, resolveDefaultParagraphStyle };

package/dist/docx/defaultParagraphStyle.js

@@ -0,0 +1,54 @@
+//#region src/docx/defaultParagraphStyle.ts
+/** The name Word's built-in default paragraph style always carries in the file. */
+const BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME = "Normal";
+/** The id English Word gives it, kept as the last resort for the reverse case. */
+const BUILT_IN_DEFAULT_PARAGRAPH_STYLE_ID = "Normal";
+/**
+* The formatting Word's default template gives Normal: 8pt (160 twips) after
+* spacing, 1.08x line spacing.
+*
+* A package that declares neither a default paragraph style nor `w:docDefaults`
+* renders as though it declared this, so anything that mints the missing
+* default has to mint the formatting with it.
+*/
+const BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING = {
+	spaceAfter: 160,
+	lineSpacing: 259,
+	lineSpacingRule: "auto"
+};
+/**
+* The default paragraph style a set needs when its source declared none.
+*
+* The id only has to be free, because the set is what defines it. The
+* formatting has to be the built-in template's whenever the source had no
+* `w:docDefaults`, because that is what the source itself rendered as: a
+* consumer applies its built-in Normal only where no default paragraph style
+* exists, and this minted style is one. Where the source did declare
+* `w:docDefaults`, the set carries them and they remain authoritative, so the
+* minted style states nothing.
+*/
+const mintDefaultParagraphStyle = ({ takenStyleIds, hasDocDefaults }) => {
+	let styleId = BUILT_IN_DEFAULT_PARAGRAPH_STYLE_ID;
+	for (let suffix = 1; takenStyleIds.has(styleId); suffix += 1) styleId = `${BUILT_IN_DEFAULT_PARAGRAPH_STYLE_ID}${suffix}`;
+	return {
+		styleId,
+		type: "paragraph",
+		name: BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME,
+		default: true,
+		...hasDocDefaults ? {} : { pPr: { ...BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING } }
+	};
+};
+const resolveDefaultParagraphStyle = (styles) => {
+	let flagged;
+	let namedBuiltIn;
+	let idBuiltIn;
+	for (const style of styles) {
+		if (style.type !== "paragraph") continue;
+		if (style.default) flagged = style;
+		if (namedBuiltIn === void 0 && style.name === "Normal") namedBuiltIn = style;
+		if (idBuiltIn === void 0 && style.styleId === "Normal") idBuiltIn = style;
+	}
+	return flagged ?? namedBuiltIn ?? idBuiltIn;
+};
+//#endregion
+export { BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING, BUILT_IN_DEFAULT_PARAGRAPH_STYLE_ID, BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME, mintDefaultParagraphStyle, resolveDefaultParagraphStyle };

package/dist/docx/documentParser.d.ts

@@ -1,6 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
 import { StyleMap } from "./styleParser.js";
+import { ParseContext } from "./parseContext.js";
 //#region src/docx/documentParser.d.ts
 /**
  * Extract template variables from text
@@ -27,7 +28,7 @@ declare function extractAllTemplateVariables(content: document_d_exports.BlockCo
  * @param media - Media files
  * @returns DocumentBody with content, sections, and template variables
  */
-declare function parseDocumentBody(xml: string, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, numbering?: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null): document_d_exports.DocumentBody;
+declare function parseDocumentBody(xml: string, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, numbering?: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null, context?: ParseContext): document_d_exports.DocumentBody;
 /**
  * Get all paragraphs from document body (flattened)
  */

package/dist/docx/documentParser.js

@@ -119,7 +119,7 @@ function canonicalizeLeadingBodySectionProperties(bodyElement, body) {
 * @param media - Media files
 * @returns DocumentBody with content, sections, and template variables
 */
-function parseDocumentBody(xml, styles = null, theme = null, numbering = null, rels = null, media = null) {
+function parseDocumentBody(xml, styles = null, theme = null, numbering = null, rels = null, media = null, context) {
 	const result = { content: [] };
 	if (!xml) return result;
 	const streamed = parseStreamingXml(xml);
@@ -129,7 +129,7 @@ function parseDocumentBody(xml, styles = null, theme = null, numbering = null, r
 	if (!bodyEl) return result;
 	result.content = parseBlockContent(bodyEl, styles, theme, numbering, rels, media, { rootXmlns: collectXmlnsDeclarations(documentEl) });
 	const finalSectPr = findChild(bodyEl, "w", "sectPr");
-	if (finalSectPr) result.finalSectionProperties = parseSectionProperties(finalSectPr);
+	if (finalSectPr) result.finalSectionProperties = parseSectionProperties(finalSectPr, context);
 	canonicalizeLeadingBodySectionProperties(bodyEl, result);
 	result.sections = buildSections(result.content, result.finalSectionProperties);
 	return result;

package/dist/docx/drawingUtils.d.ts

@@ -67,6 +67,13 @@ declare function parseWrapElement(wrapEl: XmlElement | null, behindDoc: boolean,
 /**
  * Parse wrap from an anchor element (finds wrap child internally).
  */
+/**
+ * Read `wp:anchor/@behindDoc`, the flag that puts an anchored object behind the
+ * body text. The attribute is xsd:boolean, so `1`, `0`, `true` and `false` are
+ * all legal spellings and producers differ: Word writes `1`, others `true`.
+ * Absent means in front of the text.
+ */
+declare function parseAnchorBehindDoc(anchor: XmlElement): boolean;
 declare function parseAnchorWrap(anchor: XmlElement): document_d_exports.ImageWrap | undefined;
 /**
  * Resolve a ColorValue to a CSS hex string using default theme colors.
@@ -74,4 +81,4 @@ declare function parseAnchorWrap(anchor: XmlElement): document_d_exports.ImageWr
  */
 declare function resolveColorValueToHex(color: document_d_exports.ColorValue | undefined): string | undefined;
 //#endregion
-export { THEME_COLOR_TO_DRAWING_SCHEME, WRAP_ELEMENT_NAMES, parseAnchorPosition, parseAnchorWrap, parseColorElement, parseFill, parseOutline, parsePositionH, parsePositionV, parseWrapElement, resolveColorValueToHex };
+export { THEME_COLOR_TO_DRAWING_SCHEME, WRAP_ELEMENT_NAMES, parseAnchorBehindDoc, parseAnchorPosition, parseAnchorWrap, parseColorElement, parseFill, parseOutline, parsePositionH, parsePositionV, parseWrapElement, resolveColorValueToHex };

package/dist/docx/drawingUtils.js

@@ -1,6 +1,6 @@
 import { ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, ShapeOutlineStyleSchema, narrowEnum } from "./parserEnums.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
-import { findByFullName, findChildByLocalName, findChildrenByLocalName, getAttribute, getChildElements, getTextContent, parseNumericAttribute } from "./xmlParser.js";
+import { findByFullName, findChildByLocalName, findChildrenByLocalName, getAttribute, getChildElements, getTextContent, parseNumericAttribute, parseOnOffValue } from "./xmlParser.js";
 //#region src/docx/drawingUtils.ts
 /**
 * Map OOXML scheme names to standard theme color slots.
@@ -361,9 +361,18 @@ function parseWrapElement(wrapEl, behindDoc, anchorDistances) {
 /**
 * Parse wrap from an anchor element (finds wrap child internally).
 */
+/**
+* Read `wp:anchor/@behindDoc`, the flag that puts an anchored object behind the
+* body text. The attribute is xsd:boolean, so `1`, `0`, `true` and `false` are
+* all legal spellings and producers differ: Word writes `1`, others `true`.
+* Absent means in front of the text.
+*/
+function parseAnchorBehindDoc(anchor) {
+	return parseOnOffValue(getAttribute(anchor, null, "behindDoc")) ?? false;
+}
 function parseAnchorWrap(anchor) {
 	const children = getChildElements(anchor);
-	const behindDoc = getAttribute(anchor, null, "behindDoc") === "1";
+	const behindDoc = parseAnchorBehindDoc(anchor);
 	const wrapEl = children.find((el) => WRAP_ELEMENT_NAMES.includes(el.name ?? ""));
 	const distT = parseNumericAttribute(anchor, null, "distT");
 	const distB = parseNumericAttribute(anchor, null, "distB");
@@ -409,4 +418,4 @@ function resolveColorValueToHex(color) {
 	if (color.themeColor) return `#${DEFAULT_THEME_COLOR_HEX[color.themeColor] ?? "000000"}`;
 }
 //#endregion
-export { THEME_COLOR_TO_DRAWING_SCHEME, WRAP_ELEMENT_NAMES, parseAnchorPosition, parseAnchorWrap, parseColorElement, parseFill, parseOutline, parsePositionH, parsePositionV, parseWrapElement, resolveColorValueToHex };
+export { THEME_COLOR_TO_DRAWING_SCHEME, WRAP_ELEMENT_NAMES, parseAnchorBehindDoc, parseAnchorPosition, parseAnchorWrap, parseColorElement, parseFill, parseOutline, parsePositionH, parsePositionV, parseWrapElement, resolveColorValueToHex };

package/dist/docx/fieldParser.js

@@ -1,7 +1,7 @@
 import { formatOoxmlCounter } from "./ooxmlCounterFormatter.js";
 import { FieldTypeSchema, narrowEnum } from "./parserEnums.js";
 import { parseRun } from "./runParser.js";
-import { findChildren, getAttribute } from "./xmlParser.js";
+import { findChildren, getAttribute, parseOnOffAttribute } from "./xmlParser.js";
 //#region src/docx/fieldParser.ts
 /**
 * All known field types from OOXML specification
@@ -164,10 +164,8 @@ function parseSimpleField(node, styles, theme) {
 		fieldType: parseFieldType(instruction),
 		content: []
 	};
-	const fldLock = getAttribute(node, "w", "fldLock");
-	if (fldLock === "1" || fldLock === "true") field.fldLock = true;
-	const dirty = getAttribute(node, "w", "dirty");
-	if (dirty === "1" || dirty === "true") field.dirty = true;
+	if (parseOnOffAttribute(node, "w", "fldLock") === true) field.fldLock = true;
+	if (parseOnOffAttribute(node, "w", "dirty") === true) field.dirty = true;
 	const children = findChildren(node, "w", "r");
 	for (const child of children) {
 		const run = parseRun(child, styles, theme);

package/dist/docx/footnoteParser.d.ts

@@ -1,6 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
 import { StyleMap } from "./styleParser.js";
+import { ParseContext } from "./parseContext.js";
 import { parseEndnoteProperties, parseFootnoteProperties } from "./notePropertiesParser.js";
 //#region src/docx/footnoteParser.d.ts
 /**
@@ -52,7 +53,7 @@ type EndnoteMap = {
  * @param media - Media files for images
  * @returns FootnoteMap with all footnotes
  */
-declare function parseFootnotes(footnotesXml: string | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, numbering?: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null): FootnoteMap;
+declare function parseFootnotes(footnotesXml: string | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, numbering?: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null, context?: ParseContext): FootnoteMap;
 /**
  * Parse endnotes.xml
  *
@@ -64,7 +65,7 @@ declare function parseFootnotes(footnotesXml: string | null, styles?: StyleMap |
  * @param media - Media files for images
  * @returns EndnoteMap with all endnotes
  */
-declare function parseEndnotes(endnotesXml: string | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, numbering?: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null): EndnoteMap;
+declare function parseEndnotes(endnotesXml: string | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, numbering?: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null, context?: ParseContext): EndnoteMap;
 /**
  * Get plain text content of a footnote.
  *

package/dist/docx/footnoteParser.js

@@ -4,6 +4,7 @@ import { parseParagraph } from "./paragraphParser.js";
 import { parseSdtProperties } from "./sdtProperties.js";
 import { parseTable } from "./tableParser.js";
 import { findChild, findChildren, getAttributes, getChildElements, getLocalName, parseXml } from "./xmlParser.js";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/footnoteParser.ts
 /**
 * Parse note type attribute
@@ -69,7 +70,7 @@ function parseFootnote(element, styles, theme, numbering, rels, media) {
 * @param media - Media files for images
 * @returns FootnoteMap with all footnotes
 */
-function parseFootnotes(footnotesXml, styles = null, theme = null, numbering = null, rels = null, media = null) {
+function parseFootnotes(footnotesXml, styles = null, theme = null, numbering = null, rels = null, media = null, context) {
 	const byId = /* @__PURE__ */ new Map();
 	const footnotes = [];
 	if (!footnotesXml) return createFootnoteMap(byId, footnotes);
@@ -78,6 +79,14 @@ function parseFootnotes(footnotesXml, styles = null, theme = null, numbering = n
 	const footnoteElements = findChildren(rootElement, "w", "footnote");
 	for (const fnEl of footnoteElements) {
 		const footnote = parseFootnote(fnEl, styles, theme, numbering, rels, media);
+		if (byId.has(footnote.id)) {
+			context?.warn({
+				code: PARSE_WARNING_CODES.duplicateNoteId,
+				element: "w:footnote",
+				at: `w:id ${String(footnote.id)}`
+			});
+			continue;
+		}
 		byId.set(footnote.id, footnote);
 		footnotes.push(footnote);
 	}
@@ -129,7 +138,7 @@ function parseEndnote(element, styles, theme, numbering, rels, media) {
 * @param media - Media files for images
 * @returns EndnoteMap with all endnotes
 */
-function parseEndnotes(endnotesXml, styles = null, theme = null, numbering = null, rels = null, media = null) {
+function parseEndnotes(endnotesXml, styles = null, theme = null, numbering = null, rels = null, media = null, context) {
 	const byId = /* @__PURE__ */ new Map();
 	const endnotes = [];
 	if (!endnotesXml) return createEndnoteMap(byId, endnotes);
@@ -138,6 +147,14 @@ function parseEndnotes(endnotesXml, styles = null, theme = null, numbering = nul
 	const endnoteElements = findChildren(rootElement, "w", "endnote");
 	for (const enEl of endnoteElements) {
 		const endnote = parseEndnote(enEl, styles, theme, numbering, rels, media);
+		if (byId.has(endnote.id)) {
+			context?.warn({
+				code: PARSE_WARNING_CODES.duplicateNoteId,
+				element: "w:endnote",
+				at: `w:id ${String(endnote.id)}`
+			});
+			continue;
+		}
 		byId.set(endnote.id, endnote);
 		endnotes.push(endnote);
 	}

package/dist/docx/groupDrawingParser.js

@@ -121,7 +121,7 @@ const renderPicture = (picture, index, rels, media) => {
 	if (width <= 0 || height <= 0) return "";
 	const blipFill = findChildByLocalName(picture, "blipFill");
 	const blip = findChildByLocalName(blipFill, "blip");
-	const { src } = resolveImageData(getAttribute(blip, "r", "embed") ?? getAttribute(blip, "r", "link") ?? "", rels, media);
+	const { src } = resolveImageData(getAttribute(blip, "r", "embed") ?? getAttribute(blip, "r", "link") ?? void 0, rels, media);
 	if (!src) return "";
 	const sourceRect = findChildByLocalName(blipFill, "srcRect");
 	const left = Math.max(0, numericAttr(sourceRect, "l")) / CROP_SCALE;

package/dist/docx/headerFooterRefParser.d.ts

@@ -1,14 +1,26 @@
 import { document_d_exports } from "../types/document.js";
+import { ParseContext } from "./parseContext.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/headerFooterRefParser.d.ts
+/**
+ * Read a `w:type` attribute as one of ECMA-376's three `ST_HdrFtr` values.
+ *
+ * The enumeration is `even`, `default` and `first` (17.18.36); `default` is
+ * the odd-page header, which is why a producer writing `odd` means the same
+ * thing. Word opens such a package, so anything outside the enumeration reads
+ * as the default the schema itself defaults to. Everything that compares
+ * header/footer reference types has to read them through here, or a
+ * normalisation at this boundary looks like a lost reference downstream.
+ */
+declare function parseHeaderFooterType(typeAttr: string | null, context?: ParseContext): document_d_exports.HeaderFooterType;
 /**
  * Parse a header reference from sectPr (w:headerReference)
  */
-declare function parseHeaderReference(element: XmlElement): document_d_exports.HeaderReference;
+declare function parseHeaderReference(element: XmlElement, context?: ParseContext): document_d_exports.HeaderReference | null;
 /**
  * Parse a footer reference from sectPr (w:footerReference)
  */
-declare function parseFooterReference(element: XmlElement): document_d_exports.FooterReference;
+declare function parseFooterReference(element: XmlElement, context?: ParseContext): document_d_exports.FooterReference | null;
 /**
  * Parse all header references from a sectPr element
  */
@@ -18,4 +30,4 @@ declare function parseHeaderReferences(sectPr: XmlElement): document_d_exports.H
  */
 declare function parseFooterReferences(sectPr: XmlElement): document_d_exports.FooterReference[];
 //#endregion
-export { parseFooterReference, parseFooterReferences, parseHeaderReference, parseHeaderReferences };
+export { parseFooterReference, parseFooterReferences, parseHeaderFooterType, parseHeaderReference, parseHeaderReferences };

package/dist/docx/headerFooterRefParser.js

@@ -1,34 +1,65 @@
 import { findChildren, getAttribute } from "./xmlParser.js";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/headerFooterRefParser.ts
 /**
-* Parse header type attribute
+* Header/Footer Reference Parser
+*
+* Parses header/footer references (w:headerReference, w:footerReference) that
+* appear in section properties. Extracted from headerFooterParser to break the
+* circular dependency: headerFooterParser -> paragraphParser -> sectionParser -> headerFooterParser.
 */
-function parseHeaderFooterType(typeAttr) {
+/**
+* Read a `w:type` attribute as one of ECMA-376's three `ST_HdrFtr` values.
+*
+* The enumeration is `even`, `default` and `first` (17.18.36); `default` is
+* the odd-page header, which is why a producer writing `odd` means the same
+* thing. Word opens such a package, so anything outside the enumeration reads
+* as the default the schema itself defaults to. Everything that compares
+* header/footer reference types has to read them through here, or a
+* normalisation at this boundary looks like a lost reference downstream.
+*/
+function parseHeaderFooterType(typeAttr, context) {
 	switch (typeAttr) {
 		case "first": return "first";
 		case "even": return "even";
-		default: return "default";
+		case "default":
+		case null: return "default";
+		default:
+			context?.warn({
+				code: PARSE_WARNING_CODES.headerFooterTypeOutsideEnum,
+				value: typeAttr,
+				element: "w:type"
+			});
+			return "default";
 	}
 }
-function parseHeaderFooterReference(element) {
-	const typeAttr = getAttribute(element, "w", "type");
-	const rId = getAttribute(element, "r", "id") ?? "";
+/**
+* A reference with no `r:id` names no part, so it is not a reference.
+*
+* Coercing the missing attribute to `""` used to put the empty string in the
+* model, where it became a part-map key on one side and an `r:id=""` the
+* schema rejects on the other. Null here keeps the reference out of the model
+* entirely, which is what the source said.
+*/
+function parseHeaderFooterReference(element, context) {
+	const rId = getAttribute(element, "r", "id");
+	if (rId === null || rId.length === 0) return null;
 	return {
-		type: parseHeaderFooterType(typeAttr),
+		type: parseHeaderFooterType(getAttribute(element, "w", "type"), context?.scoped({ at: `r:id "${rId}"` })),
 		rId
 	};
 }
 /**
 * Parse a header reference from sectPr (w:headerReference)
 */
-function parseHeaderReference(element) {
-	return parseHeaderFooterReference(element);
+function parseHeaderReference(element, context) {
+	return parseHeaderFooterReference(element, context);
 }
 /**
 * Parse a footer reference from sectPr (w:footerReference)
 */
-function parseFooterReference(element) {
-	return parseHeaderFooterReference(element);
+function parseFooterReference(element, context) {
+	return parseHeaderFooterReference(element, context);
 }
 /**
 * Parse all header references from a sectPr element
@@ -36,7 +67,10 @@ function parseFooterReference(element) {
 function parseHeaderReferences(sectPr) {
 	const refs = [];
 	const headerRefElements = findChildren(sectPr, "w", "headerReference");
-	for (const el of headerRefElements) refs.push(parseHeaderReference(el));
+	for (const el of headerRefElements) {
+		const ref = parseHeaderReference(el);
+		if (ref) refs.push(ref);
+	}
 	return refs;
 }
 /**
@@ -45,8 +79,11 @@ function parseHeaderReferences(sectPr) {
 function parseFooterReferences(sectPr) {
 	const refs = [];
 	const footerRefElements = findChildren(sectPr, "w", "footerReference");
-	for (const el of footerRefElements) refs.push(parseFooterReference(el));
+	for (const el of footerRefElements) {
+		const ref = parseFooterReference(el);
+		if (ref) refs.push(ref);
+	}
 	return refs;
 }
 //#endregion
-export { parseFooterReference, parseFooterReferences, parseHeaderReference, parseHeaderReferences };
+export { parseFooterReference, parseFooterReferences, parseHeaderFooterType, parseHeaderReference, parseHeaderReferences };

package/dist/docx/headerFooterReferenceNormalization.d.ts

@@ -1,5 +1,8 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/headerFooterReferenceNormalization.d.ts
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+declare const DANGLING_HEADER_REFERENCE_WARNING: "dangling-header-reference";
+declare const DANGLING_FOOTER_REFERENCE_WARNING: "dangling-footer-reference";
 type NormalizeHeaderFooterReferencesInput = {
   documentBody: document_d_exports.DocumentBody;
   headers?: Map<string, document_d_exports.HeaderFooter>;
@@ -11,4 +14,4 @@ type NormalizeHeaderFooterReferencesResult = {
 };
 declare const normalizeHeaderFooterReferences: ({ documentBody, headers, footers }: NormalizeHeaderFooterReferencesInput) => NormalizeHeaderFooterReferencesResult;
 //#endregion
-export { normalizeHeaderFooterReferences };
+export { DANGLING_FOOTER_REFERENCE_WARNING, DANGLING_HEADER_REFERENCE_WARNING, normalizeHeaderFooterReferences };

package/dist/docx/headerFooterReferenceNormalization.js

@@ -1,4 +1,8 @@
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/headerFooterReferenceNormalization.ts
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+const DANGLING_HEADER_REFERENCE_WARNING = PARSE_WARNING_CODES.danglingHeaderReference;
+const DANGLING_FOOTER_REFERENCE_WARNING = PARSE_WARNING_CODES.danglingFooterReference;
 const normalizeHeaderFooterReferences = ({ documentBody, headers, footers }) => {
 	const seenSectionProperties = /* @__PURE__ */ new Set();
 	let removedDanglingHeaderReferences = 0;
@@ -61,4 +65,4 @@ const removeDanglingReferences = (references, validParts) => {
 	};
 };
 //#endregion
-export { normalizeHeaderFooterReferences };
+export { DANGLING_FOOTER_REFERENCE_WARNING, DANGLING_HEADER_REFERENCE_WARNING, normalizeHeaderFooterReferences };

package/dist/docx/hyperlinkParser.js

@@ -1,6 +1,7 @@
 import { sanitizeExternalUrl, sanitizeLinkTarget } from "../utils/urlSecurity.js";
+import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "./relsParser.js";
 import { parseRun } from "./runParser.js";
-import { getAttribute, getChildElements, getLocalName, mergeXmlnsDeclarations, parseNumericAttribute } from "./xmlParser.js";
+import { getAttribute, getChildElements, getLocalName, mergeXmlnsDeclarations, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
 //#region src/docx/hyperlinkParser.ts
 /**
 * Parse bookmark start (w:bookmarkStart)
@@ -49,11 +50,9 @@ function parseHyperlink(node, rels, styles = null, theme = null, media = null, r
 	const rId = getAttribute(node, "r", "id");
 	if (rId) {
 		hyperlink.rId = rId;
-		if (rels) {
-			const rel = rels.get(rId);
-			if (rel) {
-				if (sanitizeExternalUrl(rel.target)) hyperlink.href = rel.target;
-			}
+		const resolved = resolveRelationshipIdOfType(rels, rId, RELATIONSHIP_TYPES.hyperlink);
+		if (resolved.status === "resolved") {
+			if (sanitizeExternalUrl(resolved.relationship.target)) hyperlink.href = resolved.relationship.target;
 		}
 	}
 	const anchor = getAttribute(node, "w", "anchor");
@@ -65,8 +64,7 @@ function parseHyperlink(node, rels, styles = null, theme = null, media = null, r
 	if (tooltip) hyperlink.tooltip = tooltip;
 	const tgtFrame = getAttribute(node, "w", "tgtFrame");
 	if (tgtFrame) hyperlink.target = sanitizeLinkTarget(tgtFrame);
-	const history = getAttribute(node, "w", "history");
-	if (history === "1" || history === "true") hyperlink.history = true;
+	if (parseOnOffAttribute(node, "w", "history") === true) hyperlink.history = true;
 	const docLocation = getAttribute(node, "w", "docLocation");
 	if (docLocation) hyperlink.docLocation = docLocation;
 	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
@@ -168,13 +166,11 @@ function getHyperlinkRuns(hyperlink) {
 * @returns The resolved URL or undefined
 */
 function resolveHyperlinkUrl(hyperlink, rels) {
-	if (hyperlink.rId) {
-		const rel = rels.get(hyperlink.rId);
-		if (rel) {
-			if (sanitizeExternalUrl(rel.target)) {
-				hyperlink.href = rel.target;
-				return hyperlink.href;
-			}
+	const resolved = resolveRelationshipIdOfType(rels, hyperlink.rId, RELATIONSHIP_TYPES.hyperlink);
+	if (resolved.status === "resolved") {
+		if (sanitizeExternalUrl(resolved.relationship.target)) {
+			hyperlink.href = resolved.relationship.target;
+			return hyperlink.href;
 		}
 	}
 	if (hyperlink.anchor && !hyperlink.href) {

package/dist/docx/imageParser.d.ts

@@ -9,7 +9,7 @@ import { XmlElement } from "./xmlParser.js";
  * @param media - Media files map
  * @returns Object with src (data URL or blob), mimeType, and filename
  */
-declare function resolveImageData(rId: string, rels: document_d_exports.RelationshipMap | undefined, media: Map<string, document_d_exports.MediaFile> | undefined): {
+declare function resolveImageData(rId: string | undefined, rels: document_d_exports.RelationshipMap | undefined, media: Map<string, document_d_exports.MediaFile> | undefined): {
   src?: string;
   mimeType?: string;
   filename?: string;