@stll/folio-core 0.54.2 → 0.55.0

package/dist/docx/ensureParaIds.js

@@ -1,8 +1,10 @@
 import { deterministicHexId } from "../utils/hexId.js";
-import { isXmlNameBoundary, spliceXml } from "./selectiveXmlPatch.js";
+import { resolvePackageRelationshipTarget } from "./packageParts.js";
+import { 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 { scanStreamingXmlElements } from "./streamingXmlParser.js";
+import { resolveNamespaceUri } from "./xmlNamespaceContext.js";
+import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, getAttribute, getChildElements, getLocalName, getNamespaceUri, parseXmlDocument, resolveAttributeNamespaceUri } from "./xmlParser.js";
 import { TaggedError } from "better-result";
 import JSZip from "jszip";
 //#region src/docx/ensureParaIds.ts
@@ -27,7 +29,7 @@ import JSZip from "jszip";
 * so documents carrying features folio's parser does not model come back
 * with those features byte-identical. Contract:
 *
-* - Parts covered: `word/document.xml`, `word/header*.xml`, `word/footer*.xml`,
+* - Parts covered: the officeDocument relationship target, `word/header*.xml`, `word/footer*.xml`,
 *   `word/footnotes.xml`, `word/endnotes.xml`. Paragraphs nested in table
 *   cells and in `mc:Choice` text boxes are plain `<w:p>` elements inside
 *   those parts and are covered by the same scan. The comments part mints its
@@ -50,12 +52,10 @@ 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}.
+* - Prefixes are aliases: elements and attributes resolve against their
+*   in-scope namespace URI, including Strict and Transitional profiles and
+*   nested rebinding. Minted attributes use a root prefix with no conflicting
+*   nested binding; a fresh prefix is declared when necessary.
 * - Idempotent: a document that already has full coverage is returned as the
 *   original bytes, untouched (`alreadyComplete: true`). A body with
 *   paragraphs the scan did not see is refused, never reported complete.
@@ -63,6 +63,11 @@ import JSZip from "jszip";
 *   When normalization would rewrite the package, it fails unless the caller
 *   explicitly allows signature invalidation after warning the user.
 */
+const ENSURE_PARA_IDS_REASONS = {
+	NORMALIZATION_FAILED: "normalization-failed",
+	NAMESPACE_INVALID: "namespace-invalid",
+	SIGNED_PACKAGE: "signed-package"
+};
 /** A malformed or unsupported package prevented paragraph-ID normalization. */
 var EnsureParaIdsError = class extends TaggedError("EnsureParaIdsError") {};
 const W14_NAMESPACE_URI = "http://schemas.microsoft.com/office/word/2010/wordml";
@@ -71,53 +76,15 @@ const MC_IGNORABLE_W14 = "w14";
 const DIGITAL_SIGNATURE_PART_PREFIX = "_xmlsignatures/";
 /** Word reads an all-zero `w14:paraId` as "no id assigned". */
 const RESERVED_ZERO_ID_PATTERN = /^0*$/u;
-const DOCUMENT_PART = "word/document.xml";
+const PACKAGE_RELATIONSHIP_URI = "http://schemas.openxmlformats.org/package/2006/relationships";
 const TARGET_PART_PATTERNS = [
-	/^word\/document\.xml$/u,
 	/^word\/header\d*\.xml$/u,
 	/^word\/footer\d*\.xml$/u,
 	/^word\/footnotes\.xml$/u,
 	/^word\/endnotes\.xml$/u
 ];
