@stll/folio-core 0.43.0 → 0.44.0

package/dist/docx/defaultParagraphStyle.d.ts

@@ -17,6 +17,23 @@ declare const BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING: {
   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, resolveDefaultParagraphStyle };
+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

@@ -16,6 +16,28 @@ const BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING = {
 	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;
@@ -29,4 +51,4 @@ const resolveDefaultParagraphStyle = (styles) => {
 	return flagged ?? namedBuiltIn ?? idBuiltIn;
 };
 //#endregion
-export { BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING, BUILT_IN_DEFAULT_PARAGRAPH_STYLE_ID, BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME, resolveDefaultParagraphStyle };
+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,7 +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)) continue;
+		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);
 	}
@@ -130,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);
@@ -139,7 +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)) continue;
+		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,4 +1,5 @@
 import { document_d_exports } from "../types/document.js";
+import { ParseContext } from "./parseContext.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/headerFooterRefParser.d.ts
 /**
@@ -11,15 +12,15 @@ import { XmlElement } from "./xmlParser.js";
  * 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): document_d_exports.HeaderFooterType;
+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
  */

package/dist/docx/headerFooterRefParser.js

@@ -1,6 +1,14 @@
 import { findChildren, getAttribute } from "./xmlParser.js";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/headerFooterRefParser.ts
 /**
+* 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.
+*/
+/**
 * 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
@@ -10,32 +18,48 @@ import { findChildren, getAttribute } from "./xmlParser.js";
 * 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) {
+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
@@ -43,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;
 }
 /**
@@ -52,7 +79,10 @@ 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

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;

package/dist/docx/imageParser.js

@@ -1,9 +1,9 @@
 import { sanitizeImageSrc } from "../utils/sanitizeImageSrc.js";
 import { emuToPixels } from "../utils/units.js";
 import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
-import { WRAP_ELEMENT_NAMES, parsePositionH, parsePositionV, parseWrapElement } from "./drawingUtils.js";
+import { WRAP_ELEMENT_NAMES, parseAnchorBehindDoc, parsePositionH, parsePositionV, parseWrapElement } from "./drawingUtils.js";
 import { parseGraphicFrameLocks } from "./graphicFrameLocks.js";
-import { resolveTarget } from "./relsParser.js";
+import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "./relsParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
 import { findByFullName, findChild, getAttribute, getChildElements, parseNumericAttribute, parseOnOffValue } from "./xmlParser.js";
 //#region src/docx/imageParser.ts
@@ -178,17 +178,20 @@ function parseImageOpacity(blip) {
 	return Math.max(0, amt / 1e5);
 }
 /**
-* Extract rId from a:blip element
+* Extract rId from a:blip element.
+*
+* Undefined when the drawing has no blip to read one from: a chart, a diagram
+* or an OLE frame carries an `a:graphic` that is not a picture, and a
+* `wp:inline` may carry no graphic at all.
 */
 function extractBlipRId(blip) {
-	if (!blip) return "";
+	if (!blip) return;
 	const rEmbed = getAttribute(blip, "r", "embed");
 	if (rEmbed) return rEmbed;
 	const embed = getAttribute(blip, null, "embed");
 	if (embed) return embed;
 	const rLink = getAttribute(blip, "r", "link");
 	if (rLink) return rLink;
-	return "";
 }
 /**
 * Find transform (a:xfrm) from picture shape properties
@@ -242,10 +245,9 @@ function getMimeType(path) {
 * @returns Object with src (data URL or blob), mimeType, and filename
 */
 function resolveImageData(rId, rels, media) {
-	if (!rId || !rels) return {};
-	const rel = rels.get(rId);
-	if (!rel) return {};
-	const targetPath = rel.target;
+	const resolved = resolveRelationshipIdOfType(rels, rId, RELATIONSHIP_TYPES.image);
+	if (resolved.status !== "resolved") return {};
+	const targetPath = resolved.relationship.target;
 	if (!targetPath) return {};
 	const normalizedPath = normalizeMediaPath(targetPath);
 	const filename = targetPath.split("/").pop();
@@ -319,7 +321,7 @@ function parseInline(inlineEl, rels, media) {
 	if (distR !== void 0) wrap.distR = distR;
 	const image = {
 		type: "image",
-		rId,
+		...rId === void 0 ? {} : { rId },
 		size,
 		wrap
 	};
@@ -337,11 +339,12 @@ function parseInline(inlineEl, rels, media) {
 	if (crop) image.crop = crop;
 	if (opacity !== void 0) image.opacity = opacity;
 	if (frameLocks) image.frameLocks = frameLocks;
-	if (props.hlinkRId && rels) {
-		const safeHref = sanitizeExternalUrl(resolveTarget(rels, props.hlinkRId));
+	const hlink = resolveRelationshipIdOfType(rels, props.hlinkRId, RELATIONSHIP_TYPES.hyperlink);
+	if (hlink.status === "resolved") {
+		const safeHref = sanitizeExternalUrl(hlink.relationship.target);
 		if (safeHref) {
 			image.hlinkHref = safeHref;
-			image.hlinkRId = props.hlinkRId;
+			image.hlinkRId = hlink.relationship.id;
 		}
 	}
 	return image;
@@ -359,7 +362,7 @@ function parseAnchor(anchorEl, rels, media) {
 	const padding = parseEffectExtent(findByFullName(anchorEl, "wp:effectExtent"));
 	const props = parseDocProps(findByFullName(anchorEl, "wp:docPr"));
 	const frameLocks = parseGraphicFrameLocks(anchorEl);
-	const behindDoc = parseOnOffValue(getAttribute(anchorEl, null, "behindDoc")) === true;
+	const behindDoc = parseAnchorBehindDoc(anchorEl);
 	const layoutInCell = parseOnOffAttr(anchorEl, "layoutInCell");
 	const allowOverlap = parseOnOffAttr(anchorEl, "allowOverlap");
 	const anchorDistT = parseNumericAttribute(anchorEl, null, "distT");
@@ -391,7 +394,7 @@ function parseAnchor(anchorEl, rels, media) {
 	const transform = parseTransform(findPictureTransform(anchorEl));
 	const image = {
 		type: "image",
-		rId,
+		...rId === void 0 ? {} : { rId },
 		size,
 		wrap
 	};
@@ -412,11 +415,12 @@ function parseAnchor(anchorEl, rels, media) {
 	if (frameLocks) image.frameLocks = frameLocks;
 	if (layoutInCell !== void 0) image.layoutInCell = layoutInCell;
 	if (allowOverlap !== void 0) image.allowOverlap = allowOverlap;
-	if (props.hlinkRId && rels) {
-		const safeHref = sanitizeExternalUrl(resolveTarget(rels, props.hlinkRId));
+	const hlink = resolveRelationshipIdOfType(rels, props.hlinkRId, RELATIONSHIP_TYPES.hyperlink);
+	if (hlink.status === "resolved") {
+		const safeHref = sanitizeExternalUrl(hlink.relationship.target);
 		if (safeHref) {
 			image.hlinkHref = safeHref;
-			image.hlinkRId = props.hlinkRId;
+			image.hlinkRId = hlink.relationship.id;
 		}
 	}
 	return image;

package/dist/docx/imageRawXml.js

@@ -46,12 +46,12 @@ const DRAWING_SAFETY_CLASSES = {
 	OPAQUE: "opaque"
 };
 /**
-* Regenerated DrawingML points at `image.rId`, and `serializePicGraphic` falls
-* back to `"rId1"` when that id is empty, which rebinds the picture to whichever
-* relationship happens to be first. A drawing with no relationship id therefore
-* has no faithful regeneration.
+* A drawing with no picture relationship has no picture to regenerate. The
+* serializer writes the anchor back without a graphic, which is faithful for an
+* anchor that never had one and lossy for a chart or an OLE frame, so the
+* drawing counts as opaque and an edit must block the save.
 */
-const canRegenerateDrawing = (drawing) => drawing.image.rId !== "";
+const canRegenerateDrawing = (drawing) => drawing.image.rId !== void 0;
 /**
 * Classify a drawing by what the run serializer will do with it.
 *

package/dist/docx/markupRangeMarker.d.ts

@@ -0,0 +1,15 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/markupRangeMarker.d.ts
+declare const parseMarkupRangeMarker: (node: XmlElement) => document_d_exports.MarkupRangeMarker;
+declare const parseBookmarkRangeMarker: (node: XmlElement) => document_d_exports.BookmarkRangeMarker;
+/**
+ * `w:author` is required on `CT_MoveBookmark`, so an absent one takes the same
+ * `Unknown` fallback a tracked change takes rather than leaving the saved
+ * package short of an attribute the schema demands. `w:date` is required too,
+ * but inventing a timestamp would state a fact about the document that is not
+ * true, so an absent date stays absent.
+ */
+declare const parseMoveBookmarkMarker: (node: XmlElement) => document_d_exports.MoveBookmarkMarker;
+//#endregion
+export { parseBookmarkRangeMarker, parseMarkupRangeMarker, parseMoveBookmarkMarker };