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

package/dist/docx/selectiveSave.js

@@ -0,0 +1,247 @@
+import { hasUnsynthesizedReplyRanges } from "./commentReplyMarkers.js";
+import { RELATIONSHIP_TYPES } from "./relsParser.js";
+import { validateFolioDocumentModel } from "./modelValidation.js";
+import { parseNumbering } from "./numberingParser.js";
+import { buildPatchedDocumentXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectChangedNumberingDefs, collectParaIds } from "./selectiveXmlPatch.js";
+import { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
+import { serializeDocument } from "./serializer/documentSerializer.js";
+import { serializeEndnotes, serializeFootnotes } from "./serializer/noteSerializer.js";
+import { serializeNumberingXml } from "./serializer/numberingSerializer.js";
+import { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_PART_LOWER, addCommentsExtendedOverride, addCommentsExtendedRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, updateCoreProperties } from "./rezip.js";
+import { parseCommentsExtended } from "./commentParser.js";
+import "./selectiveSaveFlags.js";
+//#region src/docx/selectiveSave.ts
+const SYNTHETIC_IMAGE_RID_PREFIX = "rId_img_";
+/**
+* Check if document content has new images (data: URL without rId) or
+* new hyperlinks (href without rId). Combined into a single traversal
+* to avoid walking the block tree twice.
+*/
+function hasNewImagesOrHyperlinks(blocks) {
+	const runHasNewImage = (run) => run.content.some((c) => c.type === "drawing" && c.image?.src?.startsWith("data:") === true && (!c.image.rId || c.image.rId.startsWith(SYNTHETIC_IMAGE_RID_PREFIX)));
+	for (const block of blocks) if (block.type === "paragraph") {
+		for (const item of block.content) if (item.type === "run") {
+			if (runHasNewImage(item)) return true;
+		} else if (item.type === "hyperlink" && item.href && !item.rId && !item.anchor) return true;
+		else if (item.type === "insertion" || item.type === "deletion" || item.type === "moveFrom" || item.type === "moveTo") {
+			for (const sub of item.content) if (sub.type === "run" && runHasNewImage(sub)) return true;
+		}
+	} else if (block.type === "table") {
+		for (const row of block.rows) for (const cell of row.cells) if (hasNewImagesOrHyperlinks(cell.content)) return true;
+	}
+	return false;
+}
+/**
+* Splice edited footnote/endnote paragraphs into their parts and return the
+* candidate ids that could NOT be routed to a note part (an id that is neither
+* a body nor a note paragraph — the caller bails on those).
+*
+* The document model only retains the normal notes, so this never rewrites a
+* whole note part (that would drop the separator notes the model omits): it
+* splices only the edited note paragraphs by `paraId` via
+* {@link buildPatchedNoteXml}, keeping separators and unedited notes byte-exact.
+*
+* Returns null to signal the caller should bail to a full repack (a note
+* paragraph could not be spliced safely).
+*/
+async function patchNoteParts(zip, doc, candidateIds, updates) {
+	const footnotes = doc.package.footnotes ?? [];
+	const endnotes = doc.package.endnotes ?? [];
+	const remainingIds = new Set(candidateIds);
+	if (footnotes.length === 0 && endnotes.length === 0) return remainingIds;
+	const findPart = (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;
+	};
+	const patchPart = async (conventionalLowerPath, serialize) => {
+		const file = findPart(conventionalLowerPath);
+		if (!file) return true;
+		const originalXml = await file.async("text");
+		const originalIds = collectParaIds(originalXml);
+		const partIds = /* @__PURE__ */ new Set();
+		for (const id of remainingIds) if (originalIds.has(id)) partIds.add(id);
+		if (partIds.size === 0) return true;
+		const patched = buildPatchedNoteXml(originalXml, serialize(), partIds);
+		if (patched === null) return false;
+		updates.set(file.name, patched);
+		for (const id of partIds) remainingIds.delete(id);
+		return true;
+	};
+	if (footnotes.length > 0 && !await patchPart("word/footnotes.xml", () => serializeFootnotes(footnotes))) return null;
+	if (endnotes.length > 0 && !await patchPart("word/endnotes.xml", () => serializeEndnotes(endnotes))) return null;
+	return remainingIds;
+}
+const 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 commentsExtendedInfoEqual = (a, b) => {
+	if (a.size !== b.size) return false;
+	for (const [paraId, infoA] of a) {
+		const infoB = b.get(paraId);
+		if (!infoB || infoA.parentParaId !== infoB.parentParaId || (infoA.done ?? false) !== (infoB.done ?? false)) return false;
+	}
+	return true;
+};
+/**
+* Reconcile commentsExtended.xml on the selective path. Returns `false` to
+* signal the caller must bail to a full repack (which owns removing / rewiring
+* the part + content-type + relationship as a unit); `true` when the part is
+* unchanged or was safely patched into `updates`.
+*
+* - Threading unchanged (compared through the same parser, so attribute-order
+*   noise is ignored): leave the part byte-exact.
+* - Threading removed (no desired part but a baseline exists): bail — removing
+*   the part plus its dangling override/relationship cleanly is the full
+*   repack's job.
+* - Threading changed: write the part and ensure its override + relationship,
+*   bailing if the packaging files needed to wire it are absent.
+*/
+async function patchCommentsExtended(zip, comments, updates) {
+	const desiredXml = serializeCommentsExtended(comments);
+	const existing = findZipEntryCaseInsensitive(zip, COMMENTS_EXTENDED_PART_LOWER);
+	if (!desiredXml) return existing === null;
+	const baselineInfo = existing ? parseCommentsExtended(await existing.async("text")) : /* @__PURE__ */ new Map();
+	if (commentsExtendedInfoEqual(parseCommentsExtended(desiredXml), baselineInfo)) return true;
+	updates.set(existing?.name ?? "word/commentsExtended.xml", desiredXml);
+	return ensureCommentsExtendedPackaging(zip, updates);
+}
+/**
+* Add the content-type override + relationship for commentsExtended.xml if
+* absent, composing over any pending `updates`. Returns `false` when a packaging
+* file needed to wire the part is missing (the caller then bails to full repack
+* rather than write a part nothing references).
+*/
+async function ensureCommentsExtendedPackaging(zip, updates) {
+	const ctPath = "[Content_Types].xml";
+	const ctXml = updates.get(ctPath) ?? await zip.file(ctPath)?.async("text");
+	if (ctXml === void 0) return false;
+	const nextCt = addCommentsExtendedOverride(ctXml);
+	if (nextCt !== ctXml) updates.set(ctPath, nextCt);
+	const relsPath = "word/_rels/document.xml.rels";
+	const relsXml = updates.get(relsPath) ?? await zip.file(relsPath)?.async("text");
+	if (relsXml === void 0) return false;
+	const nextRels = addCommentsExtendedRelationship(relsXml);
+	if (nextRels !== relsXml) updates.set(relsPath, nextRels);
+	return true;
+}
+/**
+* Splice edited numbering definitions into word/numbering.xml when the model's
+* numbering differs from the original part.
+*
+* Numbering definitions carry no `paraId`, so this is NOT keyed off
+* `changedParaIds` — it always runs (like the comments/header updates) and uses
+* a re-parse+re-serialize baseline to detect which `w:abstractNum` / `w:num`
+* definitions actually changed. The model omits parts of numbering.xml
+* (`w:nsid`/`w:tmpl`, custom formats, level sub-elements), so only the changed
+* definitions are spliced by id; every other definition stays byte-exact.
+*
+* Any absent numbering part, unchanged numbering, or unsplittable edit leaves
+* the original part untouched — the file is simply not added to `updates`.
+*/
+async function patchNumberingPart(zip, doc, updates) {
+	const numbering = doc.package.numbering;
+	if (!numbering || numbering.abstractNums.length === 0 && numbering.nums.length === 0) return;
+	const conventionalLowerPath = "word/numbering.xml";
+	let file = zip.file(conventionalLowerPath);
+	if (!file) {
+		for (const [path, entry] of Object.entries(zip.files)) if (!entry.dir && path.toLowerCase() === conventionalLowerPath) {
+			file = entry;
+			break;
+		}
+	}
+	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;
+	updates.set(file.name, patched);
+}
+/**
+* Attempt a selective save — patch only changed paragraphs in document.xml.
+* Also updates comments, headers/footers, and core properties so that
+* all document parts stay in sync even when only paragraphs are patched.
+*
+* Returns the saved ArrayBuffer, or null if selective save is not possible
+* (caller should fall back to full repack).
+*/
+async function attemptSelectiveSave(doc, originalBuffer, options) {
+	const { changedParaIds, structuralChange, hasUntrackedChanges } = options;
+	const maxBytes = options.maxBytes ?? 104857600;
+	if (structuralChange) return null;
+	if (hasUntrackedChanges) return null;
+	if (originalBuffer.byteLength > maxBytes) return null;
+	const content = doc.package.document.content;
+	if (hasNewImagesOrHyperlinks(content)) return null;
+	if (hasUnmaterializedHeaderFooter(doc)) return null;
+	if (hasModelDrivenPictureWatermark(doc)) return null;
+	if (hasUnsynthesizedReplyRanges(doc)) return null;
+	if (!validateFolioDocumentModel(doc).valid) return null;
+	const comments = doc.package.document.comments ?? [];
+	const hasComments = comments.length > 0;
+	const headerFooterUpdates = collectHeaderFooterUpdates(doc);
+	try {
+		const zip = await (await import("jszip")).default.loadAsync(originalBuffer);
+		const updates = /* @__PURE__ */ new Map();
+		if (changedParaIds.size > 0) {
+			const docXmlFile = zip.file("word/document.xml");
+			if (!docXmlFile) return null;
+			const originalDocXml = await docXmlFile.async("text");
+			const bodyParaIds = collectParaIds(originalDocXml);
+			const bodyChangedIds = /* @__PURE__ */ new Set();
+			const noteCandidateIds = /* @__PURE__ */ new Set();
+			for (const id of changedParaIds) if (bodyParaIds.has(id)) bodyChangedIds.add(id);
+			else noteCandidateIds.add(id);
+			if (noteCandidateIds.size > 0) {
+				const unrouted = await patchNoteParts(zip, doc, noteCandidateIds, updates);
+				if (unrouted === null || unrouted.size > 0) return null;
+			}
+			if (bodyChangedIds.size > 0) {
+				const patchedDocXml = buildPatchedDocumentXml(originalDocXml, serializeDocument(doc), bodyChangedIds);
+				if (!patchedDocXml) return null;
+				updates.set("word/document.xml", patchedDocXml);
+			}
+		}
+		const hadCommentsFile = zip.file("word/comments.xml") !== null;
+		if (hasComments || hadCommentsFile) {
+			ensureThreadedCommentParaIds(comments);
+			updates.set("word/comments.xml", serializeComments(comments));
+		}
+		if (hasComments) {
+			const ctFile = zip.file("[Content_Types].xml");
+			if (ctFile) {
+				const ctXml = await ctFile.async("text");
+				if (!ctXml.includes("/word/comments.xml")) updates.set("[Content_Types].xml", ctXml.replace("</Types>", `<Override PartName="/word/comments.xml" ContentType="${COMMENTS_CONTENT_TYPE}"/></Types>`));
+			}
+			const relsPath = "word/_rels/document.xml.rels";
+			const relsFile = zip.file(relsPath);
+			if (relsFile) {
+				const relsXml = await relsFile.async("text");
+				if (!relsXml.includes("comments.xml")) {
+					const maxId = findMaxRId(relsXml);
+					updates.set(relsPath, relsXml.replace("</Relationships>", `<Relationship Id="rId${maxId + 1}" Type="${RELATIONSHIP_TYPES.comments}" Target="comments.xml"/></Relationships>`));
+				}
+			}
+		}
+		if (!await patchCommentsExtended(zip, comments, updates)) return null;
+		await patchNumberingPart(zip, doc, updates);
+		for (const [path, xml] of headerFooterUpdates) updates.set(path, xml);
+		const corePropsFile = zip.file("docProps/core.xml");
+		if (corePropsFile) {
+			const corePropsXml = await corePropsFile.async("text");
+			updates.set("docProps/core.xml", updateCoreProperties(corePropsXml, { updateModifiedDate: true }));
+		}
+		return await applyUpdatesToZip(zip, updates);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { attemptSelectiveSave };

package/dist/docx/selectiveSaveFlags.d.ts

@@ -0,0 +1,33 @@
+//#region src/docx/selectiveSaveFlags.d.ts
+/**
+ * Selective Save Feature Flags
+ *
+ * Operational controls for the selective save path. Default values keep the
+ * existing full-repack behavior in place so hosts opt in explicitly.
+ *
+ * - `selectiveSave` — gate the selective branch entirely.
+ * - `selectiveSaveTripwire` — run selective + full and compare bytes for CI
+ *   observability. Never blocks the user-visible save.
+ * - `selectiveSaveMaxBytes` — refuse the selective path for original buffers
+ *   above this size, since holding them in memory plus the JSZip overhead is
+ *   the dominant cost.
+ */
+type FolioSelectiveSaveFlags = {
+  /** Enable the selective save path. Default: false (full repack only). */selectiveSave?: boolean;
+  /**
+   * Run selective save and full repack on every save, compare bytes, and emit
+   * a `TripwireResult` via `onSelectiveSaveTripwire`. Independent of
+   * `selectiveSave`: the tripwire always observes both paths.
+   */
+  selectiveSaveTripwire?: boolean; /** Maximum original buffer size, in bytes, for which selective save is allowed. */
+  selectiveSaveMaxBytes?: number;
+};
+declare const DEFAULT_SELECTIVE_SAVE_MAX_BYTES: number;
+type ResolvedSelectiveSaveFlags = {
+  selectiveSave: boolean;
+  selectiveSaveTripwire: boolean;
+  selectiveSaveMaxBytes: number;
+};
+declare function resolveSelectiveSaveFlags(flags: FolioSelectiveSaveFlags | undefined): ResolvedSelectiveSaveFlags;
+//#endregion
+export { DEFAULT_SELECTIVE_SAVE_MAX_BYTES, FolioSelectiveSaveFlags, ResolvedSelectiveSaveFlags, resolveSelectiveSaveFlags };

package/dist/docx/selectiveSaveFlags.js

@@ -0,0 +1,11 @@
+//#region src/docx/selectiveSaveFlags.ts
+const DEFAULT_SELECTIVE_SAVE_MAX_BYTES = 100 * 1024 * 1024;
+function resolveSelectiveSaveFlags(flags) {
+	return {
+		selectiveSave: flags?.selectiveSave ?? false,
+		selectiveSaveTripwire: flags?.selectiveSaveTripwire ?? false,
+		selectiveSaveMaxBytes: flags?.selectiveSaveMaxBytes ?? 104857600
+	};
+}
+//#endregion
+export { DEFAULT_SELECTIVE_SAVE_MAX_BYTES, resolveSelectiveSaveFlags };

package/dist/docx/selectiveSaveTripwire.d.ts

@@ -0,0 +1,33 @@
+//#region src/docx/selectiveSaveTripwire.d.ts
+/**
+ * Selective Save Tripwire
+ *
+ * Compares the bytes produced by selective save against a full repack of the
+ * same document, so CI and local soak can detect divergence between the two
+ * paths before it reaches a user's `.docx`.
+ *
+ * Tripwire NEVER blocks a save. The host receives a structured `TripwireResult`
+ * via callback and decides what to do (log, surface as observability event,
+ * fail a CI assertion, etc.).
+ *
+ * The diff ignores `docProps/core.xml` because both paths refresh
+ * `dcterms:modified` with the current wall clock and would always disagree.
+ */
+type TripwireResult = {
+  kind: "match";
+} | {
+  kind: "selective-skipped";
+  reason: string;
+} | {
+  kind: "entry-set-diff";
+  onlyInSelective: readonly string[];
+  onlyInFull: readonly string[];
+} | {
+  kind: "entry-byte-diff";
+  path: string;
+  selectiveSize: number;
+  fullSize: number;
+};
+declare function compareSelectiveVsFull(selective: ArrayBuffer | null, full: ArrayBuffer): Promise<TripwireResult>;
+//#endregion
+export { TripwireResult, compareSelectiveVsFull };

package/dist/docx/selectiveSaveTripwire.js

@@ -0,0 +1,79 @@
+import { panic } from "better-result";
+//#region src/docx/selectiveSaveTripwire.ts
+/**
+* Selective Save Tripwire
+*
+* Compares the bytes produced by selective save against a full repack of the
+* same document, so CI and local soak can detect divergence between the two
+* paths before it reaches a user's `.docx`.
+*
+* Tripwire NEVER blocks a save. The host receives a structured `TripwireResult`
+* via callback and decides what to do (log, surface as observability event,
+* fail a CI assertion, etc.).
+*
+* The diff ignores `docProps/core.xml` because both paths refresh
+* `dcterms:modified` with the current wall clock and would always disagree.
+*/
+const IGNORED_PATHS = /* @__PURE__ */ new Set(["docProps/core.xml"]);
+async function listEntries(buffer) {
+	const zip = await (await import("jszip")).default.loadAsync(buffer);
+	const paths = [];
+	for (const [path, entry] of Object.entries(zip.files)) {
+		if (entry.dir) continue;
+		if (IGNORED_PATHS.has(path)) continue;
+		paths.push(path);
+	}
+	paths.sort();
+	return {
+		zip,
+		paths
+	};
+}
+function bytesEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+function readEntryBytes(zip, path, side) {
+	const entry = zip.file(path);
+	if (!entry) panic(`Missing ${side} zip entry: ${path}`);
+	return entry.async("uint8array");
+}
+function readCommonEntryBytes(selectiveZip, fullZip) {
+	return Promise.all(selectiveZip.paths.map(async (path) => {
+		const [selective, full] = await Promise.all([readEntryBytes(selectiveZip.zip, path, "selective"), readEntryBytes(fullZip.zip, path, "full")]);
+		return {
+			path,
+			selective,
+			full
+		};
+	}));
+}
+async function compareSelectiveVsFull(selective, full) {
+	if (selective === null) return {
+		kind: "selective-skipped",
+		reason: "selective-returned-null"
+	};
+	const [selectiveZip, fullZip] = await Promise.all([listEntries(selective), listEntries(full)]);
+	const selectiveSet = new Set(selectiveZip.paths);
+	const fullSet = new Set(fullZip.paths);
+	const onlyInSelective = [];
+	const onlyInFull = [];
+	for (const path of selectiveSet) if (!fullSet.has(path)) onlyInSelective.push(path);
+	for (const path of fullSet) if (!selectiveSet.has(path)) onlyInFull.push(path);
+	if (onlyInSelective.length > 0 || onlyInFull.length > 0) return {
+		kind: "entry-set-diff",
+		onlyInSelective,
+		onlyInFull
+	};
+	const entries = await readCommonEntryBytes(selectiveZip, fullZip);
+	for (const { path, selective: selectiveBytes, full: fullBytes } of entries) if (!bytesEqual(selectiveBytes, fullBytes)) return {
+		kind: "entry-byte-diff",
+		path,
+		selectiveSize: selectiveBytes.length,
+		fullSize: fullBytes.length
+	};
+	return { kind: "match" };
+}
+//#endregion
+export { compareSelectiveVsFull };

package/dist/docx/selectiveXmlPatch.d.ts

@@ -0,0 +1,103 @@
+//#region src/docx/selectiveXmlPatch.d.ts
+/**
+ * Selective XML Patch Module
+ *
+ * Patches only changed paragraphs in document.xml, preserving
+ * unchanged content byte-for-byte. Uses string offset tracking
+ * with proper tag depth counting (not regex) to handle nested elements.
+ */
+/**
+ * Find the exact string start and end offsets of a <w:p> element
+ * identified by its w14:paraId attribute.
+ *
+ * Handles nested <w:p> elements (e.g. inside mc:AlternateContent)
+ * via proper depth counting.
+ *
+ * Returns null if paraId not found or appears more than once (ambiguous).
+ */
+declare function findParagraphOffsets(xml: string, paraId: string): {
+  start: number;
+  end: number;
+} | null;
+/**
+ * Extract the serialized XML for a specific paragraph by paraId
+ * from a fully serialized document.xml string.
+ */
+declare function extractParagraphXml(serializedXml: string, paraId: string): string | null;
+/**
+ * Count <w:p> elements in an XML string (top-level paragraph count).
+ * Counts opening <w:p tags that are NOT self-closing.
+ */
+declare function countParagraphElements(xml: string): number;
+/**
+ * Find all paraIds in an XML string and return counts (to detect duplicates).
+ */
+declare function collectParaIds(xml: string): Map<string, number>;
+type PatchValidationResult = {
+  safe: boolean;
+  reason?: string;
+};
+type PatchSafetyOptions = {
+  /**
+   * Require the original and serialized XML to hold the same number of `<w:p>`
+   * elements. Guards document.xml against structural drift. Notes disable it:
+   * the model only retains the normal notes, so a serialized note part
+   * legitimately has fewer paragraphs than the original (which still carries
+   * the separator notes). See {@link buildPatchedNoteXml}.
+   */
+  checkParagraphCount?: boolean;
+};
+/**
+ * Validate that a selective patch can be safely applied.
+ *
+ * Checks:
+ * - All changed paraIds exist in original XML (exactly once)
+ * - All changed paraIds exist in serialized XML (exactly once)
+ * - Paragraph count matches between original and serialized (unless disabled)
+ */
+declare function validatePatchSafety(originalXml: string, serializedXml: string, changedIds: Set<string>, options?: PatchSafetyOptions): PatchValidationResult;
+/**
+ * Build a patched document.xml by splicing new paragraph XML into
+ * the original at the correct offsets. Only changed paragraphs
+ * are replaced; everything else is preserved byte-for-byte.
+ *
+ * Returns null if any step fails.
+ */
+declare function buildPatchedDocumentXml(originalXml: string, serializedXml: string, changedIds: Set<string>): string | null;
+/**
+ * Build a patched note part (word/footnotes.xml / word/endnotes.xml) by
+ * splicing edited note paragraphs into the original, preserving unchanged
+ * content byte-for-byte.
+ *
+ * Unlike {@link buildPatchedDocumentXml} this does NOT require the paragraph
+ * counts to match: the document model only retains the normal notes, so the
+ * serialized note XML omits the separator / continuationSeparator paragraphs
+ * the original part still carries. Splicing by `paraId` keeps those separators
+ * and every unedited note byte-exact while replacing only the edited ones.
+ *
+ * Returns null if any changed id is missing or ambiguous in either input, so
+ * the caller can fall back to preserving the original part verbatim.
+ */
+declare function buildPatchedNoteXml(originalXml: string, serializedXml: string, changedIds: Set<string>): string | null;
+type ChangedNumberingDefs = {
+  abstractNums: Set<string>;
+  nums: Set<string>;
+};
+/**
+ * The numbering definitions whose current serialization differs from the
+ * baseline (re-parsed original) serialization — the ones actually edited. An id
+ * is only considered when it resolves uniquely in BOTH inputs, so a definition
+ * added or removed relative to the original (which cannot be spliced by id) is
+ * left out; both save paths defer those to the byte-exact original part.
+ */
+declare function collectChangedNumberingDefs(baselineXml: string, currentXml: string): ChangedNumberingDefs;
+/**
+ * Build a patched `word/numbering.xml` by splicing the changed `w:abstractNum` /
+ * `w:num` definitions from `currentXml` (the model's serialization) into
+ * `originalXml`, preserving every other byte. Returns the original unchanged
+ * when nothing changed, or null when a changed id cannot be resolved uniquely
+ * in either input (so the caller preserves the original part verbatim).
+ */
+declare function buildPatchedNumberingXml(originalXml: string, currentXml: string, changed: ChangedNumberingDefs): string | null;
+//#endregion
+export { ChangedNumberingDefs, PatchSafetyOptions, PatchValidationResult, buildPatchedDocumentXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, validatePatchSafety };