@stll/folio-core 0.6.1 → 0.8.0

package/dist/docx/compatibility.js

@@ -1,77 +1,167 @@
+import { getFolioDocxCapability } from "./capabilities.js";
+import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
 //#region src/docx/compatibility.ts
-const COMPATIBLE_DOCX = {
-	canSafelyEdit: true,
-	reasons: [],
-	unsupportedContentCount: 0
+const resolveCompatibilityContext = (doc, options) => ({
+	host: options.host ?? "unknown",
+	profile: options.profile ?? doc.package.conformanceClass ?? DOCX_CONFORMANCE_CLASSES.UNKNOWN
+});
+const getCoverageState = (value, coveredValues) => {
+	if (value === "unknown") return "unknown";
+	return coveredValues.includes(value) ? "covered" : "unverified";
 };
-function inspectDocxCompatibility(doc) {
+const inspectDocxCompatibility = (doc, options = {}) => {
+	const context = resolveCompatibilityContext(doc, options);
 	const reasons = /* @__PURE__ */ new Set();
-	let unsupportedContentCount = 0;
-	const record = (reason) => {
-		reasons.add(reason);
-		unsupportedContentCount += 1;
+	const issues = [];
+	const record = (location) => {
+		const code = "opaqueDrawing";
+		const capability = getFolioDocxCapability(code);
+		reasons.add(code);
+		issues.push({
+			code,
+			capability,
+			coverage: {
+				host: getCoverageState(context.host, capability.hosts),
+				profile: getCoverageState(context.profile, capability.profiles)
+			},
+			location
+		});
 	};
-	inspectBlocks(doc.package.document.content, record);
-	for (const header of doc.package.headers?.values() ?? []) inspectHeaderFooter(header, record);
-	for (const footer of doc.package.footers?.values() ?? []) inspectHeaderFooter(footer, record);
-	for (const footnote of doc.package.footnotes ?? []) inspectBlocks(footnote.content, record);
-	for (const endnote of doc.package.endnotes ?? []) inspectBlocks(endnote.content, record);
-	if (unsupportedContentCount === 0) return COMPATIBLE_DOCX;
+	inspectBlocks(doc.package.document.content, {
+		part: { type: "document" },
+		path: "package.document.content",
+		record
+	});
+	for (const [relationshipId, header] of doc.package.headers?.entries() ?? []) inspectHeaderFooter(header, {
+		part: {
+			type: "header",
+			relationshipId
+		},
+		path: `package.headers.get(${JSON.stringify(relationshipId)}).content`,
+		record
+	});
+	for (const [relationshipId, footer] of doc.package.footers?.entries() ?? []) inspectHeaderFooter(footer, {
+		part: {
+			type: "footer",
+			relationshipId
+		},
+		path: `package.footers.get(${JSON.stringify(relationshipId)}).content`,
+		record
+	});
+	for (const footnote of doc.package.footnotes ?? []) inspectBlocks(footnote.content, {
+		part: {
+			type: "footnote",
+			id: footnote.id
+		},
+		path: `package.footnotes[id=${footnote.id}].content`,
+		record
+	});
+	for (const endnote of doc.package.endnotes ?? []) inspectBlocks(endnote.content, {
+		part: {
+			type: "endnote",
+			id: endnote.id
+		},
+		path: `package.endnotes[id=${endnote.id}].content`,
+		record
+	});
 	return {
-		canSafelyEdit: false,
+		schemaVersion: 1,
+		context,
+		canSafelyEdit: issues.length === 0,
+		issues,
 		reasons: Array.from(reasons),
-		unsupportedContentCount
+		unsupportedContentCount: issues.length
 	};
-}
-function inspectBlocks(blocks, record) {
-	for (const block of blocks) {
+};
+function inspectBlocks(blocks, context) {
+	for (const [blockIndex, block] of blocks.entries()) {
+		const blockPath = `${context.path}[${blockIndex}]`;
 		if (block.type === "paragraph") {
-			inspectParagraphContent(block.content, record);
+			inspectParagraphContent(block.content, {
+				...block.paraId === void 0 ? {} : { blockId: block.paraId },
+				part: context.part,
+				path: `${blockPath}.content`,
+				record: context.record
+			});
 			continue;
 		}
 		if (block.type === "table") {
-			for (const row of block.rows) for (const cell of row.cells) inspectBlocks(cell.content, record);
+			for (const [rowIndex, row] of block.rows.entries()) for (const [cellIndex, cell] of row.cells.entries()) inspectBlocks(cell.content, {
+				part: context.part,
+				path: `${blockPath}.rows[${rowIndex}].cells[${cellIndex}].content`,
+				record: context.record
+			});
 			continue;
 		}
-		inspectBlocks(block.content, record);
+		inspectBlocks(block.content, {
+			part: context.part,
+			path: `${blockPath}.content`,
+			record: context.record
+		});
 	}
 }
-function inspectHeaderFooter(headerFooter, record) {
-	inspectBlocks(headerFooter.content, record);
+function inspectHeaderFooter(headerFooter, context) {
+	inspectBlocks(headerFooter.content, context);
 }
-function inspectParagraphContent(content, record) {
-	for (const item of content) {
+function inspectParagraphContent(content, context) {
+	for (const [itemIndex, item] of content.entries()) {
+		const itemContext = {
+			...context,
+			path: `${context.path}[${itemIndex}]`
+		};
 		if (item.type === "run") {
-			inspectRun(item, record);
+			inspectRun(item, itemContext);
 			continue;
 		}
 		if (item.type === "hyperlink") {
-			inspectHyperlink(item, record);
+			inspectHyperlink(item, itemContext);
 			continue;
 		}
 		if (item.type === "inlineSdt") {
-			inspectParagraphContent(item.content, record);
+			inspectParagraphContent(item.content, {
+				...itemContext,
+				path: `${itemContext.path}.content`
+			});
 			continue;
 		}
 		if (item.type === "insertion" || item.type === "deletion" || item.type === "moveFrom" || item.type === "moveTo") {
-			inspectParagraphContent(item.content, record);
+			inspectParagraphContent(item.content, {
+				...itemContext,
+				path: `${itemContext.path}.content`
+			});
 			continue;
 		}
 		if (item.type === "simpleField") {
-			inspectParagraphContent(item.content, record);
+			inspectParagraphContent(item.content, {
+				...itemContext,
+				path: `${itemContext.path}.content`
+			});
 			continue;
 		}
 		if (item.type === "complexField") {
-			for (const run of item.fieldCode) inspectRun(run, record);
-			for (const run of item.fieldResult) inspectRun(run, record);
+			for (const [runIndex, run] of item.fieldCode.entries()) inspectRun(run, {
+				...itemContext,
+				path: `${itemContext.path}.fieldCode[${runIndex}]`
+			});
+			for (const [runIndex, run] of item.fieldResult.entries()) inspectRun(run, {
+				...itemContext,
+				path: `${itemContext.path}.fieldResult[${runIndex}]`
+			});
 		}
 	}
 }
-function inspectHyperlink(hyperlink, record) {
-	for (const child of hyperlink.children) if (child.type === "run") inspectRun(child, record);
+function inspectHyperlink(hyperlink, context) {
+	for (const [childIndex, child] of hyperlink.children.entries()) if (child.type === "run") inspectRun(child, {
+		...context,
+		path: `${context.path}.children[${childIndex}]`
+	});
 }
-function inspectRun(run, record) {
-	for (const content of run.content) if (content.type === "drawing" && content.rawXml) record("opaqueDrawing");
+function inspectRun(run, context) {
+	for (const [contentIndex, content] of run.content.entries()) if (content.type === "drawing" && content.rawXml) context.record({
+		...context.blockId === void 0 ? {} : { blockId: context.blockId },
+		part: context.part,
+		path: `${context.path}.content[${contentIndex}]`
+	});
 }
 //#endregion
 export { inspectDocxCompatibility };

package/dist/docx/conformance.d.ts

@@ -0,0 +1,6 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/docx/conformance.d.ts
+declare const detectDocxConformanceClass: (documentXml: string | null) => document_d_exports.DocxConformanceClass;
+//#endregion
+export { detectDocxConformanceClass };

package/dist/docx/conformance.js

@@ -0,0 +1,18 @@
+import { getLocalName, getNamespacePrefix, parseXmlDocument } from "./xmlParser.js";
+import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
+//#region src/docx/conformance.ts
+const STRICT_MAIN_NAMESPACE = "http://purl.oclc.org/ooxml/wordprocessingml/main";
+const TRANSITIONAL_MAIN_NAMESPACE = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+const detectDocxConformanceClass = (documentXml) => {
+	if (documentXml === null) return DOCX_CONFORMANCE_CLASSES.UNKNOWN;
+	const root = parseXmlDocument(documentXml);
+	if (root === null || getLocalName(root.name ?? "") !== "document") return DOCX_CONFORMANCE_CLASSES.UNKNOWN;
+	const prefix = getNamespacePrefix(root.name ?? "");
+	const namespaceAttribute = prefix === null ? "xmlns" : `xmlns:${prefix}`;
+	const namespace = root.attributes?.[namespaceAttribute];
+	if (namespace === STRICT_MAIN_NAMESPACE) return DOCX_CONFORMANCE_CLASSES.STRICT;
+	if (namespace === TRANSITIONAL_MAIN_NAMESPACE) return DOCX_CONFORMANCE_CLASSES.TRANSITIONAL;
+	return DOCX_CONFORMANCE_CLASSES.UNKNOWN;
+};
+//#endregion
+export { detectDocxConformanceClass };

package/dist/docx/ensureParaIds.d.ts

@@ -0,0 +1,29 @@
+//#region src/docx/ensureParaIds.d.ts
+declare const EnsureParaIdsError_base: import("better-result").TaggedErrorClass<"EnsureParaIdsError", {
+  message: string;
+  cause?: unknown;
+}>;
+/** A malformed or unsupported package prevented paragraph-ID normalization. */
+declare class EnsureParaIdsError extends EnsureParaIdsError_base {}
+/** Counts and normalized bytes returned by {@link ensureParaIds}. */
+type EnsureParaIdsResult = {
+  /** The normalized `.docx`; the input bytes verbatim when `alreadyComplete`. */docx: Uint8Array; /** Paragraphs that received a paraId (missing or all-zero before). */
+  assigned: number; /** Duplicate paraIds reassigned (the first occurrence keeps the id). */
+  deduplicated: number; /** True when the input already had full, unique coverage. */
+  alreadyComplete: boolean;
+};
+/** Controls mutation of package metadata that has security implications. */
+type EnsureParaIdsOptions = {
+  /**
+   * Allow normalization to invalidate existing OPC digital signatures.
+   * Callers must warn the user before opting in.
+   */
+  allowSignedPackageMutation?: boolean;
+};
+/**
+ * Backfill `w14:paraId` on every paragraph of a `.docx` buffer. All package,
+ * XML, and compression failures are surfaced as {@link EnsureParaIdsError}.
+ */
+declare const ensureParaIds: (docx: Uint8Array | ArrayBuffer, options?: EnsureParaIdsOptions) => Promise<EnsureParaIdsResult>;
+//#endregion
+export { EnsureParaIdsError, EnsureParaIdsOptions, EnsureParaIdsResult, ensureParaIds };

package/dist/docx/ensureParaIds.js

@@ -0,0 +1,423 @@
+import { isXmlNameBoundary } from "./selectiveXmlPatch.js";
+import { deterministicHexId } from "../utils/hexId.js";
+import { TaggedError } from "better-result";
+import JSZip from "jszip";
+//#region src/docx/ensureParaIds.ts
+/**
+* Headless `w14:paraId` normalization for a `.docx` buffer.
+*
+* Word 2010+ stamps every paragraph with a `w14:paraId`, but Google Docs
+* exports, LibreOffice, python-docx, and docx4j generally do not. Paragraphs
+* without one are invisible to everything that anchors on paraId (block ids,
+* comment threads, AI-edit targeting) and fall back to positional `seq-NNNN`
+* ids that renumber after structural edits. Hosts call {@link ensureParaIds}
+* once at ingest so every stored version has full id coverage before any
+* snapshot or external anchor is created.
+*
+* IDs remain stable in folio and identity-preserving DOCX round-trips.
+* Microsoft Word can establish a new `w14:docId` and replace all paragraph
+* IDs on its first save of a non-Word-produced package; callers that ingest
+* such an externally edited version must normalize it again and cannot assume
+* the pre-save IDs still match.
+*
+* The pass patches part XML in place (string splices, no model round-trip),
+* 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`,
+*   `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
+*   own deterministic paraIds at save time (see `commentSerializer`) and is
+*   left untouched; its ids still count toward uniqueness.
+* - Paragraphs inside `mc:Fallback` are never modified: Word regenerates the
+*   fallback branch (duplicating the `mc:Choice` ids) on save, so stamping or
+*   deduplicating there would churn on every Word round-trip.
+* - Existing ids are preserved. Only three cases get a fresh id: a missing
+*   `paraId`, the reserved all-zero value (Word reads `00000000` as "no id"),
+*   and a duplicate of an id already seen earlier in the scan (first
+*   occurrence keeps it — the same rule `ParaIdAllocatorExtension` applies in
+*   the editor). `w14:textId` is written alongside a newly minted `paraId`
+*   (same value) and never touched otherwise; it is a text-revision marker,
+*   not identity.
+* - Fresh ids are deterministic (`deterministicHexId` over document content,
+*   part path, and paragraph ordinal), so the pass is a pure function of the
+*   input bytes: retrying an ingest produces identical output.
+* - Each patched part's root element gets `xmlns:w14` / `xmlns:mc`
+*   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.
+* - Idempotent: a document that already has full coverage is returned as the
+*   original bytes, untouched (`alreadyComplete: true`).
+* - 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.
+*/
+/** 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";
+const MC_NAMESPACE_URI = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+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 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 PARAGRAPH_OPEN = "<w:p";
+const FALLBACK_OPEN = "<mc:Fallback";
+const FALLBACK_CLOSE = "</mc:Fallback>";
+const OPAQUE_XML_REGIONS = [
+	{
+		open: "<!--",
+		close: "-->"
+	},
+	{
+		open: "<![CDATA[",
+		close: "]]>"
+	},
+	{
+		open: "<?",
+		close: "?>"
+	}
+];
+/**
+* The parser accepts the `w:` fallback prefix for paraId, and comment parts
+* link replies via `w15:paraId` — all three count toward uniqueness.
+*/
+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 applySplices = (xml, edits) => {
+	const ordered = [...edits].sort((a, b) => b.start - a.start);
+	let result = xml;
+	for (const { start, end, text } of ordered) result = result.slice(0, start) + text + result.slice(end);
+	return result;
+};
+const createEnsureParaIdsError = (message, cause) => new EnsureParaIdsError({
+	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());
+	}
+};
+const collectFallbackParaIds = (xml, partPath, into) => {
+	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;
+		}
+		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 (fallbackDepth === 0 || !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}`);
+		const id = OPEN_TAG_PARA_ID_PATTERN.exec(xml.slice(tagStart, tagEnd + 1))?.groups?.["id"];
+		if (id) into.add(id.toUpperCase());
+		pos = tagEnd + 1;
+	}
+};
+/**
+* Deterministic fresh id for the paragraph at `ordinal` in `partPath`,
+* salted past collisions with any id anywhere in the document.
+*/
+const mintParaId = (context, partPath, ordinal) => {
+	const seed = `${context.docKey}:${partPath}:${ordinal}`;
+	let id = deterministicHexId(seed);
+	for (let salt = 1; context.taken.has(id); salt += 1) id = deterministicHexId(`${seed}:${salt}`);
+	context.taken.add(id);
+	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.
+*/
+const scanPart = (xml, partPath, context, seen) => {
+	const edits = [];
+	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;
+		ordinal += 1;
+		const openTag = xml.slice(tagStart, tagEnd + 1);
+		const paraIdMatch = OPEN_TAG_PARA_ID_PATTERN.exec(openTag);
+		if (!paraIdMatch) {
+			const id = mintParaId(context, partPath, ordinal);
+			const insertAt = tagStart + 4;
+			const textIdMatch = OPEN_TAG_TEXT_ID_PATTERN.exec(openTag);
+			if (textIdMatch) {
+				edits.push({
+					start: insertAt,
+					end: insertAt,
+					text: ` w14:paraId="${id}"`
+				});
+				const range = attributeValueRange(textIdMatch, tagStart, "id");
+				edits.push({
+					...range,
+					text: id
+				});
+			} else edits.push({
+				start: insertAt,
+				end: insertAt,
+				text: ` w14:paraId="${id}" w14:textId="${id}"`
+			});
+			assigned += 1;
+			seen.add(id);
+			continue;
+		}
+		const value = paraIdMatch.groups["id"].toUpperCase();
+		const unassigned = RESERVED_ZERO_ID_PATTERN.test(value);
+		if (!unassigned && !seen.has(value)) {
+			seen.add(value);
+			continue;
+		}
+		const id = mintParaId(context, partPath, ordinal);
+		edits.push({
+			...attributeValueRange(paraIdMatch, tagStart, "id"),
+			text: id
+		});
+		const textIdMatch = OPEN_TAG_TEXT_ID_PATTERN.exec(openTag);
+		if (textIdMatch) edits.push({
+			...attributeValueRange(textIdMatch, tagStart, "id"),
+			text: id
+		});
+		else {
+			const insertAt = tagStart + 4;
+			edits.push({
+				start: insertAt,
+				end: insertAt,
+				text: ` w14:textId="${id}"`
+			});
+		}
+		if (unassigned) assigned += 1;
+		else deduplicated += 1;
+		seen.add(id);
+	}
+	return {
+		edits,
+		assigned,
+		deduplicated
+	};
+};
+/**
+* Splice edits ensuring the part's root element declares `xmlns:w14` /
+* `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) => {
+	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);
+	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);
+	if (ignorable) {
+		const tokens = ignorable.groups["value"].split(/\s+/u).filter((token) => token.length > 0);
+		if (!tokens.includes(MC_IGNORABLE_W14)) {
+			const { end } = attributeValueRange(ignorable, rootStart, "value");
+			const text = tokens.length === 0 ? MC_IGNORABLE_W14 : ` ${MC_IGNORABLE_W14}`;
+			edits.push({
+				start: end,
+				end,
+				text
+			});
+		}
+	} else declarations.push(` mc:Ignorable="${MC_IGNORABLE_W14}"`);
+	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("")
+		});
+	}
+	return edits;
+};
+/** 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);
+const hasDigitalSignatureParts = (zip) => Object.values(zip.files).some(({ dir, name }) => !dir && name.toLowerCase().startsWith(DIGITAL_SIGNATURE_PART_PREFIX));
+/**
+* Backfill `w14:paraId` on every paragraph of a `.docx` buffer. See the
+* module doc for the exact contract. Throws {@link EnsureParaIdsError} when
+* the buffer is not a WordprocessingML package or a part is malformed.
+*/
+const ensureParaIdsInternal = async (docx, options) => {
+	const zip = await JSZip.loadAsync(docx);
+	const xmlPartNames = [];
+	zip.forEach((relativePath, entry) => {
+		const lower = relativePath.toLowerCase();
+		if (!entry.dir && lower.startsWith("word/") && lower.endsWith(".xml")) xmlPartNames.push(relativePath);
+	});
+	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 partTexts = /* @__PURE__ */ new Map();
+	for (const name of xmlPartNames) {
+		const entry = zip.file(name);
+		if (entry) partTexts.set(name, await entry.async("text"));
+	}
+	const taken = /* @__PURE__ */ new Set();
+	for (const text of partTexts.values()) collectExistingParaIds(text, taken);
+	const context = {
+		taken,
+		docKey: deterministicHexId(partTexts.get(documentPartName))
+	};
+	const targetParts = [documentPartName, ...xmlPartNames.filter((name) => name !== documentPartName && isTargetPart(name)).sort((a, b) => a.localeCompare(b))];
+	const seen = /* @__PURE__ */ new Set();
+	for (const [partPath, xml] of partTexts) if (isTargetPart(partPath)) collectFallbackParaIds(xml, partPath, 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);
+		if (scan.edits.length === 0) continue;
+		assigned += scan.assigned;
+		deduplicated += scan.deduplicated;
+		updates.set(partPath, applySplices(xml, [...scan.edits, ...ensureRootNamespaces(xml, partPath)]));
+	}
+	if (updates.size === 0) return {
+		docx: toUint8Array(docx),
+		assigned: 0,
+		deduplicated: 0,
+		alreadyComplete: true
+	};
+	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.");
+	for (const [partPath, content] of updates) zip.file(partPath, content, {
+		compression: "DEFLATE",
+		compressionOptions: { level: 6 }
+	});
+	return {
+		docx: await zip.generateAsync({
+			type: "uint8array",
+			compression: "DEFLATE",
+			compressionOptions: { level: 6 }
+		}),
+		assigned,
+		deduplicated,
+		alreadyComplete: false
+	};
+};
+/**
+* Backfill `w14:paraId` on every paragraph of a `.docx` buffer. All package,
+* XML, and compression failures are surfaced as {@link EnsureParaIdsError}.
+*/
+const ensureParaIds = async (docx, options = {}) => {
+	try {
+		return await ensureParaIdsInternal(docx, options);
+	} catch (error) {
+		if (error instanceof EnsureParaIdsError) throw error;
+		const message = error instanceof Error ? error.message : String(error);
+		throw createEnsureParaIdsError(`Failed to normalize paragraph IDs: ${message}`, error);
+	}
+};
+//#endregion
+export { EnsureParaIdsError, ensureParaIds };