-const OPAQUE_XML_REGIONS = [
-	{
-		open: "<!--",
-		close: "-->"
-	},
-	{
-		open: "<![CDATA[",
-		close: "]]>"
-	},
-	{
-		open: "<?",
-		close: "?>"
-	}
-];
-/**
-* 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 = /\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
-	};
-};
+/** Reserve package ids even in parts whose content the pass leaves untouched. */
+const ANY_PARA_ID_PATTERN = /\s[^\s=<>/"':]+:paraId\s*=\s*(?<quote>["'])(?<id>[\s\S]*?)\k<quote>/gu;
 /**
 * 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
@@ -135,84 +102,98 @@ const applySplices = (xml, edits, partPath) => {
 	return patched;
 };
 const createEnsureParaIdsError = (message, cause) => new EnsureParaIdsError({
+	reason: ENSURE_PARA_IDS_REASONS.NORMALIZATION_FAILED,
 	message,
 	...cause === void 0 ? {} : { cause }
 });
-const skipOpaqueXmlRegion = (xml, start, partPath) => {
-	for (const { open, close } of OPAQUE_XML_REGIONS) {
-		if (!xml.startsWith(open, start)) continue;
-		const closeStart = xml.indexOf(close, start + open.length);
-		if (closeStart === -1) throw createEnsureParaIdsError(`Unterminated ${open} region in ${partPath}`);
-		return closeStart + close.length;
-	}
-	return null;
-};
-const attributeValueRange = (match, absoluteOffset, group) => {
-	const quote = match.groups["quote"];
-	const value = match.groups[group];
-	const start = absoluteOffset + match.index + match[0].indexOf(quote) + 1;
-	return {
-		start,
-		end: start + value.length
-	};
-};
 const collectExistingParaIds = (xml, into) => {
 	for (const match of xml.matchAll(ANY_PARA_ID_PATTERN)) {
 		const id = match.groups["id"];
 		if (id.length > 0) into.add(id.toUpperCase());
 	}
 };
-/**
-* 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) {
-		const tagStart = xml.indexOf("<", pos);
-		if (tagStart === -1) return;
-		const opaqueEnd = skipOpaqueXmlRegion(xml, tagStart, partPath);
-		if (opaqueEnd !== null) {
-			pos = opaqueEnd;
-			continue;
+/** Resolve every element and attribute in its own scope; retain source offsets for splices. */
+const partSpelling = (xml, partPath) => {
+	let root;
+	let rootNameEnd = 0;
+	let ignorable;
+	const paragraphs = [];
+	const fallbacks = /* @__PURE__ */ new WeakSet();
+	const bindings = /* @__PURE__ */ new Map();
+	if (scanStreamingXmlElements(xml, ({ element, attributeValueSpans: spans, nameEnd, parent }) => {
+		const unboundElement = (element.name ?? "").includes(":") && getNamespaceUri(element) === void 0;
+		const unboundAttribute = Object.keys(element.attributes ?? {}).some((attribute) => attribute.includes(":") && !attribute.startsWith("xmlns:") && resolveAttributeNamespaceUri(element, attribute) === void 0);
+		if (unboundElement || unboundAttribute) throw new EnsureParaIdsError({
+			reason: ENSURE_PARA_IDS_REASONS.NAMESPACE_INVALID,
+			message: `Undeclared namespace prefix in ${partPath}`
+		});
+		if (parent === void 0) {
+			if (root !== void 0) throw createEnsureParaIdsError(`Multiple roots in ${partPath}`);
+			root = element;
+			rootNameEnd = nameEnd;
 		}
-		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 (xml[tagEnd - 1] !== "/") fallbackDepth += 1;
-			pos = tagEnd + 1;
-			continue;
+		for (const [name, value] of Object.entries(element.attributes ?? {})) {
+			if (name !== "xmlns" && !name.startsWith("xmlns:")) continue;
+			const prefix = name === "xmlns" ? "" : name.slice(6);
+			let uris = bindings.get(prefix);
+			if (uris === void 0) {
+				uris = /* @__PURE__ */ new Set();
+				bindings.set(prefix, uris);
+			}
+			uris.add(String(value));
 		}
-		const fallbackClose = matchCloseTag(xml, tagStart, prefixes.mc, "Fallback");
-		if (fallbackClose !== -1) {
-			fallbackDepth = Math.max(0, fallbackDepth - 1);
-			pos = tagStart + fallbackClose;
-			continue;
+		const inFallback = parent !== void 0 && fallbacks.has(parent) || getLocalName(element.name ?? "") === "Fallback" && getNamespaceUri(element) === MC_NAMESPACE_URI;
+		if (inFallback) fallbacks.add(element);
+		let paraId;
+		let textId;
+		for (const [name, span] of spans) {
+			const namespace = resolveAttributeNamespaceUri(element, name);
+			const localName = getLocalName(name);
+			const value = String(element.attributes?.[name] ?? "");
+			if (element === root && namespace === MC_NAMESPACE_URI && localName === "Ignorable") ignorable = {
+				...span,
+				value
+			};
+			if (namespace !== W14_NAMESPACE_URI && !WORDPROCESSINGML_NAMESPACE_URIS.has(namespace ?? "")) continue;
+			if (localName === "paraId") {
+				if (paraId === void 0 || namespace === W14_NAMESPACE_URI) paraId = {
+					...span,
+					value
+				};
+			}
+			if (localName === "textId") textId = {
+				...span,
+				value
+			};
 		}
-		const nameLength = matchOpenTag(xml, tagStart, prefixes.main, "p");
-		if (nameLength === -1) {
-			pos = tagStart + 1;
-			continue;
+		if (getLocalName(element.name ?? "") === "p" && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "")) paragraphs.push({
+			nameEnd,
+			inFallback,
+			paraId,
+			textId
+		});
+	}).status === "unsupported" || root === void 0) throw createEnsureParaIdsError(`Malformed XML in ${partPath}`);
+	const rootElement = root;
+	const prefixFor = (uri, preferred) => {
+		for (const [prefix, boundUri] of rootElement.namespaceScope?.bindings ?? []) {
+			if (prefix === "" || boundUri !== uri) continue;
+			if (uri !== W14_NAMESPACE_URI || bindings.get(prefix)?.size === 1) return prefix;
 		}
-		const tagEnd = xml.indexOf(">", tagStart);
-		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());
-	}
+		let candidate = preferred;
+		for (let suffix = 1; bindings.has(candidate); suffix += 1) candidate = `${preferred}_${suffix}`;
+		return candidate;
+	};
+	return {
+		root,
+		rootNameEnd,
+		ignorable,
+		paragraphs,
+		w14Prefix: prefixFor(W14_NAMESPACE_URI, MC_IGNORABLE_W14),
+		mcPrefix: prefixFor(MC_NAMESPACE_URI, "mc")
+	};
+};
+const collectFallbackParaIds = (spelling, into) => {
+	for (const { inFallback, paraId } of spelling.paragraphs) if (inFallback && paraId?.value) into.add(paraId.value.toUpperCase());
 };
 /**
 * Deterministic fresh id for the paragraph at `ordinal` in `partPath`,
@@ -225,35 +206,27 @@ const mintParaId = (context, partPath, ordinal) => {
 	context.taken.add(id);
 	return id;
 };
-/**
-* 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, spelling, context, seen) => {
+const scanPart = ({ partPath, spelling, context, seen }) => {
 	const edits = [];
 	const minted = [];
 	const w14 = spelling.w14Prefix;
 	let assigned = 0;
 	let deduplicated = 0;
 	let ordinal = 0;
-	for (const { tagStart, tagEnd, nameEnd, inFallback } of paragraphOpenTags(xml, partPath, spelling)) {
+	for (const { nameEnd, inFallback, paraId, textId } of spelling.paragraphs) {
 		if (inFallback) continue;
 		ordinal += 1;
-		const openTag = xml.slice(tagStart, tagEnd + 1);
-		const paraIdMatch = spelling.paraId.exec(openTag);
-		if (!paraIdMatch) {
+		if (paraId === void 0) {
 			const id = mintParaId(context, partPath, ordinal);
-			const textIdMatch = spelling.textId.exec(openTag);
-			if (textIdMatch) {
+			if (textId !== void 0) {
 				edits.push({
 					start: nameEnd,
 					end: nameEnd,
 					text: ` ${w14}:paraId="${id}"`
 				});
 				edits.push({
-					...attributeValueRange(textIdMatch, tagStart, "value"),
+					start: textId.start,
+					end: textId.end,
 					text: id
 				});
 			} else edits.push({
@@ -266,7 +239,7 @@ const scanPart = (xml, partPath, spelling, context, seen) => {
 			seen.add(id);
 			continue;
 		}
-		const value = paraIdMatch.groups["value"].toUpperCase();
+		const value = paraId.value.toUpperCase();
 		const unassigned = RESERVED_ZERO_ID_PATTERN.test(value);
 		if (!unassigned && !seen.has(value)) {
 			seen.add(value);
@@ -274,12 +247,13 @@ const scanPart = (xml, partPath, spelling, context, seen) => {
 		}
 		const id = mintParaId(context, partPath, ordinal);
 		edits.push({
-			...attributeValueRange(paraIdMatch, tagStart, "value"),
+			start: paraId.start,
+			end: paraId.end,
 			text: id
 		});
-		const textIdMatch = spelling.textId.exec(openTag);
-		if (textIdMatch) edits.push({
-			...attributeValueRange(textIdMatch, tagStart, "value"),
+		if (textId !== void 0) edits.push({
+			start: textId.start,
+			end: textId.end,
 			text: id
 		});
 		else edits.push({
@@ -296,8 +270,7 @@ const scanPart = (xml, partPath, spelling, context, seen) => {
 		edits,
 		minted,
 		assigned,
-		deduplicated,
-		paragraphs: ordinal
+		deduplicated
 	};
 };
 /**
@@ -305,71 +278,42 @@ const scanPart = (xml, partPath, spelling, 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, { prefixes, w14Prefix }) => {
-	let pos = 0;
-	let rootStart = -1;
-	while (pos < xml.length) {
-		const lt = xml.indexOf("<", pos);
-		if (lt === -1) break;
-		const opaqueEnd = skipOpaqueXmlRegion(xml, lt, partPath);
-		if (opaqueEnd !== null) {
-			pos = opaqueEnd;
-			continue;
-		}
-		if (xml[lt + 1] === "!") {
-			const skipTo = xml.indexOf(">", lt);
-			if (skipTo === -1) throw createEnsureParaIdsError(`Unterminated prolog in ${partPath}`);
-			pos = skipTo + 1;
-			continue;
-		}
-		rootStart = lt;
-		break;
-	}
-	if (rootStart === -1) throw createEnsureParaIdsError(`No root element in ${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 ensureRootNamespaces = ({ root, rootNameEnd, ignorable, w14Prefix, mcPrefix }) => {
 	const edits = [];
 	const declarations = [];
-	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(w14Prefix)) {
-			const { end } = attributeValueRange(ignorable, rootStart, "value");
-			const text = tokens.length === 0 ? w14Prefix : ` ${w14Prefix}`;
-			edits.push({
-				start: end,
-				end,
-				text
-			});
-		}
-	} else declarations.push(` ${mcPrefix}:Ignorable="${w14Prefix}"`);
-	if (declarations.length > 0) {
-		let nameEnd = rootStart + 1;
-		while (nameEnd < xml.length && !isXmlNameBoundary(xml[nameEnd])) nameEnd += 1;
-		edits.push({
-			start: nameEnd,
-			end: nameEnd,
-			text: declarations.join("")
+	if (resolveNamespaceUri(root.namespaceScope, mcPrefix) !== MC_NAMESPACE_URI) declarations.push(` xmlns:${mcPrefix}="${MC_NAMESPACE_URI}"`);
+	if (resolveNamespaceUri(root.namespaceScope, w14Prefix) !== W14_NAMESPACE_URI) declarations.push(` xmlns:${w14Prefix}="${W14_NAMESPACE_URI}"`);
+	if (ignorable !== void 0) {
+		const tokens = ignorable.value.split(/\s+/u).filter((token) => token.length > 0);
+		if (!tokens.includes(w14Prefix)) edits.push({
+			start: ignorable.end,
+			end: ignorable.end,
+			text: tokens.length === 0 ? w14Prefix : ` ${w14Prefix}`
 		});
-	}
+	} else declarations.push(` ${mcPrefix}:Ignorable="${w14Prefix}"`);
+	if (declarations.length > 0) edits.push({
+		start: rootNameEnd,
+		end: rootNameEnd,
+		text: declarations.join("")
+	});
 	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`);
+const mainDocumentPart = (rels, entries) => {
+	const root = parseXmlDocument(rels);
+	if (root === null || getLocalName(root.name ?? "") !== "Relationships" || getNamespaceUri(root) !== PACKAGE_RELATIONSHIP_URI) throw createEnsureParaIdsError("Malformed package relationships");
+	const documents = getChildElements(root).filter((element) => {
+		if (getLocalName(element.name ?? "") !== "Relationship" || getNamespaceUri(element) !== PACKAGE_RELATIONSHIP_URI) return false;
+		const type = getAttribute(element, null, "Type");
+		return [...OFFICE_RELATIONSHIP_NAMESPACE_URIS].some((uri) => type === `${uri}/officeDocument`);
+	});
+	const document = documents.at(0);
+	if (documents.length !== 1 || document === void 0 || getAttribute(document, null, "TargetMode") === "External") throw createEnsureParaIdsError("Package must have one internal officeDocument relationship");
+	const target = getAttribute(document, null, "Target");
+	const partPath = target === null ? void 0 : resolvePackageRelationshipTarget(target, "_rels/.rels");
+	if (partPath === void 0) throw createEnsureParaIdsError("Invalid officeDocument target");
+	const name = entries.find((entry) => entry.toLowerCase() === partPath);
+	if (name === void 0) throw createEnsureParaIdsError("officeDocument part not found");
+	return name;
 };
 /** OPC part names are case-insensitive; compare lowercased. */
 const isTargetPart = (path) => TARGET_PART_PATTERNS.some((pattern) => pattern.test(path.toLowerCase()));
