@stll/folio-core 0.51.0 → 0.53.0

package/dist/docx/ensureParaIds.js

@@ -1,6 +1,8 @@
 import { deterministicHexId } from "../utils/hexId.js";
 import { isXmlNameBoundary, spliceXml } from "./selectiveXmlPatch.js";
 import { loadDocxArchive } from "./server/boundedArchive.js";
+import { matchCloseTag, matchOpenTag, resolveWordprocessingPrefixes } from "./wordprocessingPrefixes.js";
+import { WORDPROCESSINGML_NAMESPACE_URIS, getChildElements, getLocalName, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
 import { TaggedError } from "better-result";
 import JSZip from "jszip";
 //#region src/docx/ensureParaIds.ts
@@ -48,8 +50,15 @@ import JSZip from "jszip";
 *   declarations and a `mc:Ignorable` listing `w14` when missing — non-Word
 *   producers declare neither, and absent `mc:Ignorable` handling is what
 *   makes pre-2010 consumers choke on the new attributes.
+* - Prefixes are aliases. Each part is scanned under the prefixes its root
+*   binds to WordprocessingML (a default namespace included), `w14` and `mc`
+*   (see `resolveWordprocessingPrefixes`), and a minted id is written under
+*   the part's own `w14` prefix, which is the one `mc:Ignorable` lists. A
+*   part whose bindings a string scan cannot follow (a nested element that
+*   rebinds one of them) is refused with {@link EnsureParaIdsError}.
 * - Idempotent: a document that already has full coverage is returned as the
-*   original bytes, untouched (`alreadyComplete: true`).
+*   original bytes, untouched (`alreadyComplete: true`). A body with
+*   paragraphs the scan did not see is refused, never reported complete.
 * - Digitally signed packages are returned untouched when already complete.
 *   When normalization would rewrite the package, it fails unless the caller
 *   explicitly allows signature invalidation after warning the user.
@@ -70,9 +79,6 @@ const TARGET_PART_PATTERNS = [
 	/^word\/footnotes\.xml$/u,
 	/^word\/endnotes\.xml$/u
 ];
-const PARAGRAPH_OPEN = "<w:p";
-const FALLBACK_OPEN = "<mc:Fallback";
-const FALLBACK_CLOSE = "</mc:Fallback>";
 const OPAQUE_XML_REGIONS = [
 	{
 		open: "<!--",
@@ -88,15 +94,30 @@ const OPAQUE_XML_REGIONS = [
 	}
 ];
 /**
-* The parser accepts the `w:` fallback prefix for paraId, and comment parts
-* link replies via `w15:paraId` — all three count toward uniqueness.
+* Every prefixed `paraId` counts toward uniqueness: the parser accepts the
+* WordprocessingML fallback, comment parts link replies via `w15:paraId`, and
+* a producer may spell any of them under a prefix of its own. Over-collecting
+* only steers a minted id away from a value; it never keeps one.
 */
-const ANY_PARA_ID_PATTERN = /\bw(?:14|15)?:paraId=(?<quote>["'])(?<id>[\s\S]*?)\k<quote>/gu;
-const OPEN_TAG_PARA_ID_PATTERN = /\sw(?:14)?:paraId=(?<quote>["'])(?<id>[\s\S]*?)\k<quote>/u;
-const OPEN_TAG_TEXT_ID_PATTERN = /\sw(?:14)?:textId=(?<quote>["'])(?<id>[\s\S]*?)\k<quote>/u;
-const XMLNS_W14_PATTERN = /\sxmlns:w14=(?<quote>["'])(?<value>[\s\S]*?)\k<quote>/u;
-const XMLNS_MC_PATTERN = /\sxmlns:mc=(?<quote>["'])(?<value>[\s\S]*?)\k<quote>/u;
-const MC_IGNORABLE_PATTERN = /\smc:Ignorable=(?<quote>["'])(?<value>[\s\S]*?)\k<quote>/u;
+const ANY_PARA_ID_PATTERN = /\s[^\s=<>/"':]+:paraId=(?<quote>["'])(?<id>[\s\S]*?)\k<quote>/gu;
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+/** An attribute `localName` under any of `prefixes`, with `quote` and `value` groups. */
+const prefixedAttributePattern = (prefixes, localName) => {
+	const names = prefixes.filter((prefix) => prefix !== "").map(escapeRegExp);
+	return names.length === 0 ? /(?!)/u : new RegExp(`\\s(?:${names.join("|")}):${localName}=(?<quote>["'])(?<value>[\\s\\S]*?)\\k<quote>`, "u");
+};
+const partSpelling = (xml, partPath) => {
+	const resolution = resolveWordprocessingPrefixes(xml);
+	if (resolution.type === "unsupported") throw createEnsureParaIdsError(`Cannot normalize paragraph ids in ${partPath}: ${resolution.reason}`);
+	const { prefixes } = resolution;
+	const attributePrefixes = [...prefixes.w14, ...prefixes.main];
+	return {
+		prefixes,
+		paraId: prefixedAttributePattern(attributePrefixes, "paraId"),
+		textId: prefixedAttributePattern(attributePrefixes, "textId"),
+		w14Prefix: (prefixes.w14Declared ? prefixes.w14[0] : void 0) ?? MC_IGNORABLE_W14
+	};
+};
 /**
 * Stamp the edits into the part through the splice owner, which refuses a
 * result that would leave a comment range with only one half. These edits
@@ -141,7 +162,12 @@ const collectExistingParaIds = (xml, into) => {
 		if (id.length > 0) into.add(id.toUpperCase());
 	}
 };
-const collectFallbackParaIds = (xml, partPath, into) => {
+/**
+* Every paragraph open tag of a part in document order, under whichever
+* WordprocessingML prefix the part binds, with whether it sits in
+* `mc:Fallback` (under the part's own `mc` prefix).
+*/
+function* paragraphOpenTags(xml, partPath, { prefixes }) {
 	let fallbackDepth = 0;
 	let pos = 0;
 	while (pos < xml.length) {
@@ -152,27 +178,40 @@ const collectFallbackParaIds = (xml, partPath, into) => {
 			pos = opaqueEnd;
 			continue;
 		}
-		if (xml.startsWith(FALLBACK_OPEN, tagStart) && isXmlNameBoundary(xml[tagStart + 12])) {
+		if (matchOpenTag(xml, tagStart, prefixes.mc, "Fallback") !== -1) {
 			const tagEnd = xml.indexOf(">", tagStart);
-			if (tagEnd === -1) throw createEnsureParaIdsError(`Unterminated <mc:Fallback> tag in ${partPath}`);
+			if (tagEnd === -1) throw createEnsureParaIdsError(`Unterminated mc:Fallback tag in ${partPath}`);
 			if (xml[tagEnd - 1] !== "/") fallbackDepth += 1;
 			pos = tagEnd + 1;
 			continue;
 		}
-		if (xml.startsWith(FALLBACK_CLOSE, tagStart)) {
+		const fallbackClose = matchCloseTag(xml, tagStart, prefixes.mc, "Fallback");
+		if (fallbackClose !== -1) {
 			fallbackDepth = Math.max(0, fallbackDepth - 1);
-			pos = tagStart + 14;
+			pos = tagStart + fallbackClose;
 			continue;
 		}
-		if (fallbackDepth === 0 || !xml.startsWith(PARAGRAPH_OPEN, tagStart) || !isXmlNameBoundary(xml[tagStart + 4])) {
+		const nameLength = matchOpenTag(xml, tagStart, prefixes.main, "p");
+		if (nameLength === -1) {
 			pos = tagStart + 1;
 			continue;
 		}
 		const tagEnd = xml.indexOf(">", tagStart);
-		if (tagEnd === -1) throw createEnsureParaIdsError(`Unterminated <w:p> tag in ${partPath}`);
-		const id = OPEN_TAG_PARA_ID_PATTERN.exec(xml.slice(tagStart, tagEnd + 1))?.groups?.["id"];
-		if (id) into.add(id.toUpperCase());
+		if (tagEnd === -1) throw createEnsureParaIdsError(`Unterminated paragraph tag in ${partPath}`);
 		pos = tagEnd + 1;
+		yield {
+			tagStart,
+			tagEnd,
+			nameEnd: tagStart + nameLength,
+			inFallback: fallbackDepth > 0
+		};
+	}
+}
+const collectFallbackParaIds = (xml, partPath, spelling, into) => {
+	for (const { tagStart, tagEnd, inFallback } of paragraphOpenTags(xml, partPath, spelling)) {
+		if (!inFallback) continue;
+		const id = spelling.paraId.exec(xml.slice(tagStart, tagEnd + 1))?.groups?.["value"];
+		if (id) into.add(id.toUpperCase());
 	}
 };
 /**
@@ -187,74 +226,45 @@ const mintParaId = (context, partPath, ordinal) => {
 	return id;
 };
 /**
-* One forward scan over a part: every `<w:p>` open tag outside `mc:Fallback`
-* either keeps its paraId (valid, first occurrence) or gets a splice edit
-* minting / replacing one. `seen` spans parts so the first-occurrence rule is
-* document-wide across the scan order.
+* One forward scan over a part: every paragraph open tag outside
+* `mc:Fallback` either keeps its paraId (valid, first occurrence) or gets a
+* splice edit minting / replacing one. `seen` spans parts so the
+* first-occurrence rule is document-wide across the scan order.
 */
-const scanPart = (xml, partPath, context, seen) => {
+const scanPart = (xml, partPath, spelling, context, seen) => {
 	const edits = [];
+	const w14 = spelling.w14Prefix;
 	let assigned = 0;
 	let deduplicated = 0;
 	let ordinal = 0;
-	let fallbackDepth = 0;
-	let pos = 0;
-	while (pos < xml.length) {
-		const tagStart = xml.indexOf("<", pos);
-		if (tagStart === -1) break;
-		const opaqueEnd = skipOpaqueXmlRegion(xml, tagStart, partPath);
-		if (opaqueEnd !== null) {
-			pos = opaqueEnd;
-			continue;
-		}
-		if (xml.startsWith(FALLBACK_OPEN, tagStart) && isXmlNameBoundary(xml[tagStart + 12])) {
-			const tagEnd = xml.indexOf(">", tagStart);
-			if (tagEnd === -1) throw createEnsureParaIdsError(`Unterminated <mc:Fallback> tag in ${partPath}`);
-			if (xml[tagEnd - 1] !== "/") fallbackDepth += 1;
-			pos = tagEnd + 1;
-			continue;
-		}
-		if (xml.startsWith(FALLBACK_CLOSE, tagStart)) {
-			fallbackDepth = Math.max(0, fallbackDepth - 1);
-			pos = tagStart + 14;
-			continue;
-		}
-		if (!xml.startsWith(PARAGRAPH_OPEN, tagStart) || !isXmlNameBoundary(xml[tagStart + 4])) {
-			pos = tagStart + 1;
-			continue;
-		}
-		const tagEnd = xml.indexOf(">", tagStart);
-		if (tagEnd === -1) throw createEnsureParaIdsError(`Unterminated <w:p> tag in ${partPath}`);
-		pos = tagEnd + 1;
-		if (fallbackDepth > 0) continue;
+	for (const { tagStart, tagEnd, nameEnd, inFallback } of paragraphOpenTags(xml, partPath, spelling)) {
+		if (inFallback) continue;
 		ordinal += 1;
 		const openTag = xml.slice(tagStart, tagEnd + 1);
-		const paraIdMatch = OPEN_TAG_PARA_ID_PATTERN.exec(openTag);
+		const paraIdMatch = spelling.paraId.exec(openTag);
 		if (!paraIdMatch) {
 			const id = mintParaId(context, partPath, ordinal);
-			const insertAt = tagStart + 4;
-			const textIdMatch = OPEN_TAG_TEXT_ID_PATTERN.exec(openTag);
+			const textIdMatch = spelling.textId.exec(openTag);
 			if (textIdMatch) {
 				edits.push({
-					start: insertAt,
-					end: insertAt,
-					text: ` w14:paraId="${id}"`
+					start: nameEnd,
+					end: nameEnd,
+					text: ` ${w14}:paraId="${id}"`
 				});
-				const range = attributeValueRange(textIdMatch, tagStart, "id");
 				edits.push({
-					...range,
+					...attributeValueRange(textIdMatch, tagStart, "value"),
 					text: id
 				});
 			} else edits.push({
-				start: insertAt,
-				end: insertAt,
-				text: ` w14:paraId="${id}" w14:textId="${id}"`
+				start: nameEnd,
+				end: nameEnd,
+				text: ` ${w14}:paraId="${id}" ${w14}:textId="${id}"`
 			});
 			assigned += 1;
 			seen.add(id);
 			continue;
 		}
-		const value = paraIdMatch.groups["id"].toUpperCase();
+		const value = paraIdMatch.groups["value"].toUpperCase();
 		const unassigned = RESERVED_ZERO_ID_PATTERN.test(value);
 		if (!unassigned && !seen.has(value)) {
 			seen.add(value);
@@ -262,22 +272,19 @@ const scanPart = (xml, partPath, context, seen) => {
 		}
 		const id = mintParaId(context, partPath, ordinal);
 		edits.push({
-			...attributeValueRange(paraIdMatch, tagStart, "id"),
+			...attributeValueRange(paraIdMatch, tagStart, "value"),
 			text: id
 		});
-		const textIdMatch = OPEN_TAG_TEXT_ID_PATTERN.exec(openTag);
+		const textIdMatch = spelling.textId.exec(openTag);
 		if (textIdMatch) edits.push({
-			...attributeValueRange(textIdMatch, tagStart, "id"),
+			...attributeValueRange(textIdMatch, tagStart, "value"),
 			text: id
 		});
-		else {
-			const insertAt = tagStart + 4;
-			edits.push({
-				start: insertAt,
-				end: insertAt,
-				text: ` w14:textId="${id}"`
-			});
-		}
+		else edits.push({
+			start: nameEnd,
+			end: nameEnd,
+			text: ` ${w14}:textId="${id}"`
+		});
 		if (unassigned) assigned += 1;
 		else deduplicated += 1;
 		seen.add(id);
@@ -285,7 +292,8 @@ const scanPart = (xml, partPath, context, seen) => {
 	return {
 		edits,
 		assigned,
-		deduplicated
+		deduplicated,
+		paragraphs: ordinal
 	};
 };
 /**
@@ -293,7 +301,7 @@ const scanPart = (xml, partPath, context, seen) => {
 * `xmlns:mc` and lists `w14` in `mc:Ignorable`, so consumers that predate the
 * 2010 extensions skip the new attributes instead of rejecting the part.
 */
-const ensureRootNamespaces = (xml, partPath) => {
+const ensureRootNamespaces = (xml, partPath, { prefixes, w14Prefix }) => {
 	let pos = 0;
 	let rootStart = -1;
 	while (pos < xml.length) {
@@ -317,29 +325,26 @@ const ensureRootNamespaces = (xml, partPath) => {
 	const rootEnd = xml.indexOf(">", rootStart);
 	if (rootEnd === -1) throw createEnsureParaIdsError(`Unterminated root element in ${partPath}`);
 	const rootTag = xml.slice(rootStart, rootEnd + 1);
+	if (!prefixes.mcDeclared && prefixes.mc.length === 0) throw createEnsureParaIdsError(`xmlns:mc has an unexpected namespace URI in ${partPath}`);
+	if (!prefixes.w14Declared && prefixes.w14.length === 0) throw createEnsureParaIdsError(`xmlns:w14 has an unexpected namespace URI in ${partPath}`);
 	const edits = [];
 	const declarations = [];
-	const mcNamespace = XMLNS_MC_PATTERN.exec(rootTag);
-	if (mcNamespace) {
-		if (mcNamespace.groups["value"] !== MC_NAMESPACE_URI) throw createEnsureParaIdsError(`xmlns:mc has an unexpected namespace URI in ${partPath}`);
-	} else declarations.push(` xmlns:mc="${MC_NAMESPACE_URI}"`);
-	const w14Namespace = XMLNS_W14_PATTERN.exec(rootTag);
-	if (w14Namespace) {
-		if (w14Namespace.groups["value"] !== W14_NAMESPACE_URI) throw createEnsureParaIdsError(`xmlns:w14 has an unexpected namespace URI in ${partPath}`);
-	} else declarations.push(` xmlns:w14="${W14_NAMESPACE_URI}"`);
-	const ignorable = MC_IGNORABLE_PATTERN.exec(rootTag);
+	const mcPrefix = (prefixes.mcDeclared ? prefixes.mc[0] : void 0) ?? "mc";
+	if (!prefixes.mcDeclared) declarations.push(` xmlns:mc="${MC_NAMESPACE_URI}"`);
+	if (!prefixes.w14Declared) declarations.push(` xmlns:w14="${W14_NAMESPACE_URI}"`);
+	const ignorable = prefixedAttributePattern(prefixes.mcDeclared ? prefixes.mc : [mcPrefix], "Ignorable").exec(rootTag);
 	if (ignorable) {
 		const tokens = ignorable.groups["value"].split(/\s+/u).filter((token) => token.length > 0);
-		if (!tokens.includes(MC_IGNORABLE_W14)) {
+		if (!tokens.includes(w14Prefix)) {
 			const { end } = attributeValueRange(ignorable, rootStart, "value");
-			const text = tokens.length === 0 ? MC_IGNORABLE_W14 : ` ${MC_IGNORABLE_W14}`;
+			const text = tokens.length === 0 ? w14Prefix : ` ${w14Prefix}`;
 			edits.push({
 				start: end,
 				end,
 				text
 			});
 		}
-	} else declarations.push(` mc:Ignorable="${MC_IGNORABLE_W14}"`);
+	} else declarations.push(` ${mcPrefix}:Ignorable="${w14Prefix}"`);
 	if (declarations.length > 0) {
 		let nameEnd = rootStart + 1;
 		while (nameEnd < xml.length && !isXmlNameBoundary(xml[nameEnd])) nameEnd += 1;
@@ -351,6 +356,17 @@ const ensureRootNamespaces = (xml, partPath) => {
 	}
 	return edits;
 };
+const hasWordParagraph = (element) => getLocalName(element.name ?? "") === "p" && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "") || getChildElements(element).some(hasWordParagraph);
+/**
+* A body the string scan saw no paragraph in is either genuinely empty or
+* spelled in a way the scan missed. Only the namespace-aware parser can tell
+* which, and it only has to be asked in that rare case: `alreadyComplete`
+* must never describe paragraphs nobody looked at.
+*/
+const assertNoUnscannedParagraphs = (xml, partPath) => {
+	const root = parseXmlDocument(xml);
+	if (root !== null && hasWordParagraph(root)) throw createEnsureParaIdsError(`Cannot normalize paragraph ids in ${partPath}: its paragraphs are not spelled in a way the scan can patch`);
+};
 /** OPC part names are case-insensitive; compare lowercased. */
 const isTargetPart = (path) => TARGET_PART_PATTERNS.some((pattern) => pattern.test(path.toLowerCase()));
 const toUint8Array = (docx) => docx instanceof Uint8Array ? docx : new Uint8Array(docx);
@@ -380,19 +396,25 @@ const ensureParaIdsInternal = async (docx, options) => {
 		docKey: deterministicHexId(partTexts.get(documentPartName))
 	};
 	const targetParts = [documentPartName, ...xmlPartNames.filter((name) => name !== documentPartName && isTargetPart(name)).sort((a, b) => a.localeCompare(b))];
+	const spellings = /* @__PURE__ */ new Map();
 	const seen = /* @__PURE__ */ new Set();
-	for (const [partPath, xml] of partTexts) if (isTargetPart(partPath)) collectFallbackParaIds(xml, partPath, seen);
-	else collectExistingParaIds(xml, seen);
+	for (const [partPath, xml] of partTexts) if (isTargetPart(partPath)) {
+		const spelling = partSpelling(xml, partPath);
+		spellings.set(partPath, spelling);
+		collectFallbackParaIds(xml, partPath, spelling, seen);
+	} else collectExistingParaIds(xml, seen);
 	const updates = /* @__PURE__ */ new Map();
 	let assigned = 0;
 	let deduplicated = 0;
 	for (const partPath of targetParts) {
 		const xml = partTexts.get(partPath);
-		const scan = scanPart(xml, partPath, context, seen);
+		const spelling = spellings.get(partPath);
+		const scan = scanPart(xml, partPath, spelling, context, seen);
+		if (partPath === documentPartName && scan.paragraphs === 0) assertNoUnscannedParagraphs(xml, partPath);
 		if (scan.edits.length === 0) continue;
 		assigned += scan.assigned;
 		deduplicated += scan.deduplicated;
-		updates.set(partPath, applySplices(xml, [...scan.edits, ...ensureRootNamespaces(xml, partPath)], partPath));
+		updates.set(partPath, applySplices(xml, [...scan.edits, ...ensureRootNamespaces(xml, partPath, spelling)], partPath));
 	}
 	if (updates.size === 0) return {
 		docx: toUint8Array(docx),

package/dist/docx/footnoteParser.js

@@ -4,7 +4,8 @@ import { parseParagraph } from "./paragraphParser.js";
 import { standalonePreviewLedger } from "./previewBudget.js";
 import { captureSdtSiblingMarkers, parseSdtProperties } from "./sdtProperties.js";
 import { parseTable } from "./tableParser.js";
-import { findChildren, findWordprocessingChild, getAttributes, getChildElements, getLocalName, parseXml } from "./xmlParser.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { WORDPROCESSINGML_NAMESPACE_URIS, findChildren, findWordprocessingChild, getAttributes, getChildElements, getLocalName, parseXml } from "./xmlParser.js";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/footnoteParser.ts
 /**
@@ -49,7 +50,10 @@ function parseNoteBlockContent(element, styles, theme, numbering, rels, media, p
 				properties,
 				content: sdtContent ? parseNoteBlockContent(sdtContent, styles, theme, numbering, rels, media, previews) : []
 			});
-		}
+		} else if (localName === "altChunk" && WORDPROCESSINGML_NAMESPACE_URIS.has(child.namespaceUri ?? "")) blocks.push({
+			type: "preservedBlock",
+			xml: captureVerbatimXml(child)
+		});
 	}
 	return blocks;
 }
@@ -79,7 +83,7 @@ function parseFootnotes(footnotesXml, styles = null, theme = null, numbering = n
 	const byId = /* @__PURE__ */ new Map();
 	const footnotes = [];
 	if (!footnotesXml) return createFootnoteMap(byId, footnotes);
-	const rootElement = parseXml(footnotesXml).elements?.find((el) => el.type === "element" && (el.name === "w:footnotes" || el.name?.endsWith(":footnotes")));
+	const rootElement = parseXml(footnotesXml).elements?.find((el) => el.type === "element" && getLocalName(el.name ?? "") === "footnotes");
 	if (!rootElement) return createFootnoteMap(byId, footnotes);
 	const footnoteElements = findChildren(rootElement, "w", "footnote");
 	for (const fnEl of footnoteElements) {
@@ -148,7 +152,7 @@ function parseEndnotes(endnotesXml, styles = null, theme = null, numbering = nul
 	const byId = /* @__PURE__ */ new Map();
 	const endnotes = [];
 	if (!endnotesXml) return createEndnoteMap(byId, endnotes);
-	const rootElement = parseXml(endnotesXml).elements?.find((el) => el.type === "element" && (el.name === "w:endnotes" || el.name?.endsWith(":endnotes")));
+	const rootElement = parseXml(endnotesXml).elements?.find((el) => el.type === "element" && getLocalName(el.name ?? "") === "endnotes");
 	if (!rootElement) return createEndnoteMap(byId, endnotes);
 	const endnoteElements = findChildren(rootElement, "w", "endnote");
 	for (const enEl of endnoteElements) {

package/dist/docx/headerFooterParser.js

@@ -5,7 +5,7 @@ import { assignHeaderFooterVerbatimXml } from "./headerFooterVerbatim.js";
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
 import { standalonePreviewLedger } from "./previewBudget.js";
 import { parseWatermark } from "./watermarkParser.js";
-import { collectXmlnsDeclarations, parseXml } from "./xmlParser.js";
+import { collectXmlnsDeclarations, getLocalName, parseXml } from "./xmlParser.js";
 //#region src/docx/headerFooterParser.ts
 /**
 * Parse a header XML file (word/header*.xml)
@@ -28,7 +28,7 @@ function parseHeader(headerXml, hdrFtrType = "default", styles = null, theme = n
 		content: []
 	};
 	if (!headerXml) return result;
-	const rootElement = parseXml(headerXml).elements?.find((el) => el.type === "element" && (el.name === "w:hdr" || el.name?.endsWith(":hdr")));
+	const rootElement = parseXml(headerXml).elements?.find((el) => el.type === "element" && getLocalName(el.name ?? "") === "hdr");
 	if (!rootElement) return result;
 	const watermarkResult = parseWatermark(rootElement);
 	if (watermarkResult) {
@@ -72,7 +72,7 @@ function parseFooter(footerXml, hdrFtrType = "default", styles = null, theme = n
 		content: []
 	};
 	if (!footerXml) return result;
-	const rootElement = parseXml(footerXml).elements?.find((el) => el.type === "element" && (el.name === "w:ftr" || el.name?.endsWith(":ftr")));
+	const rootElement = parseXml(footerXml).elements?.find((el) => el.type === "element" && getLocalName(el.name ?? "") === "ftr");
 	if (!rootElement) return result;
 	result.content = parseBlockContent(rootElement, styles, theme, numbering, rels, media, {
 		inHeaderFooter: true,

package/dist/docx/headerFooterReferenceNormalization.d.ts

@@ -13,5 +13,24 @@ type NormalizeHeaderFooterReferencesResult = {
   removedDanglingFooterReferences: number;
 };
 declare const normalizeHeaderFooterReferences: ({ documentBody, headers, footers }: NormalizeHeaderFooterReferencesInput) => NormalizeHeaderFooterReferencesResult;
+type AssignHeaderFooterRolesInput = {
+  documentBody: document_d_exports.DocumentBody;
+  headers?: Map<string, document_d_exports.HeaderFooter>;
+  footers?: Map<string, document_d_exports.HeaderFooter>;
+};
+/**
+ * Give each header and footer part the role a section reference states for
+ * it.
+ *
+ * A part says nothing about which pages it serves: the `w:type` of the
+ * `w:headerReference` / `w:footerReference` naming it does (ECMA-376 Part 1
+ * §17.10.5, `ST_HdrFtr`). The parts are read from the document's
+ * relationships, before any section is consulted, so each is read as a
+ * default part and takes its role here, from the first section that
+ * references it. A part no section references stays default; one several
+ * sections reference in different roles keeps the first, and a reader that
+ * needs every role reads the section references themselves.
+ */
+declare const assignHeaderFooterRoles: ({ documentBody, headers, footers }: AssignHeaderFooterRolesInput) => void;
 //#endregion
-export { DANGLING_FOOTER_REFERENCE_WARNING, DANGLING_HEADER_REFERENCE_WARNING, normalizeHeaderFooterReferences };
+export { DANGLING_FOOTER_REFERENCE_WARNING, DANGLING_HEADER_REFERENCE_WARNING, assignHeaderFooterRoles, normalizeHeaderFooterReferences };

package/dist/docx/headerFooterReferenceNormalization.js

@@ -4,12 +4,9 @@ import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 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;
 	let removedDanglingFooterReferences = 0;
 	const normalizeSectionProperties = (sectionProperties) => {
-		if (!sectionProperties || seenSectionProperties.has(sectionProperties)) return;
-		seenSectionProperties.add(sectionProperties);
 		const headerResult = removeDanglingReferences(sectionProperties.headerReferences, headers);
 		if (headerResult.changed) {
 			removedDanglingHeaderReferences += headerResult.removed;
@@ -23,34 +20,62 @@ const normalizeHeaderFooterReferences = ({ documentBody, headers, footers }) =>
 			else delete sectionProperties.footerReferences;
 		}
 	};
-	const normalizeParagraph = (paragraph) => {
-		normalizeSectionProperties(paragraph.sectionProperties);
+	forEachSectionProperties(documentBody, normalizeSectionProperties);
+	return {
+		removedDanglingHeaderReferences,
+		removedDanglingFooterReferences
 	};
-	const normalizeTable = (table) => {
-		for (const row of table.rows) for (const cell of row.cells) normalizeBlocks(cell.content);
+};
+/**
+* Visit every distinct section record once, in section order: the paragraph
+* carriers in document order, then the body's final `w:sectPr`.
+*/
+const forEachSectionProperties = (documentBody, visit) => {
+	const seen = /* @__PURE__ */ new Set();
+	const visitOnce = (sectionProperties) => {
+		if (!sectionProperties || seen.has(sectionProperties)) return;
+		seen.add(sectionProperties);
+		visit(sectionProperties);
 	};
-	const normalizeBlock = (block) => {
-		if (block.type === "paragraph") {
-			normalizeParagraph(block);
-			return;
-		}
-		if (block.type === "table") {
-			normalizeTable(block);
-			return;
-		}
-		if (block.type !== "blockSdt") return;
-		normalizeBlocks(block.content);
+	const visitBlocks = (blocks) => {
+		for (const block of blocks) if (block.type === "paragraph") visitOnce(block.sectionProperties);
+		else if (block.type === "table") visitTable(block);
+		else if (block.type === "blockSdt" || block.type === "blockCustomXml") visitBlocks(block.content);
 	};
-	const normalizeBlocks = (blocks) => {
-		for (const block of blocks) normalizeBlock(block);
+	const visitTable = (table) => {
+		for (const row of table.rows) for (const cell of row.cells) visitBlocks(cell.content);
 	};
-	normalizeBlocks(documentBody.content);
-	normalizeSectionProperties(documentBody.finalSectionProperties);
-	for (const section of documentBody.sections ?? []) normalizeSectionProperties(section.properties);
-	return {
-		removedDanglingHeaderReferences,
-		removedDanglingFooterReferences
+	visitBlocks(documentBody.content);
+	visitOnce(documentBody.finalSectionProperties);
+	for (const section of documentBody.sections ?? []) visitOnce(section.properties);
+};
+/**
+* Give each header and footer part the role a section reference states for
+* it.
+*
+* A part says nothing about which pages it serves: the `w:type` of the
+* `w:headerReference` / `w:footerReference` naming it does (ECMA-376 Part 1
+* §17.10.5, `ST_HdrFtr`). The parts are read from the document's
+* relationships, before any section is consulted, so each is read as a
+* default part and takes its role here, from the first section that
+* references it. A part no section references stays default; one several
+* sections reference in different roles keeps the first, and a reader that
+* needs every role reads the section references themselves.
+*/
+const assignHeaderFooterRoles = ({ documentBody, headers, footers }) => {
+	const assigned = /* @__PURE__ */ new Set();
+	const assign = (references, parts) => {
+		for (const { type, rId } of references ?? []) {
+			const part = parts?.get(rId);
+			if (!part || assigned.has(part)) continue;
+			assigned.add(part);
+			part.hdrFtrType = type;
+		}
 	};
+	forEachSectionProperties(documentBody, (sectionProperties) => {
+		assign(sectionProperties.headerReferences, headers);
+		assign(sectionProperties.footerReferences, footers);
+	});
 };
 const removeDanglingReferences = (references, validParts) => {
 	if (!references || !validParts) return {
@@ -66,4 +91,4 @@ const removeDanglingReferences = (references, validParts) => {
 	};
 };
 //#endregion
-export { DANGLING_FOOTER_REFERENCE_WARNING, DANGLING_HEADER_REFERENCE_WARNING, normalizeHeaderFooterReferences };
+export { DANGLING_FOOTER_REFERENCE_WARNING, DANGLING_HEADER_REFERENCE_WARNING, assignHeaderFooterRoles, normalizeHeaderFooterReferences };

package/dist/docx/hyperlinkParser.d.ts

@@ -1,8 +1,8 @@
 import { document_d_exports } from "../types/document.js";
 import { XmlElement } from "./xmlParser.js";
+import { ChildReader } from "./containerChildren.js";
 import { PreviewLedger } from "./previewBudget.js";
 import { StyleMap } from "./styleParser.js";
-import { ChildReader } from "./containerChildren.js";
 //#region src/docx/hyperlinkParser.d.ts
 /**
  * Parse a hyperlink element (w:hyperlink)

package/dist/docx/index.d.ts

@@ -1,6 +1,6 @@
 import { getCachedNumberingMap } from "./numberingParser.js";
+import { NO_NUMBERING_NUM_ID, NO_PARAGRAPH_NUMBERING, ParagraphNumberingOverride, ParagraphNumberingSlots, ResolvedParagraphNumbering, isNumberingReference, mergeParagraphNumbering, paragraphNumberingFromSlots, paragraphNumberingLevel, paragraphNumberingReferenceId, paragraphNumberingSlots, readParagraphNumbering, resolveParagraphNumbering, sameEffectiveParagraphNumbering, sameStatedParagraphNumbering } from "./numberingReference.js";
 import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, DocxEncryptionErrorCode, isDocxEncryptionError } from "./encryption/errors.js";
 import { DecryptDocxOptions, DecryptDocxResult, decryptDocxIfNeeded, openDocxBuffer } from "./encryption/openEncryptedDocx.js";
-import { NO_NUMBERING_NUM_ID, NO_PARAGRAPH_NUMBERING, ParagraphNumberingOverride, ParagraphNumberingSlots, ResolvedParagraphNumbering, isNumberingReference, mergeParagraphNumbering, paragraphNumberingFromSlots, paragraphNumberingLevel, paragraphNumberingReferenceId, paragraphNumberingSlots, readParagraphNumbering, resolveParagraphNumbering, sameEffectiveParagraphNumbering, sameStatedParagraphNumbering } from "./numberingReference.js";
 import { FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, FolioDocumentMetadataProperty, FolioDocumentPrivacyArchiveError, FolioDocumentPrivacyOptions, FolioDocumentPrivacyReport, FolioDocumentPrivacyTransform, InvalidFolioDocumentPrivacyOptionsError, RewriteDocxMetadataPrivacyResult, isFolioDocumentPrivacyTransform, rewriteDocxMetadataPrivacy } from "./metadataPrivacy.js";
 export { DOCX_ENCRYPTION_ERROR_CODES, type DecryptDocxOptions, type DecryptDocxResult, DocxEncryptionError, type DocxEncryptionErrorCode, FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, type FolioDocumentMetadataProperty, FolioDocumentPrivacyArchiveError, type FolioDocumentPrivacyOptions, type FolioDocumentPrivacyReport, type FolioDocumentPrivacyTransform, InvalidFolioDocumentPrivacyOptionsError, NO_NUMBERING_NUM_ID, NO_PARAGRAPH_NUMBERING, type ParagraphNumberingOverride, type ParagraphNumberingSlots, type ResolvedParagraphNumbering, type RewriteDocxMetadataPrivacyResult, decryptDocxIfNeeded, getCachedNumberingMap, isDocxEncryptionError, isFolioDocumentPrivacyTransform, isNumberingReference, mergeParagraphNumbering, openDocxBuffer, paragraphNumberingFromSlots, paragraphNumberingLevel, paragraphNumberingReferenceId, paragraphNumberingSlots, readParagraphNumbering, resolveParagraphNumbering, rewriteDocxMetadataPrivacy, sameEffectiveParagraphNumbering, sameStatedParagraphNumbering };

package/dist/docx/listNumberingInstances.d.ts

@@ -0,0 +1,59 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/listNumberingInstances.d.ts
+/** The two kinds of list a command can create. */
+declare const LIST_KINDS: readonly ["bullet", "numbered"];
+type ListKind = (typeof LIST_KINDS)[number];
+/** What a numbered list's first level counts in and how its marker reads. */
+type ListLevelFormat = {
+  numFmt: document_d_exports.NumberFormat;
+  /** `w:lvlText` for level 0, e.g. `%1.` or `%1)`. */
+  lvlText: string;
+};
+/** The first-level appearance and start a new list is minted with. */
+type NewListDefinition = {
+  kind: ListKind;
+  /** Level-0 format of a numbered list; the template's `%1.` decimal otherwise. */
+  format?: ListLevelFormat | undefined;
+  /** The value the first item shows, stated as a level-0 `w:startOverride`. */
+  start?: number | undefined;
+};
+type MintedListInstance = {
+  definitions: document_d_exports.NumberingDefinitions;
+  numId: number;
+};
+/**
+ * Define a new list: a new `w:abstractNum` of the requested kind and the
+ * `w:num` naming it. `definitions` must already hold every instance the
+ * document references (see {@link completeListNumbering}), so the new ids
+ * collide with none of them.
+ */
+declare const mintListInstance: (definitions: document_d_exports.NumberingDefinitions | null | undefined, { kind, format, start }: NewListDefinition) => MintedListInstance;
+type RestartListInstanceOptions = {
+  abstractNumId: number;
+  ilvl: number;
+  start: number;
+};
+/**
+ * A new `w:num` over an existing `w:abstractNum`, with a `w:startOverride` at
+ * `ilvl`: *Restart Numbering* and *Set Numbering Value*. The override is what
+ * makes a consumer count the instance on its own rather than continue the
+ * other instances of the same definition.
+ */
+declare const restartListInstance: (definitions: document_d_exports.NumberingDefinitions | null | undefined, { abstractNumId, ilvl, start }: RestartListInstanceOptions) => MintedListInstance;
+/** One paragraph's numbering reference and the rendering it resolved to. */
+type ListInstanceReference = {
+  numId: number;
+  ilvl: number;
+  rendering: document_d_exports.ListRendering;
+};
+/**
+ * Define every instance `references` name that `definitions` does not.
+ *
+ * A reference the editor resolved carries its rendering, and a rendering is
+ * what a minted instance leaves behind; a reference without one (a dangling
+ * id read from a file) has no rendering and so is never defined here. Returns
+ * `definitions` itself when nothing is missing.
+ */
+declare const completeListNumbering: (definitions: document_d_exports.NumberingDefinitions | undefined, references: Iterable<ListInstanceReference>) => document_d_exports.NumberingDefinitions | undefined;
+//#endregion
+export { LIST_KINDS, ListInstanceReference, ListKind, ListLevelFormat, completeListNumbering, mintListInstance, restartListInstance };