@stll/folio-core 0.52.0 → 0.54.0

package/dist/docx/documentParser.js

@@ -40,7 +40,7 @@ function extractAllTemplateVariables(content) {
 	} else if (block.type === "table") {
 		const tableVars = extractTableVariables(block);
 		for (const v of tableVars) if (!variables.includes(v)) variables.push(v);
-	} else if (block.type === "blockSdt") {
+	} else if (block.type === "blockSdt" || block.type === "blockCustomXml") {
 		for (const v of extractAllTemplateVariables(block.content)) if (!variables.includes(v)) variables.push(v);
 	}
 	return variables;
@@ -56,7 +56,7 @@ function extractTableVariables(table) {
 	} else if (cellContent.type === "table") {
 		const nestedVars = extractTableVariables(cellContent);
 		for (const v of nestedVars) if (!variables.includes(v)) variables.push(v);
-	} else if (cellContent.type === "blockSdt") {
+	} else if (cellContent.type === "blockSdt" || cellContent.type === "blockCustomXml") {
 		for (const v of extractAllTemplateVariables(cellContent.content)) if (!variables.includes(v)) variables.push(v);
 	}
 	return variables;
@@ -153,7 +153,7 @@ function parseDocumentBackground(documentEl, context) {
 function parseDocumentBody(xml, styles = null, theme = null, numbering = null, rels = null, media = null, context, previews = standalonePreviewLedger()) {
 	const result = { content: [] };
 	if (!xml) return result;
-	const documentEl = (parseXml(xml).elements ?? []).find((el) => el.type === "element" && (el.name === "w:document" || el.name?.endsWith(":document")));
+	const documentEl = (parseXml(xml).elements ?? []).find((el) => el.type === "element" && getLocalName(el.name ?? "") === "document");
 	if (!documentEl) return result;
 	const background = parseDocumentBackground(documentEl, context);
 	if (background !== void 0) result.background = background;
@@ -177,14 +177,14 @@ function getAllParagraphs(body) {
 	const paragraphs = [];
 	for (const block of body.content) if (block.type === "paragraph") paragraphs.push(block);
 	else if (block.type === "table") paragraphs.push(...getTableParagraphs(block));
-	else if (block.type === "blockSdt") paragraphs.push(...getParagraphsFromBlocks(block.content));
+	else if (block.type === "blockSdt" || block.type === "blockCustomXml") paragraphs.push(...getParagraphsFromBlocks(block.content));
 	return paragraphs;
 }
 const getParagraphsFromBlocks = (blocks) => {
 	const paragraphs = [];
 	for (const block of blocks) if (block.type === "paragraph") paragraphs.push(block);
 	else if (block.type === "table") paragraphs.push(...getTableParagraphs(block));
-	else if (block.type === "blockSdt") paragraphs.push(...getParagraphsFromBlocks(block.content));
+	else if (block.type === "blockSdt" || block.type === "blockCustomXml") paragraphs.push(...getParagraphsFromBlocks(block.content));
 	return paragraphs;
 };
 /**
@@ -194,7 +194,7 @@ function getTableParagraphs(table) {
 	const paragraphs = [];
 	for (const row of table.rows) for (const cell of row.cells) for (const content of cell.content) if (content.type === "paragraph") paragraphs.push(content);
 	else if (content.type === "table") paragraphs.push(...getTableParagraphs(content));
-	else if (content.type === "blockSdt") paragraphs.push(...getParagraphsFromBlocks(content.content));
+	else if (content.type === "blockSdt" || content.type === "blockCustomXml") paragraphs.push(...getParagraphsFromBlocks(content.content));
 	return paragraphs;
 }
 /**
@@ -205,13 +205,13 @@ function getAllTables(body) {
 	for (const block of body.content) if (block.type === "table") {
 		tables.push(block);
 		tables.push(...getNestedTables(block));
-	} else if (block.type === "blockSdt") tables.push(...getTablesFromBlocks(block.content));
+	} else if (block.type === "blockSdt" || block.type === "blockCustomXml") tables.push(...getTablesFromBlocks(block.content));
 	return tables;
 }
 const getTablesFromBlocks = (blocks) => {
 	const tables = [];
 	for (const block of blocks) if (block.type === "table") tables.push(block, ...getNestedTables(block));
-	else if (block.type === "blockSdt") tables.push(...getTablesFromBlocks(block.content));
+	else if (block.type === "blockSdt" || block.type === "blockCustomXml") tables.push(...getTablesFromBlocks(block.content));
 	return tables;
 };
 /**
@@ -222,7 +222,7 @@ function getNestedTables(table) {
 	for (const row of table.rows) for (const cell of row.cells) for (const content of cell.content) if (content.type === "table") {
 		tables.push(content);
 		tables.push(...getNestedTables(content));
-	} else if (content.type === "blockSdt") tables.push(...getTablesFromBlocks(content.content));
+	} else if (content.type === "blockSdt" || content.type === "blockCustomXml") tables.push(...getTablesFromBlocks(content.content));
 	return tables;
 }
 /**
@@ -232,13 +232,13 @@ function getDocumentText(body) {
 	const lines = [];
 	for (const block of body.content) if (block.type === "paragraph") lines.push(getParagraphText(block));
 	else if (block.type === "table") lines.push(getTableText(block));
-	else if (block.type === "blockSdt") lines.push(getTextFromBlocks(block.content));
+	else if (block.type === "blockSdt" || block.type === "blockCustomXml") lines.push(getTextFromBlocks(block.content));
 	return lines.join("\n");
 }
 const getTextFromBlocks = (blocks) => blocks.flatMap((block) => {
 	if (block.type === "paragraph") return [getParagraphText(block)];
 	if (block.type === "table") return [getTableText(block)];
-	return block.type === "blockSdt" ? [getTextFromBlocks(block.content)] : [];
+	return block.type === "blockSdt" || block.type === "blockCustomXml" ? [getTextFromBlocks(block.content)] : [];
 }).join("\n");
 /**
 * Get plain text from a table
@@ -251,7 +251,7 @@ function getTableText(table) {
 			const cellTexts = [];
 			for (const content of cell.content) if (content.type === "paragraph") cellTexts.push(getParagraphText(content));
 			else if (content.type === "table") cellTexts.push(getTableText(content));
-			else if (content.type === "blockSdt") cellTexts.push(getTextFromBlocks(content.content));
+			else if (content.type === "blockSdt" || content.type === "blockCustomXml") cellTexts.push(getTextFromBlocks(content.content));
 			rowTexts.push(cellTexts.join("\n"));
 		}
 		lines.push(rowTexts.join("	"));

package/dist/docx/drawingIdNormalization.d.ts

@@ -1,5 +1,7 @@
 import { DocxParagraphSurfaces } from "./paragraphTraversal.js";
 //#region src/docx/drawingIdNormalization.d.ts
+/** Drawing IDs are package-local identifiers, not image content. */
+declare const drawingXmlWithoutIdentity: (xml: string) => string;
 declare const normalizeDrawingIds: (surfaces: DocxParagraphSurfaces) => void;
 //#endregion
-export { normalizeDrawingIds };
+export { drawingXmlWithoutIdentity, normalizeDrawingIds };

package/dist/docx/drawingIdNormalization.js

@@ -22,6 +22,11 @@ const reassignRawDrawingId = ({ xml, id }) => {
 	visit(root);
 	return foundDocPr ? (root.elements ?? []).map(captureVerbatimXml).join("") : null;
 };
+/** Drawing IDs are package-local identifiers, not image content. */
+const drawingXmlWithoutIdentity = (xml) => reassignRawDrawingId({
+	xml,
+	id: "0"
+}) ?? xml;
 const needsGeneratedId = ({ id }) => id === void 0 || id === "" || id === "0";
 const normalizeDrawingIds = (surfaces) => {
 	const entries = [];
@@ -73,4 +78,4 @@ const normalizeDrawingIds = (surfaces) => {
 	}
 };
 //#endregion
-export { normalizeDrawingIds };
+export { drawingXmlWithoutIdentity, normalizeDrawingIds };

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