@@ -382,12 +326,11 @@ const hasDigitalSignatureParts = (zip) => Object.values(zip.files).some(({ dir,
 */
 const ensureParaIdsInternal = async (docx, options) => {
 	const archive = await loadDocxArchive(docx);
-	const xmlPartNames = archive.entries.filter((relativePath) => {
-		const lower = relativePath.toLowerCase();
-		return lower.startsWith("word/") && lower.endsWith(".xml");
-	});
-	const documentPartName = xmlPartNames.find((name) => name.toLowerCase() === DOCUMENT_PART);
-	if (documentPartName === void 0) throw createEnsureParaIdsError("word/document.xml not found: not a WordprocessingML package");
+	const relsPath = archive.entries.find((name) => name.toLowerCase() === "_rels/.rels");
+	const rels = relsPath === void 0 ? null : await archive.readEntryString(relsPath);
+	if (rels === null) throw createEnsureParaIdsError("Package relationships not found");
+	const documentPartName = mainDocumentPart(rels, archive.entries);
+	const xmlPartNames = archive.entries.filter((name) => name.toLowerCase().endsWith(".xml") || name === documentPartName);
 	const partTexts = /* @__PURE__ */ new Map();
 	for (const name of xmlPartNames) {
 		const text = await archive.readEntryString(name);
@@ -395,17 +338,19 @@ const ensureParaIdsInternal = async (docx, options) => {
 	}
 	const taken = /* @__PURE__ */ new Set();
 	for (const text of partTexts.values()) collectExistingParaIds(text, taken);
+	const documentXml = partTexts.get(documentPartName);
+	if (documentXml === void 0) throw createEnsureParaIdsError("officeDocument part is unreadable");
 	const context = {
 		taken,
-		docKey: deterministicHexId(partTexts.get(documentPartName))
+		docKey: deterministicHexId(documentXml)
 	};
 	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)) {
+	for (const [partPath, xml] of partTexts) if (partPath === documentPartName || isTargetPart(partPath)) {
 		const spelling = partSpelling(xml, partPath);
 		spellings.set(partPath, spelling);
-		collectFallbackParaIds(xml, partPath, spelling, seen);
+		collectFallbackParaIds(spelling, seen);
 	} else collectExistingParaIds(xml, seen);
 	const updates = /* @__PURE__ */ new Map();
 	const mintedParaIds = [];
@@ -414,13 +359,17 @@ const ensureParaIdsInternal = async (docx, options) => {
 	for (const partPath of targetParts) {
 		const xml = partTexts.get(partPath);
 		const spelling = spellings.get(partPath);
-		const scan = scanPart(xml, partPath, spelling, context, seen);
-		if (partPath === documentPartName && scan.paragraphs === 0) assertNoUnscannedParagraphs(xml, partPath);
+		const scan = scanPart({
+			partPath,
+			spelling,
+			context,
+			seen
+		});
 		if (scan.edits.length === 0) continue;
 		assigned += scan.assigned;
 		deduplicated += scan.deduplicated;
 		for (const id of scan.minted) mintedParaIds.push(id);
-		updates.set(partPath, applySplices(xml, [...scan.edits, ...ensureRootNamespaces(xml, partPath, spelling)], partPath));
+		updates.set(partPath, applySplices(xml, [...scan.edits, ...ensureRootNamespaces(spelling)], partPath));
 	}
 	if (updates.size === 0) return {
 		docx: toUint8Array(docx),
@@ -430,7 +379,10 @@ const ensureParaIdsInternal = async (docx, options) => {
 		mintedParaIds: []
 	};
 	const zip = await JSZip.loadAsync(docx);
-	if (hasDigitalSignatureParts(zip) && options.allowSignedPackageMutation !== true) throw createEnsureParaIdsError("Refusing to normalize a digitally signed package because rewriting OOXML invalidates its signatures. Warn the user and pass allowSignedPackageMutation only if invalidation is acceptable.");
+	if (hasDigitalSignatureParts(zip) && options.allowSignedPackageMutation !== true) throw new EnsureParaIdsError({
+		reason: ENSURE_PARA_IDS_REASONS.SIGNED_PACKAGE,
+		message: "Refusing to normalize a digitally signed package because rewriting OOXML invalidates its signatures. Warn the user and pass allowSignedPackageMutation only if invalidation is acceptable."
+	});
 	for (const [partPath, content] of updates) {
 		const sourceEntry = zip.file(partPath);
 		if (sourceEntry === null) throw createEnsureParaIdsError(`Package part disappeared during normalization: ${partPath}`);
@@ -466,4 +418,4 @@ const ensureParaIds = async (docx, options = {}) => {
 	}
 };
 //#endregion
-export { EnsureParaIdsError, ensureParaIds };
+export { ENSURE_PARA_IDS_REASONS, EnsureParaIdsError, ensureParaIds };

package/dist/docx/foldedListNumberFields.d.ts

@@ -0,0 +1,85 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/foldedListNumberFields.d.ts
+/** Whether `content` is markup that may stand between a field and the tab that follows it. */
+declare const isListNumberGapMarker: (content: document_d_exports.ParagraphContent) => boolean;
+/** Whether `content` is a `LISTNUM` field, by its parsed type or its instruction. */
+declare const isListNumberField: (content: document_d_exports.ParagraphContent) => content is document_d_exports.ComplexField;
+/** A run that holds one tab and nothing else. */
+declare const isTabOnlyRun: (content: document_d_exports.ParagraphContent) => content is document_d_exports.Run;
+/** Whether `value` is what a capture stands for: a complex field, or a run. */
+declare const isFoldedListNumber: (value: unknown) => value is document_d_exports.FoldedListNumber;
+/** What `content` stands for when it is a capture the fold left, else nothing. */
+declare const foldedListNumberOf: (content: document_d_exports.ParagraphContent) => document_d_exports.FoldedListNumber | undefined;
+/** Whether `content` is a capture the fold left in place of a field or its tab. */
+declare const isFoldedListNumberCapture: (content: document_d_exports.ParagraphContent) => boolean;
+type ListNumberFieldFold = {
+  /** The content, each folded field and its tab replaced by a capture. */
+  content: document_d_exports.ParagraphContent[];
+  /** The cached display of each folded field that has one, in source order. */
+  cached: string[];
+  /** Every `LISTNUM` field the content holds, folded or not. */
+  fieldCount: number;
+};
+/**
+ * Replace the `LISTNUM` fields that open a paragraph, and the tab after each,
+ * by captures of the markup they were read from.
+ *
+ * Only what stands ahead of the first thing the line shows is folded: a field
+ * after text is on the line where the text is. `sourceMarkupOf` answers the
+ * markup; a field it has none for is left as the field it is, and ends the
+ * fold. Bookmark and comment markers between a field and its tab stay where
+ * they are, and the tab is still the field's when only they separate the two.
+ */
+declare const foldListNumberFields: (content: readonly document_d_exports.ParagraphContent[], sourceMarkupOf: (item: document_d_exports.ComplexField | document_d_exports.Run) => string | undefined) => ListNumberFieldFold;
+/** One item of a paragraph, as far as the fold needs to know it. */
+type ListNumberFoldItem =
+/** A capture of a field, with the text its cached result shows. */
+{
+  kind: "field";
+  cached: string;
+} |
+/** A capture of the tab after a field. */
+{
+  kind: "tab";
+} |
+/** Markup that shows nothing. */
+{
+  kind: "hidden";
+} |
+/** Anything the line shows. */
+{
+  kind: "shown";
+};
+type ListNumberFoldPlan = {
+  /** The items' indices in the order they are to stand in. */
+  order: number[];
+  /** Indices of the captures that stay hidden; every other capture goes on the line. */
+  hidden: ReadonlySet<number>;
+  /** What the marker shows after its own text, or nothing. */
+  suffix: string | undefined;
+};
+/**
+ * Decide which captures of a paragraph stay hidden, and what its marker shows.
+ *
+ * `markerShowsFields` says whether the paragraph's marker shows folded fields
+ * at all. When it does not, no capture is hidden.
+ *
+ * When it does, the captures it shows are the ones that open the paragraph:
+ * those ahead of the first thing the line shows, each field followed at most
+ * by its own tab. Text put in front of them was put in front of the body, not
+ * of the marker, so if the first capture no longer opens the paragraph, it
+ * and the captures that stand with it go back to the start. Every capture
+ * further in is on the line.
+ */
+declare const planListNumberFold: (items: readonly ListNumberFoldItem[], markerShowsFields: boolean) => ListNumberFoldPlan;
+/** The item a capture stands for, which shows on the line; any other item is itself. */
+declare const unfoldedListNumberContent: (content: document_d_exports.ParagraphContent) => document_d_exports.ParagraphContent;
+/**
+ * Bring `paragraph` to the one form the fold allows: the captures its marker
+ * shows stand at its start, every other capture is the field or the tab it
+ * stood for, and the marker shows exactly the fields still hidden behind it.
+ * A capture under a tracked change is never hidden.
+ */
+declare const normalizeFoldedListNumbers: (paragraph: document_d_exports.Paragraph) => void;
+//#endregion
+export { ListNumberFieldFold, ListNumberFoldItem, ListNumberFoldPlan, foldListNumberFields, foldedListNumberOf, isFoldedListNumber, isFoldedListNumberCapture, isListNumberField, isListNumberGapMarker, isTabOnlyRun, normalizeFoldedListNumbers, planListNumberFold, unfoldedListNumberContent };