@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/docx/rezip.js

@@ -0,0 +1,1194 @@
+import { applyReplyThreadMarkers } from "./commentReplyMarkers.js";
+import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
+import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
+import { assertValidFolioDocumentModel } from "./modelValidation.js";
+import { parseNumbering } from "./numberingParser.js";
+import { buildPatchedNoteXml, buildPatchedNumberingXml, collectChangedNumberingDefs, collectParaIds, extractParagraphXml } from "./selectiveXmlPatch.js";
+import { escapeXml } from "./serializer/xmlUtils.js";
+import { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
+import { serializeDocument } from "./serializer/documentSerializer.js";
+import { serializeHeaderFooter } from "./serializer/headerFooterSerializer.js";
+import { serializeEndnotes, serializeFootnotes } from "./serializer/noteSerializer.js";
+import { serializeNumberingXml } from "./serializer/numberingSerializer.js";
+import { isPreservableDocxEntry } from "./unzip.js";
+import { panic } from "better-result";
+import JSZip from "jszip";
+//#region src/docx/rezip.ts
+/**
+* DOCX Repacker - Repack modified document into valid DOCX
+*
+* Takes a Document with modified content and creates a new DOCX file
+* by updating document.xml while preserving all other files from
+* the original ZIP archive.
+*
+* This ensures round-trip fidelity:
+* - styles.xml, theme1.xml, fontTable.xml remain untouched
+* - Media files preserved
+* - Relationships preserved
+* - Only document.xml is updated with new content
+*
+* OOXML Package Structure:
+* - [Content_Types].xml - Content type declarations
+* - _rels/.rels - Package relationships
+* - word/document.xml - Main document (modified)
+* - word/styles.xml - Styles (preserved)
+* - word/theme/theme1.xml - Theme (preserved)
+* - word/numbering.xml - Numbering (preserved)
+* - word/fontTable.xml - Font table (preserved)
+* - word/settings.xml - Settings (preserved)
+* - word/header*.xml - Headers (preserved)
+* - word/footer*.xml - Footers (preserved)
+* - word/footnotes.xml - Footnotes (preserved)
+* - word/endnotes.xml - Endnotes (preserved)
+* - word/media/* - Media files (preserved)
+* - word/_rels/document.xml.rels - Document relationships (preserved)
+* - docProps/* - Document properties (preserved)
+*/
+var DocxPackageFidelityError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DocxPackageFidelityError";
+	}
+};
+/**
+* Find the highest rId number in a relationships XML string.
+*/
+function findMaxRId(relsXml) {
+	let maxId = 0;
+	for (const match of relsXml.matchAll(/Id="rId(?<id>\d+)"/gu)) {
+		const id = Number.parseInt(match.groups["id"], 10);
+		if (id > maxId) maxId = id;
+	}
+	return maxId;
+}
+const countDocumentSections = (xml) => Array.from(xml.matchAll(/<w:sectPr\b/gu)).length;
+const extractHeaderFooterReferences = (xml) => {
+	const references = [];
+	for (const match of xml.matchAll(/<w:(?<element>headerReference|footerReference)\b[^>]*>/gu)) {
+		const tag = match[0];
+		const type = /\bw:type="(?<type>[^"]+)"/u.exec(tag)?.groups?.["type"] ?? "default";
+		const rId = /\br:id="(?<rId>[^"]+)"/u.exec(tag)?.groups?.["rId"];
+		const element = match.groups?.["element"];
+		if (!rId || element !== "headerReference" && element !== "footerReference") continue;
+		references.push({
+			element,
+			type,
+			rId
+		});
+	}
+	return references;
+};
+const hasParsedHeaderFooterPart = (doc, ref) => {
+	return (ref.element === "headerReference" ? doc.package.headers : doc.package.footers)?.has(ref.rId) ?? false;
+};
+function assertDocumentPackageFidelity(originalDocumentXml, serializedDocumentXml, doc) {
+	const originalSectionCount = countDocumentSections(originalDocumentXml);
+	if (countDocumentSections(serializedDocumentXml) < originalSectionCount) throw new DocxPackageFidelityError("Full DOCX repack would drop section properties. Use selective patching instead.");
+	const serializedRefs = new Set(extractHeaderFooterReferences(serializedDocumentXml).map((ref) => `${ref.element}:${ref.type}:${ref.rId}`));
+	if (extractHeaderFooterReferences(originalDocumentXml).filter((ref) => hasParsedHeaderFooterPart(doc, ref) && !serializedRefs.has(`${ref.element}:${ref.type}:${ref.rId}`)).length > 0) throw new DocxPackageFidelityError("Full DOCX repack would drop header/footer references. Use selective patching instead.");
+}
+async function serializeCommentsToZip(doc, zip, compressionLevel) {
+	const comments = doc.package.document.comments ?? [];
+	const hadCommentsFile = zip.file("word/comments.xml") !== null;
+	if (comments.length === 0 && !hadCommentsFile) return;
+	ensureThreadedCommentParaIds(comments);
+	const commentsXml = serializeComments(comments);
+	zip.file("word/comments.xml", commentsXml, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+	await ensureCommentsContentType(zip, compressionLevel);
+	await ensureCommentsRelationship(zip, compressionLevel);
+	await syncCommentsExtendedPart(comments, zip, compressionLevel);
+}
+/**
+* Bring `word/commentsExtended.xml` and its packaging (content-type override +
+* relationship) in line with the model: write the part when there is thread /
+* resolved state to record, or remove the part AND its override AND its
+* relationship together when there is none. Managing all three consistently
+* keeps the package valid (a dangling override or a relationship pointing at a
+* removed part triggers Word's repair prompt). The reply-thread markers in
+* `document.xml` are synthesized separately (see {@link applyReplyThreadMarkers}).
+*/
+async function syncCommentsExtendedPart(comments, zip, compressionLevel) {
+	const xml = serializeCommentsExtended(comments);
+	const existing = findZipEntryCaseInsensitive(zip, COMMENTS_EXTENDED_PART_LOWER);
+	if (!xml) {
+		if (!existing) return;
+		zip.remove(existing.name);
+		await transformPackagingFile(zip, "[Content_Types].xml", removeCommentsExtendedOverride, compressionLevel);
+		await transformPackagingFile(zip, "word/_rels/document.xml.rels", removeCommentsExtendedRelationship, compressionLevel);
+		return;
+	}
+	zip.file(existing?.name ?? "word/commentsExtended.xml", xml, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+	await transformPackagingFile(zip, "[Content_Types].xml", addCommentsExtendedOverride, compressionLevel);
+	await transformPackagingFile(zip, "word/_rels/document.xml.rels", addCommentsExtendedRelationship, compressionLevel);
+}
+/** Read a packaging file, apply a pure transform, and write it back if it changed. */
+async function transformPackagingFile(zip, path, transform, compressionLevel) {
+	const file = zip.file(path);
+	if (!file) return;
+	const xml = await file.async("text");
+	const next = transform(xml);
+	if (next !== xml) zip.file(path, next, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+function findZipEntryCaseInsensitive(zip, lowerPath) {
+	const direct = zip.file(lowerPath);
+	if (direct) return direct;
+	for (const [path, file] of Object.entries(zip.files)) if (!file.dir && path.toLowerCase() === lowerPath) return file;
+	return null;
+}
+const EMPTY_RELS_XML = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\"></Relationships>";
+function headerFooterFilename(target) {
+	return target.startsWith("/") ? target.slice(1) : `word/${target}`;
+}
+/**
+* The relationships part for a header/footer. A part at `<dir>/<name>` keeps its
+* rels at `<dir>/_rels/<name>.rels` — e.g. `word/headers/header1.xml` ->
+* `word/headers/_rels/header1.xml.rels`, not a flattened `word/_rels/...`.
+*/
+function headerFooterRelsPath(target) {
+	const partPath = headerFooterFilename(target);
+	const lastSlash = partPath.lastIndexOf("/");
+	const directory = lastSlash === -1 ? "" : partPath.slice(0, lastSlash);
+	const name = lastSlash === -1 ? partPath : partPath.slice(lastSlash + 1);
+	return `${directory ? `${directory}/` : ""}_rels/${name}.rels`;
+}
+/**
+* Express an absolute package path as a relationship target relative to the
+* part at `partPath`. e.g. media `word/media/image1.png` for a part at
+* `word/headers/header2.xml` -> `../media/image1.png` (and `media/image1.png`
+* for a part at the `word/` root). The inverse of `resolveRelativePath`.
+*/
+function relativeTargetForPart(partPath, absoluteTarget) {
+	const lastSlash = partPath.lastIndexOf("/");
+	const fromDir = lastSlash === -1 ? [] : partPath.slice(0, lastSlash).split("/");
+	const to = absoluteTarget.split("/");
+	let shared = 0;
+	while (shared < fromDir.length && shared < to.length - 1 && fromDir[shared] === to[shared]) shared += 1;
+	return `${"../".repeat(fromDir.length - shared)}${to.slice(shared).join("/")}`;
+}
+function collectImageParts(doc) {
+	const parts = [{
+		relsPath: "word/_rels/document.xml.rels",
+		blocks: doc.package.document.content
+	}];
+	const rels = doc.package.relationships;
+	if (!rels) return parts;
+	const addHeaderFooterParts = (map, type) => {
+		if (!map) return;
+		for (const [rId, headerFooter] of map.entries()) {
+			const rel = rels.get(rId);
+			if (!rel || rel.type !== type || !rel.target) continue;
+			parts.push({
+				relsPath: headerFooterRelsPath(rel.target),
+				blocks: headerFooter.content
+			});
+		}
+	};
+	addHeaderFooterParts(doc.package.headers, RELATIONSHIP_TYPES.header);
+	addHeaderFooterParts(doc.package.footers, RELATIONSHIP_TYPES.footer);
+	return parts;
+}
+async function readRelsOrStub(zip, relsPath) {
+	const file = zip.file(relsPath);
+	return (file ? await file.async("text") : EMPTY_RELS_XML).replace(/<Relationships(?<attrs>[^>]*)\/>/u, "<Relationships$<attrs>></Relationships>");
+}
+function findMaxImageNum(zip) {
+	let maxImageNum = 0;
+	zip.forEach((relativePath) => {
+		const m = /^word\/media\/image(?<num>\d+)\./u.exec(relativePath);
+		if (m) {
+			const num = Number.parseInt(m.groups["num"], 10);
+			if (num > maxImageNum) maxImageNum = num;
+		}
+	});
+	return maxImageNum;
+}
+async function registerImageExtensions(zip, extensions, compressionLevel) {
+	if (extensions.size === 0) return;
+	const ctFile = zip.file("[Content_Types].xml");
+	if (!ctFile) return;
+	let ctXml = await ctFile.async("text");
+	let changed = false;
+	for (const ext of extensions) {
+		if (ctXml.includes(`Extension="${ext}"`)) continue;
+		const contentType = getContentTypeForExtension(ext, "");
+		ctXml = ctXml.replace("</Types>", `<Default Extension="${ext}" ContentType="${contentType}"/></Types>`);
+		changed = true;
+	}
+	if (!changed) return;
+	zip.file("[Content_Types].xml", ctXml, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+/**
+* Collect all newly inserted images with data-URL src from the document content.
+* Existing DOCX images may also have a resolved data URL for preview; those must
+* continue to reference their original media part. Editor-created images use a
+* synthetic rId until they are assigned a real DOCX relationship here.
+*/
+const SYNTHETIC_IMAGE_RID_PREFIX = "rId_img_";
+const isNewDataUrlImage = (image) => image.src?.startsWith("data:") && (!image.rId || image.rId.startsWith(SYNTHETIC_IMAGE_RID_PREFIX));
+function collectNewImages(blocks) {
+	const images = [];
+	const collectFromRun = (run) => {
+		for (const c of run.content) if (c.type === "drawing" && c.image && isNewDataUrlImage(c.image)) images.push(c.image);
+	};
+	for (const block of blocks) if (block.type === "paragraph") {
+		for (const item of block.content) if (item.type === "run") collectFromRun(item);
+		else if (item.type === "insertion" || item.type === "deletion" || item.type === "moveFrom" || item.type === "moveTo") {
+			for (const sub of item.content) if (sub.type === "run") collectFromRun(sub);
+		}
+	} else if (block.type === "table") for (const row of block.rows) for (const cell of row.cells) images.push(...collectNewImages(cell.content));
+	return images;
+}
+/** Map MIME type to file extension (inverse of getContentTypeForExtension) */
+const MIME_TO_EXT = {
+	"image/png": "png",
+	"image/jpeg": "jpeg",
+	"image/gif": "gif",
+	"image/bmp": "bmp",
+	"image/tiff": "tiff",
+	"image/webp": "webp",
+	"image/svg+xml": "svg"
+};
+/**
+* Decode a data URL to binary ArrayBuffer and file extension.
+*/
+function decodeDataUrl(dataUrl) {
+	const match = /^data:(?<mime>[^;]+);base64,(?<data>.+)$/u.exec(dataUrl);
+	if (!match) panic("Invalid data URL");
+	const binary = atob(match.groups["data"]);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.codePointAt(i) ?? 0;
+	return {
+		data: bytes.buffer,
+		extension: MIME_TO_EXT[match.groups["mime"]] ?? "png"
+	};
+}
+/**
+* Process newly inserted images: add binary data to ZIP, create relationships,
+* update content types, and rewrite rIds in the document model so the serializer
+* outputs correct references.
+*
+* Mutates the images' rId fields in-place.
+*/
+async function processNewImages(parts, zip, compressionLevel) {
+	let maxImageNum = findMaxImageNum(zip);
+	const extensionsAdded = /* @__PURE__ */ new Set();
+	for (const { relsPath, blocks } of parts) {
+		const newImages = collectNewImages(blocks);
+		if (newImages.length === 0) continue;
+		const relsXml = await readRelsOrStub(zip, relsPath);
+		let maxId = findMaxRId(relsXml);
+		const relEntries = [];
+		const partPath = relsPath.replace("/_rels/", "/").replace(/\.rels$/u, "");
+		for (const image of newImages) {
+			if (!image.src) continue;
+			const { data, extension } = decodeDataUrl(image.src);
+			maxImageNum++;
+			maxId++;
+			const mediaPath = `word/media/${`image${maxImageNum}.${extension}`}`;
+			const newRId = `rId${maxId}`;
+			zip.file(mediaPath, data, {
+				compression: "DEFLATE",
+				compressionOptions: { level: compressionLevel }
+			});
+			relEntries.push(`<Relationship Id="${newRId}" Type="${RELATIONSHIP_TYPES.image}" Target="${escapeXml(relativeTargetForPart(partPath, mediaPath))}"/>`);
+			extensionsAdded.add(extension);
+			image.rId = newRId;
+		}
+		if (relEntries.length > 0) {
+			const updatedRelsXml = relsXml.replace("</Relationships>", `${relEntries.join("")}</Relationships>`);
+			zip.file(relsPath, updatedRelsXml, {
+				compression: "DEFLATE",
+				compressionOptions: { level: compressionLevel }
+			});
+		}
+	}
+	await registerImageExtensions(zip, extensionsAdded, compressionLevel);
+}
+/**
+* Collect all hyperlinks that have an href but no rId from block content.
+* These are newly created hyperlinks that need relationship entries.
+*/
+function collectHyperlinksWithoutRId(blocks) {
+	const hyperlinks = [];
+	for (const block of blocks) if (block.type === "paragraph") {
+		for (const item of block.content) if (item.type === "hyperlink" && item.href && !item.rId && !item.anchor) hyperlinks.push(item);
+	} else if (block.type === "table") for (const row of block.rows) for (const cell of row.cells) hyperlinks.push(...collectHyperlinksWithoutRId(cell.content));
+	return hyperlinks;
+}
+/**
+* Process newly created hyperlinks: assign rIds and add relationship entries.
+* Mutates the hyperlinks' rId fields in-place.
+*/
+async function processNewHyperlinks(newHyperlinks, zip, compressionLevel) {
+	if (newHyperlinks.length === 0) return;
+	const relsPath = "word/_rels/document.xml.rels";
+	const relsFile = zip.file(relsPath);
+	if (!relsFile) return;
+	let relsXml = await relsFile.async("text");
+	let maxId = findMaxRId(relsXml);
+	const relEntries = [];
+	for (const hyperlink of newHyperlinks) {
+		maxId++;
+		const newRId = `rId${maxId}`;
+		if (!hyperlink.href) continue;
+		relEntries.push(`<Relationship Id="${newRId}" Type="${RELATIONSHIP_TYPES.hyperlink}" Target="${escapeXml(hyperlink.href)}" TargetMode="External"/>`);
+		hyperlink.rId = newRId;
+	}
+	if (relEntries.length > 0) {
+		relsXml = relsXml.replace("</Relationships>", `${relEntries.join("")}</Relationships>`);
+		zip.file(relsPath, relsXml, {
+			compression: "DEFLATE",
+			compressionOptions: { level: compressionLevel }
+		});
+	}
+}
+/**
+* Repack a Document into a valid DOCX file
+*
+* @param doc - Document with modified content
+* @param options - Optional repack options
+* @returns Promise resolving to DOCX as ArrayBuffer
+* @throws {Error} if document has no original buffer for round-trip
+*/
+async function repackDocx(doc, options = {}) {
+	if (!doc.originalBuffer) panic("Cannot repack document: no original buffer for round-trip. Use createDocx() for new documents.");
+	const { compressionLevel = 6, updateModifiedDate = true, modifiedBy } = options;
+	const exportDocument = doc;
+	const originalZip = await JSZip.loadAsync(doc.originalBuffer);
+	const newZip = new JSZip();
+	for (const [path, file] of Object.entries(originalZip.files)) {
+		if (file.dir) {
+			newZip.folder(path.replace(/\/$/u, ""));
+			continue;
+		}
+		if (!isPreservableDocxEntry(path)) continue;
+		const content = await file.async("arraybuffer");
+		newZip.file(path, content, {
+			compression: "DEFLATE",
+			compressionOptions: { level: compressionLevel }
+		});
+	}
+	await materializeNewHeaderFooterParts(exportDocument, newZip, compressionLevel);
+	await processNewImages(collectImageParts(exportDocument), newZip, compressionLevel);
+	await processNewHyperlinks(collectHyperlinksWithoutRId(exportDocument.package.document.content), newZip, compressionLevel);
+	assertValidFolioDocumentModel(exportDocument, "Cannot repack invalid DOCX document model");
+	applyReplyThreadMarkers(exportDocument);
+	const documentXml = serializeDocument(exportDocument);
+	const originalDocumentXml = await originalZip.file("word/document.xml")?.async("text");
+	if (originalDocumentXml) assertDocumentPackageFidelity(originalDocumentXml, documentXml, exportDocument);
+	newZip.file("word/document.xml", documentXml, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+	await rebindWatermarkRelIds(exportDocument, newZip, compressionLevel);
+	serializeHeadersFootersToZip(exportDocument, newZip, compressionLevel);
+	await serializeNotesToZip(exportDocument, originalZip, newZip, compressionLevel);
+	await serializeNumberingIntoZip(exportDocument, originalZip, newZip, compressionLevel);
+	await serializeCommentsToZip(exportDocument, newZip, compressionLevel);
+	if (updateModifiedDate) {
+		const corePropsPath = "docProps/core.xml";
+		const corePropsFile = originalZip.file(corePropsPath);
+		if (corePropsFile) {
+			const updatedCoreProps = updateCoreProperties(await corePropsFile.async("text"), {
+				updateModifiedDate,
+				...modifiedBy !== void 0 ? { modifiedBy } : {}
+			});
+			newZip.file(corePropsPath, updatedCoreProps, {
+				compression: "DEFLATE",
+				compressionOptions: { level: compressionLevel }
+			});
+		}
+	}
+	return await newZip.generateAsync({
+		type: "arraybuffer",
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+/**
+* Repack a Document using raw content for more control
+*
+* @param doc - Document with modified content
+* @param rawContent - Original raw content from unzipDocx
+* @param options - Optional repack options
+* @returns Promise resolving to DOCX as ArrayBuffer
+*/
+async function repackDocxFromRaw(doc, rawContent, options = {}) {
+	const { compressionLevel = 6, updateModifiedDate = true, modifiedBy } = options;
+	const exportDocument = doc;
+	const newZip = new JSZip();
+	for (const [path, file] of Object.entries(rawContent.originalZip.files)) {
+		if (file.dir) {
+			newZip.folder(path.replace(/\/$/u, ""));
+			continue;
+		}
+		if (!isPreservableDocxEntry(path)) continue;
+		const content = await file.async("arraybuffer");
+		newZip.file(path, content, {
+			compression: "DEFLATE",
+			compressionOptions: { level: compressionLevel }
+		});
+	}
+	await materializeNewHeaderFooterParts(exportDocument, newZip, compressionLevel);
+	await processNewImages(collectImageParts(exportDocument), newZip, compressionLevel);
+	await processNewHyperlinks(collectHyperlinksWithoutRId(exportDocument.package.document.content), newZip, compressionLevel);
+	assertValidFolioDocumentModel(exportDocument, "Cannot repack invalid DOCX document model");
+	applyReplyThreadMarkers(exportDocument);
+	const documentXml = serializeDocument(exportDocument);
+	if (rawContent.documentXml) assertDocumentPackageFidelity(rawContent.documentXml, documentXml, exportDocument);
+	newZip.file("word/document.xml", documentXml, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+	await rebindWatermarkRelIds(exportDocument, newZip, compressionLevel);
+	serializeHeadersFootersToZip(exportDocument, newZip, compressionLevel);
+	await serializeNotesToZip(exportDocument, rawContent.originalZip, newZip, compressionLevel);
+	await serializeNumberingIntoZip(exportDocument, rawContent.originalZip, newZip, compressionLevel);
+	await serializeCommentsToZip(exportDocument, newZip, compressionLevel);
+	if (updateModifiedDate && rawContent.corePropsXml) {
+		const updatedCoreProps = updateCoreProperties(rawContent.corePropsXml, {
+			updateModifiedDate,
+			...modifiedBy !== void 0 ? { modifiedBy } : {}
+		});
+		newZip.file("docProps/core.xml", updatedCoreProps, {
+			compression: "DEFLATE",
+			compressionOptions: { level: compressionLevel }
+		});
+	}
+	return await newZip.generateAsync({
+		type: "arraybuffer",
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+const COMMENTS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
+const COMMENTS_EXTENDED_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
+const COMMENTS_EXTENDED_PART = "word/commentsExtended.xml";
+const COMMENTS_EXTENDED_PART_LOWER = "word/commentsextended.xml";
+function addCommentsExtendedOverride(contentTypesXml) {
+	if (contentTypesXml.toLowerCase().includes("/word/commentsextended.xml")) return contentTypesXml;
+	return contentTypesXml.replace("</Types>", `<Override PartName="/word/commentsExtended.xml" ContentType="${COMMENTS_EXTENDED_CONTENT_TYPE}"/></Types>`);
+}
+function removeCommentsExtendedOverride(contentTypesXml) {
+	return contentTypesXml.replace(/<Override\b[^>]*commentsExtended\.xml[^>]*\/>/giu, "");
+}
+function addCommentsExtendedRelationship(relsXml) {
+	if (relsXml.toLowerCase().includes("commentsextended.xml")) return relsXml;
+	const newRId = `rId${findMaxRId(relsXml) + 1}`;
+	return relsXml.replace("</Relationships>", `<Relationship Id="${newRId}" Type="${RELATIONSHIP_TYPES.commentsExtended}" Target="commentsExtended.xml"/></Relationships>`);
+}
+function removeCommentsExtendedRelationship(relsXml) {
+	return relsXml.replace(/<Relationship\b[^>]*commentsExtended\.xml[^>]*\/>/giu, "");
+}
+/**
+* Ensure [Content_Types].xml contains an Override for word/comments.xml.
+* If the document already had comments, this is a no-op.
+*/
+async function ensureCommentsContentType(zip, compressionLevel) {
+	const ctFile = zip.file("[Content_Types].xml");
+	if (!ctFile) return;
+	let ctXml = await ctFile.async("text");
+	if (ctXml.includes("/word/comments.xml")) return;
+	ctXml = ctXml.replace("</Types>", `<Override PartName="/word/comments.xml" ContentType="${COMMENTS_CONTENT_TYPE}"/></Types>`);
+	zip.file("[Content_Types].xml", ctXml, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+/**
+* Ensure word/_rels/document.xml.rels contains a Relationship for comments.xml.
+* If the document already had comments, this is a no-op.
+*/
+async function ensureCommentsRelationship(zip, compressionLevel) {
+	const relsPath = "word/_rels/document.xml.rels";
+	const relsFile = zip.file(relsPath);
+	if (!relsFile) return;
+	let relsXml = await relsFile.async("text");
+	if (relsXml.includes("comments.xml")) return;
+	const newRId = `rId${findMaxRId(relsXml) + 1}`;
+	relsXml = relsXml.replace("</Relationships>", `<Relationship Id="${newRId}" Type="${RELATIONSHIP_TYPES.comments}" Target="comments.xml"/></Relationships>`);
+	zip.file(relsPath, relsXml, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+/**
+* Update only document.xml in a DOCX buffer (minimal changes)
+*
+* @param originalBuffer - Original DOCX as ArrayBuffer
+* @param newDocumentXml - New document.xml content
+* @param options - Optional repack options
+* @returns Promise resolving to DOCX as ArrayBuffer
+*/
+async function updateDocumentXml(originalBuffer, newDocumentXml, options = {}) {
+	const { compressionLevel = 6 } = options;
+	const zip = await JSZip.loadAsync(originalBuffer);
+	zip.file("word/document.xml", newDocumentXml, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+	return zip.generateAsync({
+		type: "arraybuffer",
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+/**
+* Update a specific XML file in a DOCX buffer
+*
+* @param originalBuffer - Original DOCX as ArrayBuffer
+* @param path - Path within the ZIP (e.g., "word/styles.xml")
+* @param content - New XML content
+* @param options - Optional repack options
+* @returns Promise resolving to DOCX as ArrayBuffer
+*/
+async function updateXmlFile(originalBuffer, path, content, options = {}) {
+	const { compressionLevel = 6 } = options;
+	const zip = await JSZip.loadAsync(originalBuffer);
+	zip.file(path, content, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+	return zip.generateAsync({
+		type: "arraybuffer",
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+/**
+* Update multiple files in a DOCX buffer
+*
+* @param originalBuffer - Original DOCX as ArrayBuffer
+* @param updates - Map of path -> content for files to update
+* @param options - Optional repack options
+* @returns Promise resolving to DOCX as ArrayBuffer
+*/
+async function updateMultipleFiles(originalBuffer, updates, options = {}) {
+	return applyUpdatesToZip(await JSZip.loadAsync(originalBuffer), updates, options);
+}
+/**
+* Apply file updates to an already-loaded JSZip instance and generate the output.
+* Use this when the zip is already loaded to avoid a redundant decompression pass.
+*/
+function applyUpdatesToZip(zip, updates, options = {}) {
+	const { compressionLevel = 6 } = options;
+	for (const [path, content] of updates) zip.file(path, content, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+	return zip.generateAsync({
+		type: "arraybuffer",
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+/**
+* Add a new relationship to document.xml.rels
+*
+* @param originalBuffer - Original DOCX as ArrayBuffer
+* @param relationship - New relationship to add
+* @returns Promise resolving to { buffer: ArrayBuffer, rId: string }
+*/
+async function addRelationship(originalBuffer, relationship) {
+	const zip = await JSZip.loadAsync(originalBuffer);
+	const relsPath = "word/_rels/document.xml.rels";
+	const relsFile = zip.file(relsPath);
+	if (!relsFile) panic("document.xml.rels not found in DOCX");
+	const relsXml = await relsFile.async("text");
+	const newRId = `rId${findMaxRId(relsXml) + 1}`;
+	const targetModeAttr = relationship.targetMode === "External" ? " TargetMode=\"External\"" : "";
+	const newRelElement = `<Relationship Id="${newRId}" Type="${relationship.type}" Target="${escapeXml(relationship.target)}"${targetModeAttr}/>`;
+	const updatedRelsXml = relsXml.replace("</Relationships>", `${newRelElement}</Relationships>`);
+	zip.file(relsPath, updatedRelsXml);
+	return {
+		buffer: await zip.generateAsync({
+			type: "arraybuffer",
+			compression: "DEFLATE",
+			compressionOptions: { level: 6 }
+		}),
+		rId: newRId
+	};
+}
+/**
+* Add a media file to the DOCX
+*
+* @param originalBuffer - Original DOCX as ArrayBuffer
+* @param filename - Filename for the media (e.g., "image1.png")
+* @param data - Binary data for the media file
+* @param mimeType - MIME type (e.g., "image/png")
+* @returns Promise resolving to { buffer: ArrayBuffer, rId: string, path: string }
+*/
+async function addMedia(originalBuffer, filename, data, mimeType) {
+	const zip = await JSZip.loadAsync(originalBuffer);
+	const mediaPath = `word/media/${filename}`;
+	zip.file(mediaPath, data);
+	const relResult = await addRelationship(await zip.generateAsync({ type: "arraybuffer" }), {
+		type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
+		target: `media/${filename}`
+	});
+	const contentTypesFile = zip.file("[Content_Types].xml");
+	if (contentTypesFile) {
+		const contentTypesXml = await contentTypesFile.async("text");
+		const extension = filename.split(".").pop()?.toLowerCase() || "";
+		if (!contentTypesXml.includes(`Extension="${extension}"`) && extension) {
+			const extensionElement = `<Default Extension="${extension}" ContentType="${getContentTypeForExtension(extension, mimeType)}"/>`;
+			const updatedContentTypes = contentTypesXml.replace("</Types>", `${extensionElement}</Types>`);
+			const finalZip = await JSZip.loadAsync(relResult.buffer);
+			finalZip.file("[Content_Types].xml", updatedContentTypes);
+			return {
+				buffer: await finalZip.generateAsync({
+					type: "arraybuffer",
+					compression: "DEFLATE",
+					compressionOptions: { level: 6 }
+				}),
+				rId: relResult.rId,
+				path: mediaPath
+			};
+		}
+	}
+	return {
+		buffer: relResult.buffer,
+		rId: relResult.rId,
+		path: mediaPath
+	};
+}
+/**
+* Collect serialized header/footer XML updates from the document model.
+* Uses the relationship map to resolve rId → filename.
+*/
+const HEADER_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml";
+const FOOTER_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml";
+/**
+* A header/footer is "unmaterialized" when it lives in the package map but its
+* rId has no resolvable relationship in `document.xml.rels` — i.e. it was
+* created in memory (header editor, watermark coverage) and still lacks a part,
+* relationship, and `[Content_Types]` entry. The selective fast-path can't
+* register those, so it must bail to a full repack when this returns true.
+*/
+function hasUnmaterializedHeaderFooter(doc) {
+	const rels = doc.package.relationships;
+	const hasNew = (map, type) => {
+		if (!map) return false;
+		for (const rId of map.keys()) {
+			const rel = rels?.get(rId);
+			if (!rel || rel.type !== type || !rel.target) return true;
+		}
+		return false;
+	};
+	return hasNew(doc.package.headers, RELATIONSHIP_TYPES.header) || hasNew(doc.package.footers, RELATIONSHIP_TYPES.footer);
+}
+function findMaxHeaderFooterNum(zip, prefix) {
+	let max = 0;
+	const pattern = new RegExp(`^word/${prefix}(\\d+)\\.xml$`, "u");
+	zip.forEach((relativePath) => {
+		const m = pattern.exec(relativePath);
+		if (m) {
+			const num = Number.parseInt(m[1], 10);
+			if (num > max) max = num;
+		}
+	});
+	return max;
+}
+/**
+* Materialize header/footer parts created in memory (rId present in the package
+* map, absent from `document.xml.rels`). For each: mint a `word/<prefix>N.xml`
+* target, add a document relationship under the *existing* rId (a valid NCName,
+* so the section's `<w:headerReference r:id>` keeps resolving without rewriting
+* document.xml), and a `[Content_Types].xml` Override. The part body is written
+* afterwards by `serializeHeadersFootersToZip`, which can now resolve the new
+* relationship.
+*/
+async function materializeNewHeaderFooterParts(doc, zip, compressionLevel) {
+	const rels = doc.package.relationships;
+	if (!rels) return;
+	if (!hasUnmaterializedHeaderFooter(doc)) return;
+	const relEntries = [];
+	const overrides = [];
+	let maxHeaderNum = findMaxHeaderFooterNum(zip, "header");
+	let maxFooterNum = findMaxHeaderFooterNum(zip, "footer");
+	let maxRId = 0;
+	const considerNumericRId = (id) => {
+		const match = /^rId(?<num>\d+)$/u.exec(id);
+		if (match) {
+			const n = Number.parseInt(match.groups["num"], 10);
+			if (n > maxRId) maxRId = n;
+		}
+	};
+	for (const id of rels.keys()) considerNumericRId(id);
+	for (const id of doc.package.headers?.keys() ?? []) considerNumericRId(id);
+	for (const id of doc.package.footers?.keys() ?? []) considerNumericRId(id);
+	const remapRefs = (refs, oldRId, newRId) => {
+		for (const ref of refs ?? []) if (ref.rId === oldRId) ref.rId = newRId;
+	};
+	const materialize = (map, relType, prefix, contentType, isHeader) => {
+		if (!map) return;
+		for (const rId of [...map.keys()]) {
+			const existing = rels.get(rId);
+			if (existing && existing.type === relType && existing.target) continue;
+			let effectiveRId = rId;
+			if (existing) {
+				effectiveRId = `rId${++maxRId}`;
+				const headerFooter = map.get(rId);
+				if (headerFooter) {
+					map.delete(rId);
+					map.set(effectiveRId, headerFooter);
+				}
+				for (const block of doc.package.document.content) if (block.type === "paragraph") remapRefs(isHeader ? block.sectionProperties?.headerReferences : block.sectionProperties?.footerReferences, rId, effectiveRId);
+				const finalProps = doc.package.document.finalSectionProperties;
+				remapRefs(isHeader ? finalProps?.headerReferences : finalProps?.footerReferences, rId, effectiveRId);
+			}
+			const filename = `${prefix}${prefix === "header" ? ++maxHeaderNum : ++maxFooterNum}.xml`;
+			rels.set(effectiveRId, {
+				id: effectiveRId,
+				type: relType,
+				target: filename
+			});
+			relEntries.push(`<Relationship Id="${escapeXml(effectiveRId)}" Type="${relType}" Target="${filename}"/>`);
+			overrides.push(`<Override PartName="/word/${filename}" ContentType="${contentType}"/>`);
+		}
+	};
+	materialize(doc.package.headers, RELATIONSHIP_TYPES.header, "header", HEADER_CONTENT_TYPE, true);
+	materialize(doc.package.footers, RELATIONSHIP_TYPES.footer, "footer", FOOTER_CONTENT_TYPE, false);
+	if (relEntries.length === 0) return;
+	const compressionOptions = { level: compressionLevel };
+	const relsPath = "word/_rels/document.xml.rels";
+	const relsXml = await readRelsOrStub(zip, relsPath);
+	zip.file(relsPath, relsXml.replace("</Relationships>", `${relEntries.join("")}</Relationships>`), {
+		compression: "DEFLATE",
+		compressionOptions
+	});
+	const ctFile = zip.file("[Content_Types].xml");
+	if (ctFile) {
+		let ctXml = await ctFile.async("text");
+		const missing = overrides.filter((override) => {
+			const partName = /PartName="(?<partName>[^"]+)"/u.exec(override)?.groups?.["partName"];
+			return partName ? !ctXml.includes(`PartName="${partName}"`) : true;
+		});
+		if (missing.length > 0) {
+			ctXml = ctXml.replace("</Types>", `${missing.join("")}</Types>`);
+			zip.file("[Content_Types].xml", ctXml, {
+				compression: "DEFLATE",
+				compressionOptions
+			});
+		}
+	}
+}
+/**
+* A picture watermark is "model-driven" when its raw VML was cleared (so the
+* serializer synthesizes `<v:imagedata r:id>` from `imageRId`). Its image
+* relationship may need rebinding into the header's own rels — work only the
+* full-repack path does — so the selective fast-path bails whenever any such
+* watermark is present, regardless of header count (a single header's rId could
+* have been set without yet resolving in that header's rels).
+*/
+function hasModelDrivenPictureWatermark(doc) {
+	const headers = doc.package.headers;
+	if (!headers) return false;
+	for (const hf of headers.values()) if (hf.watermark?.kind === "picture" && !hf.rawWatermarkXml) return true;
+	return false;
+}
+/**
+* Rebind each picture watermark's `imageRId` so it resolves in its own header
+* part's rels. A watermark propagated across headers (or onto a header created
+* by coverage) carries the source header's rId, which is meaningless in a
+* sibling header's `word/_rels/header*.xml.rels`. Per header: keep the rId if
+* it already resolves; otherwise reuse an existing relationship to the same
+* media target, or mint a new one. The media bytes are shared (preserved from
+* the source), so no new media part is written. Raw-replay watermarks are
+* byte-exact and skipped.
+*/
+async function rebindWatermarkRelIds(doc, zip, compressionLevel) {
+	const rels = doc.package.relationships;
+	const headers = doc.package.headers;
+	if (!rels || !headers) return;
+	const pending = [];
+	for (const [rId, hf] of headers) {
+		const watermark = hf.watermark;
+		if (!watermark || watermark.kind !== "picture" || hf.rawWatermarkXml) continue;
+		const rel = rels.get(rId);
+		if (!rel?.target) continue;
+		pending.push({
+			watermark,
+			relsPath: headerFooterRelsPath(rel.target),
+			partPath: headerFooterFilename(rel.target)
+		});
+	}
+	if (pending.length === 0) return;
+	const relsXmlByPath = /* @__PURE__ */ new Map();
+	const headerRelsPaths = new Set(pending.map((p) => p.relsPath));
+	for (const rel of rels.values()) if (rel.type === RELATIONSHIP_TYPES.header && rel.target) headerRelsPaths.add(headerFooterRelsPath(rel.target));
+	for (const relsPath of headerRelsPaths) relsXmlByPath.set(relsPath, await readRelsOrStub(zip, relsPath));
+	const relImage = (rel, relsPath) => {
+		if (rel?.type !== RELATIONSHIP_TYPES.image || !rel.target) return;
+		return rel.targetMode === "External" ? {
+			mode: "external",
+			url: rel.target
+		} : {
+			mode: "internal",
+			absolute: resolveRelativePath(relsPath, rel.target)
+		};
+	};
+	const sameImage = (a, b) => a.mode === "internal" && b.mode === "internal" ? a.absolute === b.absolute : a.mode === "external" && b.mode === "external" && a.url === b.url;
+	const resolveCanonical = (imageRId) => {
+		for (const [relsPath, xml] of relsXmlByPath) {
+			const canonical = relImage(parseRelationships(xml).get(imageRId), relsPath);
+			if (canonical) return canonical;
+		}
+	};
+	const changedPaths = /* @__PURE__ */ new Set();
+	for (const { watermark, relsPath, partPath } of pending) {
+		let canonical;
+		if (watermark.imageTarget !== void 0) canonical = watermark.imageTargetExternal ? {
+			mode: "external",
+			url: watermark.imageTarget
+		} : {
+			mode: "internal",
+			absolute: watermark.imageTarget
+		};
+		else canonical = resolveCanonical(watermark.imageRId);
+		if (!canonical) continue;
+		const relsXml = relsXmlByPath.get(relsPath) ?? EMPTY_RELS_XML;
+		const localRels = parseRelationships(relsXml);
+		const local = relImage(localRels.get(watermark.imageRId), relsPath);
+		if (local && sameImage(local, canonical)) continue;
+		let resolvedRId;
+		for (const [id, rel] of localRels) {
+			const image = relImage(rel, relsPath);
+			if (image && sameImage(image, canonical)) {
+				resolvedRId = id;
+				break;
+			}
+		}
+		if (!resolvedRId) {
+			resolvedRId = `rId${findMaxRId(relsXml) + 1}`;
+			const relXml = canonical.mode === "external" ? `<Relationship Id="${resolvedRId}" Type="${RELATIONSHIP_TYPES.image}" Target="${escapeXml(canonical.url)}" TargetMode="External"/>` : `<Relationship Id="${resolvedRId}" Type="${RELATIONSHIP_TYPES.image}" Target="${escapeXml(relativeTargetForPart(partPath, canonical.absolute))}"/>`;
+			relsXmlByPath.set(relsPath, relsXml.replace("</Relationships>", `${relXml}</Relationships>`));
+			changedPaths.add(relsPath);
+		}
+		watermark.imageRId = resolvedRId;
+	}
+	const compressionOptions = { level: compressionLevel };
+	for (const path of changedPaths) {
+		const xml = relsXmlByPath.get(path);
+		if (xml) zip.file(path, xml, {
+			compression: "DEFLATE",
+			compressionOptions
+		});
+	}
+}
+function collectHeaderFooterUpdates(doc) {
+	const updates = /* @__PURE__ */ new Map();
+	const rels = doc.package.relationships;
+	if (!rels) return updates;
+	const documentRelsPath = "word/_rels/document.xml.rels";
+	const parts = [{
+		map: doc.package.headers,
+		type: RELATIONSHIP_TYPES.header
+	}, {
+		map: doc.package.footers,
+		type: RELATIONSHIP_TYPES.footer
+	}];
+	for (const { map, type } of parts) {
+		if (!map) continue;
+		for (const [rId, headerFooter] of map.entries()) {
+			const rel = rels.get(rId);
+			if (rel && rel.type === type && rel.target) {
+				const filename = resolveRelativePath(documentRelsPath, rel.target);
+				updates.set(filename, serializeHeaderFooter(headerFooter));
+			}
+		}
+	}
+	return updates;
+}
+/**
+* Serialize modified headers and footers into the ZIP
+*/
+function serializeHeadersFootersToZip(doc, zip, compressionLevel) {
+	const compressionOptions = { level: compressionLevel };
+	for (const [filename, xml] of collectHeaderFooterUpdates(doc)) zip.file(filename, xml, {
+		compression: "DEFLATE",
+		compressionOptions
+	});
+}
+/**
+* Write edited footnote/endnote bodies into the repacked ZIP.
+*
+* The full repack rebuilds document.xml from the model, but note parts are
+* preserved from the original ZIP: the model only retains the normal notes, so
+* re-emitting the whole part would drop the separator / continuationSeparator
+* notes Word requires. Instead each edited note paragraph is spliced by `paraId`
+* into the ORIGINAL part, so an edited note gets the model content while
+* separators and every unedited note stay byte-exact.
+*
+* Full repack has no change-tracking signal, so "edited" is detected by
+* comparing the current model's note serialization against a BASELINE that
+* re-parses and re-serializes the original part. Both go through the same
+* (lossy) parse+serialize — e.g. the in-note `w:footnoteRef` auto-number mark
+* the model does not represent is dropped on both sides — so an unedited note
+* matches its baseline and is left verbatim (mark intact); only a genuine body
+* edit differs and is spliced.
+*/
+async function serializeNotesToZip(doc, originalZip, newZip, compressionLevel) {
+	const footnotes = doc.package.footnotes ?? [];
+	if (footnotes.length > 0) await patchNotePartIntoZip("word/footnotes.xml", serializeFootnotes(footnotes), (xml) => serializeFootnotes(parseFootnotes(xml).getNormalFootnotes()), originalZip, newZip, compressionLevel);
+	const endnotes = doc.package.endnotes ?? [];
+	if (endnotes.length > 0) await patchNotePartIntoZip("word/endnotes.xml", serializeEndnotes(endnotes), (xml) => serializeEndnotes(parseEndnotes(xml).getNormalEndnotes()), originalZip, newZip, compressionLevel);
+}
+/**
+* Write edited numbering definitions into word/numbering.xml.
+*
+* Like the note parts, numbering.xml is preserved verbatim by the copy loop:
+* the model does not faithfully retain it (abstractNums drop `w:nsid`/`w:tmpl`,
+* custom number formats collapse, level `w:pPr`/`w:rPr` keep only a subset), so
+* re-emitting the whole part would lose those pieces. Instead each edited
+* `w:abstractNum` / `w:num` is spliced by id into the ORIGINAL part.
+*
+* Full repack has no change-tracking signal, so "edited" is detected by
+* comparing the model's numbering serialization against a BASELINE that
+* re-parses and re-serializes the original part. Both go through the same
+* (lossy) parse+serialize, so an unedited definition matches its baseline and
+* is left byte-exact; only a genuine definition edit differs and is spliced.
+*/
+async function serializeNumberingIntoZip(doc, originalZip, newZip, compressionLevel) {
+	const numbering = doc.package.numbering;
+	if (!numbering || numbering.abstractNums.length === 0 && numbering.nums.length === 0) return;
+	const file = findNotePartEntry(originalZip, "word/numbering.xml");
+	if (!file) return;
+	const originalXml = await file.async("text");
+	const baselineXml = serializeNumberingXml(parseNumbering(originalXml).definitions);
+	const currentXml = serializeNumberingXml(numbering);
+	const changed = collectChangedNumberingDefs(baselineXml, currentXml);
+	if (changed.abstractNums.size === 0 && changed.nums.size === 0) return;
+	const patched = buildPatchedNumberingXml(originalXml, currentXml, changed);
+	if (patched === null) return;
+	newZip.file(file.name, patched, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+async function patchNotePartIntoZip(conventionalLowerPath, currentXml, baselineFrom, originalZip, newZip, compressionLevel) {
+	const file = findNotePartEntry(originalZip, conventionalLowerPath);
+	if (!file) return;
+	const originalXml = await file.async("text");
+	const changedIds = collectChangedNoteParaIds(baselineFrom(originalXml), currentXml);
+	if (changedIds.size === 0) return;
+	const patched = buildPatchedNoteXml(originalXml, currentXml, changedIds);
+	if (patched === null) return;
+	newZip.file(file.name, patched, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
+/**
+* The note paragraphs whose current serialization differs from the baseline
+* (re-parsed original) serialization — i.e. the ones actually edited. A
+* paragraph is only considered when its `paraId` resolves uniquely in both,
+* so it can be spliced safely.
+*/
+function collectChangedNoteParaIds(baselineXml, currentXml) {
+	const changed = /* @__PURE__ */ new Set();
+	const baselineIds = collectParaIds(baselineXml);
+	for (const [id, count] of collectParaIds(currentXml)) {
+		if (count !== 1 || baselineIds.get(id) !== 1) continue;
+		const before = extractParagraphXml(baselineXml, id);
+		const after = extractParagraphXml(currentXml, id);
+		if (before !== null && after !== null && before !== after) changed.add(id);
+	}
+	return changed;
+}
+/**
+* Locate a note part in the ZIP, matching case-insensitively so a producer that
+* cased the entry differently still resolves to the existing part.
+*/
+function findNotePartEntry(zip, conventionalLowerPath) {
+	const direct = zip.file(conventionalLowerPath);
+	if (direct) return direct;
+	for (const [path, file] of Object.entries(zip.files)) if (!file.dir && path.toLowerCase() === conventionalLowerPath) return file;
+	return null;
+}
+/**
+* Update core properties XML with new modification date
+*/
+function updateCoreProperties(corePropsXml, options) {
+	let result = corePropsXml;
+	if (options.updateModifiedDate) {
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		if (result.includes("<dcterms:modified")) result = result.replace(/<dcterms:modified[^<>]*>[^<]*<\/dcterms:modified>/u, `<dcterms:modified xsi:type="dcterms:W3CDTF">${now}</dcterms:modified>`);
+		else result = result.replace("</cp:coreProperties>", `<dcterms:modified xsi:type="dcterms:W3CDTF">${now}</dcterms:modified></cp:coreProperties>`);
+	}
+	if (options.modifiedBy) if (result.includes("<cp:lastModifiedBy")) result = result.replace(/<cp:lastModifiedBy>[^<]*<\/cp:lastModifiedBy>/u, `<cp:lastModifiedBy>${escapeXml(options.modifiedBy)}</cp:lastModifiedBy>`);
+	else result = result.replace("</cp:coreProperties>", `<cp:lastModifiedBy>${escapeXml(options.modifiedBy)}</cp:lastModifiedBy></cp:coreProperties>`);
+	return result;
+}
+/**
+* Get content type for a file extension
+*/
+function getContentTypeForExtension(extension, mimeType) {
+	if (mimeType) return mimeType;
+	return {
+		png: "image/png",
+		jpg: "image/jpeg",
+		jpeg: "image/jpeg",
+		gif: "image/gif",
+		bmp: "image/bmp",
+		tif: "image/tiff",
+		tiff: "image/tiff",
+		svg: "image/svg+xml",
+		webp: "image/webp",
+		wmf: "image/x-wmf",
+		emf: "image/x-emf"
+	}[extension] || "application/octet-stream";
+}
+/**
+* Validate that a buffer is a valid DOCX file
+*
+* @param buffer - Buffer to validate
+* @returns Promise resolving to validation result
+*/
+async function validateDocx(buffer) {
+	const errors = [];
+	const warnings = [];
+	try {
+		const zip = await JSZip.loadAsync(buffer);
+		for (const file of ["[Content_Types].xml", "word/document.xml"]) if (!zip.file(file)) errors.push(`Missing required file: ${file}`);
+		for (const file of [
+			"_rels/.rels",
+			"word/_rels/document.xml.rels",
+			"word/styles.xml"
+		]) if (!zip.file(file)) warnings.push(`Missing recommended file: ${file}`);
+		const docFile = zip.file("word/document.xml");
+		if (docFile) {
+			const docXml = await docFile.async("text");
+			if (!docXml.includes("<?xml")) warnings.push("document.xml missing XML declaration");
+			if (!docXml.includes("<w:document")) errors.push("document.xml missing w:document element");
+			if (!docXml.includes("<w:body>")) errors.push("document.xml missing w:body element");
+		}
+		const ctFile = zip.file("[Content_Types].xml");
+		if (ctFile) {
+			const ctXml = await ctFile.async("text");
+			if (!ctXml.includes("word/document.xml") && !ctXml.includes("application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml")) warnings.push("Content_Types.xml may be missing document.xml type declaration");
+		}
+	} catch (error) {
+		errors.push(`Failed to read as ZIP: ${error instanceof Error ? error.message : "Unknown error"}`);
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+/**
+* Check if buffer looks like a DOCX file (quick check)
+*
+* @param buffer - Buffer to check
+* @returns true if buffer starts with ZIP signature
+*/
+function isDocxBuffer(buffer) {
+	if (buffer.byteLength < 4) return false;
+	const view = new Uint8Array(buffer);
+	return view[0] === 80 && view[1] === 75;
+}
+/**
+* Create a new empty DOCX file
+*
+* @returns Promise resolving to minimal DOCX as ArrayBuffer
+*/
+function createEmptyDocx() {
+	const zip = new JSZip();
+	zip.file("[Content_Types].xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+  <Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>
+  <Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>
+  <Override PartName="/docProps/app.xml" ContentType="application/vnd.openxmlformats-officedocument.extended-properties+xml"/>
+</Types>`);
+	zip.file("_rels/.rels", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
+  <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Target="docProps/core.xml"/>
+  <Relationship Id="rId3" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties" Target="docProps/app.xml"/>
+</Relationships>`);
+	zip.file("word/_rels/document.xml.rels", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
+</Relationships>`);
+	zip.file("word/document.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+  <w:body>
+    <w:p>
+      <w:r>
+        <w:t></w:t>
+      </w:r>
+    </w:p>
+    <w:sectPr>
+      <w:pgSz w:w="12240" w:h="15840"/>
+      <w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720" w:gutter="0"/>
+    </w:sectPr>
+  </w:body>
+</w:document>`);
+	zip.file("word/styles.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:docDefaults>
+    <w:rPrDefault>
+      <w:rPr>
+        <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>
+        <w:sz w:val="22"/>
+      </w:rPr>
+    </w:rPrDefault>
+    <w:pPrDefault>
+      <w:pPr>
+        <w:spacing w:after="200" w:line="276" w:lineRule="auto"/>
+      </w:pPr>
+    </w:pPrDefault>
+  </w:docDefaults>
+  <w:style w:type="paragraph" w:default="1" w:styleId="Normal">
+    <w:name w:val="Normal"/>
+  </w:style>
+</w:styles>`);
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	zip.file("docProps/core.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <dc:creator>EigenPal DOCX Editor</dc:creator>
+  <dcterms:created xsi:type="dcterms:W3CDTF">${now}</dcterms:created>
+  <dcterms:modified xsi:type="dcterms:W3CDTF">${now}</dcterms:modified>
+</cp:coreProperties>`);
+	zip.file("docProps/app.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties">
+  <Application>EigenPal DOCX Editor</Application>
+  <AppVersion>1.0.0</AppVersion>
+</Properties>`);
+	return zip.generateAsync({
+		type: "arraybuffer",
+		compression: "DEFLATE",
+		compressionOptions: { level: 6 }
+	});
+}
+/**
+* Create a new DOCX from a Document (without requiring original buffer)
+*
+* @param doc - Document to serialize
+* @returns Promise resolving to DOCX as ArrayBuffer
+*/
+async function createDocx(doc) {
+	const emptyBuffer = await createEmptyDocx();
+	return repackDocx({
+		...doc,
+		originalBuffer: emptyBuffer
+	});
+}
+//#endregion
+export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocxPackageFidelityError, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, isDocxBuffer, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx };